User callback script¶
Introduction¶
During the backup process, Back In Time can call a user defined script can be
called in response to various events. This script is named user-callback.
By default, the path is $XDG_CONFIG_HOME/backintime/user-callback. It always
resides in the same location as the config file itself. Therefore, if the
--config option is used to define a config file in another location, Back
In Time will search in that location for the user-callback script.
The file needs to be executable. The filename cannot be modified. The content of the file can be edited via the GUI: Manage profiles > Options > Edit user-callback (see also Options tab in Manage profiles dialog).
Arguments and return value¶
The script can take three arguments. In case of error events, there will be a fourth argument with an error code and sometimes a fifth argument with additional information.
The return value of the script should be 0 if the backup should
continue. Return values other than 0 will stop the backup.
- The profile id (1=Main Profile, ...).
- Profile name.
- Callback reason:
| Value | Reason |
|---|---|
| 1 | A backup process is about to start. |
| 2 | A backup process has ended. |
| 3 | A new backup was created. The following two extra arguments are backup ID and backup path. |
| 4 | There was an error. See next table for error codes. |
| 5 | The (graphical) application has started. |
| 6 | The (graphical) application has closed. |
| 7 | Mounting a filesystem for the profile may be necessary. |
| 8 | Unmounting a filesystem for the profile may be necessary. |
Possible error codes (see Callback reason 4) as fourth argument are:
| Code | Error |
|---|---|
| 1 | Configuration is either missing or invalid. |
| 2 | A backup process is already running.1 |
| 3 | Can't find backups directory.2 |
| 4 | A backup for "now" already exists. The fifth argument is the backup ID. |
| 5 | Error while creating a backup.3 The fifth argument contains more error information. |
| 6 | New backup created but with errors.3 The fifth argument is the backup ID. |
Implementation¶
The UserCallbackPlugin is a class defined in
common/plugins/usercallbackplugin.py.
It is a child class of Plugin which you can be found in
common/pluginmanager.py.
Examples¶
Several example scripts can be found in the directory
/usr/share/doc/backintime or in the
projects repository.