salt.modules.snapper

Module to manage filesystem snapshots with snapper

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 '*' snapper.set_config sync_acl=True

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 overwritten 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