asif/NextCloudBackup
1
0
Fork 0
Code Issues Pull Requests Releases 2 Activity

readme: proofreading and layout changes

Browse Source
This commit is contained in:
Asif Bacchus 2018-10-23 05:40:44 -06:00
parent 0718413d79
commit 2e0138cf8a
1 changed files with 38 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
README.md
View File

@ -10,7 +10,7 @@ This script automates the following tasks:
- Optionally copies a 503 error page to your webserver so users know when your - Optionally copies a 503 error page to your webserver so users know when your
server is unavailable due to backups being performed. The 503 file is removed server is unavailable due to backups being performed. The 503 file is removed
when the backup is completed so users can login again when the backup is completed so users can login again
- Dumps mySQL database and adds it to the backup - Dumps the NextCloud mySQL database and adds it to the backup
- Handles entering and exiting NextCloud's maintenance mode to 'lock' accounts - Handles entering and exiting NextCloud's maintenance mode to 'lock' accounts
so changes are not made during the backup process so changes are not made during the backup process
- Allows you to specify additional files you want backed up - Allows you to specify additional files you want backed up
@ -41,7 +41,7 @@ This script automates the following tasks:
- [borg specific entries (lines 1-4)](#borg-specific-entries-lines-1-4) - [borg specific entries (lines 1-4)](#borg-specific-entries-lines-1-4)
- [additional files/directories to backup](#additional-filesdirectories-to-backup) - [additional files/directories to backup](#additional-filesdirectories-to-backup)
- [exclusion patterns](#exclusion-patterns) - [exclusion patterns](#exclusion-patterns)
- [purge timeframe options](#purge-timeframe-options) - [prune timeframe options](#prune-timeframe-options)
- [borg remote location](#borg-remote-location) - [borg remote location](#borg-remote-location)
- [Examples](#examples) - [Examples](#examples)
- [SQL details file](#sql-details-file) - [SQL details file](#sql-details-file)
@ -71,19 +71,19 @@ Remember to make the script executable!
chmod +x backup.sh chmod +x backup.sh
``` ```
In addition, you can rename this script file to anything you like. The log file In addition, you can rename the script file to anything you like. The log file
will use that same name by default when naming itself and any mention of this will use that same name by default when naming itself and any mention of this
file in the logs will automatically use whatever name you choose to give it. file in the logs will automatically use whatever name you choose to give it.
## Environment notes ## Environment notes
The script is designed to be easy to use but still be flexible enough to The script is designed to be easy to use but still be flexible enough to
accommodate a wide range of NextCloud setups. I have tested it with accommodate a wide range of NextCloud setups. I have tested it with NextCloud
NextCloud 13 and 14 using a standard LEMP setup (Debian Stretch, NGINX, mariaDB 13 and 14 using a standard LEMP setup (Debian Stretch, NGINX, mariaDB & PHP7).
& PHP7). The script accepts several parameters to provide it with the settings The script accepts several parameters to provide it with the settings it
it requires to function. In addition, it reads external files for SQL and borg requires to function. In addition, it reads external plain-text files for SQL
settings so you don't have to weed through the script code to supply things and borg settings so you don't have to weed through the script code to supply
like passwords. things like passwords.
## Why this script must be run as root ## Why this script must be run as root
@ -99,7 +99,7 @@ You can run the script with the *'-?'* parameter to access the built-in help
which explains the parameters. However, the following is a more detailed which explains the parameters. However, the following is a more detailed
explanation of each parameter and how to use them. explanation of each parameter and how to use them.
**Note that any parameters needing a directory (webroot, nextcloud root, etc.) **Note that any parameters needing a directory (webroot, nextcloud root, etc.)
can be entered with or without the trailing / since it's stripped by the script can be entered with or without the trailing '/' since it's stripped by the script
anyways.** anyways.**
General usage: General usage:
@ -143,7 +143,8 @@ unavailable' while being backed up. A sample 503 page is included for you.
If you remove the default file or the one you specify is missing, a warning will If you remove the default file or the one you specify is missing, a warning will
be issued by the script but, it will continue executing. More details on the be issued by the script but, it will continue executing. More details on the
503 notification can be found later in the [503 functionality](#503-functionality) section of this 503 notification can be found later in the [503 functionality](#503-functionality) section of this
document. **Default: _scriptpath/503.html_** document.\
**Default: _scriptpath/503.html_**
#### Path to borg details file: -b _/path/to/filename.file_ #### Path to borg details file: -b _/path/to/filename.file_
@ -151,22 +152,22 @@ This is a text file that lays out various borg options such as repo name,
password, additional files to include, exclusion patters, etc. A sample file is password, additional files to include, exclusion patters, etc. A sample file is
included for your reference. More details, including the *required order* of included for your reference. More details, including the *required order* of
entries can be found later in this document in the [borg details file](#borg-details-file) entries can be found later in this document in the [borg details file](#borg-details-file)
section. section.\
**Default: _scriptpath/nc_borg.details_** **Default: _scriptpath/nc_borg.details_**
#### Desired log file location: -l _/path/to/filename.file_ #### Desired log file location: -l _/path/to/filename.file_
If you have a particular place and filename you'd like this script use for it's If you have a particular place and filename you'd like this script to use for
log, then you can specify it using this parameter. I would recommend it's log, then you can specify it using this parameter. I would recommend
*'/var/log/backup.log'*. By default, the script will name the log file *'/var/log/backup.log'*. By default, the script will name the log file
*scriptname*.log and will save it in the same directory as the script itself. *scriptname*.log and will save it in the same directory as the script itself.\
**Default: _scriptpath/scriptname.log_** **Default: _scriptpath/scriptname.log_**
#### Path to SQL details file: -s _/path/to/filename.file_ #### Path to SQL details file: -s _/path/to/filename.file_
This is a text file containing the details needed to connect to NextCloud's SQL This is a text file containing the details needed to connect to NextCloud's SQL
database. More information about the *required order* of entries can be found database. More information about the *required order* of entries can be found
later in this document in the [sql details file](#sql-details-file) section. later in this document in the [sql details file](#sql-details-file) section.\
**Default: _scriptpath/nc_sql.details_** **Default: _scriptpath/nc_sql.details_**
#### Verbose output from borg: -v (no arguments) #### Verbose output from borg: -v (no arguments)
@ -194,8 +195,8 @@ document.
## Borg details file ## Borg details file
This file contains all the data needed to access your borg remote data repo. This file contains all the data needed to access your borg remote data repo.
Each line must contain specific information in a specific order or needs to be Each line must contain specific information in a specific order or *needs to be
blank if that data is not required. The sample file includes this data and blank if that data is not required*. The sample file includes this data and
example entries. The file must have the following information in the following example entries. The file must have the following information in the following
order: order:
@ -205,7 +206,7 @@ order:
4. password for ssh key/repo **(required)** 4. password for ssh key/repo **(required)**
5. path to file listing additional files/directories to backup 5. path to file listing additional files/directories to backup
6. path to file containing borg-specific exclusion patterns 6. path to file containing borg-specific exclusion patterns
7. purge timeframe options 7. prune timeframe options
8. location of borg remote instance 8. location of borg remote instance
### Protect your borg details file ### Protect your borg details file
@ -259,15 +260,15 @@ what files you'd like borg to ignore during the backup. The sample file,
*'excludeLocations.borg'* contains a list of directories to exclude assuming a *'excludeLocations.borg'* contains a list of directories to exclude assuming a
standard NextCloud install -- the previews directory and the cache directory. standard NextCloud install -- the previews directory and the cache directory.
You need to run *'borg help patterns'* for help on how to specify any additional You need to run *'borg help patterns'* for help on how to specify any additional
exclusion patterns since the format is not your standard BASH format and only exclusion patterns since the format is not standard BASH format and only
sometimes uses standard regex. sometimes uses standard regex.
If you leave this line blank, the script will note it is not processing any If you leave this line blank, the script will note it is not processing any
exclusions and will proceed with backing up all files specified. exclusions and will proceed with backing up all files specified.
### purge timeframe options ### prune timeframe options
Here you can let borg purge know how you want to manage your backup history. Here you can let borg prune know how you want to manage your backup history.
Consult the borg documentation and then copy the relevant options directly into Consult the borg documentation and then copy the relevant options directly into
this line including any spaces, etc. The example file contains the following as this line including any spaces, etc. The example file contains the following as
a staring point: a staring point:
@ -284,8 +285,8 @@ backups and then an infinite amount of end-of-month backups.
If you're using rsync, then just have this say *'borg1'*. If you are using If you're using rsync, then just have this say *'borg1'*. If you are using
another provider, you'll have to reference their locally installed copy of borg another provider, you'll have to reference their locally installed copy of borg
relative to your repo path. You can also leave this blank if your provider does relative to your home directory. You can also leave this blank if your provider
not run borg locally but your backups/restores will be slower. does not run borg locally but your backups/restores will be slower.
### Examples ### Examples
@ -296,7 +297,7 @@ backups made in the last 14 days.
```Ini ```Ini
/var/borgbackup /var/borgbackup
/var/borgbackup/SSHprivate.key /var/borgbackup/SSHprivate.key
myuser@server001.rsync.net:NCBackup/ myuser@usw-s001.rsync.net:NCBackup/
myPaSsWoRd myPaSsWoRd
/root/NCscripts/xtraLocations.borg /root/NCscripts/xtraLocations.borg
/root/NCscripts/excludeLocations.borg /root/NCscripts/excludeLocations.borg
@ -310,7 +311,7 @@ end-of-week
```Ini ```Ini
/var/borgbackup /var/borgbackup
/root/keys/rsyncPrivate.key /root/keys/rsyncPrivate.key
myuser@server001.rsync.net:myBackup/ myuser@usw-s001.rsync.net:myBackup/
PaSsWoRd PaSsWoRd
/var/borgbackup/include.list /var/borgbackup/include.list
@ -401,7 +402,7 @@ server {
return 503; return 503;
} }
... ...
error_page 530 @backup error_page 503 @backup
location @backup { location @backup {
root /usr/share/nginx/html; root /usr/share/nginx/html;
rewrite ^(.*)$ /503.html break; rewrite ^(.*)$ /503.html break;
@ -410,11 +411,11 @@ server {
``` ```
This tells NGINX that if it finds the file *'503.html'* at the path This tells NGINX that if it finds the file *'503.html'* at the path
*'/usr/share/nginx/html'* (webroot) then return an error code 503. Next, *'/usr/share/nginx/html'* (webroot) then return an error code 503. When it
rewrite any url to *'domain.tld/503.html'* and thus, display the custom 503 encounters an error 503, rewrite any url to *'domain.tld/503.html'* and thus,
error page. On the other hand, if it can't find 503.html at the path specified display the custom 503 error page. On the other hand, if it can't find 503.html
(i.e. the script has deleted it because the backup is completed), then go about at the path specified (i.e. the script has deleted it because the backup is
business as usual. completed), then go about business as usual.
#### Apache #### Apache
@ -506,6 +507,11 @@ level as follows:
A detailed breakdown of the files and all options are included in a separate A detailed breakdown of the files and all options are included in a separate
readme in the *'/etc/logwatch'* folder of this git archive. readme in the *'/etc/logwatch'* folder of this git archive.
If you don't really care how it works, then you can just copy the
*/etc/logwatch* folder to the appropriate Logwatch configuration directory for
your system. The file directory layout in this git archive is already correct
for Debian/Ubuntu systems. You will have to update the log-group file to
reflect the path to your script's log file.
### Remember to rotate your logs ### Remember to rotate your logs
The log file generated by this script is fairly detailed so it can grow quite The log file generated by this script is fairly detailed so it can grow quite