From c3cc5d7cee97d62033257702b9549ff849152557 Mon Sep 17 00:00:00 2001 From: Alexander Neumann Date: Sat, 28 Apr 2018 16:19:16 +0200 Subject: [PATCH] Update docs --- doc/010_introduction.rst | 3 + doc/020_installation.rst | 14 ++- doc/030_preparing_a_new_repo.rst | 22 +++-- doc/040_backup.rst | 155 ++++++++++++++++++++++--------- doc/045_working_with_repos.rst | 22 ++--- doc/050_restore.rst | 12 +-- doc/060_forget.rst | 8 +- doc/070_encryption.rst | 10 +- doc/075_scripting.rst | 6 +- doc/100_references.rst | 39 +++----- doc/110_talks.rst | 34 +++++++ doc/cache.rst | 36 ------- doc/conf.py | 2 +- doc/index.rst | 1 + doc/manual_rest.rst | 75 ++++++++------- 15 files changed, 255 insertions(+), 184 deletions(-) create mode 100644 doc/110_talks.rst delete mode 100644 doc/cache.rst diff --git a/doc/010_introduction.rst b/doc/010_introduction.rst index 6128c6662..5c213f6cd 100644 --- a/doc/010_introduction.rst +++ b/doc/010_introduction.rst @@ -14,3 +14,6 @@ Introduction ############ +Restic is a fast and secure backup program. In the following sections, we will +present typical workflows, starting with installing, preparing a new +repository, and making the first backup. diff --git a/doc/020_installation.rst b/doc/020_installation.rst index df10fcb84..6cab0c9a1 100644 --- a/doc/020_installation.rst +++ b/doc/020_installation.rst @@ -145,9 +145,17 @@ Admin rights. Docker Container **************** +We're maintaining a bare docker container with just a few files and the restic +binary, you can get it with `docker pull` like this: + +.. code-block:: console + + $ docker pull restic/restic + .. note:: - | A docker container is available as a contribution (Thank you!). - | You can find it at https://github.com/Lobaro/restic-backup-docker + | Another docker container which offers more configuration options is + | available as a contribution (Thank you!). You can find it at + | https://github.com/Lobaro/restic-backup-docker From Source *********** @@ -173,7 +181,7 @@ You can easily cross-compile restic for all supported platforms, just supply the target OS and platform via the command-line options like this (for Windows and FreeBSD respectively): -:: +.. code-block:: console $ go run build.go --goos windows --goarch amd64 diff --git a/doc/030_preparing_a_new_repo.rst b/doc/030_preparing_a_new_repo.rst index 7d865d9a5..2133ec7c2 100644 --- a/doc/030_preparing_a_new_repo.rst +++ b/doc/030_preparing_a_new_repo.rst @@ -15,20 +15,24 @@ Preparing a new repository ########################## The place where your backups will be saved at is called a "repository". -This chapter explains how to create ("init") such a repository. +This chapter explains how to create ("init") such a repository. The repository +can be stored locally, or on some remote server or service. We'll first cover +using a local repository, the remaining sections of this chapter cover all the +other options. You can skip to the next chapter once you've read the relevant +section here. Local ***** -In order to create a repository at ``/tmp/backup``, run the following +In order to create a repository at ``/srv/restic-repo``, run the following command and enter the same password twice: .. code-block:: console - $ restic init --repo /tmp/backup + $ restic init --repo /srv/restic-repo enter password for new backend: enter password again: - created restic backend 085b3c76b9 at /tmp/backup + created restic backend 085b3c76b9 at /srv/restic-repo Please note that knowledge of your password is required to access the repository. Losing your password means that your data is irrecoverably lost. @@ -55,10 +59,10 @@ simply be achieved by changing the URL scheme in the ``init`` command: .. code-block:: console - $ restic -r sftp:user@host:/tmp/backup init + $ restic -r sftp:user@host:/srv/restic-repo init enter password for new backend: enter password again: - created restic backend f1c6108821 at sftp:user@host:/tmp/backup + created restic backend f1c6108821 at sftp:user@host:/srv/restic-repo Please note that knowledge of your password is required to access the repository. Losing your password means that your data is irrecoverably lost. @@ -87,7 +91,7 @@ specify the user name in this case): :: - $ restic -r sftp:foo:/tmp/backup init + $ restic -r sftp:foo:/srv/restic-repo init You can also add an entry with a special host name which does not exist, just for use with restic, and use the ``Hostname`` option to set the @@ -104,7 +108,7 @@ Then use it in the backend specification: :: - $ restic -r sftp:restic-backup-host:/tmp/backup init + $ restic -r sftp:restic-backup-host:/srv/restic-repo init Last, if you'd like to use an entirely different program to create the SFTP connection, you can specify the command to be run with the option @@ -509,5 +513,5 @@ On MSYS2, you can install ``winpty`` as follows: .. code-block:: console $ pacman -S winpty - $ winpty restic -r /tmp/backup init + $ winpty restic -r /srv/restic-repo init diff --git a/doc/040_backup.rst b/doc/040_backup.rst index a181879d5..badc836ba 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -21,43 +21,88 @@ again: .. code-block:: console - $ restic -r /tmp/backup backup ~/work + $ restic -r /srv/restic-repo --verbose backup ~/work + open repository enter password for repository: - scan [/home/user/work] - scanned 764 directories, 1816 files in 0:00 - [0:29] 100.00% 54.732 MiB/s 1.582 GiB / 1.582 GiB 2580 / 2580 items 0 errors ETA 0:00 - duration: 0:29, 54.47MiB/s + password is correct + lock repository + load index files + start scan + start backup + scan finished in 1.837s + processed 1.720 GiB in 0:12 + Files: 5307 new, 0 changed, 0 unmodified + Dirs: 1867 new, 0 changed, 0 unmodified + Added: 1.700 GiB snapshot 40dc1520 saved As you can see, restic created a backup of the directory and was pretty fast! The specific snapshot just created is identified by a sequence of hexadecimal characters, ``40dc1520`` in this case. +If you don't pass the ``--verbose`` option, restic will print less data (but +you'll still get a nice live status display). + If you run the command again, restic will create another snapshot of your data, but this time it's even faster. This is de-duplication at work! .. code-block:: console - $ restic -r /tmp/backup backup ~/work + $ restic -r /srv/restic-repo backup --verbose ~/work + open repository enter password for repository: - using parent snapshot 40dc1520aa6a07b7b3ae561786770a01951245d2367241e71e9485f18ae8228c - scan [/home/user/work] - scanned 764 directories, 1816 files in 0:00 - [0:00] 100.00% 0B/s 1.582 GiB / 1.582 GiB 2580 / 2580 items 0 errors ETA 0:00 - duration: 0:00, 6572.38MiB/s + password is correct + lock repository + load index files + using parent snapshot d875ae93 + start scan + start backup + scan finished in 1.881s + processed 1.720 GiB in 0:03 + Files: 0 new, 0 changed, 5307 unmodified + Dirs: 0 new, 0 changed, 1867 unmodified + Added: 0 B snapshot 79766175 saved -You can even backup individual files in the same repository. +You can even backup individual files in the same repository (not passing +``--verbose`` means less output): .. code-block:: console - $ restic -r /tmp/backup backup ~/work.txt - scan [/home/user/work.txt] - scanned 0 directories, 1 files in 0:00 - [0:00] 100.00% 0B/s 220B / 220B 1 / 1 items 0 errors ETA 0:00 - duration: 0:00, 0.03MiB/s - snapshot 31f7bd63 saved + $ restic -r /srv/restic-repo backup ~/work.txt + enter password for repository: + password is correct + snapshot 249d0210 saved + +If you're interested in what restic does, pass ``--verbose`` twice (or +``--verbose 2``) to display detailed information about each file and directory +restic encounters: + +.. code-block:: console + + $ echo 'more data foo bar' >> ~/work.txt + + $ restic -r /srv/restic-repo backup --verbose --verbose ~/work.txt + open repository + enter password for repository: + password is correct + lock repository + load index files + using parent snapshot f3f8d56b + start scan + start backup + scan finished in 2.115s + modified /home/user/work.txt, saved in 0.007s (22 B added) + modified /home/user/, saved in 0.008s (0 B added, 378 B metadata) + modified /home/, saved in 0.009s (0 B added, 375 B metadata) + processed 22 B in 0:02 + Files: 0 new, 1 changed, 0 unmodified + Dirs: 0 new, 2 changed, 0 unmodified + Data Blobs: 1 new + Tree Blobs: 3 new + Added: 1.116 KiB + snapshot 8dc503fc saved In fact several hosts may use the same repository to backup directories and files leading to a greater de-duplication. @@ -87,33 +132,53 @@ the exclude options are: - ``--exclude-if-present`` Specified one or more times to exclude a folders content if it contains a given file (optionally having a given header) -Basic example: + Let's say we have a file called ``excludes.txt`` with the following content: -.. code-block:: console - - $ cat exclude +:: # exclude go-files *.go # exclude foo/x/y/z/bar foo/x/bar foo/bar foo/**/bar - $ restic -r /tmp/backup backup ~/work --exclude="*.c" --exclude-file=exclude + +It can be used like this: + +.. code-block:: console + + $ restic -r /srv/restic-repo backup ~/work --exclude="*.c" --exclude-file=excludes.txt + +This instruct restic to exclude files matching the following criteria: + + * All files matching ``*.go`` (second line in ``excludes.txt``) + * All files and sub-directories named ``bar`` which reside somewhere below a directory called ``foo`` (fourth line in ``excludes.txt``) + * All files matching ``*.c`` (parameter ``--exclude``) Please see ``restic help backup`` for more specific information about each exclude option. Patterns use `filepath.Glob `__ internally, -see `filepath.Match `__ for syntax. -Patterns are tested against the full path of a file/dir to be saved, not only -against the relative path below the argument given to restic backup. -Patterns need to match on complete path components. (``foo`` matches -``/dir1/foo/dir2/file`` and ``/dir/foo`` but does not match ``/dir/foobar`` or -``barfoo``.) A trailing ``/`` is ignored. A leading ``/`` anchors the -pattern at the root directory. (``/bin`` matches ``/bin/bash`` but does not -match ``/usr/bin/restic``.) Regular wildcards cannot be used to match over the -directory separator ``/``. (``b*ash`` matches ``/bin/bash`` but does not match -``/bin/ash``.) However ``**`` matches arbitrary subdirectories. (``foo/**/bar`` -matches ``/dir1/foo/dir2/bar/file``, ``/foo/bar/file`` and ``/tmp/foo/bar``.) -Environment-variables in exclude-files are expanded with -`os.ExpandEnv `__. +see `filepath.Match `__ for +syntax. Patterns are tested against the full path of a file/dir to be saved, +even if restic is passed a relative path to save. Environment-variables in +exclude-files are expanded with `os.ExpandEnv `__. + +Patterns need to match on complete path components. For example, the pattern ``foo``: + + * matches ``/dir1/foo/dir2/file`` and ``/dir/foo`` + * does not match ``/dir/foobar`` or ``barfoo`` + +A trailing ``/`` is ignored, a leading ``/`` anchors the +pattern at the root directory. This means, ``/bin`` matches ``/bin/bash`` but +does not match ``/usr/bin/restic``. + +Regular wildcards cannot be used to match over the +directory separator ``/``. For example: ``b*ash`` matches ``/bin/bash`` but does not match +``/bin/ash``. + +For this, the special wildcard ``**`` can be used to match arbitrary +sub-directories: The pattern ``foo/**/bar`` matches: + + * ``/dir1/foo/dir2/bar/file`` + * ``/foo/bar/file`` + * ``/tmp/foo/bar`` By specifying the option ``--one-file-system`` you can instruct restic to only backup files from the file systems the initially specified files @@ -122,15 +187,15 @@ backup ``/sys`` or ``/dev`` on a Linux system: .. code-block:: console - $ restic -r /tmp/backup backup --one-file-system / + $ restic -r /srv/restic-repo backup --one-file-system / By using the ``--files-from`` option you can read the files you want to backup from a file. This is especially useful if a lot of files have to be backed up that are not in the same folder or are maybe pre-filtered by other software. -For example maybe you want to backup files that have a certain filename -in them: +For example maybe you want to backup files which have a name that matches a +certain pattern: .. code-block:: console @@ -140,14 +205,14 @@ You can then use restic to backup the filtered files: .. code-block:: console - $ restic -r /tmp/backup backup --files-from /tmp/files_to_backup + $ restic -r /srv/restic-repo backup --files-from /tmp/files_to_backup Incidentally you can also combine ``--files-from`` with the normal files args: .. code-block:: console - $ restic -r /tmp/backup backup --files-from /tmp/files_to_backup /tmp/some_additional_file + $ restic -r /srv/restic-repo backup --files-from /tmp/files_to_backup /tmp/some_additional_file Paths in the listing file can be absolute or relative. @@ -159,7 +224,7 @@ and displays a small statistic, just pass the command two snapshot IDs: .. code-block:: console - $ restic -r /tmp/backup diff 5845b002 2ab627a6 + $ restic -r /srv/restic-repo diff 5845b002 2ab627a6 password is correct comparing snapshot ea657ce5 to 2ab627a6: @@ -206,7 +271,7 @@ this mode of operation, just supply the option ``--stdin`` to the .. code-block:: console - $ mysqldump [...] | restic -r /tmp/backup backup --stdin + $ mysqldump [...] | restic -r /srv/restic-repo backup --stdin This creates a new snapshot of the output of ``mysqldump``. You can then use e.g. the fuse mounting option (see below) to mount the repository @@ -217,7 +282,7 @@ specified with ``--stdin-filename``, e.g. like this: .. code-block:: console - $ mysqldump [...] | restic -r /tmp/backup backup --stdin --stdin-filename production.sql + $ mysqldump [...] | restic -r /srv/restic-repo backup --stdin --stdin-filename production.sql Tags for backup *************** @@ -227,7 +292,7 @@ information. Just specify the tags for a snapshot one by one with ``--tag``: .. code-block:: console - $ restic -r /tmp/backup backup --tag projectX --tag foo --tag bar ~/work + $ restic -r /srv/restic-repo backup --tag projectX --tag foo --tag bar ~/work [...] The tags can later be used to keep (or forget) snapshots with the ``forget`` diff --git a/doc/045_working_with_repos.rst b/doc/045_working_with_repos.rst index 5ee39ea26..773234ca0 100644 --- a/doc/045_working_with_repos.rst +++ b/doc/045_working_with_repos.rst @@ -22,7 +22,7 @@ Now, you can list all the snapshots stored in the repository: .. code-block:: console - $ restic -r /tmp/backup snapshots + $ restic -r /srv/restic-repo snapshots enter password for repository: ID Date Host Tags Directory ---------------------------------------------------------------------- @@ -36,7 +36,7 @@ You can filter the listing by directory path: .. code-block:: console - $ restic -r /tmp/backup snapshots --path="/srv" + $ restic -r /srv/restic-repo snapshots --path="/srv" enter password for repository: ID Date Host Tags Directory ---------------------------------------------------------------------- @@ -47,7 +47,7 @@ Or filter by host: .. code-block:: console - $ restic -r /tmp/backup snapshots --host luigi + $ restic -r /srv/restic-repo snapshots --host luigi enter password for repository: ID Date Host Tags Directory ---------------------------------------------------------------------- @@ -74,7 +74,7 @@ backup data is consistent and the integrity is unharmed: .. code-block:: console - $ restic -r /tmp/backup check + $ restic -r /srv/restic-repo check Load indexes ciphertext verification failed @@ -83,7 +83,7 @@ yield the same error: .. code-block:: console - $ restic -r /tmp/backup restore 79766175 --target /tmp/restore-work + $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work Load indexes ciphertext verification failed @@ -93,7 +93,7 @@ data files: .. code-block:: console - $ restic -r /tmp/backup check --read-data + $ restic -r /srv/restic-repo check --read-data load indexes check all packs check snapshots, trees and blobs @@ -107,9 +107,9 @@ commands check all repository data files over 5 separate invocations: .. code-block:: console - $ restic -r /tmp/backup check --read-data-subset=1/5 - $ restic -r /tmp/backup check --read-data-subset=2/5 - $ restic -r /tmp/backup check --read-data-subset=3/5 - $ restic -r /tmp/backup check --read-data-subset=4/5 - $ restic -r /tmp/backup check --read-data-subset=5/5 + $ restic -r /srv/restic-repo check --read-data-subset=1/5 + $ restic -r /srv/restic-repo check --read-data-subset=2/5 + $ restic -r /srv/restic-repo check --read-data-subset=3/5 + $ restic -r /srv/restic-repo check --read-data-subset=4/5 + $ restic -r /srv/restic-repo check --read-data-subset=5/5 diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 50c02c760..35e27e730 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -23,7 +23,7 @@ command to restore the contents of the latest snapshot to .. code-block:: console - $ restic -r /tmp/backup restore 79766175 --target /tmp/restore-work + $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work enter password for repository: restoring to /tmp/restore-work @@ -33,7 +33,7 @@ backup for a specific host, path or both. .. code-block:: console - $ restic -r /tmp/backup restore latest --target /tmp/restore-art --path "/home/art" --host luigi + $ restic -r /srv/restic-repo restore latest --target /tmp/restore-art --path "/home/art" --host luigi enter password for repository: restoring to /tmp/restore-art @@ -42,7 +42,7 @@ files in the snapshot. For example, to restore a single file: .. code-block:: console - $ restic -r /tmp/backup restore 79766175 --target /tmp/restore-work --include /work/foo + $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work --include /work/foo enter password for repository: restoring to /tmp/restore-work @@ -58,9 +58,9 @@ command to serve the repository with FUSE: .. code-block:: console $ mkdir /mnt/restic - $ restic -r /tmp/backup mount /mnt/restic + $ restic -r /srv/restic-repo mount /mnt/restic enter password for repository: - Now serving /tmp/backup at /mnt/restic + Now serving /srv/restic-repo at /mnt/restic Don't forget to umount after quitting! Mounting repositories via FUSE is not possible on OpenBSD, Solaris/illumos @@ -80,4 +80,4 @@ the data directly. This can be achieved by using the `dump` command, like this: .. code-block:: console - $ restic -r /tmp/backup dump latest production.sql | mysql + $ restic -r /srv/restic-repo dump latest production.sql | mysql diff --git a/doc/060_forget.rst b/doc/060_forget.rst index 2a3595952..ab5274758 100644 --- a/doc/060_forget.rst +++ b/doc/060_forget.rst @@ -35,7 +35,7 @@ repository like this: .. code-block:: console - $ restic -r /tmp/backup snapshots + $ restic -r /srv/restic-repo snapshots enter password for repository: ID Date Host Tags Directory ---------------------------------------------------------------------- @@ -50,7 +50,7 @@ command and specify the snapshot ID on the command line: .. code-block:: console - $ restic -r /tmp/backup forget bdbd3439 + $ restic -r /srv/restic-repo forget bdbd3439 enter password for repository: removed snapshot d3f01f63 @@ -58,7 +58,7 @@ Afterwards this snapshot is removed: .. code-block:: console - $ restic -r /tmp/backup snapshots + $ restic -r /srv/restic-repo snapshots enter password for repository: ID Date Host Tags Directory ---------------------------------------------------------------------- @@ -73,7 +73,7 @@ command must be run: .. code-block:: console - $ restic -r /tmp/backup prune + $ restic -r /srv/restic-repo prune enter password for repository: counting files in repo diff --git a/doc/070_encryption.rst b/doc/070_encryption.rst index c0889b852..a7b8716ac 100644 --- a/doc/070_encryption.rst +++ b/doc/070_encryption.rst @@ -16,8 +16,8 @@ Encryption *"The design might not be perfect, but it’s good. Encryption is a first-class feature, -the implementation looks sane and I guess the deduplication trade-off is worth it. So… I’m going to use restic for -my personal backups.*" `Filippo Valsorda`_ +the implementation looks sane and I guess the deduplication trade-off is worth +it. So… I’m going to use restic for my personal backups.*" `Filippo Valsorda`_ .. _Filippo Valsorda: https://blog.filippo.io/restic-cryptography/ @@ -31,19 +31,19 @@ per repository. In fact, you can use the ``list``, ``add``, ``remove``, and .. code-block:: console - $ restic -r /tmp/backup key list + $ restic -r /srv/restic-repo key list enter password for repository: ID User Host Created ---------------------------------------------------------------------- *eb78040b username kasimir 2015-08-12 13:29:57 - $ restic -r /tmp/backup key add + $ restic -r /srv/restic-repo key add enter password for repository: enter password for new key: enter password again: saved new key as - $ restic -r backup key list + $ restic -r /srv/restic-repo key list enter password for repository: ID User Host Created ---------------------------------------------------------------------- diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index c0a73d9b5..712a70244 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -26,10 +26,10 @@ times. The command ``snapshots`` may be used for this purpose: .. code-block:: console - $ restic -r /tmp/backup snapshots - Fatal: unable to open config file: Stat: stat /tmp/backup/config: no such file or directory + $ restic -r /srv/restic-repo snapshots + Fatal: unable to open config file: Stat: stat /srv/restic-repo/config: no such file or directory Is there a repository at the following location? - /tmp/backup + /srv/restic-repo If a repository does not exist, restic will return a non-zero exit code and print an error message. Note that restic will also return a non-zero diff --git a/doc/100_references.rst b/doc/100_references.rst index be22defa0..23ae2956e 100644 --- a/doc/100_references.rst +++ b/doc/100_references.rst @@ -625,14 +625,15 @@ are deleted, the particular snapshot vanished and all snapshots depending on data that has been added in the snapshot cannot be restored completely. Restic is not designed to detect this attack. +****** Local Cache -=========== +****** In order to speed up certain operations, restic manages a local cache of data. This document describes the data structures for the local cache with version 1. Versions --------- +======== The cache directory is selected according to the `XDG base dir specification `__. @@ -646,12 +647,21 @@ a lower version number is found the cache is recreated with the current version. If a higher version number is found the cache is ignored and left as is. -Snapshots and Indexes ---------------------- +Snapshots, Data and Indexes +=========================== Snapshot, Data and Index files are cached in the sub-directories ``snapshots``, ``data`` and ``index``, as read from the repository. +Expiry +====== + +Whenever a cache directory for a repo is used, that directory's modification +timestamp is updated to the current time. By looking at the modification +timestamps of the repo cache directories it is easy to decide which directories +are old and haven't been used in a long time. Those are probably stale and can +be removed. + ************ REST Backend @@ -798,24 +808,3 @@ Returns "200 OK" if the blob with the given name and type has been deleted from the repository, an HTTP error otherwise. -***** -Talks -***** - -The following talks will be or have been given about restic: - -- 2016-01-31: Lightning Talk at the Go Devroom at FOSDEM 2016, - Brussels, Belgium -- 2016-01-29: `restic - Backups mal - richtig `__: - Public lecture in German at `CCC Cologne - e.V. `__ in Cologne, Germany -- 2015-08-23: `A Solution to the Backup - Inconvenience `__: - Lecture at `FROSCON 2015 `__ in Bonn, Germany -- 2015-02-01: `Lightning Talk at FOSDEM - 2015 `__: A - short introduction (with slightly outdated command line) -- 2015-01-27: `Talk about restic at CCC - Aachen `__ - (in German) diff --git a/doc/110_talks.rst b/doc/110_talks.rst new file mode 100644 index 000000000..06952896f --- /dev/null +++ b/doc/110_talks.rst @@ -0,0 +1,34 @@ +.. + Normally, there are no heading levels assigned to certain characters as the structure is + determined from the succession of headings. However, this convention is used in Python’s + Style Guide for documenting which you may follow: + + # with overline, for parts + * for chapters + = for sections + - for subsections + ^ for subsubsections + " for paragraphs + + +##### +Talks +##### + +The following talks will be or have been given about restic: + +- 2016-01-31: Lightning Talk at the Go Devroom at FOSDEM 2016, + Brussels, Belgium +- 2016-01-29: `restic - Backups mal + richtig `__: + Public lecture in German at `CCC Cologne + e.V. `__ in Cologne, Germany +- 2015-08-23: `A Solution to the Backup + Inconvenience `__: + Lecture at `FROSCON 2015 `__ in Bonn, Germany +- 2015-02-01: `Lightning Talk at FOSDEM + 2015 `__: A + short introduction (with slightly outdated command line) +- 2015-01-27: `Talk about restic at CCC + Aachen `__ + (in German) diff --git a/doc/cache.rst b/doc/cache.rst deleted file mode 100644 index a39a1e76c..000000000 --- a/doc/cache.rst +++ /dev/null @@ -1,36 +0,0 @@ -Local Cache -=========== - -In order to speed up certain operations, restic manages a local cache of data. -This document describes the data structures for the local cache with version 1. - -Versions --------- - -The cache directory is selected according to the `XDG base dir specification -`__. -Each repository has its own cache sub-directory, consting of the repository ID -which is chosen at ``init``. All cache directories for different repos are -independent of each other. - -The cache dir for a repo contains a file named ``version``, which contains a -single ASCII integer line that stands for the current version of the cache. If -a lower version number is found the cache is recreated with the current -version. If a higher version number is found the cache is ignored and left as -is. - -Snapshots, Data and Indexes ---------------------------- - -Snapshot, Data and Index files are cached in the sub-directories ``snapshots``, -``data`` and ``index``, as read from the repository. - -Expiry ------- - -Whenever a cache directory for a repo is used, that directory's modification -timestamp is updated to the current time. By looking at the modification -timestamps of the repo cache directories it is easy to decide which directories -are old and haven't been used in a long time. Those are probably stale and can -be removed. - diff --git a/doc/conf.py b/doc/conf.py index 3f7c66158..3c0af927b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -35,7 +35,7 @@ master_doc = 'index' # General information about the project. project = 'restic' -copyright = '2017, restic authors' +copyright = '2018, restic authors' author = 'fd0' # The version info for the project you're documenting, acts as replacement for diff --git a/doc/index.rst b/doc/index.rst index a5f82e284..68f86c398 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -16,5 +16,6 @@ Restic Documentation 080_examples 090_participating 100_references + 110_talks faq manual_rest diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst index a53e34869..540a6d60a 100644 --- a/doc/manual_rest.rst +++ b/doc/manual_rest.rst @@ -19,6 +19,7 @@ Usage help is available: backup Create a new backup of files and/or directories cat Print internal objects to stdout check Check the repository for errors + diff Show differences between two snapshots dump Print a backed-up file to stdout find Find a file or directory forget Remove snapshots from the repository @@ -39,24 +40,24 @@ Usage help is available: version Print version information Flags: - --cacert stringSlice path to load root certificates from (default: use system certificates) - --cache-dir string set the cache directory - -h, --help help for restic - --json set output mode to JSON for commands that support it - --limit-download int limits downloads to a maximum rate in KiB/s. (default: unlimited) - --limit-upload int limits uploads to a maximum rate in KiB/s. (default: unlimited) - --no-cache do not use a local cache - --no-lock do not lock the repo, this allows some operations on read-only repos - -o, --option key=value set extended option (key=value, can be specified multiple times) - -p, --password-file string read the repository password from a file (default: $RESTIC_PASSWORD_FILE) - -q, --quiet do not output comprehensive progress report - -r, --repo string repository to backup to or restore from (default: $RESTIC_REPOSITORY) + --cacert stringSlice path to load root certificates from (default: use system certificates) + --cache-dir string set the cache directory + --cleanup-cache auto remove old cache directories + -h, --help help for restic + --json set output mode to JSON for commands that support it + --limit-download int limits downloads to a maximum rate in KiB/s. (default: unlimited) + --limit-upload int limits uploads to a maximum rate in KiB/s. (default: unlimited) + --no-cache do not use a local cache + --no-lock do not lock the repo, this allows some operations on read-only repos + -o, --option key=value set extended option (key=value, can be specified multiple times) + -p, --password-file string read the repository password from a file (default: $RESTIC_PASSWORD_FILE) + -q, --quiet do not output comprehensive progress report + -r, --repo string repository to backup to or restore from (default: $RESTIC_REPOSITORY) --tls-client-cert string path to a file containing PEM encoded TLS client certificate and private key - + -v, --verbose count[=-1] be verbose (can be specified multiple times) Use "restic [command] --help" for more information about a command. - Similar to programs such as ``git``, restic has a number of sub-commands. You can see these commands in the listing above. Each sub-command may have own command-line options, and there is a help @@ -87,21 +88,23 @@ command: --stdin-filename string file name to use when reading from stdin (default "stdin") --tag tag add a tag for the new snapshot (can be specified multiple times) --time string time of the backup (ex. '2012-11-01 22:08:41') (default: now) + --with-atime store the atime for all files and directories Global Flags: - --cacert stringSlice path to load root certificates from (default: use system certificates) - --cache-dir string set the cache directory - --json set output mode to JSON for commands that support it - --limit-download int limits downloads to a maximum rate in KiB/s. (default: unlimited) - --limit-upload int limits uploads to a maximum rate in KiB/s. (default: unlimited) - --no-cache do not use a local cache - --no-lock do not lock the repo, this allows some operations on read-only repos - -o, --option key=value set extended option (key=value, can be specified multiple times) - -p, --password-file string read the repository password from a file (default: $RESTIC_PASSWORD_FILE) - -q, --quiet do not output comprehensive progress report - -r, --repo string repository to backup to or restore from (default: $RESTIC_REPOSITORY) - --tls-client-cert string path to a TLS client certificate - --tls-client-key string path to a TLS client certificate key + --cacert stringSlice path to load root certificates from (default: use system certificates) + --cache-dir string set the cache directory + --cleanup-cache auto remove old cache directories + --json set output mode to JSON for commands that support it + --limit-download int limits downloads to a maximum rate in KiB/s. (default: unlimited) + --limit-upload int limits uploads to a maximum rate in KiB/s. (default: unlimited) + --no-cache do not use a local cache + --no-lock do not lock the repo, this allows some operations on read-only repos + -o, --option key=value set extended option (key=value, can be specified multiple times) + -p, --password-file string read the repository password from a file (default: $RESTIC_PASSWORD_FILE) + -q, --quiet do not output comprehensive progress report + -r, --repo string repository to backup to or restore from (default: $RESTIC_REPOSITORY) + --tls-client-cert string path to a file containing PEM encoded TLS client certificate and private key + -v, --verbose n[=-1] be verbose (specify --verbose multiple times or level n) Subcommand that support showing progress information such as ``backup``, ``check`` and ``prune`` will do so unless the quiet flag ``-q`` or @@ -128,7 +131,7 @@ command does that: .. code-block:: console - $ restic -r /tmp/backup tag --set NL --set CH 590c8fc8 + $ restic -r /srv/restic-repo tag --set NL --set CH 590c8fc8 create exclusive lock for repository modified tags on 1 snapshots @@ -141,19 +144,19 @@ So we can add and remove tags incrementally like this: .. code-block:: console - $ restic -r /tmp/backup tag --tag NL --remove CH + $ restic -r /srv/restic-repo tag --tag NL --remove CH create exclusive lock for repository modified tags on 1 snapshots - $ restic -r /tmp/backup tag --tag NL --add UK + $ restic -r /srv/restic-repo tag --tag NL --add UK create exclusive lock for repository modified tags on 1 snapshots - $ restic -r /tmp/backup tag --tag NL --remove NL + $ restic -r /srv/restic-repo tag --tag NL --remove NL create exclusive lock for repository modified tags on 1 snapshots - $ restic -r /tmp/backup tag --tag NL --add SOMETHING + $ restic -r /srv/restic-repo tag --tag NL --add SOMETHING no snapshots were modified Under the hood @@ -170,7 +173,7 @@ locks with the following command: .. code-block:: console - $ restic -r /tmp/backup list snapshots + $ restic -r /srv/restic-repo list snapshots d369ccc7d126594950bf74f0a348d5d98d9e99f3215082eb69bf02dc9b3e464c The ``find`` command searches for a given @@ -191,7 +194,7 @@ objects or their raw content. .. code-block:: console - $ restic -r /tmp/backup cat snapshot d369ccc7d126594950bf74f0a348d5d98d9e99f3215082eb69bf02dc9b3e464c + $ restic -r /srv/restic-repo cat snapshot d369ccc7d126594950bf74f0a348d5d98d9e99f3215082eb69bf02dc9b3e464c enter password for repository: { "time": "2015-08-12T12:52:44.091448856+02:00", @@ -242,7 +245,7 @@ lists all snapshots as JSON and uses ``jq`` to pretty-print the result: .. code-block:: console - $ restic -r /tmp/backup snapshots --json | jq . + $ restic -r /srv/restic-repo snapshots --json | jq . [ { "time": "2017-03-11T09:57:43.26630619+01:00", @@ -283,7 +286,7 @@ instead of the default, set the environment variable like this: .. code-block:: console $ export TMPDIR=/var/tmp/restic-tmp - $ restic -r /tmp/backup backup ~/work + $ restic -r /srv/restic-repo backup ~/work