From 7de8bf6c271707b6a3563144ead8d42394ea4494 Mon Sep 17 00:00:00 2001 From: Alexander Neumann Date: Sun, 21 Feb 2016 12:56:25 +0100 Subject: [PATCH] Manual: Correct headings, add section about debug --- doc/Manual.md | 41 +++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/doc/Manual.md b/doc/Manual.md index f09bb6ea9..361a12de1 100644 --- a/doc/Manual.md +++ b/doc/Manual.md @@ -1,9 +1,7 @@ -# User Manual - Thanks for using restic. This document will give you an overview of the basic functionality provided by restic. -## Building restic +# Building/installing restic If you are using Mac OS X, you can install restic using the [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 -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 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 `RESTIC_PASSWORD`. -### Password prompt on Windows +## Password prompt on Windows At the moment, restic only supports the default Windows console interaction. 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 $ 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 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 files leading to a greater de-duplication. -## List all snapshots +# List all snapshots 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 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 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: restoring to /tmp/restore-work -## Manage repository keys +# Manage repository keys 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` @@ -205,7 +203,7 @@ sub-commands to manage these keys very precisely: 5c657874 username kasimir 2015-08-12 13:35:05 *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 even worse, attackers get privileged access and modify your backup with the @@ -228,7 +226,7 @@ the same error: Load indexes ciphertext verification failed -## Mount a repository +# Mount a repository 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 @@ -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 [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 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 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. @@ -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 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: