asifbacchus / mailcowbackup

Script to backup/restore Mailcow and the host system using borgbackup. Handles 503 error page generation, mailflow stop/restart, SQL database dump, borg backup and prune and integrates with Logwatch for easy monitoring.

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).

This script automates the following tasks:

• 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 when the backup is completed so users can login again
• Dumps the Mailcow mySQL database and adds it to the backup
• Handles stopping and re-starting mail-flow containers (postfix and dovecot) so everything is in a consistent state during the backup
• Allows you to specify additional files you want backed up
• Allows you to specify files/directories to exclude from your backups
• 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

• quick start
• configuration file
• running the script
• scheduling your backup via cron
• restoring backups
• final notes

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:

# run commands as root
sudo -s

# find somewhere to clone the repo
cd /usr/local/src

# clone the repo from my server (best choice)
git clone https://git.asifbacchus.app/asif/MailcowBackup.git
# or clone from github
git clone https://github.com/asifbacchus/MailcowBackup.git

# make a home for your backup script
mkdir -p /scripts/backup
cd /scripts/backup

# copy files from cloned repo to this new home
cp /usr/local/src/MailcowBackup/backup/* ./

# make script executable and protect your .details file
chmod +x backup.sh
chmod 600 backup.details

configuration file

You will need to let the script know how to access your remote repo along with any passwords/keyfiles needed to encrypt data. This is all handled via the plain-text 'configuration details' file. By default, this file is named backup.details. The file itself is fully commented so setting it up should not be difficult. If you need more information, consult page 4.0 in the wiki.

running the script

After setting up the .details file correctly and assuming you are running a default set up of mailcow according to the documentation, you just have to run the script and it will find everything on it's own. In particular, the defaults are set as follows:

• mailcow.conf is located at /opt/mailcow-dockerized/mailcow.conf
• docker-compose file is located at /opt/mailcow-dockerized/docker-compose.yml
• the log file will be saved in the same directory as the script with the same name as the script but with the extension .log

To get a list of all configuration options with defaults:

./backup.sh --help

To run with defaults:

./backup.sh

To run with a custom log file name and location:

./backup.sh --log /var/log/mailcow_backup.log

To copy a 503 error page to your webroot:

# assuming default NGINX webroot (/usr/share/nginx/html)
./backup.sh -5
# custom webroot
./backup.sh -5 -w /var/www/

Common usage: custom log file and copy 503 to custom webroot

./backup.sh -l /var/log/mailcow_backup.log -5 -w /var/www/

Non-default mailcow location (example: /var/mailcow):

./backup.sh --docker-compose /var/mailcow/docker-compose.yml --mailcow-config /var/mailcow/mailcow.conf

For more configuration options, see page 3.0 in the wiki and page 4.4 for some configuration examples. Consult section 7 of the wiki for information about the log file and how to integrate it with logwatch.

scheduling your backup via cron

Edit your root user's crontab and add an entry like this which would run the script using defaults at 1:07am daily:

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 for more information.

final notes

I think that's everything. For detailed information, please review the wiki. 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.

I don't script too often and I'm a horrible programmer, so if you see anything that can be/should be improved, please let me know by filing an issue or submit your changes via a pull request! I love learning new ways of doing things and getting feedback, so suggestions and comments are more than welcome.

If this has helped you out, then please visit my blog at https://mytechiethoughts.com where I solve problems like this all the time on a shoe-string or zero budget. Thanks!

mailcowbackup's Issues

Wrong formating in details file...

You made the follwing changes to the details file, but the script is complaining afterwards regarding the spaces!?
Otherwise thanks for the additons 👍

-borgSSHKey="/var/borgbackup/private.key"
+borgSSHKey = "/var/borgbackup/private.key"
-borgBaseDir="/var/borgbackup"
+borgBaseDir = "/var/borgbackup"
-borgConnectRepo="[email protected]:mailcow/"
+borgConnectRepo = "[email protected]:mailcow/"

/var/borgbackup/backup.sh: 19: /var/borgbackup/backup.details: borgSSHPort: not found
/var/borgbackup/backup.sh: 24: /var/borgbackup/backup.details: borgBaseDir: not found
/var/borgbackup/backup.sh: 33: /var/borgbackup/backup.details: borgConnectRep: not found

error with borg 1.0

Hello! I get this error:

[2021-02-09 23:35:05] -- [INFO] Executing borg backup operation --
usage: borg [-h] [-V] <command> ...
borg: error: unrecognized arguments: --show-rc
[2021-02-09 23:35:06] -- [ERROR] 138: Borg exited with a critical error. Please review this log file for details. --

I think its because I'm using borg 1.0
changing the order of arguments in borgCMD seems to work:

diff --git a/backup/backup.sh b/backup/backup.sh
index 1ec685a..2c3c27b 100755
--- a/backup/backup.sh
+++ b/backup/backup.sh
@@ -672,7 +672,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="borg create --show-rc ${borgCreateParams} \
         ::$(date +%Y-%m-%d_%H%M%S) \
         ${mcConfig%/*} \
         ${sqlDumpDir} \
@@ -683,7 +683,7 @@ if [ "$exclusions" -eq 0 ]; then
         ${dockerVolumeCrypt} \
         ${xtraList}"
 elif [ "$exclusions" -eq 1 ]; then
-    borgCMD="borg --show-rc create ${borgCreateParams} \
+    borgCMD="borg create --show-rc ${borgCreateParams} \
         --exclude-from ${borgExcludeListPath} \
         ::$(date +%Y-%m-%d_%H%M%S) \
         ${mcConfig%/*} \

How to backup to local folder

Hi,

I can't access my backup space using ssh. Therefore, I plan to backup to a local folder and use ftps to mirror this folder to my backup space.

How can I configure a backup to a local folder?

Thanks,

Martin

Feature ideas and / or requests - Colours in log and SSH port config

Hey,

just finished my mailserver and was looking for a backup solution. Found your script and I'm happy with it.

Two things tho, maybe you can make the use of colour in the logfile optional? It would make parsing and looking at it with different tools more easily. (I just removed the command -v tput...)

Also, my remote server is not listening to the default ssh port 22 due to secrity reasons, so I modified line 512 to use a different port.

export BORG_RSH="ssh -p 0815 -i ${borgSSHKey}"

Would be nice to have this as a configuration option also

Otherwise thanks for your script.

Cronjob failing due to missing PATH

Sorry, me again. Just checked today if my cronjob was running last night and found ou it did not.
Little debugging later the cronjob throws a ERROR: BORG is not installed on this system!

Any idea how that could be? borg is installed as binary in /usr/local/bin and executed fine manually.
The if ! command -v borg statement looks fine for me, must have to do something with the context in which crontab jobs are started!?

Edit: Looks like my crontab env is different and is missing the PATH. I just added the PATH variable to the crontab file maybe as a feature request to minimize this issue for other, specify a location for borg in the details file?

[Suggestion] add version of script in help

Hi ,
It would be nice to have a way to know the actual version of the script ;)
I did not found it, so I am not sure if it is already somewhere.

Thanks for you contribution on that backup script.

Ben

same issue as in #13

Hey

I just found out my backup stopped working too with the same issue as in #13
Can't figure out why. Maybe a syntax change in docker itself with the new compose v2?

Usage: docker inspect [OPTIONS] NAME|ID [NAME|ID...]

Return low-level information on Docker objects
"docker inspect" requires at least 1 argument.
See 'docker inspect --help'.

Any idea on this one? Didn't change anything besides upgrading to compose v2 as suggested and don't use btrfs

What means "Line 1: Path to borg base directory"

I've tried to setup MailcowBackup for several times now, but I'm not sure how to set it up properly.
Maybe here is some additional documentation necessary?

My Backups are always failing with the following message:
[ERROR] Invalid or non-existant borg base directory specified (borg backup details file) (code: 210)

Im running Ubuntu 18.04 LTS with borgbackup from the offical Ubuntu repository.

Multiple mailcow.conf

The script bugs out trying to find the mailcow.conf since I had an apache site conf called mailcow.conf. I couldn't override the path either explicitly with an argument either. Something to look in to. I just renamed the site, but may be good for others

howto restore from a backup

Hi,

Really awesome project and I finally manage to get everything up and running with a remote borg server.

Now I'm just wondering how to restore in a proper way – don’t seem to find anything in the wiki about that part, maybe you could perhaps share some guidance for that?

Thanks.....

Reports can't start Dovecot/Postfix

Hi the script seem to be reporting it couldn't start Dovecot and Postfix when it dose manage to start it.

Got this from logs

[ERROR] Could not start Postfix container. Please check docker logs (code: 103)
[ERROR] Could not start Dovecot container. Please check docker logs (code: 104)
docker inspect" requires at least 1 argument.

Wiki is down?

Hey

For some reason I can't access any of the links to your wiki? Is there some issue with your server or is there another instance of your wiki that I could check out.

Thanks for building such a rad tool!

backup script not working with docker compose v2

Hi,

the script is not working anymore with docker compose v2 (latest mailcow and docker update)

error is:

Return low-level information on Docker objects
"docker inspect" requires at least 1 argument.
See 'docker inspect --help'.