github.com/mckael/restic@v0.8.3/doc/manual_rest.rst (about) 1 Manual 2 ====== 3 4 Usage help 5 ---------- 6 7 Usage help is available: 8 9 .. code-block:: console 10 11 $ ./restic --help 12 restic is a backup program which allows saving multiple revisions of files and 13 directories in an encrypted repository stored on different backends. 14 15 Usage: 16 restic [command] 17 18 Available Commands: 19 backup Create a new backup of files and/or directories 20 cat Print internal objects to stdout 21 check Check the repository for errors 22 dump Print a backed-up file to stdout 23 find Find a file or directory 24 forget Remove snapshots from the repository 25 generate Generate manual pages and auto-completion files (bash, zsh) 26 help Help about any command 27 init Initialize a new repository 28 key Manage keys (passwords) 29 list List objects in the repository 30 ls List files in a snapshot 31 migrate Apply migrations 32 mount Mount the repository 33 prune Remove unneeded data from the repository 34 rebuild-index Build a new index file 35 restore Extract the data from a snapshot 36 snapshots List all snapshots 37 tag Modify tags on snapshots 38 unlock Remove locks other processes created 39 version Print version information 40 41 Flags: 42 --cacert stringSlice path to load root certificates from (default: use system certificates) 43 --cache-dir string set the cache directory 44 -h, --help help for restic 45 --json set output mode to JSON for commands that support it 46 --limit-download int limits downloads to a maximum rate in KiB/s. (default: unlimited) 47 --limit-upload int limits uploads to a maximum rate in KiB/s. (default: unlimited) 48 --no-cache do not use a local cache 49 --no-lock do not lock the repo, this allows some operations on read-only repos 50 -o, --option key=value set extended option (key=value, can be specified multiple times) 51 -p, --password-file string read the repository password from a file (default: $RESTIC_PASSWORD_FILE) 52 -q, --quiet do not output comprehensive progress report 53 -r, --repo string repository to backup to or restore from (default: $RESTIC_REPOSITORY) 54 --tls-client-cert string path to a file containing PEM encoded TLS client certificate and private key 55 56 57 Use "restic [command] --help" for more information about a command. 58 59 60 Similar to programs such as ``git``, restic has a number of 61 sub-commands. You can see these commands in the listing above. Each 62 sub-command may have own command-line options, and there is a help 63 option for each command which lists them, e.g. for the ``backup`` 64 command: 65 66 .. code-block:: console 67 68 $ ./restic backup --help 69 The "backup" command creates a new snapshot and saves the files and directories 70 given as the arguments. 71 72 Usage: 73 restic backup [flags] FILE/DIR [FILE/DIR] ... 74 75 Flags: 76 -e, --exclude pattern exclude a pattern (can be specified multiple times) 77 --exclude-caches excludes cache directories that are marked with a CACHEDIR.TAG file 78 --exclude-file file read exclude patterns from a file (can be specified multiple times) 79 --exclude-if-present stringArray takes filename[:header], exclude contents of directories containing filename (except filename itself) if header of that file is as provided (can be specified multiple times) 80 --files-from string read the files to backup from file (can be combined with file args) 81 -f, --force force re-reading the target files/directories (overrides the "parent" flag) 82 -h, --help help for backup 83 --hostname hostname set the hostname for the snapshot manually. To prevent an expensive rescan use the "parent" flag 84 -x, --one-file-system exclude other file systems 85 --parent string use this parent snapshot (default: last snapshot in the repo that has the same target files/directories) 86 --stdin read backup from stdin 87 --stdin-filename string file name to use when reading from stdin (default "stdin") 88 --tag tag add a tag for the new snapshot (can be specified multiple times) 89 --time string time of the backup (ex. '2012-11-01 22:08:41') (default: now) 90 91 Global Flags: 92 --cacert stringSlice path to load root certificates from (default: use system certificates) 93 --cache-dir string set the cache directory 94 --json set output mode to JSON for commands that support it 95 --limit-download int limits downloads to a maximum rate in KiB/s. (default: unlimited) 96 --limit-upload int limits uploads to a maximum rate in KiB/s. (default: unlimited) 97 --no-cache do not use a local cache 98 --no-lock do not lock the repo, this allows some operations on read-only repos 99 -o, --option key=value set extended option (key=value, can be specified multiple times) 100 -p, --password-file string read the repository password from a file (default: $RESTIC_PASSWORD_FILE) 101 -q, --quiet do not output comprehensive progress report 102 -r, --repo string repository to backup to or restore from (default: $RESTIC_REPOSITORY) 103 --tls-client-cert string path to a TLS client certificate 104 --tls-client-key string path to a TLS client certificate key 105 106 Subcommand that support showing progress information such as ``backup``, 107 ``check`` and ``prune`` will do so unless the quiet flag ``-q`` or 108 ``--quiet`` is set. When running from a non-interactive console progress 109 reporting will be limited to once every 10 seconds to not fill your 110 logs. 111 112 Additionally on Unix systems if ``restic`` receives a SIGUSR1 signal the 113 current progress will written to the standard output so you can check up 114 on the status at will. 115 116 Manage tags 117 ----------- 118 119 Managing tags on snapshots is done with the ``tag`` command. The 120 existing set of tags can be replaced completely, tags can be added to 121 removed. The result is directly visible in the ``snapshots`` command. 122 123 Let's say we want to tag snapshot ``590c8fc8`` with the tags ``NL`` and 124 ``CH`` and remove all other tags that may be present, the following 125 command does that: 126 127 .. code-block:: console 128 129 $ restic -r /tmp/backup tag --set NL --set CH 590c8fc8 130 create exclusive lock for repository 131 modified tags on 1 snapshots 132 133 Note the snapshot ID has changed, so between each change we need to look 134 up the new ID of the snapshot. But there is an even better way, the 135 ``tag`` command accepts ``--tag`` for a filter, so we can filter 136 snapshots based on the tag we just added. 137 138 So we can add and remove tags incrementally like this: 139 140 .. code-block:: console 141 142 $ restic -r /tmp/backup tag --tag NL --remove CH 143 create exclusive lock for repository 144 modified tags on 1 snapshots 145 146 $ restic -r /tmp/backup tag --tag NL --add UK 147 create exclusive lock for repository 148 modified tags on 1 snapshots 149 150 $ restic -r /tmp/backup tag --tag NL --remove NL 151 create exclusive lock for repository 152 modified tags on 1 snapshots 153 154 $ restic -r /tmp/backup tag --tag NL --add SOMETHING 155 no snapshots were modified 156 157 Under the hood 158 -------------- 159 160 Browse repository objects 161 ~~~~~~~~~~~~~~~~~~~~~~~~~ 162 163 Internally, a repository stores data of several different types 164 described in the `design 165 documentation <https://github.com/restic/restic/blob/master/doc/Design.rst>`__. 166 You can ``list`` objects such as blobs, packs, index, snapshots, keys or 167 locks with the following command: 168 169 .. code-block:: console 170 171 $ restic -r /tmp/backup list snapshots 172 d369ccc7d126594950bf74f0a348d5d98d9e99f3215082eb69bf02dc9b3e464c 173 174 The ``find`` command searches for a given 175 `pattern <http://golang.org/pkg/path/filepath/#Match>`__ in the 176 repository. 177 178 .. code-block:: console 179 180 $ restic -r backup find test.txt 181 debug log file restic.log 182 debug enabled 183 enter password for repository: 184 found 1 matching entries in snapshot 196bc5760c909a7681647949e80e5448e276521489558525680acf1bd428af36 185 -rw-r--r-- 501 20 5 2015-08-26 14:09:57 +0200 CEST path/to/test.txt 186 187 The ``cat`` command allows you to display the JSON representation of the 188 objects or its raw content. 189 190 .. code-block:: console 191 192 $ restic -r /tmp/backup cat snapshot d369ccc7d126594950bf74f0a348d5d98d9e99f3215082eb69bf02dc9b3e464c 193 enter password for repository: 194 { 195 "time": "2015-08-12T12:52:44.091448856+02:00", 196 "tree": "05cec17e8d3349f402576d02576a2971fc0d9f9776ce2f441c7010849c4ff5af", 197 "paths": [ 198 "/home/user/work" 199 ], 200 "hostname": "kasimir", 201 "username": "username", 202 "uid": 501, 203 "gid": 20 204 } 205 206 Metadata handling 207 ~~~~~~~~~~~~~~~~~ 208 209 Restic saves and restores most default attributes, including extended attributes like ACLs. 210 Sparse files are not handled in a special way yet, and aren't restored. 211 212 The following metadata is handled by restic: 213 214 - Name 215 - Type 216 - Mode 217 - ModTime 218 - AccessTime 219 - ChangeTime 220 - UID 221 - GID 222 - User 223 - Group 224 - Inode 225 - Size 226 - Links 227 - LinkTarget 228 - Device 229 - Content 230 - Subtree 231 - ExtendedAttributes 232 233 Scripting 234 --------- 235 236 Restic supports the output of some commands in JSON format, the JSON 237 data can then be processed by other programs (e.g. 238 `jq <https://stedolan.github.io/jq/>`__). The following example 239 lists all snapshots as JSON and uses ``jq`` to pretty-print the result: 240 241 .. code-block:: console 242 243 $ restic -r /tmp/backup snapshots --json | jq . 244 [ 245 { 246 "time": "2017-03-11T09:57:43.26630619+01:00", 247 "tree": "bf25241679533df554fc0fd0ae6dbb9dcf1859a13f2bc9dd4543c354eff6c464", 248 "paths": [ 249 "/home/work/doc" 250 ], 251 "hostname": "kasimir", 252 "username": "fd0", 253 "uid": 1000, 254 "gid": 100, 255 "id": "bbeed6d28159aa384d1ccc6fa0b540644b1b9599b162d2972acda86b1b80f89e" 256 }, 257 { 258 "time": "2017-03-11T09:58:57.541446938+01:00", 259 "tree": "7f8c95d3420baaac28dc51609796ae0e0ecfb4862b609a9f38ffaf7ae2d758da", 260 "paths": [ 261 "/home/user/shared" 262 ], 263 "hostname": "kasimir", 264 "username": "fd0", 265 "uid": 1000, 266 "gid": 100, 267 "id": "b157d91c16f0ba56801ece3a708dfc53791fe2a97e827090d6ed9a69a6ebdca0" 268 } 269 ] 270 271 Temporary files 272 --------------- 273 274 During some operations (e.g. ``backup`` and ``prune``) restic uses 275 temporary files to store data. These files will, by default, be saved to 276 the system's temporary directory, on Linux this is usually located in 277 ``/tmp/``. The environment variable ``TMPDIR`` can be used to specify a 278 different directory, e.g. to use the directory ``/var/tmp/restic-tmp`` 279 instead of the default, set the environment variable like this: 280 281 .. code-block:: console 282 283 $ export TMPDIR=/var/tmp/restic-tmp 284 $ restic -r /tmp/backup backup ~/work 285 286 287 288 Caching 289 ------- 290 291 Restic keeps a cache with some files from the repository on the local machine. 292 This allows faster operations, since meta data does not need to be loaded from 293 a remote repository. The cache is automatically created, usually in an 294 OS-specific cache folder: 295 296 * Linux/other: ``~/.cache/restic`` (or ``$XDG_CACHE_HOME/restic``) 297 * macOS: ``~/Library/Caches/restic`` 298 * Windows: ``%LOCALAPPDATA%/restic`` 299 300 The command line parameter ``--cache-dir`` can each be used to override the 301 default cache location. The parameter ``--no-cache`` disables the cache 302 entirely. In this case, all data is loaded from the repo. 303 304 The cache is ephemeral: When a file cannot be read from the cache, it is loaded 305 from the repository. 306 307 Within the cache directory, there's a sub directory for each repository the 308 cache was used with. Restic updates the timestamps of a repo directory each 309 time it is used, so by looking at the timestamps of the sub directories of the 310 cache directory it can decide which sub directories are old and probably not 311 needed any more. You can either remove these directories manually, or run a 312 restic command with the ``--cleanup-cache`` flag.