snapshots module
- class snapshots.FileInfoDict[source]
Bases:
dict
A
dict
that maps a path (asbytes
) to a tuple (int
,bytes
,bytes
).
- class snapshots.GenericNonSnapshot(date, cfg)[source]
Bases:
SID
- property displayID
Snapshot ID in a user-readable format: YYYY-MM-DD HH:MM:SS
- Returns:
formatted sID
- Return type:
- property displayName
Combination of displayID, name and error indicator (if any)
- Returns:
name
- Return type:
- class snapshots.NewSnapshot(cfg)[source]
Bases:
GenericNonSnapshot
Snapshot ID object for ‘new_snapshot’ folder
- Parameters:
cfg (config.Config) – current config
- NEWSNAPSHOT = 'new_snapshot'
- SAVETOCONTINUE = 'save_to_continue'
- property hasChanges
Check if there where changes in previous sessions.
- Returns:
True
if there where changes- Return type:
- class snapshots.RootSnapshot(cfg)[source]
Bases:
GenericNonSnapshot
Snapshot ID for the filesystem root folder (‘/’)
- Parameters:
cfg (config.Config) – current config
- class snapshots.SID(date, cfg)[source]
Bases:
object
Snapshot ID object used to gather all information for a snapshot
See
Snapshots
to understand the difference.- Parameters:
date (
str
,datetime.date
ordatetime.datetime
) – used for creating this snapshot. str must be in snapshot ID format (e.g 20151218-173512-123)cfg (config.Config) – current config
- Raises:
ValueError – if
date
isstr
instance and doesn’t match the snapshot ID format (20151218-173512-123 or 20151218-173512)TypeError – if
date
is notstr
,datetime.date
ordatetime.datetime
type
- FAILED = 'failed'
- FILEINFO = 'fileinfo.bz2'
- INFO = 'info'
- LOG = 'takesnapshot.log.bz2'
- NAME = 'name'
- property displayID
Snapshot ID in a user-readable format: YYYY-MM-DD HH:MM:SS
- Returns:
formatted sID
- Return type:
- property displayName
Combination of displayID, name and error indicator (if any)
- Returns:
name
- Return type:
- exists()[source]
True
if the snapshot folder and the “backup” folder inside exist- Returns:
True
if exists- Return type:
- property failed
This snapshot has failed
- property fileInfo
Load/save “fileinfo.bz2”
- Parameters:
d (FileInfoDict) – dict of: {path: (permission, user, group)}
- Returns:
dict of: {path: (permission, user, group)}
- Return type:
- property 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:
- property 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:
- log(mode=None, decode=None)[source]
Load log from “takesnapshot.log.bz2”
- Parameters:
mode (int) – Mode used for filtering. Take a look at
snapshotlog.LogFilter
decode (encfstools.Decode) – instance used for decoding lines or
None
- Yields:
str – filtered and decoded log lines
- makeWritable()[source]
Make the snapshot path writable so we can change files inside
- Returns:
True
if successful- Return type:
- property name
Name of this snapshot
- path(*path, use_mode=[])[source]
Current path of this snapshot automatically altered for remote/encrypted version of this path
- Parameters:
- Returns:
full snapshot path
- Return type:
- pathBackup(*path, **kwargs)[source]
‘backup’ folder inside snapshots path
- Parameters:
- Returns:
full snapshot path
- Return type:
- setLastChecked()[source]
Set info files atime to current time to indicate this snapshot was checked against source without changes right now.
- class snapshots.Snapshots(cfg=None)[source]
Bases:
object
Collection of take-snapshot and restore commands.
BUHTZ 2022-10-09: In my understanding this is the representation of a snapshot in the “application layer”. This seems to be the difference to the class SID which represents a snapshot in the “data layer”.
BUHTZ 2024-02-23: Not sure but it seems to be one concret snapshot and not a collection of snapshots. In this case the class name is misleading because it is in plural form.
- Parameters:
cfg (config.Config) – current config
- SNAPSHOT_VERSION = 3
- _backup_info_file(sid)[source]
Save infos about the snapshot into the ‘info’ file. The result is stored in ‘sid.info’ also.
- Parameters:
sid (SID) – Snapshot that should get the info file.
- backup(force=False)[source]
Wrapper for
takeSnapshot()
which will prepare and clean up things for the maintakeSnapshot()
method.This will check that no other snapshots are running at the same time, there is nothing prohibiting a new snapshot (e.g. on battery) and the profile is configured correctly. This will also mount and unmount remote destinations.
- backupConfig(sid)[source]
Backup the config file to the snapshot and to the backup root if backup is encrypted.
- Parameters:
sid (SID) – snapshot in which the config should be stored
- backupPermissions(sid)[source]
Save permissions (owner, group, read-, write- and executable) for all files in Snapshot
sid
into snapshots fileInfoDict.
- backupPermissionsCallback(line, user_data)[source]
Rsync callback for
Snapshots.backupPermissions()
.- Parameters:
line (bytes) – output from rsync command
user_data (tuple) – two item tuple of (
FileInfoDict
,encfstools.Decode
)
- backupSuffix()[source]
Get suffix for backup files.
- Returns:
backup suffix in form of ‘.backup.YYYYMMDD’
- Return type:
- collectPermission(fileinfo, path)[source]
Collect permission infos about
path
and store them intofileinfo
.- 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
- decMonth(date)[source]
First day of previous month of
date
with respect on previous years. So ifdate
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:
- filter(base_sid, base_path, snapshotsList, list_diff_only=False, flag_deep_check=False, list_equal_to='')[source]
Filter snapshots from
snapshotsList
based on whetherbase_path
file is included and optional if the snapshot is unique or equal tolist_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 filteredlist_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 listedflag_deep_check (bool) – use md5sum to check uniqueness of files. More accurate 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:
- filterRsyncProgress(line)[source]
Filter rsync’s stdout for progress information and store them in ‘~/.local/share/backintime/worker<N>.progress’ file.
- 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.
- groupName(gid)[source]
Get the groupname for the given gid. gid->name will be cached to speed up subsequent requests.
- incMonth(date)[source]
First day of next month of
date
with respect on new years. So ifdate
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:
- makeDirs(path)[source]
Wrapper for
tools.makeDirs()
. Create directoriespath
recursive and return success. If not successful send error-message to log.
- remove(sid)[source]
Remove snapshot
sid
.BUHTZ 2022-10-11: From my understanding rsync is used here to sync the directory of a concrete snapshot (
sid
) against an empty temporary directory. In the consequence the sid directory is empty but not deleted. To delete that directory simple rm call (via shutil package) is used to delete the directory. No need to do this via SSH because the directory is temporary mounted.It is not clear for me why it is done that way. Why not simply “rm” the directory when it is mounted instead of using rsync in a previous step?! But I won’t change it yet.
- 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 fromfileinfo.bz2
.- Parameters:
sid (SID) – snapshot from whom to restore
paths (
list
,tuple
orstr
) – 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 runcallback (method) – callable instance which will handle messages
restore_to (str) – full path to restore to. If empty restore to original destination
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 do 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.
- 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]’. Uses a side effect by changing list items here to change the original list of the caller, too (lists are passed as reference in Python). If rsync reported an error
params[0]
will be set toTrue
. If rsync reported a changed fileparams[1]
will be set toTrue
- rsyncExclude(excludeFolders=None)[source]
Format exclude list for rsync
- Parameters:
excludeFolders (list) – list of folders to exclude
- Returns:
rsync exclude options
- Return type:
- 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.
- rsyncRemotePath(path, use_mode=['ssh', 'ssh_encfs'], quote='"')[source]
Format the destination string for rsync depending on which profile is used.
- Parameters:
- 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 andpath
like ‘’user@host:”/foo”’’
- quoted
- Return type:
- setTakeSnapshotMessage(type_id, message, timeout=-1)[source]
Update the status message of the active snapshot creation job
Write the status message into a message file to allow async processing for the GUI, plug-ins (like user-callback) and desktop notifications.
- Parameters:
type_id – Simplified severity level of the status message: 0: INFO 1: ERROR other values: defaults to INFO (may change in the future)
message – status message string
timeout – Requested maximum processing duration in plug-ins. Default: -1 (no limit) Called plug-ins must try to keep the timeout itself (it is not enforced by the
PluginManager
. In fact currently all known plug-ins do ignore the timeout value!
- 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.
- smartRemoveKeepAll(snapshots, min_date, max_date)[source]
Return all snapshots between
min_date
andmax_date
.- Parameters:
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 kept
- Return type:
- smartRemoveKeepFirst(snapshots, min_date, max_date, keep_healthy=False)[source]
Return only the first snapshot between
min_date
andmax_date
.- Parameters:
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 kept
- Return type:
- 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
dayskeep_one_per_day (int) – keep one snapshot per day for the last
keep_one_per_day
dayskeep_one_per_week (int) – keep one snapshot per week for the last
keep_one_per_week
weekskeep_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:
- statFreeSpaceLocal(path)[source]
Get free space on filesystem containing
path
in MiB usingos.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 filesystem 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 ifitem
is a folder or 1 ifitem
is a file
- Returns:
- list of two bool (
ret_val
,ret_error
) where ret_val
isTrue
if a new snapshot has been created andret_error
isTrue
if there was an error during taking the snapshot
- list of two bool (
- Return type:
- takeSnapshotMessage()[source]
Get the current message from the message file.
- Returns:
- The message type and its string or None. See
setTakeSnapshotMessage() for further details.
- Return type:
- Dev note (buhtz):
Too many try..excepts in here.
- snapshots.iterSnapshots(cfg, includeNewSnapshot=False)[source]
A generator to iterate over snapshots in current snapshot path.
- 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:
- 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: