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.
Go to file
Asif Bacchus 1ac614ee60 refactor(license): update license
- update dates
- add contact email address
2022-07-12 11:36:28 -06:00
.idea/.idea.MailcowBackup.dir/.idea chore(ide): additional Rider config files 2022-07-12 11:35:58 -06:00
backup fix(DETAILS): remove erroneous spaces 2021-03-08 03:45:18 -07:00
etc feature(LOGWATCH): Update logwatch scripts 2021-02-15 15:31:05 -07:00
.gitattributes chore(git): update git control files 2022-07-12 11:35:20 -06:00
.gitignore chore(git): update git control files 2022-07-12 11:35:20 -06:00
LICENSE refactor(license): update license 2022-07-12 11:36:28 -06:00 update TOC 2021-02-10 08:30:13 -07:00

Mailcow Backup Using borgbackup

This script automates backing up your Mailcow installation using borgbackup and a remote ssh-capable storage system. I suggest using 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


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
# or clone from github
git clone

# 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
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:

./ --help

To run with defaults:


To run with a custom log file name and location:

./ --log /var/log/mailcow_backup.log

To copy a 503 error page to your webroot:

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

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

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

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

./ --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/ -l /var/log/mailcow_backup.log > /dev/null 2>&1

restoring backups

Starting with version 3.0, a 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 where I solve problems like this all the time on a shoe-string or zero budget. Thanks!