# salt.modules.snapper

Module to manage filesystem snapshots with snapper

Added 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 '*' 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