From b5b52a30258e0e6c05c794f648a30b9847dad67e Mon Sep 17 00:00:00 2001 From: Asif Bacchus Date: Wed, 30 Jan 2019 09:58:41 -0700 Subject: [PATCH] updated readme to clarify ssh vs borg key passwd --- README.md | 115 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 84 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 5db2c4e..a80207a 100644 --- a/README.md +++ b/README.md @@ -25,36 +25,40 @@ This script automates the following tasks: - [Environment notes](#environment-notes) - [Why this script must be run as root](#why-this-script-must-be-run-as-root) - [Script parameters](#script-parameters) - - [Required parameters](#required-parameters) - - [NextCloud data directory: -d _/path/to/data/_](#nextcloud-data-directory--d-_pathtodata_) - - [NextCloud webroot: -n _/path/to/nextcloud/_](#nextcloud-webroot--n-_pathtonextcloud_) - - [webuser account: -w _accountName_](#webuser-account--w-_accountname_) - - [Optional parameters](#optional-parameters) - - [Path to 503 error page: -5 _/path/to/filename.html_](#path-to-503-error-page--5-_pathtofilenamehtml_) - - [Path to borg details file: -b _/path/to/filename.file_](#path-to-borg-details-file--b-_pathtofilenamefile_) - - [Desired log file location: -l _/path/to/filename.file_](#desired-log-file-location--l-_pathtofilenamefile_) - - [Path to SQL details file: -s _/path/to/filename.file_](#path-to-sql-details-file--s-_pathtofilenamefile_) - - [Verbose output from borg: -v (no arguments)](#verbose-output-from-borg--v-no-arguments) - - [Path to webroot: -w _/path/to/webroot/_](#path-to-webroot--w-_pathtowebroot_) + - [Required parameters](#required-parameters) + - [NextCloud data directory: -d _/path/to/data/_](#nextcloud-data-directory--d-pathtodata) + - [NextCloud webroot: -n _/path/to/nextcloud/_](#nextcloud-webroot--n-pathtonextcloud) + - [webuser account: -w _accountName_](#webuser-account--w-accountname) + - [Optional parameters](#optional-parameters) + - [Path to 503 error page: -5 _/path/to/filename.html_](#path-to-503-error-page--5-pathtofilenamehtml) + - [Path to borg details file: -b _/path/to/filename.file_](#path-to-borg-details-file--b-pathtofilenamefile) + - [Desired log file location: -l _/path/to/filename.file_](#desired-log-file-location--l-pathtofilenamefile) + - [Path to SQL details file: -s _/path/to/filename.file_](#path-to-sql-details-file--s-pathtofilenamefile) + - [Verbose output from borg: -v (no arguments)](#verbose-output-from-borg--v-no-arguments) + - [Path to webroot: -w _/path/to/webroot/_](#path-to-webroot--w-pathtowebroot) - [Borg details file](#borg-details-file) - - [Protect your borg details file](#protect-your-borg-details-file) - - [borg specific entries (lines 1-4)](#borg-specific-entries-lines-1-4) - - [additional files/directories to backup](#additional-filesdirectories-to-backup) - - [exclusion patterns](#exclusion-patterns) - - [prune timeframe options](#prune-timeframe-options) - - [borg remote location](#borg-remote-location) - - [Examples](#examples) + - [Protect your borg details file](#protect-your-borg-details-file) + - [borg specific entries (lines 1-4)](#borg-specific-entries-lines-1-4) + - [Line 1: Path to borg base directory](#line-1-path-to-borg-base-directory) + - [Line 2: Path to SSH key for remote server](#line-2-path-to-ssh-key-for-remote-server) + - [Line 3: Connection string to remote repo](#line-3-connection-string-to-remote-repo) + - [Line 4: Password for borg repo/repo key](#line-4-password-for-borg-reporepo-key) + - [additional files/directories to backup](#additional-filesdirectories-to-backup) + - [exclusion patterns](#exclusion-patterns) + - [prune timeframe options](#prune-timeframe-options) + - [borg remote location](#borg-remote-location) + - [Examples](#examples) - [SQL details file](#sql-details-file) - - [Protect your sql details file](#protect-your-sql-details-file) + - [Protect your sql details file](#protect-your-sql-details-file) - [503 functionality](#503-functionality) - - [Conditional forwarding by your webserver](#conditional-forwarding-by-your-webserver) - - [NGINX](#nginx) - - [Apache](#apache) - - [Disabling 503 functionality altogether](#disabling-503-functionality-altogether) + - [Conditional forwarding by your webserver](#conditional-forwarding-by-your-webserver) + - [NGINX](#nginx) + - [Apache](#apache) + - [Disabling 503 functionality altogether](#disabling-503-functionality-altogether) - [Scheduling: Cron](#scheduling-cron) - [The log file](#the-log-file) - - [Using Logwatch](#using-logwatch) - - [Remember to rotate your logs](#remember-to-rotate-your-logs) + - [Using Logwatch](#using-logwatch) + - [Remember to rotate your logs](#remember-to-rotate-your-logs) - [Final notes](#final-notes) ## Installation/copying @@ -201,9 +205,9 @@ example entries. The file must have the following information in the following order: 1. path to borg base directory **(required)** - 2. path to ssh private key for repo **(required)** + 2. path to ssh private key for remote server **(required)** 3. connection string to remote repo **(required)** - 4. password for ssh key/repo **(required)** + 4. password for borg repo/repo key **(required)** 5. path to file listing additional files/directories to backup 6. path to file containing borg-specific exclusion patterns 7. prune timeframe options @@ -226,10 +230,59 @@ chmod 600 nc_borg.details # restrict access to root only (read/write) If you need help with these options, then you should consult the borg documentation or search my blog at -[https://mytechiethoughts.com](https://mytechiethoughts.com) for borg. This is -especially true if you want to understand why an SSH key and passphrase are -preferred and why just a passphrase on it's own presents problems automating -borg backups. +[https://mytechiethoughts.com](https://mytechiethoughts.com) for borg. Here's a +very brief overview: + +#### Line 1: Path to borg base directory + +This is primary directory on your local system where your borg configuration is +located, **NOT* the path to your borg binary. The base directory contains the +borg configuration, cache, security files and keys. + +#### Line 2: Path to SSH key for remote server + +This is the SSH key used to connect to your remote (backup) server where your +borg repo is located. **This is NOT your borg repo key!** + +> Please note: If you are planning on executing this script via cron or some +> other form of automation, it is *highly recommended* that you use an SSH key +> **without** a password! SSH is designed such that passwords cannot simply be +> passed to it via environment variables, etc. so this is something not easily +> automated by a script such as this for security reasons. As such, your +> computer will sit and wait for you to enter the password and will NOT execute +> the actual backup portion of the script until the SSH key password is provided. +> +> If you really want/need to use an SSH key password, you will have to look into +> somethign like GNOME keyring or SSH-agent to provide a secure automated way to +> provide that password to SSH and allow this script to continue. +> +> In practice, SSH keys without passwords are still quite safe since the key +> must still be known in order to connect and most keys are quite long. In +> addition, they key only connects to the remote server, your actual information +> within the borg repository is still encrypted and secured with both a key and +> password. + +#### Line 3: Connection string to remote repo + +This is the full server and path required to connect to your borg repo on the +remote server. Very often it is the in the form of: + +``` +user@servername.tld:repo-name/ +``` + +for rsync.net it is in the following form: + +``` +username@server-number.rsync.net:repo-name/ +``` + +#### Line 4: Password for borg repo/repo key + +This is the password needed to access and decrypt your *borg repo*. Assuming +you set up your borg repo using recommended practices, this will actually be the +password for your *borg repo private key*. **This is NOT your SSH key +password!** ### additional files/directories to backup