fix(DETAILS): remove erroneous spaces

Closes github #11

README.md

@@ -1,4 +1,4 @@
-# Mailcow Backup Using borgbackup <!-- omit in toc -->
+# Mailcow Backup Using borgbackup
 
 This script automates backing up your Mailcow installation using borgbackup and a remote ssh-capable storage system.  I suggest using rsync.net since they
 have great speeds and a special pricing structure for borgbackup/attic users ([details here](https://www.rsync.net/products/attic.html)).
@@ -14,14 +14,19 @@ This script automates the following tasks:
 - Runs 'borg prune' to make sure you are trimming old backups on your schedule
 - Creates a clear, easy to parse log file so you can keep an eye on your backups and any errors/warnings
 
-## Contents <!-- omit in toc -->
+## contents
+
+<!-- toc -->
 
 - [quick start](#quick-start)
 - [configuration file](#configuration-file)
 - [running the script](#running-the-script)
 - [scheduling your backup via cron](#scheduling-your-backup-via-cron)
+- [restoring backups](#restoring-backups)
 - [final notes](#final-notes)
 
+<!-- tocstop -->
+
 ## quick start
 
 Clone this repo or download a release file into a directory of your choosing. For all examples in this document, I will assume you will run the script from */scripts/backup*. Make sure the script file is executable and you protect the *.details* file since it contains things like your repo password:
@@ -111,6 +116,10 @@ Edit your root user's crontab and add an entry like this which would run the scr
 7 1 * * * /scripts/backup/backup.sh -l /var/log/mailcow_backup.log > /dev/null 2>&1
 ```
 
+## restoring backups
+
+Starting with version 3.0, a *restore.sh* file has been included to semi-automate restoring your backups to a clean mailcow instance. There are a few steps required and they are better explained in the wiki than would be possible in a short write-up like this. Please check out the [restore process overview](https://git.asifbacchus.app/asif/MailcowBackup/wiki/8.0-Restore-overview) for more information.
+
 ## final notes
 
 I think that's everything. For detailed information, please review the [wiki](https://git.asifbacchus.app/asif/MailcowBackup/wiki/_pages). If I've forgotten to document something there, please let me know. I know the wiki is long but, I hate how much stuff for Linux and open-source programs/scripts in general are so poorly documented especially for newbies and I didn't want to make that same mistake.

backup/backup.details

@@ -20,6 +20,11 @@
 # default is "$HOME" or "~$USER" in that order.  If you're unsure, try "$HOME"
 borgBaseDir="/var/borgbackup"
 
+# SSH port on which your borg server listens. To connect on a custom port,
+# uncomment the line below and change the port number as required.
+# If you leave this line commented, the default (port 22) will be used.
+#borgSSHPort=22
+
 # full path to the SSH key used to connect to your remote backup server
 borgSSHKey="/var/borgbackup/private.key"
 
@@ -36,12 +41,13 @@ borgRepoPassphrase="p@ssW0rd"
 # FULL PATH where the associated keyfile for your repo is located -- relevant
 # only if your repo requires a keyfile (i.e. 'keyfile' vs 'repokey') and if you
 # are not using the default keyfile location
-borgKeyfileLocation="/var/borgbackup/.config/borg/keys/server_address__repo_name"
+#borgKeyfileLocation="/var/borgbackup/.config/borg/keys/server_address__repo_name"
 
-# REQUIRED: path to text file containing a list (one per line) of files/
+# additional files to backup
-# directories to include in your backup. Since this is a generic backup script,
+# by default, the script will only backup your mailcow program directory
-# nothing is defined by default. Therefore, ONLY files specified in this file
+# (e.g. /opt/mailcow-dockerized) and your mailcow data volumes. If you would
-# will be backed up!
+# like additional files included (perhaps certificates, system configuration,
+# etc.) include those locations listed one item per line in the file below
 # see repo wiki for more details
 borgXtraListPath="/scripts/backup/xtraLocations.borg"
 

backup/backup.sh

@@ -153,6 +153,10 @@ scriptHelp() {
     newline
     textblock "${magenta}--- script related parameters ---${norm}"
     newline
+    switchTextblock "-b | --borg"
+    textblock "FULL path to borg executable file if not in the default location."
+    defaultsTextblock "(/usr/bin/borg)"
+    newline
     switchTextblock "-c | --config | --details"
     textblock "Path to the configuration key/value-pair file for this script."
     defaultsTextblock "(scriptPath/scriptName.details)"
@@ -164,6 +168,14 @@ scriptHelp() {
     textblock "Path to write log file"
     defaultsTextblock "(scriptPath/scriptName.log)"
     newline
+    switchTextblock "[SWITCH] --nc | --no-color | --no-colour"
+    textblock "Do NOT use ANSI colourization in the log file (in case your preferred log viewer does not support it)."
+    defaultsTextblock "(use ANSI colourization to make log file look good)"
+    newline
+    switchTextblock "--compression"
+    textblock "Compression algorithm(s) that borg should use. Please run 'borg help compression' for details."
+    defaultsTextblock "(not specified, use borg default of lz4)"
+    newline
     switchTextblock "[SWITCH] -v | --verbose"
     textblock "Log borg output with increased verbosity (list all files). Careful! Your log file can get very large very quickly!"
     defaultsTextblock "(normal output, option is OFF)"
@@ -245,14 +257,16 @@ trapExit() {
 ## script related
 # store logfile in the same directory as this script file using the same file
 # name as the script but with the extension '.log'
-scriptPath="$( CDPATH='' cd -- "$( dirname -- "$0" )" && pwd -P )"
+scriptPath="$( CDPATH='' \cd -- "$( dirname -- "$0" )" && pwd -P )"
 scriptName="$( basename "$0" )"
 logFile="$scriptPath/${scriptName%.*}.log"
+colourizeLogFile=1
 warnCount=0
 configDetails="$scriptPath/${scriptName%.*}.details"
 err503Copied=0
 sqlDumpDirCreated=0
 exclusions=0
+borgPath="/usr/bin/borg"
 # borg output verbosity -- normal
 borgCreateParams='--stats'
 borgPruneParams='--list'
@@ -287,6 +301,19 @@ while [ $# -gt 0 ]; do
                 badParam empty "$@"
             fi
             ;;
+        --nc|--no-color|--no-colour)
+            # do NOT colourize log file
+            colourizeLogFile=0
+            ;;
+        -b|--borg)
+            # specify non-default borg path
+            if [ -n "$2" ]; then
+                borgPath="${2%/}"
+                shift
+            else
+                badParam empty "$@"
+            fi
+            ;;
         -c|--config|--details)
             # location of config details file
             if [ -n "$2" ]; then
@@ -300,6 +327,15 @@ while [ $# -gt 0 ]; do
                 badParam empty "$@"
             fi
             ;;
+        --compression)
+            # set borg archive compression
+            if [ -n "$2" ]; then
+                borgCompression="$2"
+                shift
+            else
+                badParam empty "$@"
+            fi
+            ;;
         -v|--verbose)
             # set verbose logging from borg
             borgCreateParams='--list --stats'
@@ -367,6 +403,7 @@ while [ $# -gt 0 ]; do
                 badParam empty "$@"
             else
                 dockerStartTimeout="$2"
+                shift
             fi
             ;;
         -t2|--timeout-stop)
@@ -374,6 +411,7 @@ while [ $# -gt 0 ]; do
                 badParam empty "$@"
             else
                 dockerStopTimeout="$2"
+                shift
             fi
             ;;
         *)
@@ -397,8 +435,8 @@ if [ ! -f "$configDetails" ]; then
     badParam dne "(--details default)" "$configDetails"
 fi
 # is borg installed?
-if ! command -v borg > /dev/null; then
+if ! find "$borgPath" -type f -executable > /dev/null 2>&1; then
-    printf "\n%sERROR: BORG is not installed on this system!%s\n\n" "$err" "$norm"
+    printf "\n%sERROR: BORG cannot be found in the specified or default location on this system!%s\n\n" "$err" "$norm"
     exit 3
 fi
 # if 503 functionality is enabled, do 503 related files exist?
@@ -417,7 +455,21 @@ fi
 if [ ! -f "$mcDockerCompose" ]; then
     badParam dne "(--docker-compose)" "$mcDockerCompose"
 fi
-
+# set compression level if specified
+if [ -n "$borgCompression" ]; then
+    borgCreateParams="${borgCreateParams} --compression ${borgCompression}"
+fi
+# remove colourization if parameter specified
+if [ "$colourizeLogFile" -eq 0 ]; then
+    bold=""
+    cyan=""
+    err=""
+    magenta=""
+    norm=""
+    ok=""
+    warn=""
+    yellow=""
+fi
 
 ### read mailcow.conf and set vars as needed
 # shellcheck source=./mailcow.conf.shellcheck
@@ -491,7 +543,16 @@ elif [ ! -f "${borgSSHKey}" ]; then
 fi
 printf "%sdetails:borgSSHKey %s-- %s[OK]%s\n" \
     "$magenta" "$norm" "$ok" "$norm" >> "$logFile"
-export BORG_RSH="ssh -i ${borgSSHKey}"
+## check SSH port
+if [ -z "${borgSSHPort}" ]; then
+    borgSSHPort=22
+    printf "%sdetails:borgSSHPort %s-- %s[DEFAULT]%s\n" \
+        "$magenta" "$norm" "$ok" "$norm" >> "$logFile"
+else
+    printf "%sdetails:borgSSHPort %s-- %s[CUSTOM]%s\n" \
+        "$magenta" "$norm" "$ok" "$norm" >> "$logFile"
+fi
+export BORG_RSH="ssh -i ${borgSSHKey} -p ${borgSSHPort}"
 
 ## check borg repo connect string
 if [ -z "${borgConnectRepo}" ]; then
@@ -532,7 +593,7 @@ fi
 ## export borg remote path, if specified
 if [ -n "${borgRemote}" ]; then export BORG_REMOTE_PATH="${borgRemote}"; fi
 
-## check if exlusion list file is specified
+## check if exclusion list file is specified
 if [ -n "${borgExcludeListPath}" ]; then
     # check if the file actually exists
     if [ ! -f "${borgExcludeListPath}" ]; then
@@ -600,7 +661,7 @@ if [ "$use503" -eq 1 ]; then
     printf "%s[%s] -- [INFO] Copying 503 error page to " \
         "$cyan" "$(stamp)" >> "$logFile"
     printf "webroot -- %s\n" "$norm">> "$logFile"
-    if ! cp --force "${err503Path}" "${webroot}/${err503File}" 2>> "$logFile"
+    if ! \cp --force "${err503Path}" "${webroot}/${err503File}" 2>> "$logFile"
         then
         printf "%s[%s] -- [WARNING] Failed to copy 503 error page. " \
             "$warn" "$(stamp)" >> "$logFile"
@@ -615,7 +676,7 @@ if [ "$use503" -eq 1 ]; then
 fi
 
 ### change to mailcow directory so docker commands execute properly
-cd "${mcConfig%/*}" || exitError 100 'Could not change to mailcow directory.'
+\cd "${mcConfig%/*}" || exitError 100 'Could not change to mailcow directory.'
 
 ### stop postfix and dovecot mail containers to prevent mailflow during backup
 doDocker stop postfix
@@ -642,7 +703,7 @@ docker-compose exec -T mysql-mailcow mysqldump --default-character-set=utf8mb4 \
 dumpResult=$( docker-compose exec -T mysql-mailcow echo "$?" )
 if [ "$dumpResult" -eq 0 ]; then
     printf "%s[%s] -- [INFO] SQL database dumped successfully --%s\n" \
-        "cyan" "$(stamp)" "$norm" >> "$logFile"
+        "$cyan" "$(stamp)" "$norm" >> "$logFile"
 else
     exitError 118 'There was an error dumping the mailcow SQL database.'
 fi
@@ -660,7 +721,7 @@ docker-compose exec -T redis-mailcow redis-cli save >> "$logFile" 2>&1
 rdumpResult=$( docker-compose exec -T redis-mailcow echo "$?" )
 if [ "$rdumpResult" -eq 0 ]; then
     printf "%s[%s] -- [INFO] mailcow redis dumped successfully --%s\n" \
-        "cyan" "$(stamp)" "$norm" >> "$logFile"
+        "$cyan" "$(stamp)" "$norm" >> "$logFile"
 else
     exitError 119 'There was an error dumping the mailcow redis database.'
 fi
@@ -672,7 +733,7 @@ printf "%s[%s] -- [INFO] Pre-backup tasks completed, calling borgbackup --%s\n"
 ## construct the proper borg commandline
 # base command
 if [ "$exclusions" -eq 0 ]; then
-    borgCMD="borg --show-rc create ${borgCreateParams} \
+    borgCMD="${borgPath} create --show-rc ${borgCreateParams} \
         ::$(date +%Y-%m-%d_%H%M%S) \
         ${mcConfig%/*} \
         ${sqlDumpDir} \
@@ -683,7 +744,7 @@ if [ "$exclusions" -eq 0 ]; then
         ${dockerVolumeCrypt} \
         ${xtraList}"
 elif [ "$exclusions" -eq 1 ]; then
-    borgCMD="borg --show-rc create ${borgCreateParams} \
+    borgCMD="${borgPath} create --show-rc ${borgCreateParams} \
         --exclude-from ${borgExcludeListPath} \
         ::$(date +%Y-%m-%d_%H%M%S) \
         ${mcConfig%/*} \
@@ -727,7 +788,7 @@ fi
 if [ -n "${borgPruneSettings}" ]; then
     printf "%s[%s] -- [INFO] Executing borg prune operation --%s\n" \
         "$cyan" "$(stamp)" "$norm" >> "$logFile"
-    borg prune --show-rc -v ${borgPruneParams} ${borgPruneSettings} \
+    "${borgPath}" prune --show-rc -v ${borgPruneParams} ${borgPruneSettings} \
         2>> "$logFile"
     borgPruneResult="$?"
 else

backup/restore.sh

@@ -57,7 +57,7 @@ doRestore() {
                 return 0
             fi
         else
-            if (! (cd "$sourceFiles/_data" && tar -cf - .) | (cd "${3}" && tar xvf -) ); then
+            if (! (cd "$sourceFiles/_data" && tar -cf - .) | (cd "${2}" && tar xvf -) > /dev/null 2>&1 ); then
                 return 1
             else
                 return 0
@@ -71,8 +71,50 @@ doRestore() {
 scriptHelp() {
     textNewline
     printf "%sUsage: %s [parameters]%s\n\n" "$bold" "$scriptName" "$norm"
+    textblock "The only required parameter is -b | --backup-location."
+    textblock "If a parameter is not supplied, its default value will be used."
+    textblock "Switch parameters will only be activated if specified."
+    textblockHeader "script parameters"
+    textblockParam "-b | --backup-location"
+    textblock "Directory containing extracted backup files from borg repo. REQUIRED."
     textNewline
-    textblock "If a parameter is not supplied, its default value will be used. Switch parameters will remain DEactivated if NOT specified."
+    textblockParam "-l | --log" "scriptPath/scriptName.log"
+    textblock "Path to write log file. Best efforts will be made to create any specified paths."
+    textNewline
+    textblockParam "-v | --verbose" "false"
+    textblock "Enable verbose logging. This will list EVERY restored file possibly making your log file quite large! [SWITCH]"
+    textNewline
+    textblockParam "--skip-mail" "false"
+    textblock "Skip restoring mail and encryption key. [SWITCH]"
+    textNewline
+    textblockParam "--skip-sql" "false"
+    textblock "Skip restoring mailcow settings database. [SWITCH]"
+    textNewline
+    textblockParam "--skip-postfix" "false"
+    textblock "Skip restoring postfix settings. [SWITCH]"
+    textNewline
+    textblockParam "--skip-rspamd" "false"
+    textblock "Skip restoring Rspamd settings/configuration/history. [SWITCH]"
+    textNewline
+    textblockParam "--skip-redis" "false"
+    textblock "Skip restoring redis database. [SWITCH]"
+    textNewline
+    textblockParam "-? | -h | --help"
+    textblock "Display this help screen."
+    textblockHeader "mailcow parameters"
+    textblockParam "-d | --docker-compose" "/opt/mailcow-dockerized/docker-compose.yml"
+    textblock "FULL path to mailcow's 'docker-compose.yml' file."
+    textNewline
+    textblockParam "-m | --mailcow-config" "/opt/mailcow-dockerized/mailcow.conf"
+    textblock "FULL path to mailcow configuration file ('mailcow.conf'). The path of this file is also used to determine your mailcow directory."
+    textblockHeader "docker parameters"
+    textblockParam "-t1 | --timeout-start" "180"
+    textblock "Seconds to wait for docker containers to start."
+    textNewline
+    textblockParam "-t2 | --timeout-stop" "120"
+    textblock "Seconds to wait for docker containers to stop."
+    textNewline
+    textblock "More details and examples of script usage can be found in the repo wiki at ${yellow}https://git.asifbacchus.app/asif/MailcowBackup/wiki${norm}"
     textNewline
     exit 0
 }
@@ -86,7 +128,7 @@ textblock() {
 }
 
 textblockHeader() {
-    printf "\n%s%s***%s***%s\n" "$bold" "$magenta" "$1" "$norm"
+    printf "\n%s%s*** %s ***%s\n\n" "$bold" "$magenta" "$1" "$norm"
 }
 
 textblockParam() {
@@ -458,7 +500,6 @@ if [ "$restorePostfix" -eq 1 ]; then
         writeLog 'task' "Restoring postfix files"
     fi
 
-    # restore email messages
     doRestore "${COMPOSE_PROJECT_NAME}_postfix-vol-1" "$dockerVolumePostfix"; ec="$?"
     case "$ec" in
         0)
@@ -495,7 +536,6 @@ if [ "$restoreRspamd" -eq 1 ]; then
         writeLog 'task' "Restoring Rspamd files"
     fi
 
-    # restore email messages
     doRestore "${COMPOSE_PROJECT_NAME}_rspamd-vol-1" "$dockerVolumeRspamd"; ec="$?"
     case "$ec" in
         0)
@@ -532,7 +572,6 @@ if [ "$restoreRedis" -eq 1 ]; then
         writeLog 'task' "Restoring redis database"
     fi
 
-    # restore email messages
     doRestore "${COMPOSE_PROJECT_NAME}_redis-vol-1" "$dockerVolumeRedis"; ec="$?"
     case "$ec" in
         0)

backup/xtraLocations.borg

@@ -49,12 +49,12 @@
 # include the paths to important configuration files/directories and/or
 # data directories
 
-# mailcow configuration (example)
+# mailcow configuration
-/opt/mailcow-dockerized/
+# already backed-up by the script by default based on mailcow.conf location
 
-# NGINX (example)
+# NGINX (if this host is a reverse proxy, for example)
 /etc/nginx/
 /usr/share/nginx/html/
 
-# LetsEncrypt (example)
+# LetsEncrypt
 /etc/letsencrypt/

etc/logwatch/scripts/services/backup

@@ -3,8 +3,8 @@
 #############################################################################
 # $Id$
 #############################################################################
-# Log: Backup script (backup)
+# Log: mailcow backup
-# Revision 1.0  2018/10/16
+# Revision 1.1  2019/07/20
 # Written by Asif Bacchus
 #############################################################################
 
@@ -34,7 +34,7 @@ if ($detailLevel == 0) {
         elsif ($ThisLine =~ /\-- \[WARNING\] /) {
             $summaryWarn++;
         }
-        elsif ($ThisLine =~ /All processes completed successfully/) {
+        elsif ($ThisLine =~ /All processes completed/) {
             $summarySuccess++;
         }
     }