It's possible to add custom code which is executed before and after the backup process via two script extensions. They are useful if modification of the backup script is required to extent the script capabilities and will be lost and thus have to be merged again and again every time when raspiBackup will be updated.
Three sample plugins are available and can be used as templates for new plugins. The first three report the CPU temperature, memory utilization and backup partition usage pre and post a backup run. The last one is called at the end of the backup and can be used to execute different actions depending on the success or failure of raspiBackup.
If you create your own plugin please share it with the community and announce it's availability in a comment. If there is any function missing for the plugin please write a comment and I'll check whether it's possible to provide the missing function.
All plugins have to follow a naming convention:
raspiBackup_<extensionName>_pre.sh and raspiBackup_<extensionName>_post.sh. The first one will be called before the backup starts and the second one afterwards. Both scripts don't have to exist. Configuration variable EXTENSIONS has to have <extensionName> to activate the extension. Starting with release 0.6.7 it's possible to add plugins for restore also.
Plugpoints in backup code sequence
The different plugins are called at following places:
BEFORE_STOPSERVICES (Defined commands are executed)
STOP_SERVICES (Defined commands are executed, option -o parameter)
... Backupcreation ...
START_SERVICES (Defined commands are executed, option -a parameter)
AFTER_STARTSERVICES (Defined commands are executed)
Cleanup work like deletion of obsolete backups (usually takes some time)
FINAL_COMMANDS (Starting with release 0.6.8) (Defined commands are executed)
Send eMail and notifications, final housekeeping
Plugpoints in restore code sequence
(Available starting with release 0.6.7)
The different plugins are called at following places:
...restore Backup ...
- The easiest way to install and activate the sample plugins is by using the installer and select menus Install components->Install and enable sample extensions or install them immediately in the command line (Use option -e)
- If you want to install the plugins manually download them with your browser or execute following command on your raspberry Pi to download the tar file and extract the contents to /usr/local/bin.
wget http://www.linux-tips-and-tricks.de/raspiBackup/raspiBackupSampleExtensions.tgz -O raspiBackupSampleExtensions.tgz
tar -xzf raspiBackupSampleExtensions.tgz -C /usr/local/bin
Following scripts will be copied into /usr/local/sbin:
1) raspiBackup_mem_pre.sh and raspiBackup_mem_post.sh - Reports the memory usage of the Raspberry before and after the backup run
2) raspiBackup_temp_pre.sh and raspiBackup_temp_post.sh - Reports the CPU temperature of the Raspberry before and after the backup run
3) raspiBackup_disk_pre.sh and raspiBackup_disk_post.sh - Reports the backup disk usage of the Raspberry before and after the backup run
4) raspiBackup_execute_post.sh - Execute some code when the backup finished. Actually no longer needed because options DEFAULT_BEFORE_STOPSERVICES and DEFAULT_AFTER_STARTSERVICES can be used for this.
To activate the plugins add following parameter to the raspiBackup call
-N "temp mem disk execute"
or add the following line to the config file
DEFAULT_EXTENSIONS="temp mem disk execute"
For details of the parameters and config file see this page.
Plugins will create following messages
--- RBK1001I: Memory usage - Pre backup - Used: 97 MB Free: 130 MB - Post backup - Used: 98 MB Free: 121 MB
--- RBK1000I: CPU temperature pre and post backup: 53.2'C - 55.8'C
--- RBK1002I: Disk usage pre backup: Used: 1.30 TiB Free: 2.18 TiB
--- RBK1003I: Disk usage post backup: Used: 1.30 TiB Free: 2.18 TiB
--- RBK1004I: Free change: -256.00 KiB (0.00 %)
All sample plugins use messages which start with number 1000 (for example RBK1000I). For custom plugin messages start message numbering with 2000 and don't use the number range below 1999.
Every plugin is passed the actual status of raspiBackup. Every statuscode not equal 0 received in a post plugin has to be handled as a backup failure.
Starting with version 0.6.1.1 there exists an emailPlugin which allows to write custom code which will send the eMail. That's very useful if the supported eMail clients of the script do not support the used eMailClient. In addition the format of the eMail can be customized. A sample emailPlugin which uses mailx is included in the sample plugin package.
The eMailExtension is used if mailext is used as parameter for -s. A script called raspiBackup_mail.sh will be called and has to handle the email creation and sending. Following parameters will be passed to the mailPlugin script:
email="$1" # target email address
subject="$2" # email subject
content="$3" # email contents
parms="$4" # addtl email parms passed with -E
append="$5" # file to append
If you create an eMailPlugin for a special eMailClient please write a comment at the bottom of this page. There may be other interested in the plugin also.
1) Warning: Extensions run as user root and coding errors can harm or even destroy the running Operating system !
2) It's not required to have both pre and post scripts implemented.
3) When testing the plugins the parameter -F is very useful. This flag disables the backup process and speeds up script execution.
4) The return code of the backup process is passed as parameter to the plugin script. 0 <=> OK, <>0 <=> failure
5) All plugins are executed in the scope of raspiBackup and thus it's possible to access internal variables of raspiBackup which makes the plugin heavy dependent on implementation details and the plugin may break to work in future releases. Also prefix the plugin variables with a plugin specific prefix in order to prevent nameing clashes with veriables used by raspiBackup.
6) If you want to share your plugin code just create a pull request on github where all the plugin source code is available for sharing and update.