octoleo/restic
2
2
Fork 0
mirror of https://github.com/octoleo/restic.git synced 2024-11-26 06:46:34 +00:00
Code Issues Releases Wiki Activity

Manual: Correct headings, add section about debug

Browse Source
This commit is contained in:
Alexander Neumann 2016-02-21 12:56:25 +01:00
parent 1c2992e2e5
commit 7de8bf6c27
1 changed files with 27 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/Manual.md
View File

@ -1,9 +1,7 @@
# User Manual
Thanks for using restic. This document will give you an overview of the basic Thanks for using restic. This document will give you an overview of the basic
functionality provided by restic. functionality provided by restic.
## Building restic # Building/installing restic
If you are using Mac OS X, you can install restic using the If you are using Mac OS X, you can install restic using the
[homebrew](http://brew.sh/) packet manager: [homebrew](http://brew.sh/) packet manager:
@ -81,7 +79,7 @@ them, e.g. for the `backup` command:
-f, --force Force re-reading the target. Overrides the "parent" flag -f, --force Force re-reading the target. Overrides the "parent" flag
-e, --exclude= Exclude a pattern (can be specified multiple times) -e, --exclude= Exclude a pattern (can be specified multiple times)
## Initialize a repository # Initialize a repository
First, we need to create a "repository". This is the place where your backups First, we need to create a "repository". This is the place where your backups
will be saved at. will be saved at.
@ -103,7 +101,7 @@ For automated backups, restic accepts the repository location in the
environment variable `RESTIC_REPOSITORY` and also the password in the variable environment variable `RESTIC_REPOSITORY` and also the password in the variable
`RESTIC_PASSWORD`. `RESTIC_PASSWORD`.
### Password prompt on Windows ## Password prompt on Windows
At the moment, restic only supports the default Windows console interaction. At the moment, restic only supports the default Windows console interaction.
If you use emulation environments like [MSYS2](https://msys2.github.io/) or If you use emulation environments like [MSYS2](https://msys2.github.io/) or
@ -118,7 +116,7 @@ you can install `winpty` as follows:
$ pacman -S winpty $ pacman -S winpty
$ winpty restic -r /tmp/backup init $ winpty restic -r /tmp/backup init
## Create a snapshot # Create a snapshot
Now we're ready to backup some data. The contents of a directory at a specific Now we're ready to backup some data. The contents of a directory at a specific
point in time is called a "snapshot" in restic. Run the following command and point in time is called a "snapshot" in restic. Run the following command and
@ -160,7 +158,7 @@ You can even backup individual files in the same repository.
In fact several hosts may use the same repository to backup directories and In fact several hosts may use the same repository to backup directories and
files leading to a greater de-duplication. files leading to a greater de-duplication.
## List all snapshots # List all snapshots
Now, you can list all the snapshots stored in the repository: Now, you can list all the snapshots stored in the repository:
@ -171,7 +169,7 @@ Now, you can list all the snapshots stored in the repository:
40dc1520 2015-05-08 21:38:30 kasimir /home/user/work 40dc1520 2015-05-08 21:38:30 kasimir /home/user/work
79766175 2015-05-08 21:40:19 kasimir /home/user/work 79766175 2015-05-08 21:40:19 kasimir /home/user/work
## Restore a snapshot # Restore a snapshot
Restoring a snapshot is as easy as it sounds, just use the following command to Restoring a snapshot is as easy as it sounds, just use the following command to
restore the contents of the latest snapshot to `/tmp/restore-work`: restore the contents of the latest snapshot to `/tmp/restore-work`:
@ -180,7 +178,7 @@ restore the contents of the latest snapshot to `/tmp/restore-work`:
enter password for repository: enter password for repository:
restoring <Snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST> to /tmp/restore-work restoring <Snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST> to /tmp/restore-work
## Manage repository keys # Manage repository keys
The `key` command allows you to set multiple access keys or passwords per The `key` command allows you to set multiple access keys or passwords per
repository. In fact, you can use the `list`, `add`, `remove` and `passwd` repository. In fact, you can use the `list`, `add`, `remove` and `passwd`
@ -205,7 +203,7 @@ sub-commands to manage these keys very precisely:
5c657874 username kasimir 2015-08-12 13:35:05 5c657874 username kasimir 2015-08-12 13:35:05
*eb78040b username kasimir 2015-08-12 13:29:57 *eb78040b username kasimir 2015-08-12 13:29:57
## Check integrity and consistency # Check integrity and consistency
Imagine your repository is saved on a server that has a faulty hard drive, or Imagine your repository is saved on a server that has a faulty hard drive, or
even worse, attackers get privileged access and modify your backup with the even worse, attackers get privileged access and modify your backup with the
@ -228,7 +226,7 @@ the same error:
Load indexes Load indexes
ciphertext verification failed ciphertext verification failed
## Mount a repository # Mount a repository
Browsing your backup as a regular file system is also very easy. First, create Browsing your backup as a regular file system is also very easy. First, create
a mount point such as `/mnt/restic` and then use the following command to serve a mount point such as `/mnt/restic` and then use the following command to serve
@ -245,7 +243,7 @@ Windows doesn't support FUSE directly. Projects like
yet, but we'd like to hear about your experience. For setup information see yet, but we'd like to hear about your experience. For setup information see
[dokan FUSE in dokan's wiki](https://github.com/dokan-dev/dokany/wiki/FUSE). [dokan FUSE in dokan's wiki](https://github.com/dokan-dev/dokany/wiki/FUSE).
## Create an SFTP repository # Create an SFTP repository
In order to backup data via SFTP, you must first set up a server with SSH and In order to backup data via SFTP, you must first set up a server with SSH and
let it know your public key. Passwordless login is really important since let it know your public key. Passwordless login is really important since
@ -268,7 +266,7 @@ a repository in the user's home directory on the server, use the location
`sftp://user@host/foo/bar/repo`. In this case the directory is relative to the `sftp://user@host/foo/bar/repo`. In this case the directory is relative to the
user's home directory: `foo/bar/repo`. user's home directory: `foo/bar/repo`.
## Create an Amazon S3 repository # Create an Amazon S3 repository
Restic can backup data to any Amazon S3 bucket. However, in this case, changing the URL scheme is not enough since Amazon uses special security credentials to sign HTTP requests. By consequence, you must first setup the following environment variables with the credentials you obtained while creating the bucket. Restic can backup data to any Amazon S3 bucket. However, in this case, changing the URL scheme is not enough since Amazon uses special security credentials to sign HTTP requests. By consequence, you must first setup the following environment variables with the credentials you obtained while creating the bucket.
@ -287,7 +285,22 @@ You can then easily initialize a repository that uses your Amazon S3 as a backen
For an S3-compatible repository without TLS available, use the alternative URI For an S3-compatible repository without TLS available, use the alternative URI
protocol `s3:http://server:port/bucket_name`. protocol `s3:http://server:port/bucket_name`.
## Under the hood: Browse repository objects # Debugging restic
The program can be built with debug support like this:
$ go run build.go -tags debug
Afterwards, extensive debug messages are written to the file in environment
variable `RESTIC_DEBUG`, e.g.:
$ RESTIC_DEBUG=/tmp/restic-debug.log restic backup ~/work
If you suspect that there is a bug, you can have a look at the debug log.
Please be aware that the debug log might contain sensitive information such as
file and directory names.
# Under the hood: Browse repository objects
Internally, a repository stores data of several different types described in the [design documentation](https://github.com/restic/restic/blob/master/doc/Design.md). You can `list` objects such as blobs, packs, index, snapshots, keys or locks with the following command: Internally, a repository stores data of several different types described in the [design documentation](https://github.com/restic/restic/blob/master/doc/Design.md). You can `list` objects such as blobs, packs, index, snapshots, keys or locks with the following command: