salt.modules.snapper module

Module to manage filesystem snapshots with snapper

New in version 2016.11.0.

codeauthor:Duncan Mac-Vicar P. <dmacvicar@suse.de>
codeauthor:Pablo Suárez Hernández <psuarezhernandez@suse.de>
depends:dbus Python module.
depends:snapper http://snapper.io, available in most distros
maturity:new
platform:Linux
salt.modules.snapper.changed_files(config='root', num_pre=None, num_post=None)

Returns the files changed between two snapshots

config
Configuration name.
num_pre
first snapshot ID to compare. Default is last snapshot
num_post
last snapshot ID to compare. Default is 0 (current state)

CLI example:

salt '*' snapper.changed_files
salt '*' snapper.changed_files num_pre=19 num_post=20
salt.modules.snapper.create_baseline(tag='baseline', config='root')

Creates a snapshot marked as baseline

tag
Tag name for the baseline
config
Configuration name.

CLI Example:

salt '*' snapper.create_baseline
salt '*' snapper.create_baseline my_custom_baseline
salt.modules.snapper.create_config(name=None, subvolume=None, fstype=None, template=None, extra_opts=None)

Creates a new Snapper configuration

name
Name of the new Snapper configuration.
subvolume
Path to the related subvolume.
fstype
Filesystem type of the subvolume.
template
Configuration template to use. (Default: default)
extra_opts
Extra Snapper configuration opts dictionary. It will override the values provided by the given template (if any).

CLI example:

salt '*' snapper.create_config name=myconfig subvolume=/foo/bar/ fstype=btrfs
salt '*' snapper.create_config name=myconfig subvolume=/foo/bar/ fstype=btrfs template="default"
salt '*' snapper.create_config name=myconfig subvolume=/foo/bar/ fstype=btrfs extra_opts='{"NUMBER_CLEANUP": False}'
salt.modules.snapper.create_snapshot(config='root', snapshot_type='single', pre_number=None, description=None, cleanup_algorithm='number', userdata=None, **kwargs)

Creates an snapshot

config
Configuration name.
snapshot_type
Specifies the type of the new snapshot. Possible values are single, pre and post.
pre_number
For post snapshots the number of the pre snapshot must be provided.
description
Description for the snapshot. If not given, the salt job will be used.
cleanup_algorithm
Set the cleanup algorithm for the snapshot.
number
Deletes old snapshots when a certain number of snapshots is reached.
timeline
Deletes old snapshots but keeps a number of hourly, daily, weekly, monthly and yearly snapshots.
empty-pre-post
Deletes pre/post snapshot pairs with empty diffs.
userdata
Set userdata for the snapshot (key-value pairs).

Returns the number of the created snapshot.

CLI example:

salt '*' snapper.create_snapshot
salt.modules.snapper.delete_snapshot(snapshots_ids=None, config='root')

Deletes an snapshot

config
Configuration name. (Default: root)
snapshots_ids
List of the snapshots IDs to be deleted.

CLI example:

salt '*' snapper.delete_snapshot 54
salt '*' snapper.delete_snapshot config=root 54
salt '*' snapper.delete_snapshot config=root snapshots_ids=[54,55,56]
salt.modules.snapper.diff(config='root', filename=None, num_pre=None, num_post=None)

Returns the differences between two snapshots

config
Configuration name.
filename
if not provided the showing differences between snapshots for all "text" files
num_pre
first snapshot ID to compare. Default is last snapshot
num_post
last snapshot ID to compare. Default is 0 (current state)

CLI Example:

salt '*' snapper.diff
salt '*' snapper.diff filename=/var/log/snapper.log num_pre=19 num_post=20
salt.modules.snapper.diff_jid(jid, config='root')

Returns the changes applied by a jid

jid
The job id to lookup
config
Configuration name.

CLI Example:

salt '*' snapper.diff_jid jid=20160607130930720112
salt.modules.snapper.get_config(name='root')

Retrieves all values from a given configuration

CLI example:

salt '*' snapper.get_config
salt.modules.snapper.get_snapshot(number=0, config='root')

Get detailed information about a given snapshot

CLI example:

salt '*' snapper.get_snapshot 1
salt.modules.snapper.list_configs()

List all available configs

CLI example:

salt '*' snapper.list_configs
salt.modules.snapper.list_snapshots(config='root')

List available snapshots

CLI example:

salt '*' snapper.list_snapshots config=myconfig
salt.modules.snapper.modify_snapshot(snapshot_id=None, description=None, userdata=None, cleanup=None, config='root')

Modify attributes of an existing snapshot.

config
Configuration name. (Default: root)
snapshot_id
ID of the snapshot to be modified.
cleanup
Change the cleanup method of the snapshot. (str)
description
Change the description of the snapshot. (str)
userdata
Change the userdata dictionary of the snapshot. (dict)

CLI example:

salt '*' snapper.modify_snapshot 54 description="my snapshot description"
salt '*' snapper.modify_snapshot 54 description="my snapshot description"
salt '*' snapper.modify_snapshot 54 userdata='{"foo": "bar"}'
salt '*' snapper.modify_snapshot snapshot_id=54 cleanup="number"
salt.modules.snapper.run(function, *args, **kwargs)

Runs a function from an execution module creating pre and post snapshots and associating the salt job id with those snapshots for easy undo and cleanup.

function
Salt function to call.
config
Configuration name. (default: "root")
description
A description for the snapshots. (default: None)
userdata
Data to include in the snapshot metadata. (default: None)
cleanup_algorithm
Snapper cleanup algorithm. (default: "number")
*args
args for the function to call. (default: None)
**kwargs
kwargs for the function to call (default: None)

This would run append text to /etc/motd using the file.append module, and will create two snapshots, pre and post with the associated metadata. The jid will be available as salt_jid in the userdata of the snapshot.

You can immediately see the changes

CLI Example:

salt '*' snapper.run file.append args='["/etc/motd", "some text"]'
salt.modules.snapper.set_config(name='root', **kwargs)

Set configuration values

CLI example:

salt '*' snapper.set_config SYNC_ACL=True

Keys are case insensitive as they will be always uppercased to snapper convention. The above example is equivalent to:

salt.modules.snapper.status(config='root', num_pre=None, num_post=None)

Returns a comparison between two snapshots

config
Configuration name.
num_pre
first snapshot ID to compare. Default is last snapshot
num_post
last snapshot ID to compare. Default is 0 (current state)

CLI example:

salt '*' snapper.status
salt '*' snapper.status num_pre=19 num_post=20
salt.modules.snapper.status_to_string(dbus_status)

Converts a numeric dbus snapper status into a string

CLI Example:

salt '*' snapper.status_to_string <dbus_status>
salt.modules.snapper.undo(config='root', files=None, num_pre=None, num_post=None)

Undo all file changes that happened between num_pre and num_post, leaving the files into the state of num_pre.

Warning

If one of the files has changes after num_post, they will be overwriten The snapshots are used to determine the file list, but the current version of the files will be overwritten by the versions in num_pre.

You to undo changes between num_pre and the current version of the files use num_post=0.

CLI Example:

salt '*' snapper.undo
salt.modules.snapper.undo_jid(jid, config='root')

Undo the changes applied by a salt job

jid
The job id to lookup
config
Configuration name.

CLI Example:

salt '*' snapper.undo_jid jid=20160607130930720112