usercallbackplugin module

class usercallbackplugin.UserCallbackPlugin

Bases: Plugin

Executes a script file at different backup steps to customize behavior

Back In Time allows to inform plugins (implemented in Python files) about different steps (“events”) in the backup process via the pluginmanager.PluginManager.

This plugin calls a user-defined script file (“user-callback”). By default that file is located in the config folder $XDG_CONFIG_HOME/backintime/ or another folder if command line optioni –config is used.

The user-callback script is called with up to five positional arguments:

1. The profile ID from the config file (1=Main Profile, …)

2. The profile name (from the config file)

3. A numeric code to indicate the reason why Back In Time calls the script (see the method implementation for details about the numeric code)

4. Error code (only if argument 3 has the value “4”) or snapshot ID (only if argument 3 has the value “3”)

5. Snapshot name (only if argument 3 has the value “3”)

For more details and script examples see: https://github.com/bit-team/user-callback

Notes

The user-callback script file is normally implemented as shell script but could theoretically be implemented in any script language (declared via the hash bang “#!” in the first line of the script file.

appExit()

Called when the GUI of Back In Time is closed

Returns:

None (return value will be ignored anyhow)

appStart()

Called when the GUI of Back In Time was started.

Not called when only the CLI command was started without the GUI.

Returns:

None (return value will be ignored anyhow)

callback(*args, profileID=None)

error(code, message)

Indicates errors during the backup process

Called to send errors in the backup process (while taking a snapshot) to plugins.

Parameters:

• code –

  A Back In Time error code

  Known error codes:

  1: No or no valid configuration

  (check the configuration file)

  2: A backup process is already running.

  Make sure that automatic and manual backups do not run at once.

  3: Snapshots directory not found

  (eg. when a removable drive is not mounted)

  4: The requested snapshot for “now” already exists.

  message contains the SID (snapshot ID) then.

  5: Error while taking a snapshot.

  message contains more information (as string).

  6: New snapshot taken but with errors.

  message contains the SID (snapshot ID) then.

• message – The error message for the code (mostly an empty string by default)

Returns:

None (return value will be ignored anyhow)

init(snapshots)

mount(profileID=None)

Called when mounting a filesystem for the profile may be necessary.

Parameters:

profileID – Profile ID from the configuration

Returns:

None (return value will be ignored anyhow)

newSnapshot(snapshot_id, snapshot_path)

Called when the backup process has taken a new snapshot.

A new snapshot is only taken by the backup process if required (as configured).

Parameters:

• snapshot_id – The id of the new snapshot

• snapshot_path – The path to the new snapshot

Returns:

None (return value will be ignored anyhow)

processBegin()

Called before a backup process is started.

A new snapshot is only taken if required (as configured).

Returns:

None (return value will be ignored anyhow)

processEnd()

Called after a backup process has ended

Returns:

None (return value will be ignored anyhow)

unmount(profileID=None)

Called when unmounting a filesystem for a profile may be necessary

Parameters:

profileID – Profile ID from the configuration

Returns

None (return value will be ignored anyhow)