Documentation for 'attic serve'

docs/quickstart.rst

@@ -74,7 +74,7 @@ The following example script backs up ``/home`` and
 of old archives::
 
     #!/bin/sh
-    [email protected]:repository.attic
+    [email protected]:/somewhere/my-repository.attic
 
     # Backup all of /home and /var/www except a few
     # excluded directories
@@ -138,11 +138,19 @@ 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
+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 /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

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

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,16 +154,27 @@ 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
+
+Examples
+~~~~~~~~
+::
+
+    # 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 /data/myrepo" ssh-rsa AAAAB3[...]