Invocationsyntax and -options
raspiBackup has to be invoked as user root or with sudo. The invocation syntax is
raspiBackup.sh Option1 Option2 Option3 ... backupdirectory
raspiBackup Option1 Option2 Option3 ... backupdirectory
All default options can be overwritten in a configuration file /usr/local/etc/raspiBackup.conf. A sample configuration file which has the standard options defined can be downloaded here.
All options which turn something on or off can be controlled by a trailing + or -. Example: Option -z and option -z+ turn on the backupcompression. Option -z- turns off the backupcompression and ignores the definition DEFAULT_ZIP_BACKUP in the configuration file. That way it's possible to turn off options in the commandline even they are turned on in the configuration file.
In addition to /usr/local/etc/raspiBackup.conf other config files are read if they exist. The priority of the other config files is listed in following table:
| OptionPriority | Source |
| 1 | Invocation options |
| 2 | -f <configFile> |
| 3 | $(pwd)/.raspiBackup.conf |
| 4 | ~/.raspiBackup.conf |
| 5 | /usr/local/etc/raspiBackup.conf |
Options theme sorted
- Options, which configure the backup
- Options, which configure the messages and logs
- -m: Messagedetails
- -L: Location of the debug log and the execution messages
- -l: Enable debug mode
- -G: Message language (English or German)
- -A: Send the execution log in the notification email
- -v: Log all messages from backup tools used to create the backup
- --timestamps: Display a leading timestamp with any message
- Options, which configure the notification email
- Options, which update, restore and distribute raspiBackup
- Options, which start and stop services and run plugins before and after backup processing
- Miscellaneous options
Options alphabetical sorted
| Parameter | Function | Default | Option can be set in installer | Option in configuration file |
| -a |
Commands to start services stopped before the backup. Example "service xbmc start" (Attention: There are leading and trailing double quotes). This option is mandatory together with option -o. Multiple commands have to be separated by && . As an alternative use a wrapperscript (See below). The commands should have the inverse sequence as the commands used for the -o parameter. Example:
If there are no services to stop use a colon ":" as parameter. Note: All commands are executed as root. There is no sudo required. |
None | yes |
DEFAULT_STARTSERVICES |
| -b | Blocksize used in the dd command | 1MB | no |
DEFAULT_DD_BLOCKSIZE |
| -B |
Boot partition will be save with tar instead of dd Note: This option has no function if partition oriented mode is used and option -P is used or DEFAULT_PARTITIONBASED_BACKUP=1 is defined in the configuration file. |
No | no |
DEFAULT_TAR_BOOT_PARTITION_ENABLED |
| -C | The root partition as backup target is rejected because there may not be enough space on the root parition. This option disabled the test and a backup can be created on the root partition. ATTENTION: There is no check whether there is enough space for the backup. | No | no | DEFAULT_SKIPLOCALCHECK |
| --coloring | Starting with version 0.6.5 messages can be colorized. Possible parms C for console and/or M for eMail. See also option --eMailColoring if you use the postfix eMailClient. | CM | no |
DEFAULT_COLORING |
| -D | Addition invocation parameters for dd command (e.G.. "conv=notrunc,noerror,sync") | None | no |
DEFAULT_DD_PARMS |
|
--dynamic Mount |
Starting with version 0.6.6 the specified mount point or partition will be mounted during startup and umounted at the end. If it's already mounted it's not umounted at the end. The mount point has to be defined in /etc/fstab. The option argument can either be the mount point (e.g. /backup) or the backup partition name (e.g. /dev/sdb1). | None | no |
DEFAULT_DYNAMIC_MOUNT |
| -e |
email address which will get a notification eMail Attention: The notification eMail will be send by the root user. You have to configure your eMail client on your system that following command sends an eMail successfully echo "eMail-Text" | sudo mail -s "Subject" "Rec
With configurationoption DEFAULT_SENDER_EMAIL it's possible to change the default sender addess root@$(hostname) if required. |
None | yes |
DEFAULT_EMAIL |
| -E |
Optional additional parameters which are passed in the eMail call. For sendEmail use "-f sender.mail@senderdomain -s smtp-server:587 -xu username -xp password". Attention: The parameters for -E have to have a leading and trailing double quote ". It's useful to use parameter -F to speed up the test of the email notification function Attention: If option -l 1 is used the password will be logged in the log file. Masquerade the password before sending the log to somebody. |
None | no |
DEFAULT_EMAIL_PARMS |
|
Coloring |
Default is to use the subject header in eMails to control eMail coloring because that's the way used by most of the emailCients. If postfix is used then parameter OPTION has to be used because postfix uses a dedicated option to control email coloring. |
SUBJECT | no |
DEFAULT_EMAIL_COLORING |
| -f | Configuration file which is includes last. See here for all configuration files and their precedence. | No | no | |
| -F | Fake backup. This option is useful when raspiBackup is initially tested. The time consuming backup is not started but all the parameters are checked and an email is sent. | No | no | |
| -g | This option enables a progress bar during backup and restore. For a tar backup there is no progress bar available. | no | ||
| -G | Define language of messages. Possible messages are DE (German) and EN (English). Volunteers to translate the messages into another languages are welcome. Please contact me for details. |
System language If the system language is not supported EN (English) is used. |
yes |
DEFAULT_LANGUAGE |
| -h | Help | No | no | |
|
--ignore Additional Partitions |
Starting with version 0.6.5 raspiBackup allows to have more than two partitions on the SD card when tar or rsync backup is used. But only the first two partitions, /boot and / are saved and restored. Attention: All other paritions are not saved. | No | no |
DEFAULT_IGNORE_ADDITIONAL_PARTITIONS |
| -k |
Number of backups to keep for all backup types if not overridden by following option. If you use the default you keep 3 dd, 3 tar and 3 rsync backups. Note: This option is ignored when intelligent rotaion strategy is used. |
3 | yes |
DEFAULT_KEEPBACKUPS |
| --keep_<type> |
Starting with version 0.6.4.3: Number of backups to keep for the specific backup type. <type> can be any backup type, eg dd, ddz, tar, tgz or rsync Note: These options are ignored when intelligent rotaion strategy is used. |
Parameter for option -k | no |
DEFAULT_KEEPBACKUPS_{DD|DDZ|TAR|TGZ|RSYNC} |
| -l |
Log level defines whether a debug log will be created: - off -> No debug log - debug -> Create debug log Attention: Logfile may contain sensitive data in some situations (E.g. external static IP addresses, eMailAddresses, passwords for mount commands or eMail server ...). The debug logs are stored in the backup location. In case the backup fails and the backup directory will be cleaned up the debug log is saved in the home directory of the caller first. |
on | no |
DEFAULT_LOG_LEVEL |
| -L |
Defines the log target for raspiBackup.log varlog: Target is /var/log/raspiBackup.log backup: Log will be stored in created backup current: Use current directory <Fileprefix>: The debuglog will be created with extension .log and the messagefile with extension .msg. Example: /home/pi/raspiBackup. At the end /home/pi/raspiBackup.log and /home/pi/raspiBackup.msg will exist. The backupdirectory will not get any log files. |
backup | no |
DEFAULT_LOG_OUTPUT |
| -m |
- minimal -> Write important messages only - detailed -> Write a lot of messages to show the progress |
minimal | yes |
DEFAULT_MSG_LEVEL |
| -M |
This option allows to create raspiBackup snapshots which are not included in the backup recycle process. In addition the passed text is appended to the backup directory name. See also this page for details about snapshots. Note: raspiBackup snapshots are normal backups with special properties but no real snapshots like LVM or btrf snapshots Note: These backup directories are not included in the backup recycle process and have to be deleted manually. |
no | ||
| -n | Notify if there is a newer version of raspiBackup available | Yes | no |
DEFAULT_NOTIFY_UPDATE |
| -N | Activation of plugins to activate custom code. See this page for details which also offers three sample plugins which report the CPU temperature and the memory utilization before and after the backup run. | None | no |
DEFAULT_EXTENSIONS |
|
--notify Start |
Starting with version 0.6.5 it's possible to get an eMail or Telegram notification when raspiBackup starts. Default is to send an eMail or notification only when raspiBackup finishes. | No | no |
DEFAULT_NOTIFY_START |
| -o |
Commands to stop services before the backup. Example "service smb stop" (Attention: There are leading and trailing double quotes). This option is mandatory together with option -a. Multiple commands have to be separated by && . As an alternative use a wrapperscript (See below). The commands should have the inverse sequences as the commands used for the -a parameter Example:
If there are no services to stop use a colon ":" as parameter. Note: All commands are executed as root. There is no sudo required. |
None | yes |
DEFAULT_STOPSERVICES |
| -P | Enable partitionoriented mode which allows to save more than the first two partitions which are saved in the normal mode. Use parameter -T to define which partitions should be saved. | off | yes |
DEFAULT_PARTITIONBASED_BACKUP |
|
--reboot System |
Starting with release 0.6.7 this option initiates a reboot when the backup run finished. This way all services are restarted again. Arguments passed with option -a will be ignored because of this. Note: If option -F is used no reboot will be executed. |
off | no |
DEFAULT_REBOOT_SYSTEM |
| -s |
email program to use to sent the notification eMail {mail|sendEmail|ssmtp|msmtp}. Use mail also for postfix and nullmailer and install mailtools. For sendEmail use also parameter -E to pass mandatory parameters (See parameter -E description for details) Other eMailClients can be used via an eMailPlugin Then mailext has to passed as the parameter. See this page for details about the eMailPlugin. |
no |
DEFAULT_MAIL_PROGRAM |
|
| -S | An update with option -U is executed even the versions are identical. A local betaversion and a local normal version will be replaced with the latest code level. It's primarily used to update a local beta version to the latest code level. | off | no | |
|
--smart Recycle |
Starting with version 0.6.5 this option enables the intelligent rotationstrategy. For details see here. This also disables all --keep options and they don't have to be disabled by setting them to 0. | off | yes |
DEFAULT_SMART_RECYCLE |
|
--smart Recycle Dryrun |
Starting with version 0.6.5 this option enables or disables the test mode of the intelligent rotationstrategy on. For details see here. |
yes | no |
DEFAULT_SMART_RECYCLE_DRYRUN |
|
--smart Recycle Options |
Starting with version 0.6.5 this option defines the intelligent rotationstrategy parameters. For details see here. | "7 4 12 1" | yes |
DEFAULT_SMART_RECYCLE_OPTIONS |
|
--system status |
A list of running services and open files is reported in the debug logfile. | no | ||
| -t |
Backup type which can be dd, tar or rsync. rsync uses hardlinks if the backupfilesystem is an ext3/ext4 partition Attention: rsync should not be used with NTFS formatted Backuppartitions because cannot store the access rights of an ext3/4 filesystem correctly. Therefore the access rights cannot be restored correctly on an ext3/4 filesystem and the restored image is unusable. In addition hardlinks are supported only on ext3/4 filesystems in order to minimze disk space usage. See details of the backuptypes. An external root filesystem will be saved if tar or rsync backup is used and option -P is not selected. Parameter -z can be used in addition to zip the backups to reduce the backup size. Note: dd backup can be controlled by configuration parameter DEFAULT_DD_BACKUP_SAVE_USED_PARTITIONS_ONLY which saves backuptime and -space. For details of the parameter see bottom of table. |
dd | yes |
DEFAULT_BACKUPTYPE |
| -T |
If the partitionoriented backupmode is selected with option -P this parameter can be used to define which partitions should be saved. Example: -T "1 2 5" saves the first two partitions and the fifth partition. * saves all partitions. |
* until release 0.6.5.1 "1 2" starting with release 0.6.6 |
yes |
DEFAULT_PARTITIONS_TO_BACKUP |
|
--telegram --telegram ChatID --telegram Notifications |
Starting with version 0.6.5 Telegram notifications are supported. You have to configure the token and chatid. Notifications option can be S for success and/or F for failure. With "M" raspiBackup messages are attached in a file.. With "m" raspiBackup messages are sent too. Any of these options can be combined. Example: "SFM" or "Sm". Options "M" and "m" cannot be used together. |
No
|
no |
DEFAULT_TELEGRAM_TOKEN DEFAULT_TELEGRAM_CHATID |
| --timestamps | This option can be used to prefix all messages with a timestamp. | No | no |
DEFAULT_TIMESTAMPS |
| -u |
Attention: Parameters have to follow the syntax of the backuptool used. Otherwise the backup will fail. Example for rsync or tar: "--exclude=/backup/* --exclude=/rsnapshot/* --exclude=/www-data*/*"
Note the enclosing double quotes! Additional information about the syntax is available on the man pages of the backup tools used. Following directories are not saved:
Backuppath used in invocation, /proc/* , /lost+found/* , /sys/* , /dev/* , /tmp/*, /boot/*, /run/* , /proc/* , /lost+found/* , /sys/* , /dev/* , /tmp/* , /boot/* , /run/*In addition all mounted directories from external devices which are not mounted on / are not saved. It's only the boot parition /dev/mmcblk0p1 and the root partition /dev/mmcblk0p2 or the external root filesystem on /dev/sda1 which is saved.
Note for partitionoriented backup mode:
If option -P is used the directories mentioned above are exluded in all partition backups.
rsync:
*/directory/* - Excludes directory on all partitions
mmcblk0p2/verzeichnis/* - Excludes directory on partition mmcblk0p2
tar:
directory/* - Excludes directory on all partitions
|
None | no |
DEFAULT_EXCLUDE_LIST |
|
--unsupported Environment |
Starting with release 0.6.7 this option allows to start raspiBackup also on unsupported environments. For details read this article. | off | no | |
| -U |
Upgrades the current raspiBackup version with the latest available version. The previous one will be saved as raspiBackup.sh.n.m where n and m are the versionnumbers of raspiBackup. Attention: Read this page and understand which changes and new functions will become available before upgrading. See also option -S which forces an update with the latest version even the versions are identical. |
No | no | |
| --updateUUIDs | Starting with release 0.6.4.4: A restore will create partitions with the same UUIDs and PARTUUIDs of the original system. This option will create new UUIDs and PARTUUIDs on the restored partitions. | No | no |
DEFAULT_UPDATE_UUIDS |
| -v | Verbose mode of the backup tools tar and rsync. This option is useful during initial manual backup tests in order to see the backup progress. | No | no |
DEFAULT_VERBOSE |
| -V | Presents a list of existing previous version and allows to select one of the version to restore. The actual version will be saved and can be restored later on. See also parameter -U. (Available with Release 0.6) | No | no | |
| --version |
Display the version information of raspiBackup in following format: Version: 0.6.3.2 CommitSHA: 8fbcd1a CommitDate: 2018-02-19 CommitTime: 19:18:31 That way it's possible to query the current version information in a programmatic way. |
No | no | |
| -y | This option starts the deployment of the actual script to hosts which are defined in the configuration file. Access has to be possible without password and requires the keys to be copied into authorized_keys . That way you can quickly deploy a new script version on multiple hosts. | No | no |
DEFAULT_DEPLOYMENT_HOSTS |
| -z | Use gzip with dd or tar backup to reduce the backup size | No | yes |
DEFAULT_ZIP_BACKUP |
|
An eMail will be sent only in case of backup failure Note: If raspiBackup crashes because of unexpected reasons it may happen there is no eMail send even the backup failed. You use this option on your own risk. |
No | no |
DEFAULT_MAIL_ON_ERROR_ONLY |
|
|
Backupoptions used by rsync backup. You use this option on your own risk. |
--delete -aHAx | no |
DEFAULT_RSYNC_BACKUP_OPTIONS |
|
| Backupoptions used by tarbackup. You use this option on your own risk. | -cpi | no |
DEFAULT_TAR_BACKUP_OPTIONS |
|
|
Additional backupoptions used by rsync backup. You use this option on your own risk. |
no |
DEFAULT_RSYNC_BACKUP_ADDITIONAL_OPTIONS |
||
|
Additional backupoptions used by rsync backup. You use this option on your own risk. |
no |
DEFAULT_TAR_BACKUP_ADDITIONAL_OPTIONS |
||
| Bootpartition backups use hardlinks to minimze the backupspace because bootpartitions don't change often. Note: Ssupport of hardlinks on the backupspace required (ext3/ext4 filesystem) | No | no |
DEFAULT_LINK_ BOOTPARTITIONFILES |
|
|
dd backup only saves the space used by defined partitions. That way a backup of a 32 GB SD card with a 8GB partition only needs 8GB. The root partition in general uses the the whole SD card and has to be resized with gparted or resize2fs first appropriately. See also FAQ#16 |
No | no |
DEFAULT_DD_BACKUP_SAVE_USED_PARTITIONS_ONLY |
|
| This option is used to append the log to the eMail | -a | no |
DEFAULT_APPEND_LOG_OPTION |
|
| Define the sender eMail for ssmtp and msmtp. | root@$(hostname) | no |
DEFAULT_SENDER_EMAIL |
|
|
Backup restore test reminder Intervall (Unit: Months) |
6 | no |
DEFAULT_RESTORE_REMINDER_INTERVAL |
|
| Number of reminders to execute a backup restore test | 3 | no |
DEFAULT_RESTORE_REMINDER_REPEAT |
|
| Starting with version 0.6.4.3: Defined commands are executes before and after backup creation and before stopping and after starting system services (options -a and -o) | No | no |
DEFAULT_BEFORE_STOPSERVICES DEFAULT_AFTER_STARTSERVICES |
|
| Starting with version 0.6.7 you can define a pre and post exit which is executed when a backup is restored. The syntax is identical to the extsion format for backups. | Empty | no |
DEFAULT_RESTORE_EXTENSIONS |
|
| Starting with version 0.6.7 you can redefine the color codes used for emails and console. The first pair defines the colors for warnings and the second pair the colors for errors. The first element of the pair is the HTML color code The second element defined the VT100 color code. | ("#FF8000 33" "#FF0000 31") |
no |
DEFAULT_RESTORE_EXTENSIONS |
|
|
Starting with version 0.6.8 you can sent notifications to pushover. You have to register on https://pushover.net/ first and have to create an application. PUSHOVER_USER is the Pushover User Key. PUSHOVER_TOKEN is the API Token Key for you application. Notifications option can be S for success and/or F for failure. With "M" raspiBackup messages are attached in a file.. With "m" raspiBackup messages are sent too. Any of these options can be combined. Example: "SFM" or "S"F. Priorities are the Pushover priorities. Sounds are the Pushover sounds. |
no |
DEFAULT_PUSHOVER_TOKEN DEFAULT_PUSHOVER_USER DEFAULT_PUSHOVER_NOTIFICATIONS DEFAULT_PUSHOVER_SOUND_SUCCESS DEFAULT_PUSHOVER_SOUND_FAILURE DEFAULT_PUSHOVER_PRIORITY_SUCCESS DEFAULT_PUSHOVER_PRIORITY_FAILURE |
||
|
Starting with version 0.6.8 you can sent notifications to slack. Notifications option can be S for success and/or F for failure. With "M" raspiBackup messages are attached in a file.. With "m" raspiBackup messages are sent too. Any of these options can be combined. Example: "SFM" or "S"F. |
no | DEFAULT_SLACK_WEBHOOK_URL DEFAULT_SLACK_NOTIFICATIONS |
*** Note ***
Comments are welcome. But in order to reject spam posts please consider following rules: