22

✏️ Editing: opkg.py

"""
Support for Opkg

.. important::
    If you feel that Salt should be using this module to manage packages on a
    minion, and it is using a different module (or gives an error similar to
    *'pkg.install' is not available*), see :ref:`here
    <module-provider-override>`.

.. versionadded:: 2016.3.0

.. note::

For version comparison support on opkg < 0.3.4, the ``opkg-utils`` package
    must be installed.

"""

import copy
import errno
import logging
import os
import pathlib
import re
import shlex

import salt.utils.args
import salt.utils.data
import salt.utils.files
import salt.utils.itertools
import salt.utils.path
import salt.utils.pkg
import salt.utils.stringutils
import salt.utils.versions
from salt.exceptions import CommandExecutionError, MinionError, SaltInvocationError
from salt.utils.versions import Version

REPO_REGEXP = r'^#?\s*(src|src/gz)\s+([^\s<>]+|"[^<>]+")\s+[^\s<>]+'
OPKG_CONFDIR = "/etc/opkg"
ATTR_MAP = {
    "Architecture": "arch",
    "Homepage": "url",
    "Installed-Time": "install_date_time_t",
    "Maintainer": "packager",
    "Package": "name",
    "Section": "group",
}

log = logging.getLogger(__name__)

# Define the module's virtual name
__virtualname__ = "pkg"

NILRT_RESTARTCHECK_STATE_PATH = "/var/lib/salt/restartcheck_state"

def _get_nisysapi_conf_d_path():
    return "/usr/lib/{}/nisysapi/conf.d/experts/".format(
        "arm-linux-gnueabi"
        if "arm" in __grains__.get("cpuarch")
        else "x86_64-linux-gnu"
    )

def _update_nilrt_restart_state():
    """
    NILRT systems determine whether to reboot after various package operations
    including but not limited to kernel module installs/removals by checking
    specific file md5sums & timestamps. These files are touched/modified by
    the post-install/post-remove functions of their respective packages.

The opkg module uses this function to store/update those file timestamps
    and checksums to be used later by the restartcheck module.

"""
    # TODO: This stat & md5sum should be replaced with _fingerprint_file call -W. Werner, 2020-08-18
    uname = __salt__["cmd.run_stdout"]("uname -r")
    __salt__["cmd.shell"](
        "stat -c %Y /lib/modules/{}/modules.dep >{}/modules.dep.timestamp".format(
            uname, NILRT_RESTARTCHECK_STATE_PATH
        )
    )
    __salt__["cmd.shell"](
        "md5sum /lib/modules/{}/modules.dep >{}/modules.dep.md5sum".format(
            uname, NILRT_RESTARTCHECK_STATE_PATH
        )
    )

# We can't assume nisysapi.ini always exists like modules.dep
    nisysapi_path = "/usr/local/natinst/share/nisysapi.ini"
    if os.path.exists(nisysapi_path):
        # TODO: This stat & md5sum should be replaced with _fingerprint_file call -W. Werner, 2020-08-18
        __salt__["cmd.shell"](
            "stat -c %Y {} >{}/nisysapi.ini.timestamp".format(
                nisysapi_path, NILRT_RESTARTCHECK_STATE_PATH
            )
        )
        __salt__["cmd.shell"](
            "md5sum {} >{}/nisysapi.ini.md5sum".format(
                nisysapi_path, NILRT_RESTARTCHECK_STATE_PATH
            )
        )

# Expert plugin files get added to a conf.d dir, so keep track of the total
    # no. of files, their timestamps and content hashes
    nisysapi_conf_d_path = _get_nisysapi_conf_d_path()

if os.path.exists(nisysapi_conf_d_path):
        with salt.utils.files.fopen(
            f"{NILRT_RESTARTCHECK_STATE_PATH}/sysapi.conf.d.count", "w"
        ) as fcount:
            fcount.write(str(len(os.listdir(nisysapi_conf_d_path))))

for fexpert in os.listdir(nisysapi_conf_d_path):
            _fingerprint_file(
                filename=pathlib.Path(nisysapi_conf_d_path, fexpert),
                fingerprint_dir=pathlib.Path(NILRT_RESTARTCHECK_STATE_PATH),
            )

def _fingerprint_file(*, filename, fingerprint_dir):
    """
    Compute stat & md5sum hash of provided ``filename``. Store
    the hash and timestamp in ``fingerprint_dir``.

filename
        ``Path`` to the file to stat & hash.

fingerprint_dir
        ``Path`` of the directory to store the stat and hash output files.
    """
    __salt__["cmd.shell"](
        "stat -c %Y {} > {}/{}.timestamp".format(
            filename, fingerprint_dir, filename.name
        )
    )
    __salt__["cmd.shell"](
        f"md5sum {filename} > {fingerprint_dir}/{filename.name}.md5sum"
    )

def _get_restartcheck_result(errors):
    """
    Return restartcheck result and append errors (if any) to ``errors``
    """
    rs_result = __salt__["restartcheck.restartcheck"](verbose=False)
    if isinstance(rs_result, dict) and "comment" in rs_result:
        errors.append(rs_result["comment"])
    return rs_result

def _process_restartcheck_result(rs_result):
    """
    Check restartcheck output to see if system/service restarts were requested
    and take appropriate action.
    """
    if "No packages seem to need to be restarted" in rs_result:
        return
    for rstr in rs_result:
        if "System restart required" in rstr:
            _update_nilrt_restart_state()
            __salt__["system.set_reboot_required_witnessed"]()
        else:
            service = os.path.join("/etc/init.d", rstr)
            if os.path.exists(service):
                __salt__["cmd.run"]([service, "restart"])

def __virtual__():
    """
    Confirm this module is on a nilrt based system
    """
    if __grains__.get("os_family") == "NILinuxRT":
        try:
            os.makedirs(NILRT_RESTARTCHECK_STATE_PATH)
        except OSError as exc:
            if exc.errno != errno.EEXIST:
                return (
                    False,
                    "Error creating {} (-{}): {}".format(
                        NILRT_RESTARTCHECK_STATE_PATH, exc.errno, exc.strerror
                    ),
                )
        # populate state dir if empty
        if not os.listdir(NILRT_RESTARTCHECK_STATE_PATH):
            _update_nilrt_restart_state()
        return __virtualname__

if os.path.isdir(OPKG_CONFDIR):
        return __virtualname__
    return False, "Module opkg only works on OpenEmbedded based systems"

def latest_version(*names, **kwargs):
    """
    Return the latest version of the named package available for upgrade or
    installation. If more than one package name is specified, a dict of
    name/version pairs is returned.

If the latest version of a given package is already installed, an empty
    string will be returned for that package.

CLI Example:

.. code-block:: bash

salt '*' pkg.latest_version <package name>
        salt '*' pkg.latest_version <package name>
        salt '*' pkg.latest_version <package1> <package2> <package3> ...
    """
    refresh = salt.utils.data.is_true(kwargs.pop("refresh", True))

if not names:
        return ""

ret = {}
    for name in names:
        ret[name] = ""

# Refresh before looking for the latest version available
    if refresh:
        refresh_db()

cmd = ["opkg", "list-upgradable"]
    out = __salt__["cmd.run_stdout"](cmd, output_loglevel="trace", python_shell=False)
    for line in salt.utils.itertools.split(out, "\n"):
        try:
            name, _oldversion, newversion = line.split(" - ")
            if name in names:
                ret[name] = newversion
        except ValueError:
            pass

# Return a string if only one package name passed
    if len(names) == 1:
        return ret[names[0]]
    return ret

# available_version is being deprecated
available_version = latest_version

def version(*names, **kwargs):
    """
    Returns a string representing the package version or an empty string if not
    installed. If more than one package name is specified, a dict of
    name/version pairs is returned.

CLI Example:

.. code-block:: bash

salt '*' pkg.version <package name>
        salt '*' pkg.version <package1> <package2> <package3> ...
    """
    return __salt__["pkg_resource.version"](*names, **kwargs)

def refresh_db(failhard=False, **kwargs):  # pylint: disable=unused-argument
    """
    Updates the opkg database to latest packages based upon repositories

Returns a dict, with the keys being package databases and the values being
    the result of the update attempt. Values can be one of the following:

- ``True``: Database updated successfully
    - ``False``: Problem updating database

failhard
        If False, return results of failed lines as ``False`` for the package
        database that encountered the error.
        If True, raise an error with a list of the package databases that
        encountered errors.

.. versionadded:: 2018.3.0

CLI Example:

.. code-block:: bash

salt '*' pkg.refresh_db
    """
    # Remove rtag file to keep multiple refreshes from happening in pkg states
    salt.utils.pkg.clear_rtag(__opts__)
    ret = {}
    error_repos = []
    cmd = ["opkg", "update"]
    # opkg returns a non-zero retcode when there is a failure to refresh
    # from one or more repos. Due to this, ignore the retcode.
    call = __salt__["cmd.run_all"](
        cmd,
        output_loglevel="trace",
        python_shell=False,
        ignore_retcode=True,
        redirect_stderr=True,
    )

out = call["stdout"]
    prev_line = ""
    for line in salt.utils.itertools.split(out, "\n"):
        if "Inflating" in line:
            key = line.strip().split()[1][:-1]
            ret[key] = True
        elif "Updated source" in line:
            # Use the previous line.
            key = prev_line.strip().split()[1][:-1]
            ret[key] = True
        elif "Failed to download" in line:
            key = line.strip().split()[5].split(",")[0]
            ret[key] = False
            error_repos.append(key)
        prev_line = line

if failhard and error_repos:
        raise CommandExecutionError(
            "Error getting repos: {}".format(", ".join(error_repos))
        )

# On a non-zero exit code where no failed repos were found, raise an
    # exception because this appears to be a different kind of error.
    if call["retcode"] != 0 and not error_repos:
        raise CommandExecutionError(out)

return ret

def _is_testmode(**kwargs):
    """
    Returns whether a test mode (noaction) operation was requested.
    """
    return bool(kwargs.get("test") or __opts__.get("test"))

def _append_noaction_if_testmode(cmd, **kwargs):
    """
    Adds the --noaction flag to the command if it's running in the test mode.
    """
    if _is_testmode(**kwargs):
        cmd.append("--noaction")

def _build_install_command_list(cmd_prefix, to_install, to_downgrade, to_reinstall):
    """
    Builds a list of install commands to be executed in sequence in order to process
    each of the to_install, to_downgrade, and to_reinstall lists.
    """
    cmds = []
    if to_install:
        cmd = copy.deepcopy(cmd_prefix)
        cmd.extend(to_install)
        cmds.append(cmd)
    if to_downgrade:
        cmd = copy.deepcopy(cmd_prefix)
        cmd.append("--force-downgrade")
        cmd.extend(to_downgrade)
        cmds.append(cmd)
    if to_reinstall:
        cmd = copy.deepcopy(cmd_prefix)
        cmd.append("--force-reinstall")
        cmd.extend(to_reinstall)
        cmds.append(cmd)

return cmds

def _parse_reported_packages_from_install_output(output):
    """
    Parses the output of "opkg install" to determine what packages would have been
    installed by an operation run with the --noaction flag.

We are looking for lines like:
        Installing <package> (<version>) on <target>
    or
        Upgrading <package> from <oldVersion> to <version> on root
    """
    reported_pkgs = {}
    install_pattern = re.compile(
        r"Installing\s(?P<package>.*?)\s\((?P<version>.*?)\)\son\s(?P<target>.*?)"
    )
    upgrade_pattern = re.compile(
        r"Upgrading\s(?P<package>.*?)\sfrom\s(?P<oldVersion>.*?)\sto\s(?P<version>.*?)\son\s(?P<target>.*?)"
    )
    for line in salt.utils.itertools.split(output, "\n"):
        match = install_pattern.match(line)
        if match is None:
            match = upgrade_pattern.match(line)
        if match:
            reported_pkgs[match.group("package")] = match.group("version")

return reported_pkgs

def _execute_install_command(cmd, parse_output, errors, parsed_packages):
    """
    Executes a command for the install operation.
    If the command fails, its error output will be appended to the errors list.
    If the command succeeds and parse_output is true, updated packages will be appended
    to the parsed_packages dictionary.
    """
    out = __salt__["cmd.run_all"](cmd, output_loglevel="trace", python_shell=False)
    if out["retcode"] != 0:
        if out["stderr"]:
            errors.append(out["stderr"])
        else:
            errors.append(out["stdout"])
    elif parse_output:
        parsed_packages.update(
            _parse_reported_packages_from_install_output(out["stdout"])
        )

def install(
    name=None, refresh=False, pkgs=None, sources=None, reinstall=False, **kwargs
):
    """
    Install the passed package, add refresh=True to update the opkg database.

name
        The name of the package to be installed. Note that this parameter is
        ignored if either "pkgs" or "sources" is passed. Additionally, please
        note that this option can only be used to install packages from a
        software repository. To install a package file manually, use the
        "sources" option.

CLI Example:

.. code-block:: bash

salt '*' pkg.install <package name>

refresh
        Whether or not to refresh the package database before installing.

version
        Install a specific version of the package, e.g. 1.2.3~0ubuntu0. Ignored
        if "pkgs" or "sources" is passed.

.. note::
            Remember that versions that contain a single `.` will be interpreted
            as numbers and must be double-quoted. For example, version
            ``3006.10`` will be rendered as ``3006.1``. To pass ``3006.10``
            you'll need to use double-quotes. ``version="'3006.10'"``

.. versionadded:: 2017.7.0

reinstall : False
        Specifying reinstall=True will use ``opkg install --force-reinstall``
        rather than simply ``opkg install`` for requested packages that are
        already installed.

If a version is specified with the requested package, then ``opkg
        install --force-reinstall`` will only be used if the installed version
        matches the requested version.

.. versionadded:: 2017.7.0

Multiple Package Installation Options:

pkgs
        A list of packages to install from a software repository. Must be
        passed as a python list.

CLI Example:

.. code-block:: bash

salt '*' pkg.install pkgs='["foo", "bar"]'
            salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-0ubuntu0"}]'

sources
        A list of IPK packages to install. Must be passed as a list of dicts,
        with the keys being package names, and the values being the source URI
        or local path to the package.  Dependencies are automatically resolved
        and marked as auto-installed.

CLI Example:

.. code-block:: bash

salt '*' pkg.install sources='[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]'

install_recommends
        Whether to install the packages marked as recommended. Default is True.

only_upgrade
        Only upgrade the packages (disallow downgrades), if they are already
        installed. Default is False.

.. versionadded:: 2017.7.0

Returns a dict containing the new package names and versions::

{'<package>': {'old': '<old-version>',
                       'new': '<new-version>'}}
    """
    refreshdb = salt.utils.data.is_true(refresh)

try:
        pkg_params, pkg_type = __salt__["pkg_resource.parse_targets"](
            name, pkgs, sources, **kwargs
        )
    except MinionError as exc:
        raise CommandExecutionError(exc)

old = list_pkgs()
    cmd_prefix = ["opkg", "install"]
    to_install = []
    to_reinstall = []
    to_downgrade = []

_append_noaction_if_testmode(cmd_prefix, **kwargs)
    if not pkg_params:
        return {}
    elif pkg_type == "file":
        if reinstall:
            cmd_prefix.append("--force-reinstall")
        if not kwargs.get("only_upgrade", False):
            cmd_prefix.append("--force-downgrade")
        to_install.extend(pkg_params)
    elif pkg_type == "repository":
        if not kwargs.get("install_recommends", True):
            cmd_prefix.append("--no-install-recommends")
        for pkgname, pkgversion in pkg_params.items():
            if name and pkgs is None and kwargs.get("version") and len(pkg_params) == 1:
                # Only use the 'version' param if 'name' was not specified as a
                # comma-separated list
                version_num = kwargs["version"]
            else:
                version_num = pkgversion

if version_num is None:
                # Don't allow downgrades if the version
                # number is not specified.
                if reinstall and pkgname in old:
                    to_reinstall.append(pkgname)
                else:
                    to_install.append(pkgname)
            else:
                pkgstr = f"{pkgname}={version_num}"
                cver = old.get(pkgname, "")
                if (
                    reinstall
                    and cver
                    and salt.utils.versions.compare(
                        ver1=version_num, oper="==", ver2=cver, cmp_func=version_cmp
                    )
                ):
                    to_reinstall.append(pkgstr)
                elif not cver or salt.utils.versions.compare(
                    ver1=version_num, oper=">=", ver2=cver, cmp_func=version_cmp
                ):
                    to_install.append(pkgstr)
                else:
                    if not kwargs.get("only_upgrade", False):
                        to_downgrade.append(pkgstr)
                    else:
                        # This should cause the command to fail.
                        to_install.append(pkgstr)

cmds = _build_install_command_list(
        cmd_prefix, to_install, to_downgrade, to_reinstall
    )

if not cmds:
        return {}

if refreshdb:
        refresh_db()

errors = []
    is_testmode = _is_testmode(**kwargs)
    test_packages = {}
    for cmd in cmds:
        _execute_install_command(cmd, is_testmode, errors, test_packages)

__context__.pop("pkg.list_pkgs", None)
    new = list_pkgs()
    if is_testmode:
        new = copy.deepcopy(new)
        new.update(test_packages)

ret = salt.utils.data.compare_dicts(old, new)

if pkg_type == "file" and reinstall:
        # For file-based packages, prepare 'to_reinstall' to have a list
        # of all the package names that may have been reinstalled.
        # This way, we could include reinstalled packages in 'ret'.
        for pkgfile in to_install:
            # Convert from file name to package name.
            cmd = ["opkg", "info", pkgfile]
            out = __salt__["cmd.run_all"](
                cmd, output_loglevel="trace", python_shell=False
            )
            if out["retcode"] == 0:
                # Just need the package name.
                pkginfo_dict = _process_info_installed_output(out["stdout"], [])
                if pkginfo_dict:
                    to_reinstall.append(next(iter(pkginfo_dict)))

for pkgname in to_reinstall:
        if pkgname not in ret or pkgname in old:
            ret.update(
                {pkgname: {"old": old.get(pkgname, ""), "new": new.get(pkgname, "")}}
            )

rs_result = _get_restartcheck_result(errors)

if errors:
        raise CommandExecutionError(
            "Problem encountered installing package(s)",
            info={"errors": errors, "changes": ret},
        )

_process_restartcheck_result(rs_result)

return ret

def _parse_reported_packages_from_remove_output(output):
    """
    Parses the output of "opkg remove" to determine what packages would have been
    removed by an operation run with the --noaction flag.

We are looking for lines like
        Removing <package> (<version>) from <Target>...
    """
    reported_pkgs = {}
    remove_pattern = re.compile(
        r"Removing\s(?P<package>.*?)\s\((?P<version>.*?)\)\sfrom\s(?P<target>.*?)..."
    )
    for line in salt.utils.itertools.split(output, "\n"):
        match = remove_pattern.match(line)
        if match:
            reported_pkgs[match.group("package")] = ""

return reported_pkgs

def remove(name=None, pkgs=None, **kwargs):  # pylint: disable=unused-argument
    """
    Remove packages using ``opkg remove``.

name
        The name of the package to be deleted.

Multiple Package Options:

pkgs
        A list of packages to delete. Must be passed as a python list. The
        ``name`` parameter will be ignored if this option is passed.

remove_dependencies
        Remove package and all dependencies

.. versionadded:: 2019.2.0

auto_remove_deps
        Remove packages that were installed automatically to satisfy dependencies

.. versionadded:: 2019.2.0

Returns a dict containing the changes.

CLI Example:

.. code-block:: bash

salt '*' pkg.remove <package name>
        salt '*' pkg.remove <package1>,<package2>,<package3>
        salt '*' pkg.remove pkgs='["foo", "bar"]'
        salt '*' pkg.remove pkgs='["foo", "bar"]' remove_dependencies=True auto_remove_deps=True
    """
    try:
        pkg_params = __salt__["pkg_resource.parse_targets"](name, pkgs)[0]
    except MinionError as exc:
        raise CommandExecutionError(exc)

old = list_pkgs()
    targets = [x for x in pkg_params if x in old]
    if not targets:
        return {}
    cmd = ["opkg", "remove"]
    _append_noaction_if_testmode(cmd, **kwargs)
    if kwargs.get("remove_dependencies", False):
        cmd.append("--force-removal-of-dependent-packages")
    if kwargs.get("auto_remove_deps", False):
        cmd.append("--autoremove")
    cmd.extend(targets)

out = __salt__["cmd.run_all"](cmd, output_loglevel="trace", python_shell=False)
    if out["retcode"] != 0:
        if out["stderr"]:
            errors = [out["stderr"]]
        else:
            errors = [out["stdout"]]
    else:
        errors = []

__context__.pop("pkg.list_pkgs", None)
    new = list_pkgs()
    if _is_testmode(**kwargs):
        reportedPkgs = _parse_reported_packages_from_remove_output(out["stdout"])
        new = {k: v for k, v in new.items() if k not in reportedPkgs}
    ret = salt.utils.data.compare_dicts(old, new)

rs_result = _get_restartcheck_result(errors)

if errors:
        raise CommandExecutionError(
            "Problem encountered removing package(s)",
            info={"errors": errors, "changes": ret},
        )

_process_restartcheck_result(rs_result)

return ret

def purge(name=None, pkgs=None, **kwargs):  # pylint: disable=unused-argument
    """
    Package purges are not supported by opkg, this function is identical to
    :mod:`pkg.remove <salt.modules.opkg.remove>`.

name
        The name of the package to be deleted.

Multiple Package Options:

pkgs
        A list of packages to delete. Must be passed as a python list. The
        ``name`` parameter will be ignored if this option is passed.

Returns a dict containing the changes.

CLI Example:

.. code-block:: bash

salt '*' pkg.purge <package name>
        salt '*' pkg.purge <package1>,<package2>,<package3>
        salt '*' pkg.purge pkgs='["foo", "bar"]'
    """
    return remove(name=name, pkgs=pkgs)

def upgrade(refresh=True, **kwargs):  # pylint: disable=unused-argument
    """
    Upgrades all packages via ``opkg upgrade``

Returns a dictionary containing the changes:

.. code-block:: python

{'<package>':  {'old': '<old-version>',
                        'new': '<new-version>'}}

CLI Example:

.. code-block:: bash

salt '*' pkg.upgrade
    """
    ret = {
        "changes": {},
        "result": True,
        "comment": "",
    }

errors = []

if salt.utils.data.is_true(refresh):
        refresh_db()

old = list_pkgs()

cmd = ["opkg", "upgrade"]
    result = __salt__["cmd.run_all"](cmd, output_loglevel="trace", python_shell=False)
    __context__.pop("pkg.list_pkgs", None)
    new = list_pkgs()
    ret = salt.utils.data.compare_dicts(old, new)

if result["retcode"] != 0:
        errors.append(result)

rs_result = _get_restartcheck_result(errors)

if errors:
        raise CommandExecutionError(
            "Problem encountered upgrading packages",
            info={"errors": errors, "changes": ret},
        )

_process_restartcheck_result(rs_result)

return ret

def hold(name=None, pkgs=None, sources=None, **kwargs):  # pylint: disable=W0613
    """
    Set package in 'hold' state, meaning it will not be upgraded.

name
        The name of the package, e.g., 'tmux'

CLI Example:

.. code-block:: bash

salt '*' pkg.hold <package name>

pkgs
        A list of packages to hold. Must be passed as a python list.

CLI Example:

.. code-block:: bash

salt '*' pkg.hold pkgs='["foo", "bar"]'
    """
    if not name and not pkgs and not sources:
        raise SaltInvocationError("One of name, pkgs, or sources must be specified.")
    if pkgs and sources:
        raise SaltInvocationError("Only one of pkgs or sources can be specified.")

targets = []
    if pkgs:
        targets.extend(pkgs)
    elif sources:
        for source in sources:
            targets.append(next(iter(source)))
    else:
        targets.append(name)

ret = {}
    for target in targets:
        if isinstance(target, dict):
            target = next(iter(target))

ret[target] = {"name": target, "changes": {}, "result": False, "comment": ""}

state = _get_state(target)
        if not state:
            ret[target]["comment"] = f"Package {target} not currently held."
        elif state != "hold":
            if "test" in __opts__ and __opts__["test"]:
                ret[target].update(result=None)
                ret[target]["comment"] = f"Package {target} is set to be held."
            else:
                result = _set_state(target, "hold")
                ret[target].update(changes=result[target], result=True)
                ret[target]["comment"] = f"Package {target} is now being held."
        else:
            ret[target].update(result=True)
            ret[target]["comment"] = "Package {} is already set to be held.".format(
                target
            )
    return ret

def unhold(name=None, pkgs=None, sources=None, **kwargs):  # pylint: disable=W0613
    """
    Set package current in 'hold' state to install state,
    meaning it will be upgraded.

name
        The name of the package, e.g., 'tmux'

CLI Example:

.. code-block:: bash

salt '*' pkg.unhold <package name>

pkgs
        A list of packages to hold. Must be passed as a python list.

CLI Example:

.. code-block:: bash

salt '*' pkg.unhold pkgs='["foo", "bar"]'
    """
    if not name and not pkgs and not sources:
        raise SaltInvocationError("One of name, pkgs, or sources must be specified.")
    if pkgs and sources:
        raise SaltInvocationError("Only one of pkgs or sources can be specified.")

targets = []
    if pkgs:
        targets.extend(pkgs)
    elif sources:
        for source in sources:
            targets.append(next(iter(source)))
    else:
        targets.append(name)

ret = {}
    for target in targets:
        if isinstance(target, dict):
            target = next(iter(target))

ret[target] = {"name": target, "changes": {}, "result": False, "comment": ""}

state = _get_state(target)
        if not state:
            ret[target]["comment"] = f"Package {target} does not have a state."
        elif state == "hold":
            if "test" in __opts__ and __opts__["test"]:
                ret[target].update(result=None)
                ret["comment"] = f"Package {target} is set not to be held."
            else:
                result = _set_state(target, "ok")
                ret[target].update(changes=result[target], result=True)
                ret[target]["comment"] = "Package {} is no longer being held.".format(
                    target
                )
        else:
            ret[target].update(result=True)
            ret[target]["comment"] = "Package {} is already set not to be held.".format(
                target
            )
    return ret

def _get_state(pkg):
    """
    View package state from the opkg database

Return the state of pkg
    """
    cmd = ["opkg", "status"]
    cmd.append(pkg)
    out = __salt__["cmd.run"](cmd, python_shell=False)
    state_flag = ""
    for line in salt.utils.itertools.split(out, "\n"):
        if line.startswith("Status"):
            _status, _state_want, state_flag, _state_status = line.split()

return state_flag

def _set_state(pkg, state):
    """
    Change package state on the opkg database

The state can be any of:

- hold
     - noprune
     - user
     - ok
     - installed
     - unpacked

This command is commonly used to mark a specific package to be held from
    being upgraded, that is, to be kept at a certain version.

Returns a dict containing the package name, and the new and old
    versions.
    """
    ret = {}
    valid_states = ("hold", "noprune", "user", "ok", "installed", "unpacked")
    if state not in valid_states:
        raise SaltInvocationError(f"Invalid state: {state}")
    oldstate = _get_state(pkg)
    cmd = ["opkg", "flag"]
    cmd.append(state)
    cmd.append(pkg)
    _out = __salt__["cmd.run"](cmd, python_shell=False)

# Missing return value check due to opkg issue 160
    ret[pkg] = {"old": oldstate, "new": state}
    return ret

def _list_pkgs_from_context(versions_as_list):
    """
    Use pkg list from __context__
    """
    if versions_as_list:
        return __context__["pkg.list_pkgs"]
    else:
        ret = copy.deepcopy(__context__["pkg.list_pkgs"])
        __salt__["pkg_resource.stringify"](ret)
        return ret

def list_pkgs(versions_as_list=False, **kwargs):
    """
    List the packages currently installed in a dict::

{'<package_name>': '<version>'}

CLI Example:

.. code-block:: bash

salt '*' pkg.list_pkgs
        salt '*' pkg.list_pkgs versions_as_list=True
    """
    versions_as_list = salt.utils.data.is_true(versions_as_list)
    # not yet implemented or not applicable
    if any(
        [salt.utils.data.is_true(kwargs.get(x)) for x in ("removed", "purge_desired")]
    ):
        return {}

if "pkg.list_pkgs" in __context__:
        return _list_pkgs_from_context(versions_as_list)

cmd = ["opkg", "list-installed"]
    ret = {}
    out = __salt__["cmd.run"](cmd, output_loglevel="trace", python_shell=False)
    for line in salt.utils.itertools.split(out, "\n"):
        # This is a continuation of package description
        if not line or line[0] == " ":
            continue

# This contains package name, version, and description.
        # Extract the first two.
        pkg_name, pkg_version = line.split(" - ", 2)[:2]
        __salt__["pkg_resource.add_pkg"](ret, pkg_name, pkg_version)

__salt__["pkg_resource.sort_pkglist"](ret)
    __context__["pkg.list_pkgs"] = copy.deepcopy(ret)
    if not versions_as_list:
        __salt__["pkg_resource.stringify"](ret)
    return ret

def list_upgrades(refresh=True, **kwargs):  # pylint: disable=unused-argument
    """
    List all available package upgrades.

CLI Example:

.. code-block:: bash

salt '*' pkg.list_upgrades
    """
    ret = {}
    if salt.utils.data.is_true(refresh):
        refresh_db()

cmd = ["opkg", "list-upgradable"]
    call = __salt__["cmd.run_all"](cmd, output_loglevel="trace", python_shell=False)

if call["retcode"] != 0:
        comment = ""
        if "stderr" in call:
            comment += call["stderr"]
        if "stdout" in call:
            comment += call["stdout"]
        raise CommandExecutionError(comment)
    else:
        out = call["stdout"]

for line in out.splitlines():
        name, _oldversion, newversion = line.split(" - ")
        ret[name] = newversion

return ret

def _convert_to_standard_attr(attr):
    """
    Helper function for _process_info_installed_output()

Converts an opkg attribute name to a standard attribute
    name which is used across 'pkg' modules.
    """
    ret_attr = ATTR_MAP.get(attr, None)
    if ret_attr is None:
        # All others convert to lowercase
        return attr.lower()
    return ret_attr

def _process_info_installed_output(out, filter_attrs):
    """
    Helper function for info_installed()

Processes stdout output from a single invocation of
    'opkg status'.
    """
    ret = {}
    name = None
    attrs = {}
    attr = None

for line in salt.utils.itertools.split(out, "\n"):
        if line and line[0] == " ":
            # This is a continuation of the last attr
            if filter_attrs is None or attr in filter_attrs:
                line = line.strip()
                if attrs[attr]:
                    # If attr is empty, don't add leading newline
                    attrs[attr] += "\n"
                attrs[attr] += line
            continue
        line = line.strip()
        if not line:
            # Separator between different packages
            if name:
                ret[name] = attrs
            name = None
            attrs = {}
            attr = None
            continue
        key, value = line.split(":", 1)
        value = value.lstrip()
        attr = _convert_to_standard_attr(key)
        if attr == "name":
            name = value
        elif filter_attrs is None or attr in filter_attrs:
            attrs[attr] = value

if name:
        ret[name] = attrs
    return ret

def info_installed(*names, **kwargs):
    """
    Return the information of the named package(s), installed on the system.

.. versionadded:: 2017.7.0

:param names:
        Names of the packages to get information about. If none are specified,
        will return information for all installed packages.

:param attr:
        Comma-separated package attributes. If no 'attr' is specified, all available attributes returned.

Valid attributes are:
            arch, conffiles, conflicts, depends, description, filename, group,
            install_date_time_t, md5sum, packager, provides, recommends,
            replaces, size, source, suggests, url, version

CLI Example:

.. code-block:: bash

salt '*' pkg.info_installed
        salt '*' pkg.info_installed attr=version,packager
        salt '*' pkg.info_installed <package1>
        salt '*' pkg.info_installed <package1> <package2> <package3> ...
        salt '*' pkg.info_installed <package1> attr=version,packager
        salt '*' pkg.info_installed <package1> <package2> <package3> ... attr=version,packager
    """
    attr = kwargs.pop("attr", None)
    if attr is None:
        filter_attrs = None
    elif isinstance(attr, str):
        filter_attrs = set(attr.split(","))
    else:
        filter_attrs = set(attr)

ret = {}
    if names:
        # Specific list of names of installed packages
        for name in names:
            cmd = ["opkg", "status", name]
            call = __salt__["cmd.run_all"](
                cmd, output_loglevel="trace", python_shell=False
            )
            if call["retcode"] != 0:
                comment = ""
                if call["stderr"]:
                    comment += call["stderr"]
                else:
                    comment += call["stdout"]

raise CommandExecutionError(comment)
            ret.update(_process_info_installed_output(call["stdout"], filter_attrs))
    else:
        # All installed packages
        cmd = ["opkg", "status"]
        call = __salt__["cmd.run_all"](cmd, output_loglevel="trace", python_shell=False)
        if call["retcode"] != 0:
            comment = ""
            if call["stderr"]:
                comment += call["stderr"]
            else:
                comment += call["stdout"]

raise CommandExecutionError(comment)
        ret.update(_process_info_installed_output(call["stdout"], filter_attrs))

return ret

def upgrade_available(name, **kwargs):  # pylint: disable=unused-argument
    """
    Check whether or not an upgrade is available for a given package

CLI Example:

.. code-block:: bash

salt '*' pkg.upgrade_available <package name>
    """
    return latest_version(name) != ""

def version_cmp(
    pkg1, pkg2, ignore_epoch=False, **kwargs
):  # pylint: disable=unused-argument
    """
    Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if
    pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem
    making the comparison.

ignore_epoch : False
        Set to ``True`` to ignore the epoch when comparing versions

.. versionadded:: 2016.3.4

CLI Example:

.. code-block:: bash

salt '*' pkg.version_cmp '0.2.4-0' '0.2.4.1-0'
    """

def normalize(x):
        return str(x).split(":", 1)[-1] if ignore_epoch else str(x)

pkg1 = normalize(pkg1)
    pkg2 = normalize(pkg2)

output = __salt__["cmd.run_stdout"](
        ["opkg", "--version"], output_loglevel="trace", python_shell=False
    )
    opkg_version = output.split(" ")[2].strip()
    if Version(opkg_version) >= Version("0.3.4"):
        cmd_compare = ["opkg", "compare-versions"]
    elif salt.utils.path.which("opkg-compare-versions"):
        cmd_compare = ["opkg-compare-versions"]
    else:
        log.warning(
            "Unable to find a compare-versions utility installed. Either upgrade opkg"
            " to version > 0.3.4 (preferred) or install the older opkg-compare-versions"
            " script."
        )
        return None

for oper, ret in (("<<", -1), ("=", 0), (">>", 1)):
        cmd = cmd_compare[:]
        cmd.append(shlex.quote(pkg1))
        cmd.append(oper)
        cmd.append(shlex.quote(pkg2))
        retcode = __salt__["cmd.retcode"](
            cmd, output_loglevel="trace", ignore_retcode=True, python_shell=False
        )
        if retcode == 0:
            return ret
    return None

def _set_repo_option(repo, option):
    """
    Set the option to repo
    """
    if not option:
        return
    opt = option.split("=")
    if len(opt) != 2:
        return
    if opt[0] == "trusted":
        repo["trusted"] = opt[1] == "yes"
    else:
        repo[opt[0]] = opt[1]

def _set_repo_options(repo, options):
    """
    Set the options to the repo.
    """
    delimiters = "[", "]"
    pattern = "|".join(map(re.escape, delimiters))
    for option in options:
        splitted = re.split(pattern, option)
        for opt in splitted:
            _set_repo_option(repo, opt)

def _create_repo(line, filename):
    """
    Create repo
    """
    repo = {}
    if line.startswith("#"):
        repo["enabled"] = False
        line = line[1:]
    else:
        repo["enabled"] = True
    cols = salt.utils.args.shlex_split(line.strip())
    repo["compressed"] = not cols[0] in "src"
    repo["name"] = cols[1]
    repo["uri"] = cols[2]
    repo["file"] = os.path.join(OPKG_CONFDIR, filename)
    if len(cols) > 3:
        _set_repo_options(repo, cols[3:])
    return repo

def _read_repos(conf_file, repos, filename, regex):
    """
    Read repos from configuration file
    """
    for line in conf_file:
        line = salt.utils.stringutils.to_unicode(line)
        if not regex.search(line):
            continue
        repo = _create_repo(line, filename)

# do not store duplicated uri's
        if repo["uri"] not in repos:
            repos[repo["uri"]] = [repo]

def list_repos(**kwargs):  # pylint: disable=unused-argument
    """
    Lists all repos on ``/etc/opkg/*.conf``

CLI Example:

.. code-block:: bash

salt '*' pkg.list_repos
    """
    repos = {}
    regex = re.compile(REPO_REGEXP)
    for filename in os.listdir(OPKG_CONFDIR):
        if not filename.endswith(".conf"):
            continue
        with salt.utils.files.fopen(os.path.join(OPKG_CONFDIR, filename)) as conf_file:
            _read_repos(conf_file, repos, filename, regex)
    return repos

def get_repo(repo, **kwargs):  # pylint: disable=unused-argument
    """
    Display a repo from the ``/etc/opkg/*.conf``

CLI Examples:

.. code-block:: bash

salt '*' pkg.get_repo repo
    """
    repos = list_repos()

if repos:
        for source in repos.values():
            for sub in source:
                if sub["name"] == repo:
                    return sub
    return {}

def _del_repo_from_file(repo, filepath):
    """
    Remove a repo from filepath
    """
    with salt.utils.files.fopen(filepath) as fhandle:
        output = []
        regex = re.compile(REPO_REGEXP)
        for line in fhandle:
            line = salt.utils.stringutils.to_unicode(line)
            if regex.search(line):
                if line.startswith("#"):
                    line = line[1:]
                cols = salt.utils.args.shlex_split(line.strip())
                if repo != cols[1]:
                    output.append(salt.utils.stringutils.to_str(line))
    with salt.utils.files.fopen(filepath, "w") as fhandle:
        fhandle.writelines(output)

def _set_trusted_option_if_needed(repostr, trusted):
    """
    Set trusted option to repo if needed
    """
    if trusted is True:
        repostr += " [trusted=yes]"
    elif trusted is False:
        repostr += " [trusted=no]"
    return repostr

def _add_new_repo(repo, properties):
    """
    Add a new repo entry
    """
    repostr = "# " if not properties.get("enabled") else ""
    repostr += "src/gz " if properties.get("compressed") else "src "
    if " " in repo:
        repostr += '"' + repo + '" '
    else:
        repostr += repo + " "
    repostr += properties.get("uri")
    repostr = _set_trusted_option_if_needed(repostr, properties.get("trusted"))
    repostr += "\n"
    conffile = os.path.join(OPKG_CONFDIR, repo + ".conf")

with salt.utils.files.fopen(conffile, "a") as fhandle:
        fhandle.write(salt.utils.stringutils.to_str(repostr))

def _mod_repo_in_file(repo, repostr, filepath):
    """
    Replace a repo entry in filepath with repostr
    """
    with salt.utils.files.fopen(filepath) as fhandle:
        output = []
        for line in fhandle:
            cols = salt.utils.args.shlex_split(
                salt.utils.stringutils.to_unicode(line).strip()
            )
            if repo not in cols:
                output.append(line)
            else:
                output.append(salt.utils.stringutils.to_str(repostr + "\n"))
    with salt.utils.files.fopen(filepath, "w") as fhandle:
        fhandle.writelines(output)

def del_repo(repo, **kwargs):  # pylint: disable=unused-argument
    """
    Delete a repo from ``/etc/opkg/*.conf``

If the file does not contain any other repo configuration, the file itself
    will be deleted.

CLI Examples:

.. code-block:: bash

salt '*' pkg.del_repo repo
    """
    refresh = salt.utils.data.is_true(kwargs.get("refresh", True))
    repos = list_repos()
    if repos:
        deleted_from = dict()
        for repository in repos:
            source = repos[repository][0]
            if source["name"] == repo:
                deleted_from[source["file"]] = 0
                _del_repo_from_file(repo, source["file"])

if deleted_from:
            ret = ""
            for repository in repos:
                source = repos[repository][0]
                if source["file"] in deleted_from:
                    deleted_from[source["file"]] += 1
            for repo_file, count in deleted_from.items():
                msg = "Repo '{}' has been removed from {}.\n"
                if count == 1 and os.path.isfile(repo_file):
                    msg = "File {1} containing repo '{0}' has been removed.\n"
                    try:
                        os.remove(repo_file)
                    except OSError:
                        pass
                ret += msg.format(repo, repo_file)
            if refresh:
                refresh_db()
            return ret

return f"Repo {repo} doesn't exist in the opkg repo lists"

def mod_repo(repo, **kwargs):
    """
    Modify one or more values for a repo.  If the repo does not exist, it will
    be created, so long as uri is defined.

The following options are available to modify a repo definition:

repo
        alias by which opkg refers to the repo.
    uri
        the URI to the repo.
    compressed
        defines (True or False) if the index file is compressed
    enabled
        enable or disable (True or False) repository
        but do not remove if disabled.
    refresh
        enable or disable (True or False) auto-refresh of the repositories

CLI Examples:

.. code-block:: bash

salt '*' pkg.mod_repo repo uri=http://new/uri
        salt '*' pkg.mod_repo repo enabled=False
    """
    repos = list_repos()
    found = False
    uri = ""
    if "uri" in kwargs:
        uri = kwargs["uri"]

for repository in repos:
        source = repos[repository][0]
        if source["name"] == repo:
            found = True
            repostr = ""
            if "enabled" in kwargs and not kwargs["enabled"]:
                repostr += "# "
            if "compressed" in kwargs:
                repostr += "src/gz " if kwargs["compressed"] else "src"
            else:
                repostr += "src/gz" if source["compressed"] else "src"
            repo_alias = kwargs["alias"] if "alias" in kwargs else repo
            if " " in repo_alias:
                repostr += f' "{repo_alias}"'
            else:
                repostr += f" {repo_alias}"
            repostr += " {}".format(kwargs["uri"] if "uri" in kwargs else source["uri"])
            trusted = kwargs.get("trusted")
            repostr = (
                _set_trusted_option_if_needed(repostr, trusted)
                if trusted is not None
                else _set_trusted_option_if_needed(repostr, source.get("trusted"))
            )
            _mod_repo_in_file(repo, repostr, source["file"])
        elif uri and source["uri"] == uri:
            raise CommandExecutionError(
                "Repository '{}' already exists as '{}'.".format(uri, source["name"])
            )

if not found:
        # Need to add a new repo
        if "uri" not in kwargs:
            raise CommandExecutionError(
                "Repository '{}' not found and no URI passed to create one.".format(
                    repo
                )
            )
        properties = {"uri": kwargs["uri"]}
        # If compressed is not defined, assume True
        properties["compressed"] = (
            kwargs["compressed"] if "compressed" in kwargs else True
        )
        # If enabled is not defined, assume True
        properties["enabled"] = kwargs["enabled"] if "enabled" in kwargs else True
        properties["trusted"] = kwargs.get("trusted")
        _add_new_repo(repo, properties)

if "refresh" in kwargs:
        refresh_db()

def file_list(*packages, **kwargs):  # pylint: disable=unused-argument
    """
    List the files that belong to a package. Not specifying any packages will
    return a list of _every_ file on the system's package database (not
    generally recommended).

CLI Examples:

.. code-block:: bash

salt '*' pkg.file_list httpd
        salt '*' pkg.file_list httpd postfix
        salt '*' pkg.file_list
    """
    output = file_dict(*packages)
    files = []
    for package in list(output["packages"].values()):
        files.extend(package)
    return {"errors": output["errors"], "files": files}

def file_dict(*packages, **kwargs):  # pylint: disable=unused-argument
    """
    List the files that belong to a package, grouped by package. Not
    specifying any packages will return a list of _every_ file on the system's
    package database (not generally recommended).

CLI Examples:

.. code-block:: bash

salt '*' pkg.file_list httpd
        salt '*' pkg.file_list httpd postfix
        salt '*' pkg.file_list
    """
    errors = []
    ret = {}
    cmd_files = ["opkg", "files"]

if not packages:
        packages = list(list_pkgs().keys())

for package in packages:
        files = []
        cmd = cmd_files[:]
        cmd.append(package)
        out = __salt__["cmd.run_all"](cmd, output_loglevel="trace", python_shell=False)
        for line in out["stdout"].splitlines():
            if line.startswith("/"):
                files.append(line)
            elif line.startswith(" * "):
                errors.append(line[3:])
                break
            else:
                continue
        if files:
            ret[package] = files

return {"errors": errors, "packages": ret}

def owner(*paths, **kwargs):  # pylint: disable=unused-argument
    """
    Return the name of the package that owns the file. Multiple file paths can
    be passed. Like :mod:`pkg.version <salt.modules.opkg.version`, if a single
    path is passed, a string will be returned, and if multiple paths are passed,
    a dictionary of file/package name pairs will be returned.

If the file is not owned by a package, or is not present on the minion,
    then an empty string will be returned for that path.

CLI Example:

.. code-block:: bash

salt '*' pkg.owner /usr/bin/apachectl
        salt '*' pkg.owner /usr/bin/apachectl /usr/bin/basename
    """
    if not paths:
        return ""
    ret = {}
    cmd_search = ["opkg", "search"]
    for path in paths:
        cmd = cmd_search[:]
        cmd.append(path)
        output = __salt__["cmd.run_stdout"](
            cmd, output_loglevel="trace", python_shell=False
        )
        if output:
            ret[path] = output.split(" - ")[0].strip()
        else:
            ret[path] = ""
    if len(ret) == 1:
        return next(iter(ret.values()))
    return ret

def version_clean(version):
    """
    Clean the version string removing extra data.
    There's nothing do to here for nipkg.py, therefore it will always
    return the given version.
    """
    return version

def check_extra_requirements(pkgname, pkgver):
    """
    Check if the installed package already has the given requirements.
    There's nothing do to here for nipkg.py, therefore it will always
    return True.
    """
    return True

MR SKB