503 functionality

The script includes the option of copying an error page to be served to users while the backup is being performed. This is absolutely not necessary for the script to function, it's just a nice add-on to let users know your server is offline for a few minutes. To use this, you must run the script with the -5 or --use-503 parameter. By default, this functionality is disabled.

how it works

If enabled, the script will look for any file called 503_backup.html within the script directory and will copy that file to whatever is specified as your webroot (/usr/share/nginx/html by default). You can specify a different file to be copied by using the --503-path parameter followed by the full path to the file you want to be copied to your webroot. This file can be anything, so be careful! You can specify a different webroot by using the -w or --webroot parameter followed by the path to a directory with or without the trailing slash.

This script only copies a file to a destination. What happens after that is determined by your webserver set up. Upon completion of the script, whether successful or not, the script will attempt to delete the file it copied to the webroot destination. Please see page 3.0 for examples.

webserver setup

As mentioned before, the script merely copies a file and then removes it when the script is complete. Your webserver actually determines what's done with the file. In other words, your webserver should test for the existance of the file and then take action accordingly. In my personal setups, I often just copy a blank dummy file and then have my webserver display a fancy custom error page describing that a backup is happening. Whatever option you choose, the idea is the same.

nginx

On an NGINX server (either bundled with mailcow or on your host, depending on your setup), you can use a setup like this to check for your copied file and then display it as your 503 error page.

server {
    ...
    if (-f /usr/share/nginx/html/503_backup.html) {
        return 503;  # if the file is found, trigger a 503 error
    }
...
    # display a custom 503 error page (copied to webroot)
    error_page 503 @backup
    location @backup {
        root /usr/share/nginx/html;
        rewrite ^(.*)$ /503_backup.html break;
    }
}

In the above example, you can change the rewrite section to another file if you want that displayed instead. If you want to display whatever the default 503 error page is (or if you have already customized it somewhere else), then you can skip the location block entirely and you'd just use the first part to 'throw' the 503 error:

server {
    ...
    if (-f /usr/share/nginx/html/503_backup.html) {
        return 503;
    }
    ...
}

apache

I don't use Apache for anything since I'm way more comfortable with NGINX and find it easier to use. However, my best guess as to how you'd set up the previous example on Apache would be something like this:

RewriteEngine On
RewriteCond %{ENV:REDIRECT_STATUS} !=503
RewriteCond "/var/www/503_backup.html" -f
RewriteRule ^ - [R=503,L]
...
ErrorDocument 503 /503_backup.html
...

Anyone using this script and Apache, I'd be super grateful if you could test that and let me know if it actually works. I'll add your name to this documentation as a thank you!