octoleo/restic
2
2
Fork 0
mirror of https://github.com/octoleo/restic.git synced 2024-11-15 17:47:21 +00:00
Code Issues Releases Wiki Activity
da4193c3ef
restic/doc/045_working_with_repos.rst

172 lines
6.3 KiB
ReStructuredText
Raw Normal View History

doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
..
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
#########################
Working with repositories
#########################
Listing all snapshots
=====================
Now, you can list all the snapshots stored in the repository:
.. code-block:: console
Update docs
2018-04-28 14:19:16 +00:00
$ restic -r /srv/restic-repo snapshots
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
enter password for repository:
ID Date Host Tags Directory
----------------------------------------------------------------------
40dc1520 2015-05-08 21:38:30 kasimir /home/user/work
79766175 2015-05-08 21:40:19 kasimir /home/user/work
bdbd3439 2015-05-08 21:45:17 luigi /home/art
590c8fc8 2015-05-08 21:47:38 kazik /srv
9f0bc19e 2015-05-08 21:46:11 luigi /srv
You can filter the listing by directory path:
.. code-block:: console
Update docs
2018-04-28 14:19:16 +00:00
$ restic -r /srv/restic-repo snapshots --path="/srv"
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
enter password for repository:
ID Date Host Tags Directory
----------------------------------------------------------------------
590c8fc8 2015-05-08 21:47:38 kazik /srv
9f0bc19e 2015-05-08 21:46:11 luigi /srv
Or filter by host:
.. code-block:: console
Update docs
2018-04-28 14:19:16 +00:00
$ restic -r /srv/restic-repo snapshots --host luigi
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
enter password for repository:
ID Date Host Tags Directory
----------------------------------------------------------------------
bdbd3439 2015-05-08 21:45:17 luigi /home/art
9f0bc19e 2015-05-08 21:46:11 luigi /srv
Combining filters is also possible.
Add documentation for --group-by flag for snapshots command
2019-01-04 18:39:13 +00:00
Furthermore you can group the output by the same filters (host, paths, tags):
.. code-block:: console
$ restic -r /srv/restic-repo snapshots --group-by host
enter password for repository:
snapshots for (host [kasimir])
ID Date Host Tags Directory
----------------------------------------------------------------------
40dc1520 2015-05-08 21:38:30 kasimir /home/user/work
79766175 2015-05-08 21:40:19 kasimir /home/user/work
2 snapshots
snapshots for (host [luigi])
ID Date Host Tags Directory
----------------------------------------------------------------------
bdbd3439 2015-05-08 21:45:17 luigi /home/art
9f0bc19e 2015-05-08 21:46:11 luigi /srv
2 snapshots
snapshots for (host [kazik])
ID Date Host Tags Directory
----------------------------------------------------------------------
590c8fc8 2015-05-08 21:47:38 kazik /srv
1 snapshots
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
Checking integrity and consistency
==================================
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
Imagine your repository is saved on a server that has a faulty hard
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
drive, or even worse, attackers get privileged access and modify the
files in your repository with the intention to make you restore
malicious data:
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
.. code-block:: console
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
$ echo "boom" > /srv/restic-repo/index/de30f3231ca2e6a59af4aa84216dfe2ef7339c549dc11b09b84000997b139628
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
Trying to restore a snapshot which has been modified as shown above
will yield an error:
.. code-block:: console
$ restic -r /srv/restic-repo --no-cache restore c23e491f --target /tmp/restore-work
...
Fatal: unable to load index de30f323: load <index/de30f3231c>: invalid data returned
In order to detect these things before they become a problem, it's a
good idea to regularly use the ``check`` command to test whether your
repository is healthy and consistent, and that your precious backup
data is unharmed. There are two types of checks that can be performed:
- Structural consistency and integrity, e.g. snapshots, trees and pack files (default)
- Integrity of the actual data that you backed up (enabled with flags, see below)
To verify the structure of the repository, issue the ``check`` command.
If the repository is damaged like in the example above, ``check`` will
detect this and yield the same error as when you tried to restore:
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
.. code-block:: console
Update docs
2018-04-28 14:19:16 +00:00
$ restic -r /srv/restic-repo check
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
...
load indexes
error: error loading index de30f323: load <index/de30f3231c>: invalid data returned
Fatal: LoadIndex returned errors
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
If the repository structure is intact, restic will show that no errors were found:
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
.. code-block:: console
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
$ restic -r /src/restic-repo check
...
load indexes
check all packs
check snapshots, trees and blobs
no errors were found
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
Use "pack file" instead of "data file" (#2885) - changed variable names, especially changed DataFile into PackFile - changed in some comments - always use "pack file" in docu
2020-08-16 09:16:38 +00:00
By default, the ``check`` command does not verify that the actual pack files
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
on disk in the repository are unmodified, because doing so requires reading
Use "pack file" instead of "data file" (#2885) - changed variable names, especially changed DataFile into PackFile - changed in some comments - always use "pack file" in docu
2020-08-16 09:16:38 +00:00
a copy of every pack file in the repository. To tell restic to also verify the
integrity of the pack files in the repository, use the ``--read-data`` flag:
Add --read-data-subset flag to check command Signed-off-by: Igor Fedorenko <igor@ifedorenko.com>
2018-01-02 05:38:14 +00:00
.. code-block:: console
Update docs
2018-04-28 14:19:16 +00:00
$ restic -r /srv/restic-repo check --read-data
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
...
Add --read-data-subset flag to check command Signed-off-by: Igor Fedorenko <igor@ifedorenko.com>
2018-01-02 05:38:14 +00:00
load indexes
check all packs
check snapshots, trees and blobs
read all data
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
[0:00] 100.00% 3 / 3 items
duration: 0:00
no errors were found
Use "pack file" instead of "data file" (#2885) - changed variable names, especially changed DataFile into PackFile - changed in some comments - always use "pack file" in docu
2020-08-16 09:16:38 +00:00
.. note:: Since ``--read-data`` has to download all pack files in the
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
repository, beware that it might incur higher bandwidth costs than usual
and also that it takes more time than the default ``check``.
Add --read-data-subset flag to check command Signed-off-by: Igor Fedorenko <igor@ifedorenko.com>
2018-01-02 05:38:14 +00:00
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
Alternatively, use the ``--read-data-subset=n/t`` parameter to check only a
Use "pack file" instead of "data file" (#2885) - changed variable names, especially changed DataFile into PackFile - changed in some comments - always use "pack file" in docu
2020-08-16 09:16:38 +00:00
subset of the repository pack files at a time. The parameter takes two values,
``n`` and ``t``. When the check command runs, all pack files in the repository
doc: Improve check documentation Make it clearer what the difference is between regular check and check with --read-data.
2019-12-10 20:15:59 +00:00
are logically divided in ``t`` (roughly equal) groups, and only files that
belong to group number ``n`` are checked. For example, the following commands
Use "pack file" instead of "data file" (#2885) - changed variable names, especially changed DataFile into PackFile - changed in some comments - always use "pack file" in docu
2020-08-16 09:16:38 +00:00
check all repository pack files over 5 separate invocations:
Add --read-data-subset flag to check command Signed-off-by: Igor Fedorenko <igor@ifedorenko.com>
2018-01-02 05:38:14 +00:00
.. code-block:: console
Update docs
2018-04-28 14:19:16 +00:00
$ 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
Copy Permalink