salt.states.snapper module

Managing implicit state and baselines using snapshots

New in version 2016.11.0.

Salt can manage state against explicitly defined state, for example if your minion state is defined by:

    - source: salt://configs/myconfig

If someone modifies this file, the next application of the highstate will allow the admin to correct this deviation and the file will be corrected.

Now, what happens if somebody creates a file /etc/new_config_file and deletes /etc/important_config_file? Unless you have a explicit rule, this change will go unnoticed.

The snapper state module allows you to manage state implicitly, in addition to explicit rules, in order to define a baseline and iterate with explicit rules as they show that they work in production.

The workflow is: once you have a working and audited system, you would create your baseline snapshot (eg. with salt tgt snapper.create_snapshot) and define in your state this baseline using the identifier of the snapshot (in this case: 20):

    - number: 20
    - include_diff: False
    - ignore:
      - /var/log
      - /var/cache

Baseline snapshots can be also referenced by tag. Most recent baseline snapshot is used in case of multiple snapshots with the same tag:

  • tag: my_custom_baseline_tag
  • config: external
  • ignore: - /mnt/tmp_files/

If you have this state, and you haven't done changes to the system since the snapshot, and you add a user, the state will show you the changes (including full diffs) to /etc/passwd, /etc/shadow, etc if you call it with test=True and will undo all changes if you call it without.

This allows you to add more explicit state knowing that you are starting from a very well defined state, and that you can audit any change that is not part of your explicit configuration.

So after you made this your state, you decided to introduce a change in your configuration:

    - number: 20
    - ignore:
      - /var/log
      - /var/cache

    - name: /etc/hosts
    - content: 'First line of content'
    - append_if_not_found: True

The change in /etc/hosts will be done after any other change that deviates from the specified snapshot are reverted. This could be for example, modifications to the /etc/passwd file or changes in the /etc/hosts that could render your the hosts_entry rule void or dangerous.

Once you take a new snapshot and you update the baseline snapshot number to include the change in /etc/hosts the hosts_entry rule will basically do nothing. You are free to leave it there for documentation, to ensure that the change is made in case the snapshot is wrong, but if you remove anything that comes after the snapper.baseline_snapshot as it will have no effect; by the moment the state is evaluated, the baseline state was already applied and include this change.


Make sure you specify the baseline state before other rules, otherwise the baseline state will revert all changes if they are not present in the snapshot.


Do not specify more than one baseline rule as only the last one will affect the result.

codeauthor:Duncan Mac-Vicar P. <>
codeauthor:Pablo Suárez Hernández <>
salt.states.snapper.baseline_snapshot(name, number=None, tag=None, include_diff=True, config='root', ignore=None)

Enforces that no file is modified comparing against a previously defined snapshot identified by number.

Number of selected baseline snapshot.
Tag of the selected baseline snapshot. Most recent baseline baseline snapshot is used in case of multiple snapshots with the same tag. (tag and number cannot be used at the same time)
Include a diff in the response (Default: True)
Snapper config name (Default: root)
List of files to ignore. (Default: None)