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: cmd.py

"""
Execution of arbitrary commands
===============================

The cmd state module manages the enforcement of executed commands, this
state can tell a command to run under certain circumstances.

A simple example to execute a command:

.. code-block:: yaml

# Store the current date in a file
    'date > /tmp/salt-run':
      cmd.run

Only run if another execution failed, in this case truncate syslog if there is
no disk space:

.. code-block:: yaml

'> /var/log/messages/':
      cmd.run:
        - unless: echo 'foo' > /tmp/.test && rm -f /tmp/.test

Only run if the file specified by ``creates`` does not exist, in this case
touch /tmp/foo if it does not exist:

.. code-block:: yaml

touch /tmp/foo:
      cmd.run:
        - creates: /tmp/foo

``creates`` also accepts a list of files, in which case this state will
run if **any** of the files do not exist:

.. code-block:: yaml

"echo 'foo' | tee /tmp/bar > /tmp/baz":
      cmd.run:
        - creates:
          - /tmp/bar
          - /tmp/baz

.. note::

The ``creates`` option was added to the cmd state in version 2014.7.0,
    and made a global requisite in 3001.

Sometimes when running a command that starts up a daemon, the init script
doesn't return properly which causes Salt to wait indefinitely for a response.
In situations like this try the following:

.. code-block:: yaml

run_installer:
      cmd.run:
        - name: /tmp/installer.bin > /dev/null 2>&1

Salt determines whether the ``cmd`` state is successfully enforced based on the exit
code returned by the command. If the command returns a zero exit code, then salt
determines that the state was successfully enforced. If the script returns a non-zero
exit code, then salt determines that it failed to successfully enforce the state.
If a command returns a non-zero exit code but you wish to treat this as a success,
then you must place the command in a script and explicitly set the exit code of
the script to zero.

Please note that the success or failure of the state is not affected by whether a state
change occurred nor the stateful argument.

When executing a command or script, the state (i.e., changed or not)
of the command is unknown to Salt's state system. Therefore, by default, the
``cmd`` state assumes that any command execution results in a changed state.

This means that if a ``cmd`` state is watched by another state then the
state that's watching will always be executed due to the `changed` state in
the ``cmd`` state.

.. _stateful-argument:

Using the "Stateful" Argument
-----------------------------

Many state functions in this module now also accept a ``stateful`` argument.
If ``stateful`` is specified to be true then it is assumed that the command
or script will determine its own state and communicate it back by following
a simple protocol described below:

1. :strong:`If there's nothing in the stdout of the command, then assume no
   changes.` Otherwise, the stdout must be either in JSON or its `last`
   non-empty line must be a string of key=value pairs delimited by spaces (no
   spaces on either side of ``=``).

2. :strong:`If it's JSON then it must be a JSON object (e.g., {}).` If it's
   key=value pairs then quoting may be used to include spaces.  (Python's shlex
   module is used to parse the key=value string)

Two special keys or attributes are recognized in the output::

changed: bool (i.e., 'yes', 'no', 'true', 'false', case-insensitive)
    comment: str  (i.e., any string)

So, only if ``changed`` is ``True`` then assume the command execution has
   changed the state, and any other key values or attributes in the output will
   be set as part of the changes.

3. :strong:`If there's a comment then it will be used as the comment of the
   state.`

Here's an example of how one might write a shell script for use with a
   stateful command:

.. code-block:: bash

#!/bin/bash
       #
       echo "Working hard..."

# writing the state line
       echo  # an empty line here so the next line will be the last.
       echo "changed=yes comment='something has changed' whatever=123"

And an example SLS file using this module:

.. code-block:: yaml

Run myscript:
         cmd.run:
           - name: /path/to/myscript
           - cwd: /
           - stateful: True

Run only if myscript changed something:
         cmd.run:
           - name: echo hello
           - cwd: /
           - onchanges:
               - cmd: Run myscript

Note that if the second ``cmd.run`` state also specifies ``stateful: True`` it can
   then be watched by some other states as well.

4. :strong:`The stateful argument can optionally include a test_name parameter.`

This is used to specify a command to run in test mode.  This command should
   return stateful data for changes that would be made by the command in the
   name parameter.

.. versionadded:: 2015.2.0

.. code-block:: yaml

Run myscript:
         cmd.run:
           - name: /path/to/myscript
           - cwd: /
           - stateful:
             - test_name: /path/to/myscript test

Run masterscript:
         cmd.script:
           - name: masterscript
           - source: salt://path/to/masterscript
           - cwd: /
           - stateful:
             - test_name: masterscript test

Should I use :mod:`cmd.run <salt.states.cmd.run>` or :mod:`cmd.wait <salt.states.cmd.wait>`?
--------------------------------------------------------------------------------------------

.. note::

Use :mod:`cmd.run <salt.states.cmd.run>` together with :ref:`onchanges <requisites-onchanges>`
    instead of :mod:`cmd.wait <salt.states.cmd.wait>`.

These two states are often confused. The important thing to remember about them
is that :mod:`cmd.run <salt.states.cmd.run>` states are run each time the SLS
file that contains them is applied. If it is more desirable to have a command
that only runs after some other state changes, then :mod:`cmd.wait
<salt.states.cmd.wait>` does just that. :mod:`cmd.wait <salt.states.cmd.wait>`
is designed to :ref:`watch <requisites-watch>` other states, and is
executed when the state it is watching changes. Example:

.. code-block:: yaml

/usr/local/bin/postinstall.sh:
      cmd.wait:
        - watch:
          - pkg: mycustompkg
      file.managed:
        - source: salt://utils/scripts/postinstall.sh

mycustompkg:
      pkg.installed:
        - require:
          - file: /usr/local/bin/postinstall.sh

``cmd.wait`` itself do not do anything; all functionality is inside its ``mod_watch``
function, which is called by ``watch`` on changes.

The preferred format is using the :ref:`onchanges Requisite <requisites-onchanges>`, which
works on ``cmd.run`` as well as on any other state. The example would then look as follows:

.. code-block:: yaml

/usr/local/bin/postinstall.sh:
      cmd.run:
        - onchanges:
          - pkg: mycustompkg
      file.managed:
        - source: salt://utils/scripts/postinstall.sh

mycustompkg:
      pkg.installed:
        - require:
          - file: /usr/local/bin/postinstall.sh

How do I create an environment from a pillar map?
-------------------------------------------------

The map that comes from a pillar can be directly consumed by the env option!
To use it, one may pass it like this. Example:

.. code-block:: yaml

printenv:
      cmd.run:
        - env: {{ salt['pillar.get']('example:key', {}) }}

"""

import copy
import logging
import os

import salt.utils.args
import salt.utils.functools
import salt.utils.json
import salt.utils.platform
from salt.exceptions import CommandExecutionError, SaltRenderError

log = logging.getLogger(__name__)

def _reinterpreted_state(state):
    """
    Re-interpret the state returned by salt.state.run using our protocol.
    """
    ret = state["changes"]
    state["changes"] = {}
    state["comment"] = ""

out = ret.get("stdout")
    if not out:
        if ret.get("stderr"):
            state["comment"] = ret["stderr"]
        return state

is_json = False
    try:
        data = salt.utils.json.loads(out)
        if not isinstance(data, dict):
            return _failout(
                state, "script JSON output must be a JSON object (e.g., {})!"
            )
        is_json = True
    except ValueError:
        idx = out.rstrip().rfind("\n")
        if idx != -1:
            out = out[idx + 1 :]
        data = {}
        try:
            for item in salt.utils.args.shlex_split(out):
                key, val = item.split("=")
                data[key] = val
        except ValueError:
            state = _failout(
                state,
                "Failed parsing script output! "
                "Stdout must be JSON or a line of name=value pairs.",
            )
            state["changes"].update(ret)
            return state

changed = _is_true(data.get("changed", "no"))

if "comment" in data:
        state["comment"] = data["comment"]
        del data["comment"]

if changed:
        for key in ret:
            data.setdefault(key, ret[key])

# if stdout is the state output in JSON, don't show it.
        # otherwise it contains the one line name=value pairs, strip it.
        data["stdout"] = "" if is_json else data.get("stdout", "")[:idx]
        state["changes"] = data

# FIXME: if it's not changed but there's stdout and/or stderr then those
    #       won't be shown as the function output. (though, they will be shown
    #       inside INFO logs).
    return state

def _failout(state, msg):
    state["comment"] = msg
    state["result"] = False
    return state

def _is_true(val):
    if val and str(val).lower() in ("true", "yes", "1"):
        return True
    elif str(val).lower() in ("false", "no", "0"):
        return False
    raise ValueError("Failed parsing boolean value: {}".format(val))

def wait(
    name,
    cwd=None,
    root=None,
    runas=None,
    shell=None,
    env=(),
    stateful=False,
    output_loglevel="debug",
    hide_output=False,
    use_vt=False,
    success_retcodes=None,
    success_stdout=None,
    success_stderr=None,
    **kwargs
):
    """
    Run the given command only if the watch statement calls it.

.. note::

Use :mod:`cmd.run <salt.states.cmd.run>` together with :mod:`onchanges </ref/states/requisites#onchanges>`
        instead of :mod:`cmd.wait <salt.states.cmd.wait>`.

name
        The command to execute, remember that the command will execute with the
        path and permissions of the salt-minion.

cwd
        The current working directory to execute the command in, defaults to
        /root

root
        Path to the root of the jail to use. If this parameter is set, the command
        will run inside a chroot

runas
        The user name to run the command as

shell
        The shell to use for execution, defaults to /bin/sh

env
        A list of environment variables to be set prior to execution.
        Example:

.. code-block:: yaml

script-foo:
              cmd.wait:
                - env:
                  - BATCH: 'yes'

.. warning::

The above illustrates a common PyYAML pitfall, that **yes**,
            **no**, **on**, **off**, **true**, and **false** are all loaded as
            boolean ``True`` and ``False`` values, and must be enclosed in
            quotes to be used as strings. More info on this (and other) PyYAML
            idiosyncrasies can be found :ref:`here <yaml-idiosyncrasies>`.

Variables as values are not evaluated. So $PATH in the following
        example is a literal '$PATH':

.. code-block:: yaml

script-bar:
              cmd.wait:
                - env: "PATH=/some/path:$PATH"

One can still use the existing $PATH by using a bit of Jinja:

.. code-block:: jinja

{% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
              cmd.run:
                - name: ls -l /
                - env:
                  - PATH: {{ [current_path, '/my/special/bin']|join(':') }}

.. note::
            When using environment variables on Windows, case-sensitivity
            matters, i.e. Windows uses `Path` as opposed to `PATH` for other
            systems.

stateful
        The command being executed is expected to return data about executing
        a state. For more information, see the :ref:`stateful-argument` section.

creates
        Only run if the file specified by ``creates`` do not exist. If you
        specify a list of files then this state will only run if **any** of
        the files do not exist.

.. versionadded:: 2014.7.0

output_loglevel : debug
        Control the loglevel at which the output from the command is logged to
        the minion log.

.. note::
            The command being run will still be logged at the ``debug``
            loglevel regardless, unless ``quiet`` is used for this value.

hide_output : False
        Suppress stdout and stderr in the state's results.

.. note::
            This is separate from ``output_loglevel``, which only handles how
            Salt logs to the minion log.

.. versionadded:: 2018.3.0

use_vt
        Use VT utils (saltstack) to stream the command output more
        interactively to the console and the logs.
        This is experimental.

success_retcodes
        This parameter allows you to specify a list of non-zero return codes
        that should be considered as successful. If the return code from the
        command matches any in the list, the state will have a ``True`` result
        instead of ``False``.

.. versionadded:: 2019.2.0

success_stdout: This parameter will allow a list of
        strings that when found in standard out should be considered a success.
        If stdout returned from the run matches any in the provided list,
        the return code will be overridden with zero.

.. versionadded:: 3004

success_stderr: This parameter will allow a list of
        strings that when found in standard error should be considered a success.
        If stderr returned from the run matches any in the provided list,
        the return code will be overridden with zero.

.. versionadded:: 3004
    """
    # Ignoring our arguments is intentional.
    return {"name": name, "changes": {}, "result": True, "comment": ""}

# Alias "cmd.watch" to "cmd.wait", as this is a common misconfiguration
watch = salt.utils.functools.alias_function(wait, "watch")

def wait_script(
    name,
    source=None,
    template=None,
    cwd=None,
    runas=None,
    shell=None,
    env=None,
    stateful=False,
    use_vt=False,
    output_loglevel="debug",
    hide_output=False,
    success_retcodes=None,
    success_stdout=None,
    success_stderr=None,
    **kwargs
):
    """
    Download a script from a remote source and execute it only if a watch
    statement calls it.

source
        The source script being downloaded to the minion, this source script is
        hosted on the salt master server.  If the file is located on the master
        in the directory named spam, and is called eggs, the source string is
        salt://spam/eggs

template
        If this setting is applied then the named templating engine will be
        used to render the downloaded file, currently jinja, mako, and wempy
        are supported

name
        The command to execute, remember that the command will execute with the
        path and permissions of the salt-minion.

cwd
        The current working directory to execute the command in, defaults to
        /root

runas
        The user name to run the command as

shell
        The shell to use for execution, defaults to the shell grain

env
        A list of environment variables to be set prior to execution.
        Example:

.. code-block:: yaml

salt://scripts/foo.sh:
              cmd.wait_script:
                - env:
                  - BATCH: 'yes'

.. warning::

Variables as values are not evaluated. So $PATH in the following
        example is a literal '$PATH':

.. code-block:: yaml

salt://scripts/bar.sh:
              cmd.wait_script:
                - env: "PATH=/some/path:$PATH"