TrueCloudLab/restic
16
0
Fork 2
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Documentation improvement

Browse source
This commit is contained in:
Kyle Brennan 2020-11-25 23:54:53 -08:00 committed by Michael Eischer
parent 39299e36ef
commit e457fe22bc
1 changed files with 127 additions and 94 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

221
doc/075_scripting.rst
View file

@ -38,63 +38,68 @@ 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 are no errors, restic will return a zero exit code and print the repository
metadata. metadata.
Restic and json Restic and JSON
*************** ***************
Restic can output json data if requested with the ``--json`` flag. Restic can output json data if requested with the ``--json`` flag.
The structure of that data varies depending on the circumstance. The The structure of that data varies depending on the circumstance. The
json output of Most restic commands are documented here. json output of most restic commands are documented here.
.. note:: .. note::
Not all commands support json output. If a command does not support json output, 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!) feel free to submit a pull request!
Backup Backup
------ ------
backup has multiple json structures, outlined below. The backup command has multiple json structures, outlined below.
During the backup process, Restic will print out a stream of new-line separated JSON
messages. You can determine the nature of the message by the ``message_type`` field.
Status Status
^^^^^^ ^^^^^^
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``message_type`` | always "status" | |``message_type`` | Always "status" |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``seconds_elapsed`` | Time since backup started | |``seconds_elapsed`` | Time since backup started |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``seconds_remaining`` | Estimated time remaining | |``seconds_remaining`` | Estimated time remaining |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``percent_done`` | Percentage of data backed up. (bytes_done/total_bytes) | |``percent_done`` | Percentage of data backed up (bytes_done/total_bytes) |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``total_files`` | Total number of files detected | |``total_files`` | Total number of files detected |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``files_done`` | Files completed (backed up or skipped) | |``files_done`` | Files completed (backed up or confirmed in repo) |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``total_bytes`` | Total number of bytes in backup set | |``total_bytes`` | Total number of bytes in backup set |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``bytes_done`` | Number of bytes completed | |``bytes_done`` | Number of bytes completed (backed up or confirmed in repo) |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``error_count`` | Number of errors | |``error_count`` | Number of errors |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
|``current_files`` | List of files currently being backed up | |``current_files`` | List of files currently being backed up |
+----------------------+---------------------------------------------------------+ +----------------------+------------------------------------------------------------+
Error Error
^^^^^ ^^^^^
+----------------------+--------------------------------+ +----------------------+-------------------------------------------+
| ``message_type`` | always "error" | | ``message_type`` | Always "error" |
+----------------------+--------------------------------+ +----------------------+-------------------------------------------+
| ``error`` | error message | | ``error`` | Error message |
+----------------------+--------------------------------+ +----------------------+-------------------------------------------+
| ``during`` | what restic was trying to do | | ``during`` | What restic was trying to do |
+----------------------+--------------------------------+ +----------------------+-------------------------------------------+
| ``item`` | what item was being processed | | ``item`` | Usually, the path of the problematic file |
+----------------------+--------------------------------+ +----------------------+-------------------------------------------+
Verbose Status Verbose Status
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Verbose status is a status line that supplements
+----------------------+-------------------------------------------+ +----------------------+-------------------------------------------+
| ``message_type`` | Always "verbose_status" | | ``message_type`` | Always "verbose_status" |
+----------------------+-------------------------------------------+ +----------------------+-------------------------------------------+
@ -104,16 +109,18 @@ Verbose Status
+----------------------+-------------------------------------------+ +----------------------+-------------------------------------------+
| ``duration`` | How long it took, in seconds | | ``duration`` | How long it took, in seconds |
+----------------------+-------------------------------------------+ +----------------------+-------------------------------------------+
| ``data_size`` | How big item is | | ``data_size`` | How big the item is |
+----------------------+-------------------------------------------+ +----------------------+-------------------------------------------+
| ``metadata_size`` | How big the metadata is | | ``metadata_size`` | How big the metadata is |
+----------------------+-------------------------------------------+ +----------------------+-------------------------------------------+
| ``total_files`` | how many total files there are. | | ``total_files`` | Total number of files |
+----------------------+-------------------------------------------+ +----------------------+-------------------------------------------+
Summary Summary
^^^^^^^ ^^^^^^^
Summary is the last output line in a successful backup.
+---------------------------+---------------------------------------------------------+ +---------------------------+---------------------------------------------------------+
| ``message_type`` | Always "summary" | | ``message_type`` | Always "summary" |
+---------------------------+---------------------------------------------------------+ +---------------------------+---------------------------------------------------------+
@ -141,34 +148,34 @@ Summary
+---------------------------+---------------------------------------------------------+ +---------------------------+---------------------------------------------------------+
| ``total_duration`` | Total time it took for the operation to complete | | ``total_duration`` | Total time it took for the operation to complete |
+---------------------------+---------------------------------------------------------+ +---------------------------+---------------------------------------------------------+
| ``snapshot_id`` | the ID of the new snapshot | | ``snapshot_id`` | The short ID of the new snapshot |
+---------------------------+---------------------------------------------------------+ +---------------------------+---------------------------------------------------------+
snapshots snapshots
--------- ---------
Snapshots returns a single json structure with a number of optional fields. The snapshots command returns a single JSON object, an array with the structure outlined below.
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``hostname`` | contains the hostname of the machine that's being backed up. | | ``hostname`` | The hostname of the machine that's being backed up |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``username`` | contains the username that the backup command was run as. | | ``username`` | The username that the backup command was run as |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``excludes`` | contains a list of paths and globs that were excluded from the backup. | | ``excludes`` | A list of paths and globs that were excluded from the backup |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``tags`` | contains a list of tags for the snapshot in question. | | ``tags`` | A list of tags for the snapshot in question |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``id`` | contains the long snapshot id. | | ``id`` | The long snapshot ID |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``short_id`` | contains the short snapshot id. | | ``short_id`` | The short snapshot ID |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``time`` | contains the timestamp of the backup. | | ``time`` | The timestamp of when the backup was started |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``parent`` | contains the id of the previous backup. | | ``parent`` | The ID of the previous snapshot |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``tree`` | contains something... | | ``tree`` | The ID of the root tree blob |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
| ``paths`` | contains a list of paths that were included in the backup. | | ``paths`` | A list of paths that were included in the backup |
+----------------+------------------------------------------------------------------------+ +----------------+------------------------------------------------------------------------+
cat cat
@ -180,51 +187,75 @@ By specifying ``--json``, it will suppress any non-json messages the command gen
find find
---- ----
The find command outputs an array of json objects with matches for your search term. These
matches are organized by snapshot.
+-----------------+------------------------------------------+ Snapshot
| ``path`` | Object path | ^^^^^^^^
+-----------------+------------------------------------------+
| ``permissions`` | unix permissions | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+ | ``hits`` | The number of matches in the snapshot |
| ``type`` | what type it is e.g. file, dir, etc... | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+ | ``snapshot`` | The long ID of the snapshot |
| ``atime`` | Access time | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+ | ``matches`` | Array of JSON objects detailing a match. |
| ``mtime`` | Modification time | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+
| ``ctime`` | Creation time |
+-----------------+------------------------------------------+ Match
| ``name`` | Object name | ^^^^^
+-----------------+------------------------------------------+
| ``user`` | Name of owner | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+ | ``path`` | Object path |
| ``group`` | Name of group | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+ | ``permissions`` | UNIX permissions |
| ``uid`` | ID of owner | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+ | ``type`` | what type it is e.g. file, dir, etc... |
| ``gid`` | ID of group | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+ | ``atime`` | Access time |
| ``size`` | size of object in bytes | +-----------------+----------------------------------------------+
+-----------------+------------------------------------------+ | ``mtime`` | Modification time |
+-----------------+----------------------------------------------+
| ``ctime`` | Change time |
+-----------------+----------------------------------------------+
| ``name`` | Object name |
+-----------------+----------------------------------------------+
| ``user`` | Name of owner |
+-----------------+----------------------------------------------+
| ``group`` | Name of group |
+-----------------+----------------------------------------------+
| ``mode`` | UNIX file mode, shorthand of ``permissions`` |
+-----------------+----------------------------------------------+
| ``uid`` | ID of owner |
+-----------------+----------------------------------------------+
| ``gid`` | ID of group |
+-----------------+----------------------------------------------+
| ``size`` | Size of object in bytes |
+-----------------+----------------------------------------------+
key list key list
-------- --------
The key list command returns an array of objects with the following structure.
+--------------+------------------------------------+ +--------------+------------------------------------+
| ``current`` | Is currently used key? | | ``current`` | Is currently used key? |
+--------------+------------------------------------+ +--------------+------------------------------------+
| ``id`` | Unique key ID | | ``id`` | Unique key ID |
+--------------+------------------------------------+ +--------------+------------------------------------+
| ``userName`` | user who created it | | ``userName`` | User who created it |
+--------------+------------------------------------+ +--------------+------------------------------------+
| ``hostName`` | name of machine it was created on | | ``hostName`` | Name of machine it was created on |
+--------------+------------------------------------+ +--------------+------------------------------------+
| ``created`` | timestamp when it was created | | ``created`` | Timestamp when it was created |
+--------------+------------------------------------+ +--------------+------------------------------------+
ls ls
-- --
The ls command spits out a series of newline-separated JSON objects,
the nature of which can be determined by the ``struct_type`` field.
snapshot snapshot
^^^^^^^^ ^^^^^^^^
@ -235,19 +266,19 @@ snapshot
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
| ``paths`` | List of paths included in snapshot | | ``paths`` | List of paths included in snapshot |
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
| ``hostname`` | hostname of snapshot | | ``hostname`` | Hostname of snapshot |
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
| ``username`` | user snapshot was run as | | ``username`` | User snapshot was run as |
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
| ``uid`` | uid of backup process | | ``uid`` | UID of backup process |
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
| ``gid`` | gid of backup process | | ``gid`` | GID of backup process |
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
| ``id`` | snapshot id, long form | | ``id`` | Snapshot ID, long form |
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
| ``short_id`` | snapshot id, short form | | ``short_id`` | Snapshot ID, short form |
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
| ``struct_type`` | always "snapshot" | | ``struct_type`` | Always "snapshot" |
+-----------------+-------------------------------------+ +-----------------+-------------------------------------+
@ -255,27 +286,27 @@ node
^^^^ ^^^^
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``name`` | node name | | ``name`` | Node name |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``type`` | node type | | ``type`` | Node type |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``path`` | node path | | ``path`` | Node path |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``uid`` | uid of node | | ``uid`` | UID of node |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``gid`` | gid of node | | ``gid`` | GID of node |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``size`` | size in bytes | | ``size`` | Size in bytes |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``mode`` | node mode | | ``mode`` | Node mode |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``atime`` | node access time | | ``atime`` | Node access time |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``mtime`` | node modification time | | ``mtime`` | Node modification time |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``ctime`` | node creation time | | ``ctime`` | Node creation time |
+-----------------+--------------------------+ +-----------------+--------------------------+
| ``struct_type`` | always "node" | | ``struct_type`` | Always "node" |
+-----------------+--------------------------+ +-----------------+--------------------------+
stats stats
@ -286,3 +317,5 @@ stats
+----------------------+---------------------------------------------+ +----------------------+---------------------------------------------+
| ``total_file_count`` | Number of files backed up in the repository | | ``total_file_count`` | Number of files backed up in the repository |
+----------------------+---------------------------------------------+ +----------------------+---------------------------------------------+
| ``total_blob_count`` | Number of blobs in the repository |
+----------------------+---------------------------------------------+