diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index dc7f782dc..61c1949da 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -37,3 +37,252 @@ exit code if a different error is encountered (e.g.: incorrect password to ``cat config``) and it may print a different error message. If there are no errors, restic will return a zero exit code and print the repository metadata. + +Restic and json +*************** + +Restic can output json data if requested with the ``--json`` flag. +The structure of that data varies depending on the circumstance. The +json output of Most restic commands are documented here. + +.. note:: + Not all commands support json output. If a command does not support json output, + at the time of writing, it is not supported yet. (feel free to submit a pull request!) + +Backup +------ + +backup has multiple json structures, outlined below. + +Status +^^^^^^ + ++----------------------+---------------------------------------------------------+ +|``message_type`` | always "status" | ++----------------------+---------------------------------------------------------+ +|``seconds_elapsed`` | Time since backup started | ++----------------------+---------------------------------------------------------+ +|``seconds_remaining`` | Estimated time remaining | ++----------------------+---------------------------------------------------------+ +|``percent_done`` | Percentage of data backed up. (bytes_done/total_bytes) | ++----------------------+---------------------------------------------------------+ +|``total_files`` | Total number of files detected | ++----------------------+---------------------------------------------------------+ +|``files_done`` | Files completed (backed up or skipped) | ++----------------------+---------------------------------------------------------+ +|``total_bytes`` | Total number of bytes in backup set | ++----------------------+---------------------------------------------------------+ +|``bytes_done`` | Number of bytes completed | ++----------------------+---------------------------------------------------------+ +|``error_count`` | Number of errors | ++----------------------+---------------------------------------------------------+ +|``current_files`` | List of files currently being backed up | ++----------------------+---------------------------------------------------------+ + +Error +^^^^^ + ++----------------------+--------------------------------+ +| ``message_type`` | always "error" | ++----------------------+--------------------------------+ +| ``error`` | error message | ++----------------------+--------------------------------+ +| ``during`` | what restic was trying to do | ++----------------------+--------------------------------+ +| ``item`` | what item was being processed | ++----------------------+--------------------------------+ + +Verbose Status +^^^^^^^^^^^^^^ + ++----------------------+-------------------------------------------+ +| ``message_type`` | Always "verbose_status" | ++----------------------+-------------------------------------------+ +| ``action`` | Either "new", "unchanged" or "modified" | ++----------------------+-------------------------------------------+ +| ``item`` | The item in question | ++----------------------+-------------------------------------------+ +| ``duration`` | How long it took, in seconds | ++----------------------+-------------------------------------------+ +| ``data_size`` | How big item is | ++----------------------+-------------------------------------------+ +| ``metadata_size`` | How big the metadata is | ++----------------------+-------------------------------------------+ +| ``total_files`` | how many total files there are. | ++----------------------+-------------------------------------------+ + +Summary +^^^^^^^ + ++---------------------------+---------------------------------------------------------+ +| ``message_type`` | Always "summary" | ++---------------------------+---------------------------------------------------------+ +| ``files_new`` | Number of new files | ++---------------------------+---------------------------------------------------------+ +| ``files_changed`` | Number of files that changed | ++---------------------------+---------------------------------------------------------+ +| ``files_unmodified`` | Number of files that did not change | ++---------------------------+---------------------------------------------------------+ +| ``dirs_new`` | Number of new directories | ++---------------------------+---------------------------------------------------------+ +| ``dirs_changed`` | Number of directories that changed | ++---------------------------+---------------------------------------------------------+ +| ``dirs_unmodified`` | Number of directories that did not change | ++---------------------------+---------------------------------------------------------+ +| ``data_blobs`` | Number of data blobs | ++---------------------------+---------------------------------------------------------+ +| ``tree_blobs`` | Number of tree blobs | ++---------------------------+---------------------------------------------------------+ +| ``data_added`` | Amount of data added, in bytes | ++---------------------------+---------------------------------------------------------+ +| ``total_files_processed`` | Total number of files processed | ++---------------------------+---------------------------------------------------------+ +| ``total_bytes_processed`` | Total number of bytes processed | ++---------------------------+---------------------------------------------------------+ +| ``total_duration`` | Total time it took for the operation to complete | ++---------------------------+---------------------------------------------------------+ +| ``snapshot_id`` | the ID of the new snapshot | ++---------------------------+---------------------------------------------------------+ + +snapshots +--------- + +Snapshots returns a single json structure with a number of optional fields. + ++----------------+------------------------------------------------------------------------+ +| ``hostname`` | contains the hostname of the machine that's being backed up. | ++----------------+------------------------------------------------------------------------+ +| ``username`` | contains the username that the backup command was run as. | ++----------------+------------------------------------------------------------------------+ +| ``excludes`` | contains a list of paths and globs that were excluded from the backup. | ++----------------+------------------------------------------------------------------------+ +| ``tags`` | contains a list of tags for the snapshot in question. | ++----------------+------------------------------------------------------------------------+ +| ``id`` | contains the long snapshot id. | ++----------------+------------------------------------------------------------------------+ +| ``short_id`` | contains the short snapshot id. | ++----------------+------------------------------------------------------------------------+ +| ``time`` | contains the timestamp of the backup. | ++----------------+------------------------------------------------------------------------+ +| ``parent`` | contains the id of the previous backup. | ++----------------+------------------------------------------------------------------------+ +| ``tree`` | contains something... | ++----------------+------------------------------------------------------------------------+ +| ``paths`` | contains a list of paths that were included in the backup. | ++----------------+------------------------------------------------------------------------+ + +cat +--- + +Cat will return data about various objects in the repository, already in json form. +By specifying ``--json``, it will suppress any non-json messages the command generates. + +find +---- + + ++-----------------+------------------------------------------+ +| ``path`` | Object path | ++-----------------+------------------------------------------+ +| ``permissions`` | unix permissions | ++-----------------+------------------------------------------+ +| ``type`` | what type it is e.g. file, dir, etc... | ++-----------------+------------------------------------------+ +| ``atime`` | Access time | ++-----------------+------------------------------------------+ +| ``mtime`` | Modification time | ++-----------------+------------------------------------------+ +| ``ctime`` | Creation time | ++-----------------+------------------------------------------+ +| ``name`` | Object name | ++-----------------+------------------------------------------+ +| ``user`` | Name of owner | ++-----------------+------------------------------------------+ +| ``group`` | Name of group | ++-----------------+------------------------------------------+ +| ``uid`` | ID of owner | ++-----------------+------------------------------------------+ +| ``gid`` | ID of group | ++-----------------+------------------------------------------+ +| ``size`` | size of object in bytes | ++-----------------+------------------------------------------+ + +key list +-------- + ++--------------+------------------------------------+ +| ``current`` | Is currently used key? | ++--------------+------------------------------------+ +| ``id`` | Unique key ID | ++--------------+------------------------------------+ +| ``userName`` | user who created it | ++--------------+------------------------------------+ +| ``hostName`` | name of machine it was created on | ++--------------+------------------------------------+ +| ``created`` | timestamp when it was created | ++--------------+------------------------------------+ + +ls +-- + +snapshot +^^^^^^^^ + ++-----------------+-------------------------------------+ +| ``time`` | Snapshot time | ++-----------------+-------------------------------------+ +| ``tree`` | Snapshot tree root | ++-----------------+-------------------------------------+ +| ``paths`` | List of paths included in snapshot | ++-----------------+-------------------------------------+ +| ``hostname`` | hostname of snapshot | ++-----------------+-------------------------------------+ +| ``username`` | user snapshot was run as | ++-----------------+-------------------------------------+ +| ``uid`` | uid of backup process | ++-----------------+-------------------------------------+ +| ``gid`` | gid of backup process | ++-----------------+-------------------------------------+ +| ``id`` | snapshot id, long form | ++-----------------+-------------------------------------+ +| ``short_id`` | snapshot id, short form | ++-----------------+-------------------------------------+ +| ``struct_type`` | always "snapshot" | ++-----------------+-------------------------------------+ + + +node +^^^^ + ++-----------------+--------------------------+ +| ``name`` | node name | ++-----------------+--------------------------+ +| ``type`` | node type | ++-----------------+--------------------------+ +| ``path`` | node path | ++-----------------+--------------------------+ +| ``uid`` | uid of node | ++-----------------+--------------------------+ +| ``gid`` | gid of node | ++-----------------+--------------------------+ +| ``size`` | size in bytes | ++-----------------+--------------------------+ +| ``mode`` | node mode | ++-----------------+--------------------------+ +| ``atime`` | node access time | ++-----------------+--------------------------+ +| ``mtime`` | node modification time | ++-----------------+--------------------------+ +| ``ctime`` | node creation time | ++-----------------+--------------------------+ +| ``struct_type`` | always "node" | ++-----------------+--------------------------+ + +stats +----- + ++----------------------+---------------------------------------------+ +| ``total_size`` | Repository size in bytes | ++----------------------+---------------------------------------------+ +| ``total_file_count`` | Number of files backed up in the repository | ++----------------------+---------------------------------------------+