22

✏️ Editing: snapper.py

"""
Module to manage filesystem snapshots with snapper

.. versionadded:: 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
"""

import difflib
import logging
import os
import subprocess
import time

import salt.utils.files
from salt.exceptions import CommandExecutionError

try:
    from pwd import getpwuid

HAS_PWD = True
except ImportError:
    HAS_PWD = False

try:
    import dbus  # pylint: disable=wrong-import-order

HAS_DBUS = True
except ImportError:
    HAS_DBUS = False

DBUS_STATUS_MAP = {
    1: "created",
    2: "deleted",
    4: "type changed",
    8: "modified",
    16: "permission changed",
    32: "owner changed",
    64: "group changed",
    128: "extended attributes changed",
    256: "ACL info changed",
}

SNAPPER_DBUS_OBJECT = "org.opensuse.Snapper"
SNAPPER_DBUS_PATH = "/org/opensuse/Snapper"
SNAPPER_DBUS_INTERFACE = "org.opensuse.Snapper"

log = logging.getLogger(__name__)

# pylint: disable=invalid-name
bus = None
system_bus_error = None
snapper = None
snapper_error = None

if HAS_DBUS:
    try:
        bus = dbus.SystemBus()
    except dbus.DBusException as exc:
        system_bus_error = exc
    else:
        if SNAPPER_DBUS_OBJECT in bus.list_activatable_names():
            try:
                snapper = dbus.Interface(
                    bus.get_object(SNAPPER_DBUS_OBJECT, SNAPPER_DBUS_PATH),
                    dbus_interface=SNAPPER_DBUS_INTERFACE,
                )
            except (dbus.DBusException, ValueError) as exc:
                snapper_error = exc
        else:
            snapper_error = "snapper is missing"
# pylint: enable=invalid-name

def __virtual__():
    error_msg = "The snapper module cannot be loaded: {0}"
    if not HAS_DBUS:
        return False, error_msg.format("missing python dbus module")
    elif not snapper:
        return False, error_msg.format(snapper_error)
    elif not bus:
        return False, error_msg.format(system_bus_error)
    elif not HAS_PWD:
        return False, error_msg.format("pwd module not available")

return "snapper"

def _snapshot_to_data(snapshot):
    """
    Returns snapshot data from a D-Bus response.

A snapshot D-Bus response is a dbus.Struct containing the
    information related to a snapshot:

[id, type, pre_snapshot, timestamp, user, description,
     cleanup_algorithm, userdata]

id: dbus.UInt32
    type: dbus.UInt16
    pre_snapshot: dbus.UInt32
    timestamp: dbus.Int64
    user: dbus.UInt32
    description: dbus.String
    cleaup_algorithm: dbus.String
    userdata: dbus.Dictionary
    """
    data = {}

data["id"] = snapshot[0]
    data["type"] = ["single", "pre", "post"][snapshot[1]]
    if data["type"] == "post":
        data["pre"] = snapshot[2]

if snapshot[3] != -1:
        data["timestamp"] = snapshot[3]
    else:
        data["timestamp"] = int(time.time())

data["user"] = getpwuid(snapshot[4])[0]
    data["description"] = snapshot[5]
    data["cleanup"] = snapshot[6]

data["userdata"] = {}
    for key, value in snapshot[7].items():
        data["userdata"][key] = value

return data

def _dbus_exception_to_reason(exc, args):
    """
    Returns a error message from a snapper DBusException
    """
    error = exc.get_dbus_name()
    if error == "error.unknown_config":
        return "Unknown configuration '{}'".format(args["config"])
    elif error == "error.illegal_snapshot":
        return "Invalid snapshot"
    else:
        return exc.get_dbus_name()

def list_snapshots(config="root"):
    """
    List available snapshots

CLI Example:

.. code-block:: bash

salt '*' snapper.list_snapshots config=myconfig
    """
    try:
        snapshots = snapper.ListSnapshots(config)
        return [_snapshot_to_data(s) for s in snapshots]
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while listing snapshots: {}".format(
                _dbus_exception_to_reason(exc, locals())
            )
        )

def get_snapshot(number=0, config="root"):
    """
    Get detailed information about a given snapshot

CLI Example:

.. code-block:: bash

salt '*' snapper.get_snapshot 1
    """
    try:
        snapshot = snapper.GetSnapshot(config, int(number))
        return _snapshot_to_data(snapshot)
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while retrieving snapshot: {}".format(
                _dbus_exception_to_reason(exc, locals())
            )
        )

def list_configs():
    """
    List all available configs

CLI Example:

.. code-block:: bash

salt '*' snapper.list_configs
    """
    try:
        configs = snapper.ListConfigs()
        return {config[0]: config[2] for config in configs}
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while listing configurations: {}".format(
                _dbus_exception_to_reason(exc, locals())
            )
        )

def _config_filter(value):
    if isinstance(value, bool):
        return "yes" if value else "no"
    return value

def set_config(name="root", **kwargs):
    """
    Set configuration values

CLI Example:

.. code-block:: bash

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:

.. code-block:: bash

salt '*' snapper.set_config sync_acl=True
    """
    try:
        data = {
            k.upper(): _config_filter(v)
            for k, v in kwargs.items()
            if not k.startswith("__")
        }
        snapper.SetConfig(name, data)
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while setting configuration {}: {}".format(
                name, _dbus_exception_to_reason(exc, locals())
            )
        )
    return True

def _get_last_snapshot(config="root"):
    """
    Returns the last existing created snapshot
    """
    snapshot_list = sorted(list_snapshots(config), key=lambda x: x["id"])
    return snapshot_list[-1]

def status_to_string(dbus_status):
    """
    Converts a numeric dbus snapper status into a string

CLI Example:

.. code-block:: bash

salt '*' snapper.status_to_string <dbus_status>
    """
    status_tuple = (
        dbus_status & 0b000000001,
        dbus_status & 0b000000010,
        dbus_status & 0b000000100,
        dbus_status & 0b000001000,
        dbus_status & 0b000010000,
        dbus_status & 0b000100000,
        dbus_status & 0b001000000,
        dbus_status & 0b010000000,
        dbus_status & 0b100000000,
    )

return [DBUS_STATUS_MAP[status] for status in status_tuple if status]

def get_config(name="root"):
    """
    Retrieves all values from a given configuration

CLI Example:

.. code-block:: bash

salt '*' snapper.get_config
    """
    try:
        config = snapper.GetConfig(name)
        return config
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while retrieving configuration: {}".format(
                _dbus_exception_to_reason(exc, locals())
            )
        )

def 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:

.. code-block:: bash

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}'
    """

def raise_arg_error(argname):
        raise CommandExecutionError(
            f'You must provide a "{argname}" for the new configuration'
        )

if not name:
        raise_arg_error("name")
    if not subvolume:
        raise_arg_error("subvolume")
    if not fstype:
        raise_arg_error("fstype")
    if not template:
        template = ""

try:
        snapper.CreateConfig(name, subvolume, fstype, template)
        if extra_opts:
            set_config(name, **extra_opts)
        return get_config(name)
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while creating the new configuration: {}".format(
                _dbus_exception_to_reason(exc, locals())
            )
        )

def 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:

.. code-block:: bash

salt '*' snapper.create_snapshot
    """
    if not userdata:
        userdata = {}

jid = kwargs.get("__pub_jid")
    if description is None and jid is not None:
        description = f"salt job {jid}"

if jid is not None:
        userdata["salt_jid"] = jid

new_nr = None
    try:
        if snapshot_type == "single":
            new_nr = snapper.CreateSingleSnapshot(
                config, description, cleanup_algorithm, userdata
            )
        elif snapshot_type == "pre":
            new_nr = snapper.CreatePreSnapshot(
                config, description, cleanup_algorithm, userdata
            )
        elif snapshot_type == "post":
            if pre_number is None:
                raise CommandExecutionError(
                    "pre snapshot number 'pre_number' needs to be"
                    "specified for snapshots of the 'post' type"
                )
            new_nr = snapper.CreatePostSnapshot(
                config, pre_number, description, cleanup_algorithm, userdata
            )
        else:
            raise CommandExecutionError(f"Invalid snapshot type '{snapshot_type}'")
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while listing changed files: {}".format(
                _dbus_exception_to_reason(exc, locals())
            )
        )
    return new_nr

def 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:

.. code-block:: bash

salt '*' snapper.delete_snapshot 54
        salt '*' snapper.delete_snapshot config=root 54
        salt '*' snapper.delete_snapshot config=root snapshots_ids=[54,55,56]
    """
    if not snapshots_ids:
        raise CommandExecutionError("Error: No snapshot ID has been provided")
    try:
        current_snapshots_ids = [x["id"] for x in list_snapshots(config)]
        if not isinstance(snapshots_ids, list):
            snapshots_ids = [snapshots_ids]
        if not set(snapshots_ids).issubset(set(current_snapshots_ids)):
            raise CommandExecutionError(
                "Error: Snapshots '{}' not found".format(
                    ", ".join(
                        [
                            str(x)
                            for x in set(snapshots_ids).difference(
                                set(current_snapshots_ids)
                            )
                        ]
                    )
                )
            )
        snapper.DeleteSnapshots(config, snapshots_ids)
        return {config: {"ids": snapshots_ids, "status": "deleted"}}
    except dbus.DBusException as exc:
        raise CommandExecutionError(_dbus_exception_to_reason(exc, locals()))

def 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:

.. code-block:: bash

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"
    """
    if not snapshot_id:
        raise CommandExecutionError("Error: No snapshot ID has been provided")

snapshot = get_snapshot(config=config, number=snapshot_id)
    try:
        # Updating only the explicitly provided attributes by the user
        updated_opts = {
            "description": (
                description if description is not None else snapshot["description"]
            ),
            "cleanup": cleanup if cleanup is not None else snapshot["cleanup"],
            "userdata": userdata if userdata is not None else snapshot["userdata"],
        }
        snapper.SetSnapshot(
            config,
            snapshot_id,
            updated_opts["description"],
            updated_opts["cleanup"],
            updated_opts["userdata"],
        )
        return get_snapshot(config=config, number=snapshot_id)
    except dbus.DBusException as exc:
        raise CommandExecutionError(_dbus_exception_to_reason(exc, locals()))

def _get_num_interval(config, num_pre, num_post):
    """
    Returns numerical interval based on optionals num_pre, num_post values
    """
    post = int(num_post) if num_post else 0
    pre = int(num_pre) if num_pre is not None else _get_last_snapshot(config)["id"]
    return pre, post

def _is_text_file(filename):
    """
    Checks if a file is a text file
    """
    type_of_file = subprocess.run(
        ["file", "-bi", filename],
        check=False,
        stdout=subprocess.PIPE,
        text=True,
    ).stdout
    return type_of_file.startswith("text")

def 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:

.. code-block:: bash

salt '*' snapper.run file.append args='["/etc/motd", "some text"]'
    """
    config = kwargs.pop("config", "root")
    description = kwargs.pop("description", f"snapper.run[{function}]")
    cleanup_algorithm = kwargs.pop("cleanup_algorithm", "number")
    userdata = kwargs.pop("userdata", {})

func_kwargs = {k: v for k, v in kwargs.items() if not k.startswith("__")}
    kwargs = {k: v for k, v in kwargs.items() if k.startswith("__")}

pre_nr = __salt__["snapper.create_snapshot"](
        config=config,
        snapshot_type="pre",
        description=description,
        cleanup_algorithm=cleanup_algorithm,
        userdata=userdata,
        **kwargs,
    )

if function not in __salt__:
        raise CommandExecutionError(f'function "{function}" does not exist')

try:
        ret = __salt__[function](*args, **func_kwargs)
    except CommandExecutionError as exc:
        ret = "\n".join([str(exc), __salt__[function].__doc__])

__salt__["snapper.create_snapshot"](
        config=config,
        snapshot_type="post",
        pre_number=pre_nr,
        description=description,
        cleanup_algorithm=cleanup_algorithm,
        userdata=userdata,
        **kwargs,
    )
    return ret

def 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:

.. code-block:: bash

salt '*' snapper.status
        salt '*' snapper.status num_pre=19 num_post=20
    """
    try:
        pre, post = _get_num_interval(config, num_pre, num_post)
        snapper.CreateComparison(config, int(pre), int(post))
        files = snapper.GetFiles(config, int(pre), int(post))
        status_ret = {}
        subvolume = list_configs()[config]["SUBVOLUME"]
        for file in files:
            # In case of SUBVOLUME is included in filepath we remove it
            # to prevent from filepath starting with double '/'
            _filepath = (
                file[0][len(subvolume) :] if file[0].startswith(subvolume) else file[0]
            )
            status_ret[os.path.normpath(subvolume + _filepath)] = {
                "status": status_to_string(file[1])
            }
        return status_ret
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while listing changed files: {}".format(
                _dbus_exception_to_reason(exc, locals())
            )
        )

def 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:

.. code-block:: bash

salt '*' snapper.changed_files
        salt '*' snapper.changed_files num_pre=19 num_post=20
    """
    return status(config, num_pre, num_post).keys()

def 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:

.. code-block:: bash

salt '*' snapper.undo
    """
    pre, post = _get_num_interval(config, num_pre, num_post)

changes = status(config, pre, post)
    changed = set(changes.keys())
    requested = set(files or changed)

if not requested.issubset(changed):
        raise CommandExecutionError(
            "Given file list contains files that are not present"
            "in the changed filelist: {}".format(changed - requested)
        )

cmdret = __salt__["cmd.run"](
        "snapper -c {} undochange {}..{} {}".format(
            config, pre, post, " ".join(requested)
        )
    )

try:
        components = cmdret.split(" ")
        ret = {}
        for comp in components:
            key, val = comp.split(":")
            ret[key] = val
        return ret
    except ValueError as exc:
        raise CommandExecutionError(
            f"Error while processing Snapper response: {cmdret}"
        )

def _get_jid_snapshots(jid, config="root"):
    """
    Returns pre/post snapshots made by a given Salt jid

Looks for 'salt_jid' entries into snapshots userdata which are created
    when 'snapper.run' is executed.
    """
    jid_snapshots = [
        x for x in list_snapshots(config) if x["userdata"].get("salt_jid") == jid
    ]
    pre_snapshot = [x for x in jid_snapshots if x["type"] == "pre"]
    post_snapshot = [x for x in jid_snapshots if x["type"] == "post"]

if not pre_snapshot or not post_snapshot:
        raise CommandExecutionError(f"Jid '{jid}' snapshots not found")

return (pre_snapshot[0]["id"], post_snapshot[0]["id"])

def undo_jid(jid, config="root"):
    """
    Undo the changes applied by a salt job

jid
        The job id to lookup

config
        Configuration name.

CLI Example:

.. code-block:: bash

salt '*' snapper.undo_jid jid=20160607130930720112
    """
    pre_snapshot, post_snapshot = _get_jid_snapshots(jid, config=config)
    return undo(config, num_pre=pre_snapshot, num_post=post_snapshot)

def 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:

.. code-block:: bash

salt '*' snapper.diff
        salt '*' snapper.diff filename=/var/log/snapper.log num_pre=19 num_post=20
    """
    try:
        pre, post = _get_num_interval(config, num_pre, num_post)

files = changed_files(config, pre, post)
        if filename:
            files = [filename] if filename in files else []

subvolume = list_configs()[config]["SUBVOLUME"]
        pre_mount = snapper.MountSnapshot(config, pre, False) if pre else subvolume
        post_mount = snapper.MountSnapshot(config, post, False) if post else subvolume

files_diff = dict()
        for filepath in [filepath for filepath in files if not os.path.isdir(filepath)]:

_filepath = filepath
            if filepath.startswith(subvolume):
                _filepath = filepath[len(subvolume) :]

# Just in case, removing possible double '/' from the final file paths
            pre_file = os.path.normpath(pre_mount + "/" + _filepath).replace("//", "/")
            post_file = os.path.normpath(post_mount + "/" + _filepath).replace(
                "//", "/"
            )

if os.path.isfile(pre_file):
                pre_file_exists = True
                with salt.utils.files.fopen(pre_file) as rfh:
                    pre_file_content = [
                        salt.utils.stringutils.to_unicode(_l) for _l in rfh.readlines()
                    ]
            else:
                pre_file_content = []
                pre_file_exists = False

if os.path.isfile(post_file):
                post_file_exists = True
                with salt.utils.files.fopen(post_file) as rfh:
                    post_file_content = [
                        salt.utils.stringutils.to_unicode(_l) for _l in rfh.readlines()
                    ]
            else:
                post_file_content = []
                post_file_exists = False

if _is_text_file(pre_file) or _is_text_file(post_file):
                files_diff[filepath] = {
                    "comment": "text file changed",
                    "diff": "".join(
                        difflib.unified_diff(
                            pre_file_content,
                            post_file_content,
                            fromfile=pre_file,
                            tofile=post_file,
                        )
                    ),
                }

if pre_file_exists and not post_file_exists:
                    files_diff[filepath]["comment"] = "text file deleted"
                if not pre_file_exists and post_file_exists:
                    files_diff[filepath]["comment"] = "text file created"

elif not _is_text_file(pre_file) and not _is_text_file(post_file):
                # This is a binary file
                files_diff[filepath] = {"comment": "binary file changed"}
                if pre_file_exists:
                    files_diff[filepath]["old_sha256_digest"] = __salt__[
                        "hashutil.sha256_digest"
                    ]("".join(pre_file_content))
                if post_file_exists:
                    files_diff[filepath]["new_sha256_digest"] = __salt__[
                        "hashutil.sha256_digest"
                    ]("".join(post_file_content))
                if post_file_exists and not pre_file_exists:
                    files_diff[filepath]["comment"] = "binary file created"
                if pre_file_exists and not post_file_exists:
                    files_diff[filepath]["comment"] = "binary file deleted"

if pre:
            snapper.UmountSnapshot(config, pre, False)
        if post:
            snapper.UmountSnapshot(config, post, False)
        return files_diff
    except dbus.DBusException as exc:
        raise CommandExecutionError(
            "Error encountered while showing differences between snapshots: {}".format(
                _dbus_exception_to_reason(exc, locals())
            )
        )

def diff_jid(jid, config="root"):
    """
    Returns the changes applied by a `jid`

jid
        The job id to lookup

config
        Configuration name.

CLI Example:

.. code-block:: bash

salt '*' snapper.diff_jid jid=20160607130930720112
    """
    pre_snapshot, post_snapshot = _get_jid_snapshots(jid, config=config)
    return diff(config, num_pre=pre_snapshot, num_post=post_snapshot)

def create_baseline(tag="baseline", config="root"):
    """
    Creates a snapshot marked as baseline

tag
        Tag name for the baseline

config
        Configuration name.

CLI Example:

.. code-block:: bash

salt '*' snapper.create_baseline
        salt '*' snapper.create_baseline my_custom_baseline
    """
    return __salt__["snapper.create_snapshot"](
        config=config,
        snapshot_type="single",
        description="baseline snapshot",
        cleanup_algorithm="number",
        userdata={"baseline_tag": tag},
    )

MR SKB