From 639436ff10c8f140bf477c1a281db2438a7627bc Mon Sep 17 00:00:00 2001 From: Leo Famulari Date: Mon, 6 Apr 2015 19:54:32 -0400 Subject: [PATCH 1/3] Doc example of attic serve and SSH forced commands Here is an example of how to use attic serve's --restrict-to-path option to securely automate operations over SSH. It is for the Remote section of the quickstart guide. --- docs/quickstart.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index e02b5ca1..f1257cb8 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -144,6 +144,14 @@ or:: $ attic init ssh://user@hostname:port/repository.attic +Remote operations over SSH can be automated with SSH keys. You can restrict the +use of the SSH keypair by prepending a forced command to the SSH public key in +the remote server's authorized_keys file. Only the forced command will be run +when the key authenticates a connection. This example will start attic in server +mode, and limit the attic server to a specific filesystem path:: + + command="attic serve --restrict-to-path /repository.attic" ssh-rsa AAAAB3[...] + If it is not possible to install |project_name| on the remote host, it is still possible to use the remote host to store a repository by mounting the remote filesystem, for example, using sshfs:: From eb09dee343fbc4a1efb91f7830e7382016cc603c Mon Sep 17 00:00:00 2001 From: Leo Famulari Date: Tue, 7 Apr 2015 21:17:26 -0400 Subject: [PATCH 2/3] Usage documentation for attic serve This provides an example of how to use attic serve --restrict to path to restrict the use of an SSH keypair for automating remote backups. There is also a change to allow for automatic usage documentation of serve with sphinx. --- docs/update_usage.sh | 2 +- docs/usage.rst | 11 +++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/update_usage.sh b/docs/update_usage.sh index 69498dec..703867bb 100755 --- a/docs/update_usage.sh +++ b/docs/update_usage.sh @@ -2,7 +2,7 @@ if [ ! -d usage ]; then mkdir usage fi -for cmd in change-passphrase check create delete extract info init list mount prune; do +for cmd in change-passphrase check create delete extract info init list mount prune serve; do FILENAME="usage/$cmd.rst.inc" LINE=`echo -n attic $cmd | tr 'a-z- ' '-'` echo -e ".. _attic_$cmd:\n" > $FILENAME diff --git a/docs/usage.rst b/docs/usage.rst index d04b8e13..d5e52941 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -167,3 +167,14 @@ Examples New passphrase: Enter same passphrase again: Key file "/home/USER/.attic/keys/tmp_encrypted_repo" updated + +.. include:: usage/serve.rst.inc + +Examples +~~~~~~~~ +:: + + # Allow an SSH keypair to only run attic, and only have access to repo.attic + # This will help to secure an automated remote backup system. + $ cat ~/.ssh/authorized_keys + command="attic serve --restrict-to-path /path/to/repo.attic" ssh-rsa AAAAB3[...] From 25c39e4fb08963c0870ff5fe89779e3988753f04 Mon Sep 17 00:00:00 2001 From: Leo Famulari Date: Mon, 13 Apr 2015 12:12:35 -0400 Subject: [PATCH 3/3] Add some consistency to usage and quickstart guides Now, all the examples on each page will use the same repository name, respective to each page. --- docs/quickstart.rst | 8 ++++---- docs/usage.rst | 28 ++++++++++++++-------------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f1257cb8..c83d7020 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -74,7 +74,7 @@ The following example script backs up ``/home`` and of old archives:: #!/bin/sh - REPOSITORY=username@remoteserver.com:repository.attic + REPOSITORY=username@remoteserver.com:/somewhere/my-repository.attic # Backup all of /home and /var/www except a few # excluded directories @@ -138,11 +138,11 @@ Remote repositories host is accessible using SSH. This is fastest and easiest when |project_name| is installed on the remote host, in which case the following syntax is used:: - $ attic init user@hostname:repository.attic + $ attic init user@hostname:/somewhere/my-repository.attic or:: - $ attic init ssh://user@hostname:port/repository.attic + $ attic init ssh://user@hostname:port//somewhere/my-repository.attic Remote operations over SSH can be automated with SSH keys. You can restrict the use of the SSH keypair by prepending a forced command to the SSH public key in @@ -150,7 +150,7 @@ the remote server's authorized_keys file. Only the forced command will be run when the key authenticates a connection. This example will start attic in server mode, and limit the attic server to a specific filesystem path:: - command="attic serve --restrict-to-path /repository.attic" ssh-rsa AAAAB3[...] + command="attic serve --restrict-to-path /somewhere/my-repository.attic" ssh-rsa AAAAB3[...] If it is not possible to install |project_name| on the remote host, it is still possible to use the remote host to store a repository by diff --git a/docs/usage.rst b/docs/usage.rst index d5e52941..5f803b82 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -22,13 +22,13 @@ Examples :: # Local repository - $ attic init /data/mybackuprepo.attic + $ attic init /data/myrepo # Remote repository - $ attic init user@hostname:mybackuprepo.attic + $ attic init user@hostname:/data/myrepo # Encrypted remote repository - $ attic init --encryption=passphrase user@hostname:mybackuprepo.attic + $ attic init --encryption=passphrase user@hostname:/data/myrepo .. include:: usage/create.rst.inc @@ -38,17 +38,17 @@ Examples :: # Backup ~/Documents into an archive named "my-documents" - $ attic create /data/myrepo.attic::my-documents ~/Documents + $ attic create /data/myrepo::my-documents ~/Documents # Backup ~/Documents and ~/src but exclude pyc files - $ attic create /data/myrepo.attic::my-files \ + $ attic create /data/myrepo::my-files \ ~/Documents \ ~/src \ --exclude '*.pyc' # Backup the root filesystem into an archive named "root-YYYY-MM-DD" NAME="root-`date +%Y-%m-%d`" - $ attic create /data/myrepo.attic::$NAME / --do-not-cross-mountpoints + $ attic create /data/myrepo::$NAME / --do-not-cross-mountpoints .. include:: usage/extract.rst.inc @@ -154,19 +154,19 @@ Examples :: # Create a key file protected repository - $ attic init --encryption=keyfile /tmp/encrypted-repo - Initializing repository at "/tmp/encrypted-repo" + $ attic init --encryption=keyfile /data/myrepo + Initializing repository at "/data/myrepo" Enter passphrase (empty for no passphrase): Enter same passphrase again: - Key file "/home/USER/.attic/keys/tmp_encrypted_repo" created. + Key file "/home/USER/.attic/keys/data_myrepo" created. Keep this file safe. Your data will be inaccessible without it. # Change key file passphrase - $ attic change-passphrase /tmp/encrypted-repo - Enter passphrase for key file /home/USER/.attic/keys/tmp_encrypted_repo: + $ attic change-passphrase /data/myrepo + Enter passphrase for key file /home/USER/.attic/keys/data_myrepo: New passphrase: Enter same passphrase again: - Key file "/home/USER/.attic/keys/tmp_encrypted_repo" updated + Key file "/home/USER/.attic/keys/data_myrepo" updated .. include:: usage/serve.rst.inc @@ -174,7 +174,7 @@ Examples ~~~~~~~~ :: - # Allow an SSH keypair to only run attic, and only have access to repo.attic + # Allow an SSH keypair to only run attic, and only have access to /data/myrepo # This will help to secure an automated remote backup system. $ cat ~/.ssh/authorized_keys - command="attic serve --restrict-to-path /path/to/repo.attic" ssh-rsa AAAAB3[...] + command="attic serve --restrict-to-path /data/myrepo" ssh-rsa AAAAB3[...]