API documentation

The following documentation is based on the source code of version 1.0 of the rsync-system-backup package:

rsync_system_backup

Simple to use Python API for Linux system backups powered by rsync.

The rsync_system_backup module contains the Python API of the rsync-system-backup package. The core logic of the package is contained in the RsyncSystemBackup class.

rsync_system_backup.DEFAULT_ROTATION_SCHEME = {'daily': 7, 'hourly': 24, 'monthly': 'always', 'weekly': 4}

The default rotation scheme for system backup snapshots (a dictionary).

class rsync_system_backup.RsyncSystemBackup(**kw)

Python API for the rsync-system-backup program.

The execute() method is the main entry point. If you’re looking for finer grained control refer to unlock_device(), mount_filesystem(), transfer_changes(), create_snapshot() and rotate_snapshots().

When you initialize a RsyncSystemBackup object you are required to provide a value for the destination property. You can set the values of the backup_enabled, crypto_device, destination, dry_run, exclude_list, excluded_roots, force, ionice, mount_point, notifications_enabled, rotate_enabled, rotation_scheme, snapshot_enabled, source, source_context and sudo_enabled properties by passing keyword arguments to the class initializer.

Here’s an overview of the RsyncSystemBackup class:

Superclass:	PropertyManager
Public methods:	create_snapshot(), ensure_supported_platform(), execute(), execute_helper(), mount_filesystem(), notify_failed(), notify_finished(), notify_starting(), rotate_snapshots(), transfer_changes() and unlock_device()
Properties:	backup_enabled, crypto_device, crypto_device_available, crypto_device_unlocked, crypttab_entry, destination, destination_context, dry_run, exclude_list, excluded_roots, force, ionice, mount_point, mount_point_active, notifications_enabled, rotate_enabled, rotation_scheme, snapshot_enabled, source, source_context and sudo_enabled

backup_enabled

True to enable transfer_changes(), False otherwise.

Note

The backup_enabled property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

crypto_device

The name of the encrypted filesystem to use (a string or None).

Note

The crypto_device property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

crypto_device_available

True if the encrypted filesystem is available, False otherwise.

This property is an alias for the is_available property of crypttab_entry.

crypto_device_unlocked

True if the encrypted filesystem is unlocked, False otherwise.

This property is an alias for the is_unlocked property of crypttab_entry.

crypttab_entry

The entry in /etc/crypttab corresponding to crypto_device.

The value of this property is computed automatically by parsing /etc/crypttab and looking for an entry whose target (the first of the four fields) matches crypto_device.

When an entry is found an EncryptedFileSystemEntry object is constructed, otherwise the result is None.

Note

The crypttab_entry property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

destination

The destination where backups are stored (a Destination object).

The value of destination defaults to the value of the environment variable $RSYNC_MODULE_PATH which is set by the rsync daemon before it runs the post-xfer exec command.

Note

The destination property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named destination (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

destination_context

The execution context of the system that stores the backup (the destination).

This is an execution context created by executor.contexts.

Raises:DestinationContextUnavailable when the destination is an rsync daemon module (which doesn’t allow arbitrary command execution).

Note

The destination_context property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

dry_run

True to simulate the backup without writing any files, False otherwise.

Note

The dry_run property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

exclude_list

A list of patterns (strings) that are excluded from the system backup.

The patterns in exclude_list are passed on to rsync using the --exclude option.

Note

The exclude_list property is a custom_property. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached.

excluded_roots

A list of patterns (strings) that are excluded from the system backup.

All of the patterns in this list will be rooted to the top of the filesystem hierarchy when they’re given the rsync, to avoid unintentionally excluding deeply nested directories that happen to match names in this list. This is done using the --filter=-/ PATTERN option.

Note

The excluded_roots property is a custom_property. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached.

force

True to run rsync-system-backup on unsupported platforms, False otherwise.

Note

The force property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

ionice

The I/O scheduling class for rsync (a string or None).

When this property is set ionice will be used to set the I/O scheduling class for rsync. This can be useful to reduce the impact of backups on the rest of the system.

The value of this property is expected to be one of the strings ‘idle’, ‘best-effort’ or ‘realtime’.

Note

The ionice property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

mount_point

The pathname of the mount point to use (a string or None).

Note

The mount_point property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

mount_point_active

True if mount_point is mounted already, False otherwise.

notifications_enabled

Whether desktop notifications are used (a boolean).

By default desktop notifications are enabled when a real backup is being made but disabled during dry runs.

Note

The notifications_enabled property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

rotation_scheme

The rotation scheme for snapshots (a dictionary, defaults to DEFAULT_ROTATION_SCHEME).

Note

The rotation_scheme property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

snapshot_enabled

True to enable create_snapshot(), False otherwise.

Note

The snapshot_enabled property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

source

The pathname of the directory to backup (a string, defaults to ‘/’).

Note

The source property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

source_context

The execution context of the system that is being backed up (the source).

This is expected to be an execution context created by executor.contexts. It defaults to executor.contexts.LocalContext.

Note

The source_context property is a custom_property. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached.

rotate_enabled

True to enable rotate_snapshots(), False otherwise.

Note

The rotate_enabled property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

sudo_enabled

True to run rsync and snapshot creation with superuser privileges, False otherwise.

Note

The sudo_enabled property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

execute()

Execute the requested actions (backup, snapshot and/or rotate).

The execute() method defines the high level control flow of the backup / snapshot / rotation process according to the caller’s requested configuration:

1. When backup_enabled is set notify_starting() shows a desktop notification to give the user a heads up that a system backup is about to start (because the backup may have a noticeable impact on system performance).
2. When crypto_device is set unlock_device() ensures that the configured encrypted device is unlocked.
3. When mount_point is set mount_filesystem() ensures that the configured filesystem is mounted.
4. When backup_enabled is set transfer_changes() creates or updates the system backup on destination using rsync.
5. When snapshot_enabled is set create_snapshot() creates a snapshot of the destination directory.
6. When rotate_enabled is set rotate_snapshots() rotates snapshots.
7. When backup_enabled is set notify_finished() shows a desktop notification to give the user a heads up that the system backup has finished (or failed).

ensure_supported_platform()

Make sure we’re running on a supported platform.

Raises:UnsupportedPlatformError when the output of the uname command doesn’t include the word ‘Linux’ and force is False.

When force is True this method logs a warning message instead of raising an exception.

execute_helper()

Helper for execute().

notify_starting()

Notify the desktop environment that a system backup is starting.

notify_finished(timer)

Notify the desktop environment that a system backup has finished.

notify_failed(timer)

Notify the desktop environment that a system backup has failed.

unlock_device()

Automatically unlock the encrypted filesystem to which backups are written.

Raises:

The following exceptions can be raised:

• DestinationContextUnavailable, refer to destination_context for details.
• ExternalCommandFailed when the cryptdisks_start command reports an error.

When crypto_device is set this method uses cryptdisks_start() to unlock the encrypted filesystem to which backups are written before the backup starts. When cryptdisks_start() was called before the backup started, cryptdisks_stop() will be called when the backup finishes.

To enable the use of cryptdisks_start() and cryptdisks_stop() you need to create an /etc/crypttab entry that maps your physical device to a symbolic name. If you want this process to run fully unattended you can configure a key file in /etc/crypttab, otherwise you will be asked for the password when the encrypted filesystem is unlocked.

mount_filesystem()

Automatically mount the filesystem to which backups are written.

Raises:

The following exceptions can be raised:

• DestinationContextUnavailable, refer to destination_context for details.
• ExternalCommandFailed when the mount command reports an error.

When mount_point is set this method uses the mount command to mount the filesystem to which backups are written before the backup starts. When mount was called before the backup started, umount will be called when the backup finishes. An entry for the mount point needs to be defined in /etc/fstab.

transfer_changes()

Use rsync to synchronize the files on the local system to the backup destination.

Raises:InvalidDestinationDirectory when mount_point is set and destination is a local directory that is not located under mount_point.

create_snapshot()

Create a snapshot of the destination directory.

Raises:

The following exceptions can be raised:

• DestinationContextUnavailable, refer to destination_context for details.
• ParentDirectoryUnavailable, refer to parent_directory for details.
• ExternalCommandFailed when the cp command reports an error.

rotate_snapshots()

Rotate system backup snapshots using rotate_backups.

Raises:

The following exceptions can be raised:

• DestinationContextUnavailable, refer to destination_context for details.
• ParentDirectoryUnavailable, refer to parent_directory for details.
• Any exceptions raised by rotate_backups.

The values of the dry_run, ionice and rotation_scheme properties are passed on to the RotateBackups class.

rsync_system_backup.ensure_trailing_slash(expression)

Add a trailing slash to rsync source/destination locations.

Parameters:expression – The rsync source/destination expression (a string). Returns:The same expression with exactly one trailing slash.

rsync_system_backup.cli

Usage: rsync-system-backup [OPTIONS] [SOURCE] DESTINATION

Use rsync to create full system backups.

The required DESTINATION argument specifies the (possibly remote) location where the backup is stored, in the syntax of rsync’s command line interface. The optional SOURCE argument defaults to ‘/’ which means the complete root filesystem will be included in the backup (other filesystems are excluded).

Please use the --dry-run option when getting familiar with this program and don’t remove it until you’re confident that you have the right command line, because using this program in the wrong way can cause data loss (for example by accidentally swapping the SOURCE and DESTINATION arguments).

Supported locations include:

• Local disks (possibly encrypted using LUKS).
• Remote systems that allow SSH connections.
• Remote systems that are running an rsync daemon.
• Connections to rsync daemons tunneled over SSH.

The backup process consists of several steps:

1. First rsync is used to transfer all (relevant) files to a destination directory (whether on the local system or a remote system). Every time a backup is made, this same destination directory is updated.
2. After the files have been transferred a ‘snapshot’ of the destination directory is taken and stored in a directory with a timestamp in its name. These snapshots are created using ‘cp --archive --link’.
3. Finally the existing snapshots are rotated to purge old backups according to a rotation scheme that you can customize.

Supported options:

Option	Description
-b, --backup	Create a backup using rsync but don’t create a snapshot and don’t rotate old snapshots unless the --snapshot and/or --rotate options are also given.
-s, --snapshot	Create a snapshot of the destination directory but don’t create a backup and don’t rotate old snapshots unless the --backup and/or --rotate options are also given. This option can be used to create snapshots of an rsync daemon module using a ‘post-xfer exec’ command. If DESTINATION isn’t given it defaults to the value of the environment variable $RSYNC_MODULE_PATH.
-r, --rotate	Rotate old snapshots but don’t create a backup and snapshot unless the --backup and/or --snapshot options are also given. This option can be used to rotate old snapshots of an rsync daemon module using a ‘post-xfer exec’ command. If DESTINATION isn’t given it defaults to the value of the environment variable $RSYNC_MODULE_PATH.
-m, --mount=DIRECTORY	Automatically mount the filesystem to which backups are written. When this option is given and DIRECTORY isn’t already mounted, the ‘mount’ command is used to mount the filesystem to which backups are written before the backup starts. When ‘mount’ was called before the backup started, ‘umount’ will be called when the backup finishes. An entry for the mount point needs to be defined in /etc/fstab for this to work.
-c, --crypto=NAME	Automatically unlock the encrypted filesystem to which backups are written. When this option is given and the NAME device isn’t already unlocked, the cryptdisks_start command is used to unlock the encrypted filesystem to which backups are written before the backup starts. When cryptdisks_start was called before the backup started, cryptdisks_stop will be called when the backup finishes. An entry for the encrypted filesystem needs to be defined in /etc/crypttab for this to work. If the device of the encrypted filesystem is missing and rsync-system-backup is being run non-interactively, it will exit gracefully and not show any desktop notifications. If you want the backup process to run fully unattended you can configure a key file in /etc/crypttab, otherwise you will be asked for the password each time the encrypted filesystem is unlocked.
-t, --tunnel=TUNNEL_SPEC	Connect to an rsync daemon through an SSH tunnel. This provides encryption for rsync client to daemon connections that are not otherwise encrypted. The value of TUNNEL_SPEC is expected to be an SSH alias, host name or IP address. Optionally a username can be prefixed (followed by ‘@’) and/or a port number can be suffixed (preceded by ‘:’).
-i, --ionice=CLASS	Use the ‘ionice’ program to set the I/O scheduling class and priority of the ‘rm’ invocations used to remove backups. CLASS is expected to be one of the values ‘idle’, ‘best-effort’ or ‘realtime’. Refer to the man page of the ‘ionice’ program for details about these values.
-u, --no-sudo	By default backup and snapshot creation is performed with superuser privileges, to ensure that all files are readable and filesystem metadata is preserved. The -u, --no-sudo option disables the use of ‘sudo’ during these operations.
-n, --dry-run	Don’t make any changes, just report what would be done. This doesn’t create a backup or snapshot but it does run rsync with the --dry-run option.
-x, --exclude=PATTERN	Selectively exclude certain files from being included in the backup. Refer to the rsync documentation for allowed PATTERN syntax. Note that rsync-system-backup always uses the ‘rsync --one-file-system’ option.
-f, --force	By default rsync-system-backup refuses to run on non-Linux systems because it was designed specifically for use on Linux. The use of the -f, --force option sidesteps this sanity check. Please note that you are on your own if things break!
--disable-notifications	By default a desktop notification is shown (using notify-send) before the system backup starts and after the backup finishes. The use of this option disables the notifications (notify-send will not be called at all).
-v, --verbose	Make more noise (increase logging verbosity). Can be repeated.
-q, --quiet	Make less noise (decrease logging verbosity). Can be repeated.
-h, --help	Show this message and exit.

rsync_system_backup.cli.main()

Command line interface for the rsync-system-backup program.

rsync_system_backup.cli.enable_explicit_action(options, explicit_action)

Explicitly enable an action and disable other implicit actions.

Parameters:

• options – A dictionary of options.
• explicit_action – The action to enable (one of the strings ‘backup_enabled’, ‘snapshot_enabled’, ‘rotate_enabled’).

rsync_system_backup.destinations

Parsing of rsync destination syntax (and then some).

rsync_system_backup.destinations.RSYNCD_PORT = 873

The default port of the rsync daemon (an integer).

rsync_system_backup.destinations.LOCAL_DESTINATION = <_sre.SRE_Pattern object>

A compiled regular expression pattern to parse local destinations, used as a fall back because it matches any nonempty string.

rsync_system_backup.destinations.SSH_DESTINATION = <_sre.SRE_Pattern object>

A compiled regular expression pattern to parse remote destinations of the form [USER@]HOST:DEST (using an SSH connection).

rsync_system_backup.destinations.SIMPLE_DAEMON_DESTINATION = <_sre.SRE_Pattern object>

A compiled regular expression pattern to parse remote destinations of the form [USER@]HOST::MODULE[/DIRECTORY] (using an rsync daemon connection).

rsync_system_backup.destinations.ADVANCED_DAEMON_DESTINATION = <_sre.SRE_Pattern object>

A compiled regular expression pattern to parse remote destinations of the form rsync://[USER@]HOST[:PORT]/MODULE[/DIRECTORY] (using an rsync daemon connection).

rsync_system_backup.destinations.DESTINATION_PATTERNS = [<_sre.SRE_Pattern object>, <_sre.SRE_Pattern object>, <_sre.SRE_Pattern object>, <_sre.SRE_Pattern object>]

A list of compiled regular expression patterns to match destination expressions. The patterns are ordered by decreasing specificity.

class rsync_system_backup.destinations.Destination(**kw)

The Destination class represents a location where backups are stored.

The expression property is a required property whose value is parsed to populate the values of the username, hostname, port_number, module and directory properties.

When you read the value of the expression property you get back a computed value based on the values of the previously mentioned properties. This makes it possible to manipulate the destination before passing it on to rsync.

When you initialize a Destination object you are required to provide a value for the expression property. You can set the values of the directory, expression, hostname, module, parent_directory, port_number, ssh_tunnel and username properties by passing keyword arguments to the class initializer.

Here’s an overview of the Destination class:

Superclass:	PropertyManager
Special methods:	__enter__() and __exit__()
Properties:	directory, expression, hostname, module, parent_directory, port_number, ssh_tunnel and username

expression

The destination in rsync’s command line syntax (a string).

Raises:InvalidDestinationError when you try to set this property to a value that cannot be parsed.

Note

The expression property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named expression (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

directory

The pathname of the directory where the backup should be written (a string).

Note

The directory property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

hostname

The host name or IP address of a remote system (a string).

Note

The hostname property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

module

The name of a module exported by an rsync daemon (a string).

Note

The module property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

parent_directory

The pathname of the parent directory of the backup directory (a string).

Raises:ParentDirectoryUnavailable when the parent directory can’t be determined because directory is empty or ‘/’.

Note

The parent_directory property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

port_number

The port number of a remote rsync daemon (a number).

When ssh_tunnel is set the value of port_number defaults to executor.ssh.client.SecureTunnel.local_port, otherwise it defaults to RSYNCD_PORT.

Note

The port_number property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

ssh_tunnel

A SecureTunnel object or None (defaults to None).

Note

The ssh_tunnel property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

username

The username for connecting to a remote system (a string).

Note

The username property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

__enter__()

Automatically open ssh_tunnel when required.

__exit__(exc_type=None, exc_value=None, traceback=None)

Automatically close ssh_tunnel when required

rsync_system_backup.exceptions

Custom exceptions used by rsync-system-backup.

exception rsync_system_backup.exceptions.RsyncSystemBackupError

Base exception for custom exceptions raised by rsync-system-backup.

exception rsync_system_backup.exceptions.UnsupportedPlatformError

Raised when an unsupported (non-Linux) platform is detected.

exception rsync_system_backup.exceptions.InvalidDestinationError

Raised when the given destination expression can’t be parsed.

exception rsync_system_backup.exceptions.MissingBackupDiskError

Raised when the encrypted filesystem isn’t available.

exception rsync_system_backup.exceptions.FailedToUnlockError

Raised when cryptdisks_start fails to unlock the encrypted device.

exception rsync_system_backup.exceptions.FailedToMountError

Raised when mount fails to mount the backup destination.

exception rsync_system_backup.exceptions.DestinationContextUnavailable

Raised when snapshot creation and rotation are disabled because we’re connected to an rsync daemon.

exception rsync_system_backup.exceptions.ParentDirectoryUnavailable

Raised when the parent directory of the backup directory cannot be determined.

exception rsync_system_backup.exceptions.InvalidDestinationDirectory

Raised when the backup directory isn’t located inside the given mount point.