snapshots module

class snapshots.FileInfoDict[source]

Bases: dict

A dict that maps a path (as bytes) to a tuple (int, bytes, bytes).

class snapshots.GenericNonSnapshot(date, cfg)[source]

Bases: snapshots.SID

displayID
displayName
tag
withoutTag
class snapshots.NewSnapshot(cfg)[source]

Bases: snapshots.GenericNonSnapshot

Snapshot ID object for ‘new_snapshot’ folder

Parameters:cfg (config.Config) – current config
NEWSNAPSHOT = 'new_snapshot'
SAVETOCONTINUE = 'save_to_continue'
hasChanges

Check if there where changes in previous sessions.

Returns:True if there where changes
Return type:bool
name

Name of this snapshot

Returns:name of this snapshot
Return type:str
saveToContinue

Check if ‘save_to_continue’ flag is set

Parameters:enable (bool) – set or remove flag
Returns:True if flag is set
Return type:bool
class snapshots.RootSnapshot(cfg)[source]

Bases: snapshots.GenericNonSnapshot

Snapshot ID for the filesystem root folder (‘/’)

Parameters:cfg (config.Config) – current config
name

Name of this snapshot

Returns:name of this snapshot
Return type:str
path(*path, use_mode=[])[source]

Current path of this snapshot automatically altered for remote/encrypted version of this path

Parameters:
  • *path (str) – one or more folder/files to join at the end of the path.
  • use_mode (list) – list of modes that should alter this path. If the current mode is in this list, the path will automatically altered for the remote/encrypted version of this path.
Returns:

full snapshot path

Return type:

str

class snapshots.SID(date, cfg)[source]

Bases: object

Snapshot ID object used to gather all information for a snapshot

Parameters:
Raises:
FAILED = 'failed'
FILEINFO = 'fileinfo.bz2'
INFO = 'info'
LOG = 'takesnapshot.log.bz2'
NAME = 'name'
canOpenPath(path)[source]

True if path is a file inside this snapshot

Parameters:path (str) – path from local filesystem (no snapshot path)
Returns:True if file exists
Return type:bool
displayID

**Snapshot ID in a user-readable format* – YYYY-MM-DD HH* – MM:SS

Returns:formated sID
Return type:str
displayName

Combination of displayID, name and error indicator (if any)

Returns:name
Return type:str
exists()[source]

True if the snapshot folder and the “backup” folder inside exist

Returns:True if exists
Return type:bool
failed

This snapshot has failed

Parameters:enable (bool) – set or remove flag
Returns:True if flag is set
Return type:bool
fileInfo

Load/save “fileinfo.bz2”

Parameters:d (FileInfoDict) – dict of: {path: (permission, user, group)}
Returns:dict of: {path: (permission, user, group)}
Return type:FileInfoDict
info

Load/save “info” file which contains additional information about this snapshot (using configfile.ConfigFile)

Parameters:i (configfile.ConfigFile) – info that should be saved.
Returns:snapshots information
Return type:configfile.ConfigFile
lastChecked

Date when snapshot has finished last time. This can be the end of creation of this snapshot or the last time when this snapshot was checked against source without changes.

Returns:date and time of last check (YYYY-MM-DD HH:MM:SS)
Return type:str
log(mode=None, decode=None)[source]

Load log from “takesnapshot.log.bz2”

Parameters:
Yields:

str – filtered and decoded log lines

makeDirs(*path)[source]

Create snapshot directory

Parameters:*path (str) – one or more folder/files to join at the end of the path
Returns:True if successful
Return type:bool
makeWritable()[source]

Make the snapshot path writable so we can change files inside

Returns:True if successful
Return type:bool
name

Name of this snapshot

Parameters:name (str) – new name of the snapshot
Returns:name of this snapshot
Return type:str
path(*path, use_mode=[])[source]

Current path of this snapshot automatically altered for remote/encrypted version of this path

Parameters:
  • *path (str) – one or more folder/files to join at the end of the path.
  • use_mode (list) – list of modes that should alter this path. If the current mode is in this list, the path will automatically altered for the remote/encrypted version of this path.
Returns:

full snapshot path

Return type:

str

pathBackup(*path, **kwargs)[source]

‘backup’ folder inside snapshots path

Parameters:
  • *path (str) – one or more folder/files to join at the end of the path.
  • use_mode (list) – list of modes that should alter this path. If the current mode is in this list, the path will automatically altered for the remote/encrypted version of this path.
Returns:

full snapshot path

Return type:

str

setLastChecked()[source]

Set info files atime to current time to indicate this snapshot was checked against source without changes right now.

setLog(log)[source]

Write log to “takesnapshot.log.bz2”

Parameters:log – full snapshot log
split()[source]

Split self.sid into a tuple of int’s with Year, Month, Day, Hour, Minute, Second

Returns:tuple of 6 int
Return type:tuple
tag

Snapshot ID’s tag

Returns:tag (last three digits)
Return type:str
withoutTag

Snapshot ID without tag

Returns:YYYYMMDD-HHMMSS
Return type:str
class snapshots.Snapshots(cfg=None)[source]

Bases: object

Collection of take-snapshot and restore commands.

Parameters:cfg (config.Config) – current config
GLOBAL_FLOCK = '/tmp/backintime.lock'
SNAPSHOT_VERSION = 3
backup(force=False)[source]

Wrapper for takeSnapshot() which will prepair and clean up things for the main takeSnapshot() method. This will check that no other snapshots are running at the same time, there is nothing prohibing a new snapshot (e.g. on battery) and the profile is configured correctly. This will also mount and unmount remote destinations.

Parameters:force (bool) – force taking a new snapshot even if the profile is not scheduled or the machine is running on battery
Returns:True if successful created a new snapshot
Return type:bool
backupConfig(sid)[source]

Backup the config file to the snapshot.

Parameters:sid (SID) – snapshot in which the config should be stored
backupInfo(sid)[source]

Save infos about the snapshot into the ‘info’ file.

Parameters:sid (SID) – snapshot that should get an info file
backupPermissions(sid)[source]

Save permissions (owner, group, read-, write- and executable) for all files in Snapshot sid into snapshots fileInfoDict.

Parameters:sid (SID) – snapshot that should be scanned
backupPermissionsCallback(line, user_data)[source]

Rsync callback for Snapshots.backupPermissions().

Parameters:
backupSuffix()[source]

Get suffix for backup files.

Returns:backup suffix in form of ‘.backup.YYYYMMDD’
Return type:str
busy()[source]
clearIdCache()[source]

Reset the cache for UIDs and GIDs.

clearNameCache()[source]

Reset the cache for user and group names.

clearTakeSnapshotMessage()[source]
collectPermission(fileinfo, path)[source]

Collect permission infos about path and store them into fileinfo.

Parameters:
  • fileinfo (FileInfoDict) – dict of: {path: (permission, user, group)} Using sideefect on changing dict item will change original dict, too.
  • path (bytes) – full path to file or folder

Create symlink ‘last_snapshot’ to snapshot sid

Parameters:sid (SID) – snapshot that should be linked.
Returns:True if successful
Return type:bool
decMonth(date)[source]

First day of previous month of date with respect on previous years. So if date is January this will return 1st of December previous year.

Parameters:date (datetime.date) – old date that should be decreased
Returns:1st day of previous month
Return type:datetime.date
deletePath(sid, path)[source]

Delete path and all files and folder inside in snapshot sid.

Parameters:
  • sid (SID) – snapshot ID in which path should be deleted
  • path (str) – path to delete
filter(base_sid, base_path, snapshotsList, list_diff_only=False, flag_deep_check=False, list_equal_to='')[source]

Filter snapshots from snapshotsList based on whether base_path file is included and optional if the snapshot is unique or equal to list_equal_to.

Parameters:
  • base_sid (SID) – snapshot ID that contained the original file base_path
  • base_path (str) – path to file on root filesystem.
  • snapshotsList (list) – List of SID objects that should be filtered
  • list_diff_only (bool) – if True only return unique snapshots. Which means if a file is exactly the same in different snapshots only the first snapshot will be listed
  • flag_deep_check (bool) – use md5sum to check uniqueness of files. More acurate but slow
  • list_equal_to (str) – full path to file. If not empty only return snapshots which have exactly the same file as this file
Returns:

filtered list of SID objects

Return type:

list

filterRsyncProgress(line)[source]

Filter rsync’s stdout for progress informations and store them in ‘~/.local/share/backintime/worker<N>.progress’ file.

Parameters:line (str) – stdout line from rsync
Returns:
line if it had no progress infos. None if
line was a progress
Return type:str
flockExclusive()[source]

Block backup() from other profiles or users and run them serialized

flockRelease()[source]

Release lock so other snapshots can continue

freeSpace(now)[source]

Remove old snapshots on based on different rules (only if enabled). First rule is to remove snapshots older than X years. Next will call smartRemove() to remove snapshots based on configurable intervals. Third rule is to remove the oldest snapshot until there is enough free space. Last rule will remove the oldest snapshot until there are enough free inodes.

‘last_snapshot’ symlink will be fixed when done.

Parameters:now (datetime.datetime) – date and time when takeSnapshot was started
gid(name, callback=None, backup=None)[source]

Get the Group identifier (GID) for the group in name. name->gid will be cached to speed up subsequent requests.

Parameters:
  • name (str, bytes) – groupname to search for
  • callback (method) – callable which will handle a given message
  • backup (int) – GID wich will be used if the groupname is unknown on this machine
Returns:

GID of the group in name or -1 if not found

Return type:

int

groupName(gid)[source]

Get the groupname for the given gid. gid->name will be cached to speed up subsequent requests.

Parameters:gid (int) – Group identifier (GID) to search for
Returns:name of the Group with GID gid or ‘.’ if not found
Return type:str
incMonth(date)[source]

First day of next month of date with respect on new years. So if date is December this will return 1st of January next year.

Parameters:date (datetime.date) – old date that should be increased
Returns:1st day of next month
Return type:datetime.date
makeDirs(path)[source]

Wrapper for tools.makeDirs(). Create directories path recursive and return success. If not successful send error-message to log.

Parameters:path (str) – fullpath to directories that should be created
Returns:True if successful
Return type:bool
pid()[source]
remove(sid)[source]

Remove snapshot sid.

Parameters:sid (SID) – snapshot to remove
restore(sid, paths, callback=None, restore_to='', delete=False, backup=True, only_new=False)[source]

Restore one or more files from snapshot sid to either original or a different destination. Restore is done with rsync. If available permissions will be restored from fileinfo.bz2.

Parameters:
  • sid (SID) – snapshot from whom to restore
  • paths (list, tuple or str) – single path (str) or multiple paths (list, tuple) that should be restored. For every path this will run a new rsync process. Permissions will be restored for all paths in one run
  • callback (method) – callable instance which will handle messages
  • restore_to (str) – full path to restore to. If empty restore to original destiantion
  • delete (bool) – delete newer files which are not in the snapshot
  • backup (bool) – create backup files (*.backup.YYYYMMDD) before changing or deleting local files.
  • only_new (bool) – Only restore files which does not exist or are newer than those in destination. Using “rsync –update” option.
restoreCallback(callback, ok, msg)[source]

Format messages thrown by restore depending on whether they where successful or failed.

Parameters:
  • callback (method) – callable instance which will handle the message
  • ok (bool) – True if the logged action was successful or False if it failed
  • msg (str) – message that should be send to callback
restorePermission(key_path, path, fileInfoDict, callback=None)[source]

Restore permissions (owner, group and mode). If permissions are already identical with the new ones just skip. Otherwise try to ‘chown’ to new owner and new group. If that fails (most probably because we are not running as root and normal user has no rights to change ownership of files) try to at least ‘chgrp’ to the new group. Finally ‘chmod’ the new mode.

Parameters:
  • key_path (bytes) – original path during backup. Same as in fileInfoDict.
  • path (bytes) – current path of file that should be changed.
  • fileInfoDict (FileInfoDict) – FileInfoDict
rsyncCallback(line, params)[source]

Parse rsync’s stdout, send it to takeSnapshotMessage and takeSnapshotLog. Also check if there has been changes or errors in current rsync.

Parameters:
  • line (str) – stdout line from rsync
  • params (list) – list of two bool ‘[error, changes]’. Using siteefect on changing list items will change original list, too. If rsync reported an error params[0] will be set to True. If rsync reported a changed file params[1] will be set to True
rsyncExclude(excludeFolders=None)[source]

Format exclude list for rsync

Parameters:excludeFolders (list) – list of folders to exclude
Returns:rsync exclude options
Return type:OrderedSet
rsyncInclude(includeFolders=None)[source]

Format include list for rsync. Returns a tuple of two include strings. First string need to come before exclude, second after exclude.

Parameters:includeFolders (list) – folders to include. list of tuples (item, int) where int is 0 if item is a folder or 1 if item is a file
Returns:
two item tuple of
(OrderedSet('include1 opions'), OrderedSet('include2 options'))
Return type:tuple
rsyncRemotePath(path, use_mode=['ssh', 'ssh_encfs'], quote='"')[source]

Format the destination string for rsync depending on which profile is used.

Parameters:
  • path (str) – destination path
  • use_mode (list) – list of modes in which the result should change to user@host:path instead of just path
  • quote (str) – use this to quote the path
Returns:

quoted path like ‘”/foo”’

or if the current mode is using ssh and current mode is in use_mode a combination of user, host and path like ''user@host:”/foo”’‘

Return type:

str

rsyncSuffix(includeFolders=None, excludeFolders=None)[source]

Create suffixes for rsync.

Parameters:
  • includeFolders (list) – folders to include. list of tuples (item, int) Where int is 0 if item is a folder or 1 if item is a file
  • excludeFolders (list) – list of folders to exclude
Returns:

rsync include and exclude options

Return type:

list

setTakeSnapshotMessage(type_id, message, timeout=-1)[source]
smartRemove(del_snapshots, log=None)[source]

Remove multiple snapshots either with Snapshots.remove() or in background on the remote host if mode is ssh or ssh_encfs and smart-remove in background is activated.

Parameters:
  • del_snapshots (list) – list of SID that should be removed
  • log (method) – callable method that will handle progress log
smartRemoveKeepAll(snapshots, min_date, max_date)[source]

Return all snapshots between min_date and max_date.

Parameters:
  • snapshots (list) – full list of SID objects
  • min_date (datetime.date) – minimum date for snapshots to keep
  • max_date (datetime.date) – maximum date for snapshots to keep
Returns:

set of snapshots that should be keept

Return type:

set

smartRemoveKeepFirst(snapshots, min_date, max_date, keep_healthy=False)[source]

Return only the first snapshot between min_date and max_date.

Parameters:
  • snapshots (list) – full list of SID objects
  • min_date (datetime.date) – minimum date for snapshots to keep
  • max_date (datetime.date) – maximum date for snapshots to keep
  • keep_healthy (bool) – return the first healthy snapshot (not marked as failed) instead of the first at all. If all snapshots failed this will again return the very first snapshot
Returns:

set of snapshots that should be keept

Return type:

set

smartRemoveList(now_full, keep_all, keep_one_per_day, keep_one_per_week, keep_one_per_month)[source]

Get a list of old snapshots that should be removed based on configurable intervals.

Parameters:
  • now_full (datetime.datetime) – date and time when takeSnapshot was started
  • keep_all (int) – keep all snapshots for the last keep_all days
  • keep_one_per_day (int) – keep one snapshot per day for the last keep_one_per_day days
  • keep_one_per_week (int) – keep one snapshot per week for the last keep_one_per_week weeks
  • keep_one_per_month (int) – keep one snapshot per month for the last keep_one_per_month months
Returns:

snapshots that should be removed

Return type:

list

statFreeSpaceLocal(path)[source]

Get free space on filsystem containing path in MiB using os.statvfs(). Depending on remote SFTP server this might fail on sshfs mounted shares.

Parameters:path (str) – full path
Returns:int free space in MiB
statFreeSpaceSsh()[source]

Get free space on remote filsystem in MiB. This will call df on remote host and parse its output.

Returns:int free space in MiB
takeSnapshot(sid, now, include_folders)[source]

This is the main backup routine. It will take a new snapshot and store permissions of included files and folders into fileinfo.bz2.

Parameters:
  • sid (SID) – snapshot ID which the new snapshot should get
  • now (datetime.datetime) – date and time when this snapshot was started
  • include_folders (list) – folders to include. list of tuples (item, int) where int is 0 if item is a folder or 1 if item is a file
Returns:

list of two bool

(ret_val, ret_error) where ret_val is True if a new snapshot has been created and ret_error is True if there was an error during taking the snapshot

Return type:

list

takeSnapshotMessage()[source]
uid(name, callback=None, backup=None)[source]

Get the User identifier (UID) for the user in name. name->uid will be cached to speed up subsequent requests.

Parameters:
  • name (str, bytes) – username to search for
  • callback (method) – callable which will handle a given message
  • backup (int) – UID wich will be used if the username is unknown on this machine
Returns:

UID of the user in name or -1 if not found

Return type:

int

userName(uid)[source]

Get the username for the given uid. uid->name will be cached to speed up subsequent requests.

Parameters:uid (int) – User identifier (UID) to search for
Returns:name of the user with UID uid or ‘-‘ if not found
Return type:str
snapshots.iterSnapshots(cfg, includeNewSnapshot=False)[source]

Iterate over snapshots in current snapshot path. Use this in a ‘for’ loop for faster processing than list object

Parameters:
  • cfg (config.Config) – current config
  • includeNewSnapshot (bool) – include a NewSnapshot instance if ‘new_snapshot’ folder is available.
Yields:

SID – snapshot IDs

snapshots.lastSnapshot(cfg)[source]

Most recent snapshot.

Parameters:cfg (config.Config) – current config (config.Config instance)
Returns:most recent snapshot ID
Return type:SID
snapshots.listSnapshots(cfg, includeNewSnapshot=False, reverse=True)[source]

List of snapshots in current snapshot path.

Parameters:
  • cfg (config.Config) – current config (config.Config instance)
  • includeNewSnapshot (bool) – include a NewSnapshot instance if ‘new_snapshot’ folder is available
  • reverse (bool) – sort reverse
Returns:

list of SID objects

Return type:

list