Skip to content

User callback script

Introduction

During the backup process, Back In Time can call a user defined script at different steps. This script is named user-callback and contained in the directory $XDG_CONFIG_HOME/backintime. By default $XDG_CONFIG_HOME is ~/.config). It can also be configured via the GUI: Manage profiles > Options > Edit user-callback (see also Options tab in Manage profiles dialog).

Script arguments

  1. The profile id (1=Main Profile, ...).
  2. Profile name.
  3. Callback reason:
Value Reason
1 A backup process is about to start.
2 A backup process has ended.
3 A new snapshot was taken. The following two extra arguments are snapshot ID and snapshot 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) are:

Code Error
1 Configuration is either missing or invalid.
2 A backup process is already running.1
3 Can't find snapshots folder.2
4 A snapshot for "now" already exists. The fifth argument is the snapshot ID.
5 Error while taking a snapshot.3 The fifth argument contains more error information.
6 New snapshot taken but with errors.3 The fifth argument is the snapshot ID.

Return value

The script should return 0 if the backup should continue, any value other than 0 will cancel the backup.

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.

The following is a minimal script to log all calls to user-callback to a file in $HOME/.local/state/backintime_callback_log.

#!/bin/bash
# SPDX-FileCopyrightText: © 2024 Kosta Vukicevic
# SPDX-FileCopyrightText: © 2024 @daveTheOldCoder
# SPDX-License-Identifier: CC0-1.0

LOG_FILE='/tmp/backintime_callback.log'

# Get current time
current_time=$(date +"%Y-%m-%d %H:%M:%S")

# Check if file exists, if not create it
touch $LOG_FILE

# Append current time to the file
echo -n "{$current_time}: " >> "$LOG_FILE"

# Iterate through all arguments
for arg in "$@"
do
    # Append argument to the file
    echo -n "$arg," >> "$LOG_FILE"
done

# Append newline character at the end
echo >> "$LOG_FILE"

  1. Ensure that manual and automatic backups do not run at the same time. 

  2. For example, if the snapshots folder is on a removable drive, which is either not mounted, or is mounted at a different location. 

  3. Supported added in Back In Time version 1.4.0.