forked from TrueCloudLab/restic
105 lines
4.9 KiB
ReStructuredText
105 lines
4.9 KiB
ReStructuredText
..
|
|
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
|
|
|
|
#########################
|
|
Troubleshooting
|
|
#########################
|
|
|
|
Being a backup software, the repository format ensures that the data saved in the repository
|
|
is verifiable and error-restistant. Restic even implements some self-healing functionalities.
|
|
|
|
However, situations might occur where your repository gets in an incorrect state and measurements
|
|
need to be done to get you out of this situation. These situations might be due to hardware failure,
|
|
accidentially removing files directly from the repository or bugs in the restic implementation.
|
|
|
|
This document is meant to give you some hints about how to recover from such situations.
|
|
|
|
1. Stay calm and don't over-react
|
|
********************************************
|
|
|
|
The most important thing if you find yourself in the situation of a damaged repository is to
|
|
stay calm and don't do anything you might regret later.
|
|
|
|
The following point should be always considered:
|
|
|
|
- Make a copy of you repository and try to recover from that copy. If you suspect a storage failure,
|
|
it may be even better, to make *two* copies: one to get all data out of the possibly failing storage
|
|
and another one to try the recovery process.
|
|
- Pause your regular operations on the repository or let them run on a copy. You will especially make
|
|
sure that no `forget` or `prune` is run as these command are supposed to remove data and may result
|
|
in data loss.
|
|
- Search if your issue is already known and solved. Good starting points are the restic forum and the
|
|
github issues.
|
|
- Get you some help if you are unsure what to do. Find a colleage or friend to discuss what should be done.
|
|
Also feel free to consult the restic forum.
|
|
- When using the commands below, make sure you read and understand the documentation. Some of the commands
|
|
may not be your every-day commands, so make sure you really understand what they are doing.
|
|
|
|
|
|
2. `check` is your friend
|
|
********************************************
|
|
|
|
Run `restic check` to find out what type of error you have. The results may be technical but can give you
|
|
a good hint what's really wrong.
|
|
|
|
Moreover, you can always run a `check` to ensure that your repair really was sucessful and your repository
|
|
is in a sane state again.
|
|
But make sure that your needed data is also still contained in your repository ;-)
|
|
|
|
Note that `check` also prints out warning in some cases. These warnings point out that the repo may be
|
|
optimized but is still in perfect shape and does not need any troubleshooting.
|
|
|
|
3. Index trouble -> `rebuild-index`
|
|
********************************************
|
|
|
|
A common problem with broken repostories is that the index does no longer correctly represent the contents
|
|
of your pack files. This is especially the case if some pack files got lost.
|
|
`rebuild-index` recovers this situation and ensures that the index exactly represents the pack files.
|
|
|
|
You might even need to manually remove corrupted pack files. In this case make sure, you run
|
|
`restic rebuild-index` after.
|
|
|
|
Also if you encounter problems with the index files itselves, `rebuild-index` will solve these problems
|
|
immediately.
|
|
|
|
However, rebuilding the index does not solve every problem, e.g. lost pack files.
|
|
|
|
4. Delete unneeded defect snapshots -> `forget`
|
|
********************************************
|
|
|
|
If you encounter defect snapshots but realize you can spare them, it is often a good idea to simply
|
|
delete them using `forget`. In case that your repository remains with just sane snapshots (including
|
|
all trees and files) the next `prune` run will put your repository in a sane state.
|
|
|
|
This can be also used if you manage to create new snapshots which can replace the defect ones, see
|
|
below.
|
|
|
|
5. No fear to `backup` again
|
|
********************************************
|
|
|
|
There are quite some self-healing mechanisms withing the `backup` command. So it is always a good idea to
|
|
backup again and check if this did heal your repository.
|
|
If you realize that a specific file is broken in your repository and you have this file, any run of
|
|
`backup` which includes that file will be able to heal the situation.
|
|
|
|
Note that `backup` relies on a correct index state, so make sure your index is fine or run `rebuild-index`
|
|
before running `backup`.
|
|
|
|
6. Unreferenced tree -> `recover`
|
|
********************************************
|
|
|
|
If for some reason you have unreferenced trees in your repository but you actually need them, run
|
|
`recover` it will generate a new snapshot which allows access to all trees that you have in your
|
|
repository.
|
|
|
|
Note that `recover` relies on a correct index state, so make sure your index is fine or run `rebuild-index`
|
|
before running `recover`.
|