3.0-Script-parameters.md

@@ -0,0 +1,104 @@
+## script parameters
+
+You can run the script with the *-?* or *--help* parameter to access the built-in help which explains all parameters and lists their default values. There are *no required parameters* since everything has a sensible default already set based on a standard mailcow installation. What follows is a more detailed breakdown of the parameters along with usage examples.
+
+> Any parameters requiring a directory (like webroot) can be supplied with or without a trailing slash. All parameters requiring a PATH actually require a FULL PATH including the filename!
+
+> You can use either the long or the short version of any parameter switch or any combination thereof. For example, `-l` is exactly the same as `--log`. In the same vein, mixing long and short forms would look like: `./backup.sh -c /user/jsmith/config.file --log /var/log/backup.log`.
+
+*general usage:*
+
+```bash
+/path/to/script/scriptname.sh -parameter argument -parameter argument ...
+```
+
+### script-related parameters
+
+- **-c | --config | --details**
+  - Full path to the configuration text-file for this script. By default, this is named *backup.details*. The script will look for any file with the same name as the script itself but with the extension *.details*. For example, if you re-named this script *mailcowbackup.sh*, it would look for a configuration file called *mailcowbackup.details* by default. If you break from this naming convention, or you store the configuration file in a directory different from the script location, you **must** supply it's location via this parameter.
+
+  ```bash
+  ./backup.sh --details /home/jsmith/mailcow_backup.params
+  ```
+
+- **-l | --log**
+  - Full path where you would like the script to save its log file. By default, the log file will be stored in the same directory as the script itself using the name of the script but with the extension *.log*. For example, if you re-name the script *mailcowbackup.sh*, the log file would be saved as *mailcowbackup.log* in the same directory as the script. If you want to specify an alternate location for the log (very common), then use this flag. For example, save a log file in */var/log*:
+
+  ```bash
+  ./backup.sh --log /var/log/mailcow_backup.log
+  ```
+
+- **-v | --verbose**
+  - This will instruct borgbackup to list *every* file it processes and output that to the log file. This is excellent for troubleshooting or for verifying an initial backup but should probably not be used routinely since it can make your log files get very big very quickly. This is a 'switch' parameter, it requires no additional arguments. Here's an example along with a custom log location:
+
+  ```bash
+  ./backup.sh --verbose -l /var/log/backup.log
+  ```
+
+- **-h | --help | -?**
+  - This will display the in-script help which is an abbreviated version of this page.
+
+  ```bash
+  ./backup.sh --help
+  ```
+
+### 503-related parameters
+
+- **-5 | --use-503**
+  - This tells the script you want it to copy a file to your webroot directory. This file can be anything and can be specified using the *--503-path* parameter. By default, the script will copy any file named *503_backup.html* found within the same directory as the script. This is a 'switch' parameter that enables the other 503 parameter options. If you are specifying other 503 parameters, this switch is **required**.
+
+- **--503-path**
+  - Full path to the file you want the script to copy to your webroot. This file can be anything, so be careful! While copying an HTML file is useful, sometimes you may be want to simply copy a 0-byte file for your webserver to find and then use its own internal error page. That's where this parameter can be very useful. You **must** supply the *-5* or *--use-503* option to activate this option.
+
+- **-w | --webroot**
+  - Full path to your webroot directory where you want the script to copy its default 503-error page or whatever you specified using the *--503-path* parameter. By default, this is set to the NGINX webroot at */usr/share/nginx/html/*. You may specify this parameter with or without the trailing slash.
+
+**examples:**
+
+Copy the included default 503 error page to the default NGINX webroot directory:
+
+```bash
+./backup.sh --use-503
+```
+
+Copy a custom HTML file to a custom webroot:
+
+```bash
+./backup.sh -5 --503-path /home/jsmith/my503page.html --webroot /var/www/errorpages/
+```
+
+Copy an indicator file to your webroot:
+
+```bash
+./backup -5 --503-path /scripts/resources/.backup-in-progress -w /var/www/
+```
+
+### mailcow-related parameters
+
+- **-d | --docker-compose**
+  - Full path to mailcow's docker-compose file. This option is **required** whenever you are not using the default location as per the mailcow installation documentation or if you use a customized docker-compose file in your environment for whatever reason. By default, this script assumes */opt/mailcow-dockerized/docker-compose.yml*.
+
+```bash
+./backup.sh --docker-compose /var/mailcow/mailcow.yml
+```
+
+- **-m | --mailcow-config**
+  - Full path to mailcow's configuration file (*mailcow.conf*). This option is **required** when the file is in a non-default location as per the mailcow installation documentation. By default, this script assumes */opt/mailcow-dockerized/mailcow.conf*.
+
+```bash
+./backup.sh --mailcow-config /var/mailcow/mailcow.conf
+```
+
+- **-t1 | --dockerStartTimeout**
+  - The script stops both the Postfix and Dovecot containers during backup operations to prevent new mail being sent/received. Before exiting, whether normally or not, the script will attempt to restart both containers so your mailcow is fully functional again. This is the amount of time the script will wait for containers to start up again before logging a warning and completing anyways. By default, this is set to 180 seconds (3 minutes). You can change this timeout to whatever you like, for example, let's say 60 seconds (1 minute):
+
+```bash
+./backup.sh --dockerStartTimeout 60
+```
+
+- **-t2 | --dockerStopTimeout**
+  - The script stops both the Postfix and Dovecot containers during backup operations to prevent new mail being sent/received. This is the amount of time the script will wait for that to happen before issuing a warning and continuing anyways. By default, this is set to 120 seconds (2 minutes). You can change this to whatever you like, for example, let's say 30 seconds:
+
+```bash
+./backup.sh --dockerStopTimeout 30
+```