From 9b9179312d0c471746f8c0e21a0dbd5b5ddffe92 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 28 Oct 2016 03:32:37 +0200 Subject: [PATCH 1/5] ssh: repo url docs - fix typo --- docs/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f7105d6a7..d2e803f0d 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -249,7 +249,7 @@ is installed on the remote host, in which case the following syntax is used:: or:: - $ borg init ssh://user@hostname:port//path/to/repo + $ borg init ssh://user@hostname:port/path/to/repo 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 From ca15cc80e52a89dabdd7cf45b6ca609d039e7f3d Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 28 Oct 2016 04:36:38 +0200 Subject: [PATCH 2/5] document repo URLs / archive location --- docs/usage.rst | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/usage.rst b/docs/usage.rst index d9fcc3a22..e72f3cb0b 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -12,6 +12,76 @@ command in detail. General ------- +Repository URLs +~~~~~~~~~~~~~~~ + +**Local filesystem** (or locally mounted network filesystem): + +``/path/to/repo`` - filesystem path to repo directory, absolute path + +``path/to/repo`` - filesystem path to repo directory, relative path + +Also, stuff like ``~/path/to/repo`` or ``~other/path/to/repo`` works (this is +expanded by your shell). + + +**Remote repositories** accessed via ssh user@host: + +``user@host:/path/to/repo`` - remote repo, absolute path + +``ssh://user@host:port/path/to/repo`` - same, alternative syntax, port can be given + + +**Remote repositories with relative pathes** can be given using this syntax: + +``user@host:path/to/repo`` - path relative to current directory + +``user@host:~/path/to/repo`` - path relative to user's home directory + +``user@host:~other/path/to/repo`` - path relative to other's home directory + +Note: giving ``user@host:/./path/to/repo`` or ``user@host:/~/path/to/repo`` or +``user@host:/~other/path/to/repo``is also supported, but not required here. + + +**Remote repositories with relative pathes, alternative syntax with port**: + +``ssh://user@host:port/./path/to/repo`` - path relative to current directory + +``ssh://user@host:port/~/path/to/repo`` - path relative to user's home directory + +``ssh://user@host:port/~other/path/to/repo`` - path relative to other's home directory + + +If you frequently need the same repo URL, it is a good idea to set the +``BORG_REPO`` environment variable to set a default for the repo URL: + +:: + + export BORG_REPO='ssh://user@host:port/path/to/repo' + +Then just leave away the repo URL if only a repo URL is needed and you want +to use the default - it will be read from BORG_REPO then. + +Use ``::`` syntax to give the repo URL when syntax requires giving a positional +argument for the repo (e.g. ``borg mount :: /mnt``). + + +Repository / Archive Locations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Many commands want either a repository (just give the repo URL, see above) or +an archive location, which is a repo URL followed by ``::archive_name``. + +Archive names must not contain the ``/`` (slash) character. For simplicity, +maybe also avoid blanks or other characters that have special meaning on the +shell or in a filesystem (borg mount will use the archive name as directory +name). + +If you have set BORG_REPO (see above) and an archive location is needed, use +``::archive_name`` - the repo URL part is then read from BORG_REPO. + + Type of log output ~~~~~~~~~~~~~~~~~~ From e0298b293212a243c53486cb99f0c430225dc6d2 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 28 Oct 2016 04:51:46 +0200 Subject: [PATCH 3/5] simplify quickstart only give one possible ssh url syntax, all others are documented in usage chapter. --- docs/quickstart.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index d2e803f0d..75d14bca3 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -247,9 +247,7 @@ is installed on the remote host, in which case the following syntax is used:: $ borg init user@hostname:/path/to/repo -or:: - - $ borg init ssh://user@hostname:port/path/to/repo +Note: please see the usage chapter for a full documentation of repo URLs. 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 From 11e97803938a6766b298238790f81de4480840c2 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 28 Oct 2016 04:57:15 +0200 Subject: [PATCH 4/5] quickstart: add a comment about other (remote) filesystems --- docs/quickstart.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 75d14bca3..26387aecf 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -263,3 +263,7 @@ mounting the remote filesystem, for example, using sshfs:: $ sshfs user@hostname:/path/to /path/to $ borg init /path/to/repo $ fusermount -u /path/to + +You can also use other remote filesystems in a similar way. Just be careful, +not all filesystems out there are really stable and working good enough to +be acceptable for backup usage. From a16c7d8e16c472d05034d2c5350283f95d86db19 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 28 Oct 2016 05:04:23 +0200 Subject: [PATCH 5/5] mention file:// --- docs/usage.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/usage.rst b/docs/usage.rst index e72f3cb0b..8743f6ac0 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -24,6 +24,7 @@ Repository URLs Also, stuff like ``~/path/to/repo`` or ``~other/path/to/repo`` works (this is expanded by your shell). +Note: you may also prepend a ``file://`` to a filesystem path to get URL style. **Remote repositories** accessed via ssh user@host: