add json documentation
This commit is contained in:
Kyle Brennan
Michael Eischer
parent
170e495334
commit
39299e36ef
1 changed files with 249 additions and 0 deletions
|
|
@ -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
|
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 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 |
|
||||||
|
+----------------------+---------------------------------------------+
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue