From 7cbff6925fa8eef68114cf1febc6fe149bda7622 Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Thu, 14 May 2015 17:36:53 +0200
Subject: [PATCH] Documentation for 'attic serve'

Thanks to @lfam (attic PR #277 )!

Note: As I already had refactored a lot of these pathes you changed, it was easier
to just cherry pick the hunks with the other changes and apply them manually.
---
 docs/quickstart.rst  | 16 ++++++++++++----
 docs/update_usage.sh |  2 +-
 docs/usage.rst       | 12 ++++++++++++
 3 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index a6f131c8d..366f3aacb 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -138,17 +138,25 @@ 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::
 
-  $ borg init user@hostname:backup
+  $ borg init user@hostname:/mnt/backup
 
 or::
 
-  $ borg init ssh://user@hostname:port/backup
+  $ borg init ssh://user@hostname:port//mnt/backup
 
-If it is not possible to install |project_name| on the remote host, 
+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 /mnt/backup" 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::
 
-  $ sshfs user@hostname:/path/to/folder /mnt
+  $ sshfs user@hostname:/mnt /mnt
   $ borg init /mnt/backup
   $ fusermount -u /mnt
 
diff --git a/docs/update_usage.sh b/docs/update_usage.sh
index 3089d6297..9e79f4e88 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 borg $cmd | tr 'a-z- ' '-'`
   echo -e ".. _borg_$cmd:\n" > $FILENAME
diff --git a/docs/usage.rst b/docs/usage.rst
index 2f391b043..bc5c011b9 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -168,3 +168,15 @@ Examples
     Enter same passphrase again: 
     Key file "/home/USER/.borg/keys/mnt_backup" updated
 
+
+.. include:: usage/serve.rst.inc
+
+Examples
+~~~~~~~~
+::
+
+    # Allow an SSH keypair to only run attic, and only have access to /mnt/backup.
+    # This will help to secure an automated remote backup system.
+    $ cat ~/.ssh/authorized_keys
+    command="attic serve --restrict-to-path /mnt/backup" ssh-rsa AAAAB3[...]
+