API documentation¶
The following documentation is based on the source code of version 1.1 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)[source]¶ 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 tounlock_device()
,mount_filesystem()
,transfer_changes()
,create_snapshot()
androtate_snapshots()
.When you initialize a
RsyncSystemBackup
object you are required to provide a value for thedestination
property. You can set the values of thebackup_enabled
,crypto_device
,destination
,dry_run
,exclude_list
,excluded_roots
,force
,ionice
,mount_point
,multi_fs
,notifications_enabled
,rotate_enabled
,rotation_scheme
,snapshot_enabled
,source
,source_context
andsudo_enabled
properties by passing keyword arguments to the class initializer.Here’s an overview of the
RsyncSystemBackup
class:-
backup_enabled
[source]¶ True
to enabletransfer_changes()
,False
otherwise.Note
The
backup_enabled
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
crypto_device
[source]¶ The name of the encrypted filesystem to use (a string or
None
).Note
The
crypto_device
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
crypto_device_available
¶ True
if the encrypted filesystem is available,False
otherwise.This property is an alias for the
is_available
property ofcrypttab_entry
.
-
crypto_device_unlocked
¶ True
if the encrypted filesystem is unlocked,False
otherwise.This property is an alias for the
is_unlocked
property ofcrypttab_entry
.
-
crypttab_entry
[source]¶ The entry in
/etc/crypttab
corresponding tocrypto_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) matchescrypto_device
.When an entry is found an
EncryptedFileSystemEntry
object is constructed, otherwise the result isNone
.Note
The
crypttab_entry
property is acached_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 usedel
ordelattr()
.
-
destination
[source]¶ 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 thepost-xfer exec
command.Note
The
destination
property is arequired_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
[source]¶ 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 acached_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 usedel
ordelattr()
.
-
dry_run
[source]¶ True
to simulate the backup without writing any files,False
otherwise.Note
The
dry_run
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
multi_fs
[source]¶ True
to allow rsync to cross filesystem boundaries,False
otherwise.This property has the opposite effect of the rsync command line option
--one-file-system
becausemulti_fs
defaults toFalse
which means rsync is run with--one-file-system
. You can setmulti_fs
toTrue
to omit--one-file-system
from the rsync command line.Note
The
multi_fs
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
exclude_list
[source]¶ 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 acustom_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
[source]¶ 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 acustom_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
[source]¶ True
to run rsync-system-backup on unsupported platforms,False
otherwise.Note
The
force
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
ionice
[source]¶ 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 amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
mount_point
[source]¶ The pathname of the mount point to use (a string or
None
).Note
The
mount_point
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
mount_point_active
¶ True
ifmount_point
is mounted already,False
otherwise.
-
notifications_enabled
[source]¶ 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 amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
rotation_scheme
[source]¶ The rotation scheme for snapshots (a dictionary, defaults to
DEFAULT_ROTATION_SCHEME
).Note
The
rotation_scheme
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
snapshot_enabled
[source]¶ True
to enablecreate_snapshot()
,False
otherwise.Note
The
snapshot_enabled
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
source
[source]¶ The pathname of the directory to backup (a string, defaults to ‘/’).
Note
The
source
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
source_context
[source]¶ 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 toexecutor.contexts.LocalContext
.Note
The
source_context
property is acustom_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
[source]¶ True
to enablerotate_snapshots()
,False
otherwise.Note
The
rotate_enabled
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
sudo_enabled
[source]¶ True
to runrsync
and snapshot creation with superuser privileges,False
otherwise.Note
The
sudo_enabled
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
execute
()[source]¶ 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:- When
backup_enabled
is setnotify_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). - When
crypto_device
is setunlock_device()
ensures that the configured encrypted device is unlocked. - When
mount_point
is setmount_filesystem()
ensures that the configured filesystem is mounted. - When
backup_enabled
is settransfer_changes()
creates or updates the system backup ondestination
using rsync. - When
snapshot_enabled
is setcreate_snapshot()
creates a snapshot of thedestination
directory. - When
rotate_enabled
is setrotate_snapshots()
rotates snapshots. - When
backup_enabled
is setnotify_finished()
shows a desktop notification to give the user a heads up that the system backup has finished (or failed).
- When
-
ensure_supported_platform
()[source]¶ Make sure we’re running on a supported platform.
Raises: UnsupportedPlatformError
when the output of theuname
command doesn’t include the word ‘Linux’ andforce
isFalse
.When
force
isTrue
this method logs a warning message instead of raising an exception.
-
unlock_device
()[source]¶ Automatically unlock the encrypted filesystem to which backups are written.
Raises: The following exceptions can be raised:
DestinationContextUnavailable
, refer todestination_context
for details.ExternalCommandFailed
when the cryptdisks_start command reports an error.
When
crypto_device
is set this method usescryptdisks_start()
to unlock the encrypted filesystem to which backups are written before the backup starts. Whencryptdisks_start()
was called before the backup started,cryptdisks_stop()
will be called when the backup finishes.To enable the use of
cryptdisks_start()
andcryptdisks_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
()[source]¶ Automatically mount the filesystem to which backups are written.
Raises: The following exceptions can be raised:
DestinationContextUnavailable
, refer todestination_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
()[source]¶ Use rsync to synchronize the files on the local system to the backup destination.
Raises: InvalidDestinationDirectory
whenmount_point
is set anddestination
is a local directory that is not located undermount_point
.
-
create_snapshot
()[source]¶ Create a snapshot of the destination directory.
Raises: The following exceptions can be raised:
DestinationContextUnavailable
, refer todestination_context
for details.ParentDirectoryUnavailable
, refer toparent_directory
for details.ExternalCommandFailed
when thecp
command reports an error.
-
rotate_snapshots
()[source]¶ Rotate system backup snapshots using
rotate_backups
.Raises: The following exceptions can be raised:
DestinationContextUnavailable
, refer todestination_context
for details.ParentDirectoryUnavailable
, refer toparent_directory
for details.- Any exceptions raised by
rotate_backups
.
The values of the
dry_run
,ionice
androtation_scheme
properties are passed on to theRotateBackups
class.
-
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:
- 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.
- 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
’. - 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 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 |
-r , --rotate |
Rotate old snapshots but don’t create a backup and snapshot unless the
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 |
-m , --mount=DIRECTORY |
Automatically mount the filesystem to which backups are written. When this option is given and 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 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. |
--multi-fs |
Allow rsync to cross filesystem boundaries. This option has the opposite
effect of the rsync option --one-file-system because rsync-system-backup
defaults to running rsync with --one-file-system and must be instructed
not to using --multi-fs . |
-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.
enable_explicit_action
(options, explicit_action)[source]¶ 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)[source]¶ 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 theusername
,hostname
,port_number
,module
anddirectory
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 theexpression
property. You can set the values of thedirectory
,expression
,hostname
,module
,parent_directory
,port_number
,ssh_tunnel
andusername
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
andusername
-
expression
[source]¶ 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 arequired_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
[source]¶ The pathname of the directory where the backup should be written (a string).
Note
The
directory
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
hostname
[source]¶ The host name or IP address of a remote system (a string).
Note
The
hostname
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
module
[source]¶ The name of a module exported by an rsync daemon (a string).
Note
The
module
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
parent_directory
[source]¶ The pathname of the parent directory of the backup directory (a string).
Raises: ParentDirectoryUnavailable
when the parent directory can’t be determined becausedirectory
is empty or ‘/’.Note
The
parent_directory
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
port_number
[source]¶ The port number of a remote rsync daemon (a number).
When
ssh_tunnel
is set the value ofport_number
defaults toexecutor.ssh.client.SecureTunnel.local_port
, otherwise it defaults toRSYNCD_PORT
.Note
The
port_number
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
ssh_tunnel
[source]¶ A
SecureTunnel
object orNone
(defaults toNone
).Note
The
ssh_tunnel
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
username
[source]¶ The username for connecting to a remote system (a string).
Note
The
username
property is amutable_property
. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can usedel
ordelattr()
.
-
__enter__
()[source]¶ Automatically open
ssh_tunnel
when required.
-
__exit__
(exc_type=None, exc_value=None, traceback=None)[source]¶ Automatically close
ssh_tunnel
when required
-
rsync_system_backup.exceptions
¶
Custom exceptions used by rsync-system-backup.
-
exception
rsync_system_backup.exceptions.
RsyncSystemBackupError
[source]¶ Base exception for custom exceptions raised by rsync-system-backup.
-
exception
rsync_system_backup.exceptions.
UnsupportedPlatformError
[source]¶ Raised when an unsupported (non-Linux) platform is detected.
-
exception
rsync_system_backup.exceptions.
InvalidDestinationError
[source]¶ Raised when the given destination expression can’t be parsed.
-
exception
rsync_system_backup.exceptions.
MissingBackupDiskError
[source]¶ Raised when the encrypted filesystem isn’t available.
-
exception
rsync_system_backup.exceptions.
FailedToUnlockError
[source]¶ Raised when cryptdisks_start fails to unlock the encrypted device.
-
exception
rsync_system_backup.exceptions.
FailedToMountError
[source]¶ Raised when mount fails to mount the backup destination.
Raised when snapshot creation and rotation are disabled because we’re connected to an rsync daemon.
Raised when the parent directory of the backup directory cannot be determined.