5.0-503-functionality.md

@@ -0,0 +1,61 @@
+# 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](https://git.asifbacchus.app/asif/MailcowBackup/wiki/3.0-Script-parameters#user-content-503-related-parameters) 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.
+
+```nginx
+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:
+
+```nginx
+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:
+
+```apache
+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!