golden hour

/opt/saltstack/salt/lib/python3.10/site-packages/salt/states

File/Folder	Size	Actions
__init__.py	25 B
__pycache__	-
acme.py	5.08 KB
alias.py	2.49 KB
alternatives.py	6.75 KB
ansiblegate.py	7.93 KB
apache.py	3.95 KB
apache_conf.py	2.72 KB
apache_module.py	2.73 KB
apache_site.py	2.66 KB
aptpkg.py	1.42 KB
archive.py	68.24 KB
artifactory.py	6.84 KB
at.py	7.48 KB
augeas.py	10.57 KB
aws_sqs.py	2.59 KB
azurearm_compute.py	11.78 KB
azurearm_dns.py	26.05 KB
azurearm_network.py	89.12 KB
azurearm_resource.py	28.23 KB
beacon.py	7.58 KB
bigip.py	96.63 KB
blockdev.py	5.13 KB
boto3_elasticache.py	48.01 KB
boto3_elasticsearch.py	32.58 KB
boto3_route53.py	37.54 KB
boto3_sns.py	12.69 KB
boto_apigateway.py	82.83 KB
boto_asg.py	31.93 KB
boto_cfn.py	11.53 KB
boto_cloudfront.py	6.01 KB
boto_cloudtrail.py	13.18 KB
boto_cloudwatch_alarm.py	6.4 KB
boto_cloudwatch_event.py	12.33 KB
boto_cognitoidentity.py	13.69 KB
boto_datapipeline.py	18.5 KB
boto_dynamodb.py	29.32 KB
boto_ec2.py	71.98 KB
boto_elasticache.py	16.75 KB
boto_elasticsearch_domain.py	12.27 KB
boto_elb.py	55.1 KB
boto_elbv2.py	12.19 KB
boto_iam.py	69.16 KB
boto_iam_role.py	27.12 KB
boto_iot.py	25.33 KB
boto_kinesis.py	16.69 KB
boto_kms.py	12.11 KB
boto_lambda.py	35.52 KB
boto_lc.py	11.04 KB
boto_rds.py	26 KB
boto_route53.py	19.49 KB
boto_s3.py	9.32 KB
boto_s3_bucket.py	24.67 KB
boto_secgroup.py	32.62 KB
boto_sns.py	8.92 KB
boto_sqs.py	7.97 KB
boto_vpc.py	62.23 KB
bower.py	8.26 KB
btrfs.py	10.34 KB
cabal.py	5.73 KB
ceph.py	1.9 KB
chef.py	3.76 KB
chocolatey.py	16.15 KB
chronos_job.py	4.6 KB
cimc.py	14.32 KB
cisconso.py	3.14 KB
cloud.py	14.4 KB
cmd.py	40.92 KB
composer.py	8.38 KB
consul.py	5.4 KB
cron.py	23.39 KB
cryptdev.py	6.17 KB
csf.py	9.98 KB
cyg.py	7.05 KB
ddns.py	4.2 KB
debconfmod.py	6.33 KB
dellchassis.py	24.49 KB
disk.py	6.49 KB
docker_container.py	85.27 KB
docker_image.py	16.7 KB
docker_network.py	36.78 KB
docker_volume.py	6.72 KB
drac.py	4.17 KB
dvs.py	26.29 KB
elasticsearch.py	20.38 KB
elasticsearch_index.py	3.25 KB
elasticsearch_index_template.py	3.67 KB
environ.py	5.81 KB
eselect.py	2.27 KB
esxcluster.py	22.4 KB
esxdatacenter.py	4.44 KB
esxi.py	63.07 KB
esxvm.py	20.11 KB
etcd_mod.py	11 KB
ethtool.py	9.88 KB
event.py	2.48 KB
file.py	316.7 KB
firewall.py	1.33 KB
firewalld.py	26.08 KB
gem.py	7.13 KB
git.py	123.85 KB
github.py	27.25 KB
glance_image.py	2.26 KB
glassfish.py	21.47 KB
glusterfs.py	12.21 KB
gnomedesktop.py	7.47 KB
gpg.py	5.28 KB
grafana.py	12.11 KB
grafana4_dashboard.py	17.31 KB
grafana4_datasource.py	6.15 KB
grafana4_org.py	7.73 KB
grafana4_user.py	5.52 KB
grafana_dashboard.py	17.74 KB
grafana_datasource.py	5.31 KB
grains.py	15.57 KB
group.py	9.84 KB
heat.py	9.69 KB
helm.py	10.39 KB
hg.py	6.33 KB
highstate_doc.py	1.41 KB
host.py	8.64 KB
http.py	7.46 KB
icinga2.py	9.07 KB
idem.py	3.91 KB
ifttt.py	2.12 KB
incron.py	5.71 KB
influxdb08_database.py	2.85 KB
influxdb08_user.py	3.39 KB
influxdb_continuous_query.py	2.83 KB
influxdb_database.py	2.11 KB
influxdb_retention_policy.py	4.82 KB
influxdb_user.py	4.84 KB
infoblox_a.py	4.24 KB
infoblox_cname.py	4.19 KB
infoblox_host_record.py	6.59 KB
infoblox_range.py	6.85 KB
ini_manage.py	12.67 KB
ipmi.py	8.42 KB
ipset.py	9.66 KB
iptables.py	27.65 KB
jboss7.py	23.95 KB
jenkins.py	3.36 KB
junos.py	17.78 KB
kapacitor.py	6.46 KB
kernelpkg.py	6.42 KB
keyboard.py	2.01 KB
keystone.py	27.12 KB
keystone_domain.py	2.81 KB
keystone_endpoint.py	4.69 KB
keystone_group.py	3.25 KB
keystone_project.py	3.36 KB
keystone_role.py	2.33 KB
keystone_role_grant.py	4.08 KB
keystone_service.py	2.89 KB
keystone_user.py	3.47 KB
keystore.py	5.67 KB
kmod.py	8.59 KB
kubernetes.py	24.87 KB
layman.py	2.44 KB
ldap.py	19.78 KB
libcloud_dns.py	5.7 KB
libcloud_loadbalancer.py	5.66 KB
libcloud_storage.py	5.13 KB
linux_acl.py	24.42 KB
locale.py	2.52 KB
logadm.py	4.67 KB
logrotate.py	3.86 KB
loop.py	7.74 KB
lvm.py	13.33 KB
lvs_server.py	6.28 KB
lvs_service.py	4.38 KB
lxc.py	22.17 KB
lxd.py	7.88 KB
lxd_container.py	22.25 KB
lxd_image.py	10.59 KB
lxd_profile.py	7.11 KB
mac_assistive.py	1.55 KB
mac_keychain.py	5.59 KB
mac_xattr.py	3.15 KB
macdefaults.py	2.65 KB
macpackage.py	6.76 KB
makeconf.py	6.87 KB
marathon_app.py	4.45 KB
mdadm_raid.py	6.41 KB
memcached.py	3.95 KB
modjk.py	2.84 KB
modjk_worker.py	6.49 KB
module.py	18.64 KB
mongodb_database.py	1.65 KB
mongodb_user.py	6.26 KB
monit.py	2.68 KB
mount.py	50.32 KB
mssql_database.py	3 KB
mssql_login.py	3.64 KB
mssql_role.py	2.37 KB
mssql_user.py	3.51 KB
msteams.py	2.53 KB
mysql_database.py	6.05 KB
mysql_grants.py	8.49 KB
mysql_query.py	13.07 KB
mysql_user.py	9.51 KB
net_napalm_yang.py	9.15 KB
netacl.py	31.92 KB
netconfig.py	33.42 KB
netntp.py	12.51 KB
netsnmp.py	11.33 KB
netusers.py	16.1 KB
network.py	23.97 KB
neutron_network.py	3.96 KB
neutron_secgroup.py	4 KB
neutron_secgroup_rule.py	4.75 KB
neutron_subnet.py	4.29 KB
nexus.py	4.97 KB
nfs_export.py	4.92 KB
nftables.py	19.5 KB
npm.py	11.21 KB
ntp.py	2.12 KB
nxos.py	10.37 KB
nxos_upgrade.py	3.5 KB
openstack_config.py	3.26 KB
openvswitch_bridge.py	4.36 KB
openvswitch_db.py	2.24 KB
openvswitch_port.py	17.24 KB
opsgenie.py	4.07 KB
pagerduty.py	1.89 KB
pagerduty_escalation_policy.py	5.42 KB
pagerduty_schedule.py	6.09 KB
pagerduty_service.py	3.93 KB
pagerduty_user.py	1.18 KB
panos.py	48.13 KB
pbm.py	20.46 KB
pcs.py	36.46 KB
pdbedit.py	3.43 KB
pecl.py	3.65 KB
pip_state.py	38.55 KB
pkg.py	138.08 KB
pkgbuild.py	11.37 KB
pkgng.py	685 B
pkgrepo.py	27.53 KB
portage_config.py	5.01 KB
ports.py	5.65 KB
postgres_cluster.py	4.19 KB
postgres_database.py	6.08 KB
postgres_extension.py	5.68 KB
postgres_group.py	8.52 KB
postgres_initdb.py	2.84 KB
postgres_language.py	3.94 KB
postgres_privileges.py	7.86 KB
postgres_schema.py	4.34 KB
postgres_tablespace.py	6.62 KB
postgres_user.py	9.49 KB
powerpath.py	2.34 KB
probes.py	15.06 KB
process.py	1.32 KB
proxy.py	4.94 KB
pushover.py	3.13 KB
pyenv.py	6.07 KB
pyrax_queues.py	2.97 KB
quota.py	1.4 KB
rabbitmq_cluster.py	1.84 KB
rabbitmq_plugin.py	2.77 KB
rabbitmq_policy.py	4.59 KB
rabbitmq_upstream.py	7.9 KB
rabbitmq_user.py	8.89 KB
rabbitmq_vhost.py	3.04 KB
rbac_solaris.py	6.67 KB
rbenv.py	7.36 KB
rdp.py	1.28 KB
redismod.py	4.76 KB
reg.py	19.22 KB
restconf.py	6.41 KB
rsync.py	4.45 KB
rvm.py	6.56 KB
salt_proxy.py	1.34 KB
saltmod.py	33.12 KB
saltutil.py	8.91 KB
schedule.py	12.47 KB
selinux.py	18.61 KB
serverdensity_device.py	6.41 KB
service.py	37.89 KB
slack.py	4.98 KB
smartos.py	44.83 KB
smtp.py	2.3 KB
snapper.py	7.24 KB
solrcloud.py	4.48 KB
splunk.py	4.32 KB
splunk_search.py	3.17 KB
sqlite3.py	14.7 KB
ssh_auth.py	19.57 KB
ssh_known_hosts.py	7.92 KB
stateconf.py	494 B
status.py	2.21 KB
statuspage.py	17.29 KB
supervisord.py	10.48 KB
svn.py	8.14 KB
sysctl.py	4.11 KB
sysfs.py	2.13 KB
syslog_ng.py	2.97 KB
sysrc.py	2.82 KB
telemetry_alert.py	7.04 KB
test.py	13.09 KB
testinframod.py	1.35 KB
timezone.py	3.42 KB
tls.py	1.81 KB
tomcat.py	9.72 KB
trafficserver.py	8.82 KB
tuned.py	3.32 KB
uptime.py	1.87 KB
user.py	38.63 KB
vagrant.py	11.4 KB
vault.py	3.28 KB
vbox_guest.py	4.05 KB
victorops.py	3.32 KB
virt.py	80.41 KB
virtualenv_mod.py	11.21 KB
webutil.py	3.89 KB
win_certutil.py	4.8 KB
win_dacl.py	7.96 KB
win_dism.py	14.97 KB
win_dns_client.py	8.32 KB
win_firewall.py	6.87 KB
win_iis.py	31.56 KB
win_lgpo.py	24.99 KB
win_lgpo_reg.py	10.96 KB
win_license.py	1.6 KB
win_network.py	14.18 KB
win_path.py	6.39 KB
win_pki.py	5.56 KB
win_powercfg.py	3.79 KB
win_servermanager.py	10.4 KB
win_shortcut.py	7.81 KB
win_smtp_server.py	10.01 KB
win_snmp.py	6.64 KB
win_system.py	13.78 KB
win_wua.py	16.27 KB
win_wusa.py	3.53 KB
winrepo.py	2.74 KB
wordpress.py	4.82 KB
x509.py	27.86 KB
x509_v2.py	64.78 KB
xml.py	1.75 KB
xmpp.py	2.61 KB
zabbix_action.py	9.35 KB
zabbix_host.py	27.25 KB
zabbix_hostgroup.py	5.64 KB
zabbix_mediatype.py	16.89 KB
zabbix_template.py	35.14 KB
zabbix_user.py	17.6 KB
zabbix_usergroup.py	9.64 KB
zabbix_usermacro.py	9.69 KB
zabbix_valuemap.py	8.11 KB
zcbuildout.py	5.16 KB
zenoss.py	2.89 KB
zfs.py	34.48 KB
zk_concurrency.py	5.81 KB
zone.py	46.48 KB
zookeeper.py	11.55 KB
zpool.py	13.4 KB

Edit: saltmod.py

"""
Control the Salt command interface
==================================

This state is intended for use from the Salt Master. It provides access to
sending commands down to minions as well as access to executing master-side
modules. These state functions wrap Salt's :ref:`Python API <python-api>`.

.. versionadded:: 2016.11.0

Support for masterless minions was added to the ``salt.state`` function,
    so they can run orchestration sls files. This is particularly useful when
    the rendering of a state is dependent on the execution of another state.
    Orchestration will render and execute each orchestration block
    independently, while honoring requisites to ensure the states are applied
    in the correct order.

.. seealso:: More Orchestrate documentation

* :ref:`Full Orchestrate Tutorial <orchestrate-runner>`
    * :py:func:`The Orchestrate runner <salt.runners.state.orchestrate>`
"""

import fnmatch
import logging
import sys
import threading
import time

import salt.exceptions
import salt.output
import salt.syspaths
import salt.utils.data
import salt.utils.event
import salt.utils.versions
from salt.features import features

log = logging.getLogger(__name__)

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

def __virtual__():
    """
    Named salt
    """
    return __virtualname__

def _fire_args(tag_data):
    try:
        salt.utils.event.fire_args(__opts__, __orchestration_jid__, tag_data, "run")
    except NameError:
        log.debug("Unable to fire args event due to missing __orchestration_jid__")

def _parallel_map(func, inputs):
    """
    Applies a function to each element of a list, returning the resulting list.

A separate thread is created for each element in the input list and the
    passed function is called for each of the elements. When all threads have
    finished execution a list with the results corresponding to the inputs is
    returned.

If one of the threads fails (because the function throws an exception),
    that exception is reraised. If more than one thread fails, the exception
    from the first thread (according to the index of the input element) is
    reraised.

func:
        function that is applied on each input element.
    inputs:
        list of elements that shall be processed. The length of this list also
        defines the number of threads created.
    """
    outputs = len(inputs) * [None]
    errors = len(inputs) * [None]

def create_thread(index):
        def run_thread():
            try:
                outputs[index] = func(inputs[index])
            except:  # pylint: disable=bare-except
                errors[index] = sys.exc_info()

thread = threading.Thread(target=run_thread)
        thread.start()
        return thread

threads = list(map(create_thread, range(len(inputs))))
    for thread in threads:
        thread.join()
    for error in errors:
        if error is not None:
            exc_type, exc_value, exc_traceback = error
            raise exc_value.with_traceback(exc_traceback)
    return outputs

def state(
    name,
    tgt,
    ssh=False,
    tgt_type="glob",
    ret="",
    ret_config=None,
    ret_kwargs=None,
    highstate=None,
    sls=None,
    top=None,
    saltenv=None,
    test=None,
    pillar=None,
    pillarenv=None,
    expect_minions=True,
    exclude=None,
    fail_minions=None,
    allow_fail=0,
    concurrent=False,
    timeout=None,
    batch=None,
    queue=False,
    subset=None,
    orchestration_jid=None,
    failhard=None,
    **kwargs,
):
    """
    Invoke a state run on a given target

name
        An arbitrary name used to track the state execution

tgt
        The target specification for the state run.

.. versionadded:: 2016.11.0

Masterless support: When running on a masterless minion, the ``tgt``
        is ignored and will always be the local minion.

tgt_type
        The target type to resolve, defaults to ``glob``

ret
        Optionally set a single or a list of returners to use

ret_config
        Use an alternative returner configuration

ret_kwargs
        Override individual returner configuration items

highstate
        Defaults to None, if set to True the target systems will ignore any
        sls references specified in the sls option and call state.highstate
        on the targeted minions

top
        Should be the name of a top file. If set state.top is called with this
        top file instead of state.sls.

sls
        A group of sls files to execute. This can be defined as a single string
        containing a single sls file, or a list of sls files

test
        Pass ``test=true`` or ``test=false`` through to the state function. This
        can be used to override a test mode set in the minion's config file. If
        left as the default of None and the 'test' mode is supplied on the
        command line, that value is passed instead.

pillar
        Pass the ``pillar`` kwarg through to the state function

pillarenv
        The pillar environment to grab pillars from

.. versionadded:: 2017.7.0

saltenv
        The default salt environment to pull sls files from

ssh
        Set to `True` to use the ssh client instead of the standard salt client

roster
        In the event of using salt-ssh, a roster system can be set

expect_minions
        An optional boolean for failing if some minions do not respond

fail_minions
        An optional list of targeted minions where failure is an option

allow_fail
        Pass in the number of minions to allow for failure before setting
        the result of the execution to False

exclude
        Pass exclude kwarg to state

concurrent
        Allow multiple state runs to occur at once.

WARNING: This flag is potentially dangerous. It is designed
        for use when multiple state runs can safely be run at the same
        Do not use this flag for performance optimization.

queue
        Pass ``queue=true`` through to the state function

batch
        Execute the command :ref:`in batches <targeting-batch>`. E.g.: ``10%``.

.. versionadded:: 2016.3.0

subset
        Number of minions from the targeted set to randomly use

.. versionadded:: 2017.7.0

failhard
        pass failhard down to the executing state

.. versionadded:: 2019.2.2

Examples:

Run a list of sls files via :py:func:`state.sls <salt.state.sls>` on target
    minions:

.. code-block:: yaml

webservers:
          salt.state:
            - tgt: 'web*'
            - sls:
              - apache
              - django
              - core
            - saltenv: prod

Run sls file via :py:func:`state.sls <salt.state.sls>` on target
    minions with exclude:

.. code-block:: yaml

docker:
          salt.state:
            - tgt: 'docker*'
            - sls: docker
            - exclude: docker.swarm
            - saltenv: prod

Run a full :py:func:`state.highstate <salt.state.highstate>` on target
    mininons.

.. code-block:: yaml

databases:
          salt.state:
            - tgt: role:database
            - tgt_type: grain
            - highstate: True
    """
    cmd_kw = {"arg": [], "kwarg": {}, "ret": ret, "timeout": timeout}

if ret_config:
        cmd_kw["ret_config"] = ret_config

if ret_kwargs:
        cmd_kw["ret_kwargs"] = ret_kwargs

state_ret = {"name": name, "changes": {}, "comment": "", "result": True}

try:
        allow_fail = int(allow_fail)
    except ValueError:
        state_ret["result"] = False
        state_ret["comment"] = "Passed invalid value for 'allow_fail', must be an int"
        return state_ret

cmd_kw["tgt_type"] = tgt_type
    cmd_kw["ssh"] = ssh
    if "roster" in kwargs:
        cmd_kw["roster"] = kwargs["roster"]
    cmd_kw["expect_minions"] = expect_minions
    if highstate:
        fun = "state.highstate"
    elif top:
        fun = "state.top"
        cmd_kw["arg"].append(top)
    elif sls:
        fun = "state.sls"
        if isinstance(sls, list):
            sls = ",".join(sls)
        cmd_kw["arg"].append(sls)
    else:
        state_ret["comment"] = "No highstate or sls specified, no execution made"
        state_ret["result"] = False
        return state_ret

if test is not None or __opts__.get("test"):
        cmd_kw["kwarg"]["test"] = test if test is not None else __opts__.get("test")

if pillar:
        cmd_kw["kwarg"]["pillar"] = pillar

if pillarenv is not None:
        cmd_kw["kwarg"]["pillarenv"] = pillarenv

if saltenv is not None:
        cmd_kw["kwarg"]["saltenv"] = saltenv

if exclude is not None:
        cmd_kw["kwarg"]["exclude"] = exclude

cmd_kw["kwarg"]["queue"] = queue

if isinstance(concurrent, bool):
        cmd_kw["kwarg"]["concurrent"] = concurrent
    else:
        state_ret["comment"] = "Must pass in boolean for value of 'concurrent'"
        state_ret["result"] = False
        return state_ret

if batch is not None:
        cmd_kw["batch"] = str(batch)

if subset is not None:
        cmd_kw["subset"] = subset

if failhard is True or __opts__.get("failhard"):
        cmd_kw["failhard"] = True

masterless = __opts__["__role"] == "minion" and __opts__["file_client"] == "local"
    if not masterless:
        _fire_args({"type": "state", "tgt": tgt, "name": name, "args": cmd_kw})
        cmd_ret = __salt__["saltutil.cmd"](tgt, fun, **cmd_kw)
    else:
        if top:
            cmd_kw["topfn"] = "".join(cmd_kw.pop("arg"))
        elif sls:
            cmd_kw["mods"] = "".join(cmd_kw.pop("arg"))
        cmd_kw.update(cmd_kw.pop("kwarg"))
        tmp_ret = __salt__[fun](**cmd_kw)
        cmd_ret = {
            __opts__["id"]: {
                "ret": tmp_ret,
                "out": tmp_ret.get("out", "highstate")
                if isinstance(tmp_ret, dict)
                else "highstate",
            }
        }

try:
        state_ret["__jid__"] = cmd_ret[next(iter(cmd_ret))]["jid"]
    except (StopIteration, KeyError):
        pass

changes = {}
    fail = set()
    no_change = set()

if not cmd_ret and expect_minions:
        state_ret["result"] = False
        state_ret["comment"] = "No minions returned"
        return state_ret

for minion, mdata in cmd_ret.items():
        if mdata.get("out", "") != "highstate":
            log.warning("Output from salt state not highstate")

m_ret = False

if "return" in mdata and "ret" not in mdata:
            mdata["ret"] = mdata.pop("return")

m_state = True
        if mdata.get("failed", False):
            m_state = False
        else:
            try:
                m_ret = mdata["ret"]
            except KeyError:
                m_state = False
            if m_state:
                m_state = __utils__["state.check_result"](m_ret, recurse=True)

if not m_state:
            if minion not in fail_minions:
                fail.add(minion)
            changes[minion] = m_ret
            continue
        try:
            for state_item in m_ret.values():
                if isinstance(state_item, dict):
                    if "changes" in state_item and state_item["changes"]:
                        changes[minion] = m_ret
                        break
            else:
                no_change.add(minion)
        except AttributeError:
            log.error("m_ret did not have changes %s %s", type(m_ret), m_ret)
            no_change.add(minion)

if changes:
        state_ret["changes"] = {"out": "highstate", "ret": changes}
    if len(fail) > allow_fail:
        state_ret["result"] = False
        state_ret["comment"] = "Run failed on minions: {}".format(", ".join(fail))
    else:
        state_ret["comment"] = "States ran successfully."
        if changes:
            state_ret["comment"] += " Updating {}.".format(", ".join(changes))
        if no_change:
            state_ret["comment"] += " No changes made to {}.".format(
                ", ".join(no_change)
            )
    if test or __opts__.get("test"):
        if state_ret["changes"] and state_ret["result"] is True:
            # Test mode with changes is the only case where result should ever be none
            state_ret["result"] = None
    return state_ret

def function(
    name,
    tgt,
    ssh=False,
    tgt_type="glob",
    ret="",
    ret_config=None,
    ret_kwargs=None,
    expect_minions=False,
    fail_minions=None,
    fail_function=None,
    arg=None,
    kwarg=None,
    timeout=None,
    batch=None,
    subset=None,
    failhard=None,
    **kwargs,
):  # pylint: disable=unused-argument
    """
    Execute a single module function on a remote minion via salt or salt-ssh

name
        The name of the function to run, aka cmd.run or pkg.install

tgt
        The target specification, aka '*' for all minions

tgt_type
        The target type, defaults to ``glob``

arg
        The list of arguments to pass into the function

kwarg
        The dict (not a list) of keyword arguments to pass into the function

ret
        Optionally set a single or a list of returners to use

ret_config
        Use an alternative returner configuration

ret_kwargs
        Override individual returner configuration items

expect_minions
        An optional boolean for failing if some minions do not respond

fail_minions
        An optional list of targeted minions where failure is an option

fail_function
        An optional string that points to a salt module that returns True or False
        based on the returned data dict for individual minions

ssh
        Set to `True` to use the ssh client instead of the standard salt client

roster
        In the event of using salt-ssh, a roster system can be set

.. versionadded:: 3005

batch
        Execute the command :ref:`in batches <targeting-batch>`. E.g.: ``10%``.

subset
        Number of minions from the targeted set to randomly use

.. versionadded:: 2017.7.0

failhard
        pass failhard down to the executing state

.. versionadded:: 2019.2.2

"""
    func_ret = {"name": name, "changes": {}, "comment": "", "result": True}
    if kwarg is None:
        kwarg = {}
    if isinstance(arg, str):
        func_ret["warnings"] = ["Please specify 'arg' as a list of arguments."]
        arg = arg.split()

cmd_kw = {"arg": arg or [], "kwarg": kwarg, "ret": ret, "timeout": timeout}

if batch is not None:
        cmd_kw["batch"] = str(batch)
    if subset is not None:
        cmd_kw["subset"] = subset

cmd_kw["tgt_type"] = tgt_type
    cmd_kw["ssh"] = ssh
    if "roster" in kwargs:
        cmd_kw["roster"] = kwargs["roster"]
    cmd_kw["expect_minions"] = expect_minions
    cmd_kw["_cmd_meta"] = True

if failhard is True or __opts__.get("failhard"):
        cmd_kw["failhard"] = True

if ret_config:
        cmd_kw["ret_config"] = ret_config

if ret_kwargs:
        cmd_kw["ret_kwargs"] = ret_kwargs

fun = name
    if __opts__["test"] is True:
        func_ret["comment"] = "Function {} would be executed on target {}".format(
            fun, tgt
        )
        func_ret["result"] = None
        return func_ret
    try:
        _fire_args({"type": "function", "tgt": tgt, "name": name, "args": cmd_kw})
        cmd_ret = __salt__["saltutil.cmd"](tgt, fun, **cmd_kw)
    except Exception as exc:  # pylint: disable=broad-except
        func_ret["result"] = False
        func_ret["comment"] = str(exc)
        return func_ret

try:
        func_ret["__jid__"] = cmd_ret[next(iter(cmd_ret))]["jid"]
    except (StopIteration, KeyError):
        pass

changes = {}
    fail = set()

if fail_minions is None:
        fail_minions = ()
    elif isinstance(fail_minions, str):
        fail_minions = [minion.strip() for minion in fail_minions.split(",")]
    elif not isinstance(fail_minions, list):
        func_ret.setdefault("warnings", []).append(
            "'fail_minions' needs to be a list or a comma separated string. Ignored."
        )
        fail_minions = ()
    for minion, mdata in cmd_ret.items():
        m_ret = False
        if mdata.get("retcode"):
            func_ret["result"] = False
            fail.add(minion)
        if mdata.get("failed", False):
            m_func = False
        else:
            if "return" in mdata and "ret" not in mdata:
                mdata["ret"] = mdata.pop("return")
            m_ret = mdata["ret"]
            m_func = (not fail_function and True) or __salt__[fail_function](m_ret)

if m_ret is False:
                m_func = False

if not m_func:
            if minion not in fail_minions:
                fail.add(minion)
        changes[minion] = m_ret
    if not cmd_ret:
        func_ret["result"] = False
        func_ret["comment"] = "No minions responded"
    else:
        if changes:
            func_ret["changes"] = {"ret": changes}
        if fail:
            func_ret["result"] = False
            func_ret["comment"] = "Running function {} failed on minions: {}".format(
                name, ", ".join(fail)
            )
        else:
            func_ret["comment"] = "Function ran successfully."
        if changes:
            func_ret["comment"] += " Function {} ran on {}.".format(
                name, ", ".join(changes)
            )
    return func_ret

def wait_for_event(name, id_list, event_id="id", timeout=300, node="master"):
    """
    Watch Salt's event bus and block until a condition is met

.. versionadded:: 2014.7.0

name
        An event tag to watch for; supports Reactor-style globbing.
    id_list
        A list of event identifiers to watch for -- usually the minion ID. Each
        time an event tag is matched the event data is inspected for
        ``event_id``, if found it is removed from ``id_list``. When ``id_list``
        is empty this function returns success.
    event_id : id
        The name of a key in the event data. Default is ``id`` for the minion
        ID, another common value is ``name`` for use with orchestrating
        salt-cloud events.
    timeout : 300
        The maximum time in seconds to wait before failing.

The following example blocks until all the listed minions complete a
    restart and reconnect to the Salt master:

.. code-block:: yaml

reboot_all_minions:
          salt.function:
            - name: system.reboot
            - tgt: '*'

wait_for_reboots:
          salt.wait_for_event:
            - name: salt/minion/*/start
            - id_list:
              - jerry
              - stuart
              - dave
              - phil
              - kevin
              - mike
            - require:
              - salt: reboot_all_minions
    """
    ret = {"name": name, "changes": {}, "comment": "", "result": False}

if __opts__.get("test"):
        ret["comment"] = "Orchestration would wait for event '{}'".format(name)
        ret["result"] = None
        return ret

with salt.utils.event.get_event(
        node, __opts__["sock_dir"], opts=__opts__, listen=True
    ) as sevent:

del_counter = 0
        starttime = time.time()
        timelimit = starttime + timeout
        while True:
            event = sevent.get_event(full=True)
            is_timedout = time.time() > timelimit

if event is None and not is_timedout:
                log.trace("wait_for_event: No event data; waiting.")
                continue
            elif event is None and is_timedout:
                ret["comment"] = "Timeout value reached."
                return ret

if fnmatch.fnmatch(event["tag"], name):
                val = event["data"].get(event_id)
                if val is None and "data" in event["data"]:
                    val = event["data"]["data"].get(event_id)

if val is not None:
                    if isinstance(val, list):

val_list = [id for id in id_list if id in val]

if not val_list:
                            log.trace(
                                "wait_for_event: Event identifier '%s' not in "
                                "id_list; skipping",
                                event_id,
                            )
                        elif val_list:
                            minions_seen = ret["changes"].setdefault("minions_seen", [])
                            for found_val in val_list:
                                id_list.remove(found_val)
                                del_counter += 1
                                minions_seen.append(found_val)
                                log.debug(
                                    "wait_for_event: Event identifier '%s' removed "
                                    "from id_list; %s items remaining.",
                                    found_val,
                                    len(id_list),
                                )

else:
                        try:
                            val_idx = id_list.index(val)
                        except ValueError:
                            log.trace(
                                "wait_for_event: Event identifier '%s' not in "
                                "id_list; skipping.",
                                event_id,
                            )
                        else:
                            del id_list[val_idx]
                            del_counter += 1
                            minions_seen = ret["changes"].setdefault("minions_seen", [])
                            minions_seen.append(val)

log.debug(
                                "wait_for_event: Event identifier '%s' removed "
                                "from id_list; %s items remaining.",
                                val,
                                len(id_list),
                            )
                else:
                    log.trace(
                        "wait_for_event: Event identifier '%s' not in event "
                        "'%s'; skipping.",
                        event_id,
                        event["tag"],
                    )
            else:
                log.debug("wait_for_event: Skipping unmatched event '%s'", event["tag"])

if len(id_list) == 0:
                ret["result"] = True
                ret["comment"] = "All events seen in {} seconds.".format(
                    time.time() - starttime
                )
                return ret

if is_timedout:
                ret["comment"] = "Timeout value reached."
                return ret

def runner(name, **kwargs):
    """
    Execute a runner module on the master

.. versionadded:: 2014.7.0

name
        The name of the function to run
    kwargs
        Any keyword arguments to pass to the runner function

.. code-block:: yaml

run-manage-up:
          salt.runner:
            - name: manage.up
    """
    try:
        jid = __orchestration_jid__
    except NameError:
        log.debug("Unable to fire args event due to missing __orchestration_jid__")
        jid = None

try:
        kwargs["__pub_user"] = __user__
        log.debug(
            f"added __pub_user to kwargs using dunder user '{__user__}', kwargs '{kwargs}'"
        )
    except NameError:
        log.warning("unable to find user for fire args event due to missing __user__")

if __opts__.get("test", False):
        ret = {
            "name": name,
            "result": None,
            "changes": {},
            "comment": "Runner function '{}' would be executed.".format(name),
        }
        return ret

out = __salt__["saltutil.runner"](
        name, __orchestration_jid__=jid, __env__=__env__, full_return=True, **kwargs
    )

runner_return = out.get("return")
    if isinstance(runner_return, dict) and "Error" in runner_return:
        out["success"] = False

success = out.get("success", True)
    ret = {"name": name, "changes": {"return": runner_return}, "result": success}
    ret["comment"] = "Runner function '{}' {}.".format(
        name,
        "executed" if success else "failed",
    )

if features.get("enable_deprecated_orchestration_flag", False):
        ret["__orchestration__"] = True
        salt.utils.versions.warn_until(
            "Argon",
            "The __orchestration__ return flag will be removed in Salt Argon. "
            "For more information see https://github.com/saltstack/salt/pull/59917.",
        )

if "jid" in out:
        ret["__jid__"] = out["jid"]

return ret

def parallel_runners(name, runners, **kwargs):  # pylint: disable=unused-argument
    """
    Executes multiple runner modules on the master in parallel.

.. versionadded:: 2018.3.0

A separate thread is spawned for each runner. This state is intended to be
    used with the orchestrate runner in place of the ``saltmod.runner`` state
    when different tasks should be run in parallel. In general, Salt states are
    not safe when used concurrently, so ensure that they are used in a safe way
    (e.g. by only targeting separate minions in parallel tasks).

name:
        name identifying this state. The name is provided as part of the
        output, but not used for anything else.

runners:
        list of runners that should be run in parallel. Each element of the
        list has to be a dictionary. This dictionary's name entry stores the
        name of the runner function that shall be invoked. The optional kwarg
        entry stores a dictionary of named arguments that are passed to the
        runner function.

.. code-block:: yaml

parallel-state:
           salt.parallel_runners:
             - runners:
                 my_runner_1:
                   - name: state.orchestrate
                   - kwarg:
                       mods: orchestrate_state_1
                 my_runner_2:
                   - name: state.orchestrate
                   - kwarg:
                       mods: orchestrate_state_2
    """
    # For the sake of consistency, we treat a single string in the same way as
    # a key without a value. This allows something like
    #     salt.parallel_runners:
    #       - runners:
    #           state.orchestrate
    # Obviously, this will only work if the specified runner does not need any
    # arguments.
    if isinstance(runners, str):
        runners = {runners: [{name: runners}]}
    # If the runners argument is not a string, it must be a dict. Everything
    # else is considered an error.
    if not isinstance(runners, dict):
        return {
            "name": name,
            "result": False,
            "changes": {},
            "comment": "The runners parameter must be a string or dict.",
        }
    # The configuration for each runner is given as a list of key-value pairs.
    # This is not very useful for what we want to do, but it is the typical
    # style used in Salt. For further processing, we convert each of these
    # lists to a dict. This also makes it easier to check whether a name has
    # been specified explicitly.
    for runner_id, runner_config in runners.items():
        if runner_config is None:
            runner_config = {}
        else:
            runner_config = salt.utils.data.repack_dictlist(runner_config)
        if "name" not in runner_config:
            runner_config["name"] = runner_id
        runners[runner_id] = runner_config

try:
        jid = __orchestration_jid__
    except NameError:
        log.debug("Unable to fire args event due to missing __orchestration_jid__")
        jid = None

def call_runner(runner_config):
        return __salt__["saltutil.runner"](
            runner_config["name"],
            __orchestration_jid__=jid,
            __env__=__env__,
            full_return=True,
            **(runner_config.get("kwarg", {})),
        )

try:
        outputs = _parallel_map(call_runner, list(runners.values()))
    except salt.exceptions.SaltException as exc:
        return {
            "name": name,
            "result": False,
            "success": False,
            "changes": {},
            "comment": "One of the runners raised an exception: {}".format(exc),
        }
    # We bundle the results of the runners with the IDs of the runners so that
    # we can easily identify which output belongs to which runner. At the same
    # time we exctract the actual return value of the runner (saltutil.runner
    # adds some extra information that is not interesting to us).
    outputs = {
        runner_id: out["return"] for runner_id, out in zip(runners.keys(), outputs)
    }

# If each of the runners returned its output in the format compatible with
    # the 'highstate' outputter, we can leverage this fact when merging the
    # outputs.
    highstate_output = all(
        [
            out.get("outputter", "") == "highstate" and "data" in out
            for out in outputs.values()
        ]
    )

# The following helper function is used to extract changes from highstate
    # output.

def extract_changes(obj):
        if not isinstance(obj, dict):
            return {}
        elif "changes" in obj:
            if (
                isinstance(obj["changes"], dict)
                and obj["changes"].get("out", "") == "highstate"
                and "ret" in obj["changes"]
            ):
                return obj["changes"]["ret"]
            else:
                return obj["changes"]
        else:
            found_changes = {}
            for key, value in obj.items():
                change = extract_changes(value)
                if change:
                    found_changes[key] = change
            return found_changes

if highstate_output:
        failed_runners = [
            runner_id
            for runner_id, out in outputs.items()
            if out["data"].get("retcode", 0) != 0
        ]
        all_successful = not failed_runners
        if all_successful:
            comment = "All runner functions executed successfully."
        else:
            runner_comments = [
                "Runner {} failed with return value:\n{}".format(
                    runner_id,
                    salt.output.out_format(
                        outputs[runner_id], "nested", __opts__, nested_indent=2
                    ),
                )
                for runner_id in failed_runners
            ]
            comment = "\n".join(runner_comments)
        changes = {}
        for runner_id, out in outputs.items():
            runner_changes = extract_changes(out["data"])
            if runner_changes:
                changes[runner_id] = runner_changes
    else:
        failed_runners = [
            runner_id
            for runner_id, out in outputs.items()
            if out.get("exit_code", 0) != 0
        ]
        all_successful = not failed_runners
        if all_successful:
            comment = "All runner functions executed successfully."
        else:
            if len(failed_runners) == 1:
                comment = "Runner {} failed.".format(failed_runners[0])
            else:
                comment = "Runners {} failed.".format(", ".join(failed_runners))
        changes = {"ret": {runner_id: out for runner_id, out in outputs.items()}}
    ret = {
        "name": name,
        "result": all_successful,
        "changes": changes,
        "comment": comment,
    }

# The 'runner' function includes out['jid'] as '__jid__' in the returned
    # dict, but we cannot do this here because we have more than one JID if
    # we have more than one runner.

return ret

def wheel(name, **kwargs):
    """
    Execute a wheel module on the master

.. versionadded:: 2014.7.0

name
        The name of the function to run
    kwargs
        Any keyword arguments to pass to the wheel function

.. code-block:: yaml

accept_minion_key:
          salt.wheel:
            - name: key.accept
            - match: frank
    """
    ret = {"name": name, "result": False, "changes": {}, "comment": ""}
    try:
        jid = __orchestration_jid__
    except NameError:
        log.debug("Unable to fire args event due to missing __orchestration_jid__")
        jid = None

if __opts__.get("test", False):
        ret["result"] = None
        ret["changes"] = {}
        ret["comment"] = "Wheel function '{}' would be executed.".format(name)
        return ret

out = __salt__["saltutil.wheel"](
        name, __orchestration_jid__=jid, __env__=__env__, **kwargs
    )

wheel_return = out.get("return")
    if isinstance(wheel_return, dict) and "Error" in wheel_return:
        out["success"] = False

success = out.get("success", True)
    ret = {"name": name, "changes": {"return": wheel_return}, "result": success}
    ret["comment"] = "Wheel function '{}' {}.".format(
        name,
        "executed" if success else "failed",
    )

if "jid" in out:
        ret["__jid__"] = out["jid"]

return ret