Saltstack Documentation

aliases.get_target:

Return the target associated with an alias

CLI Example:

    salt '*' aliases.get_target alias

aliases.has_target:

Return true if the alias/target is set

CLI Example:

    salt '*' aliases.has_target alias target

aliases.list_aliases:

Return the aliases found in the aliases file in this format::

    {'alias': 'target'}

CLI Example:

    salt '*' aliases.list_aliases

aliases.rm_alias:

Remove an entry from the aliases file

CLI Example:

    salt '*' aliases.rm_alias alias

aliases.set_target:

Set the entry in the aliases file for the given alias, this will overwrite
any previous entry for the given alias or create a new one if it does not
exist.

CLI Example:

    salt '*' aliases.set_target alias target

alternatives.auto:

Trigger alternatives to set the path for <name> as
specified by priority.

CLI Example:

    salt '*' alternatives.auto name

alternatives.check_exists:

Check if the given path is an alternative for a name.

New in version 2015.8.4

CLI Example:

    salt '*' alternatives.check_exists name path

alternatives.check_installed:

Check if the current highest-priority match for a given alternatives link
is set to the desired path

CLI Example:

    salt '*' alternatives.check_installed name path

alternatives.display:

Display alternatives settings for defined command name

CLI Example:

    salt '*' alternatives.display editor

alternatives.install:

Install symbolic links determining default commands

CLI Example:

    salt '*' alternatives.install editor /usr/bin/editor /usr/bin/emacs23 50

alternatives.remove:

Remove symbolic links determining the default commands.

CLI Example:

    salt '*' alternatives.remove name path

alternatives.set:

Manually set the alternative <path> for <name>.

CLI Example:

    salt '*' alternatives.set name path

alternatives.show_current:

Display the current highest-priority alternative for a given alternatives
link

CLI Example:

    salt '*' alternatives.show_current editor

alternatives.show_link:

Display master link for the alternative

New in version 2015.8.13,2016.3.4,2016.11.0

CLI Example:

    salt '*' alternatives.show_link editor

archive.cmd_unzip:

New in version 2015.5.0
    In versions 2014.7.x and earlier, this function was known as
    ``archive.unzip``.

Uses the ``unzip`` command to unpack zip files. This command is part of the
`Info-ZIP`_ suite of tools, and is typically packaged as simply ``unzip``.

.. _`Info-ZIP`: http://www.info-zip.org/

zip_file
    Path of zip file to be unpacked

dest
    The destination directory into which the file should be unpacked

excludes : None
    Comma-separated list of files not to unpack. Can also be passed in a
    Python list.

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.cmd_unzip template=jinja /tmp/zipfile.zip '/tmp/{{grains.id}}' excludes=file_1,file_2

options
    Optional when using ``zip`` archives, ignored when usign other archives
    files. This is mostly used to overwrite existing files with ``o``.
    This options are only used when ``unzip`` binary is used.

    New in version 2016.3.1

runas : None
    Unpack the zip file as the specified user. Defaults to the user under
    which the minion is running.

    New in version 2015.5.0

trim_output : False
    The number of files we should output on success before the rest are trimmed, if this is
    set to True then it will default to 100

password
    Password to use with password protected zip files

    Note:
        This is not considered secure. It is recommended to instead use
        :py:func:`archive.unzip <salt.modules.archive.unzip>` for
        password-protected ZIP files. If a password is used here, then the
        unzip command run to extract the ZIP file will not show up in the
        minion log like most shell commands Salt runs do. However, the
        password will still be present in the events logged to the minion
        log at the ``debug`` log level. If the minion is logging at
        ``debug`` (or more verbose), then be advised that the password will
        appear in the log.

    New in version 2016.11.0

CLI Example:

    salt '*' archive.cmd_unzip /tmp/zipfile.zip /home/strongbad/ excludes=file_1,file_2

archive.cmd_zip:

New in version 2015.5.0
    In versions 2014.7.x and earlier, this function was known as
    ``archive.zip``.

Uses the ``zip`` command to create zip files. This command is part of the
`Info-ZIP`_ suite of tools, and is typically packaged as simply ``zip``.

.. _`Info-ZIP`: http://www.info-zip.org/

zip_file
    Path of zip file to be created

sources
    Comma-separated list of sources to include in the zip file. Sources can
    also be passed in a Python list.

    Changed in version 2017.7.0
        Globbing is now supported for this argument

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.cmd_zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1,/tmp/{{grains.id}}.txt

cwd : None
    Use this argument along with relative paths in ``sources`` to create
    zip files which do not contain the leading directories. If not
    specified, the zip file will be created as if the cwd was ``/``, and
    creating a zip file of ``/foo/bar/baz.txt`` will contain the parent
    directories ``foo`` and ``bar``. To create a zip file containing just
    ``baz.txt``, the following command would be used:

        salt '*' archive.cmd_zip /tmp/baz.zip baz.txt cwd=/foo/bar

    New in version 2014.7.1

runas : None
    Create the zip file as the specified user. Defaults to the user under
    which the minion is running.

    New in version 2015.5.0

CLI Example:

    salt '*' archive.cmd_zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2
    # Globbing for sources (2017.7.0 and later)
    salt '*' archive.cmd_zip /tmp/zipfile.zip '/tmp/sourcefile*'

archive.gunzip:

Uses the gunzip command to unpack gzip files

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.gunzip template=jinja /tmp/{{grains.id}}.txt.gz

runas : None
    The user with which to run the gzip command line

options : None
    Pass any additional arguments to gzip

    New in version 2016.3.4

CLI Example:

    # Create /tmp/sourcefile.txt
    salt '*' archive.gunzip /tmp/sourcefile.txt.gz
    salt '*' archive.gunzip /tmp/sourcefile.txt options='--verbose'

archive.gzip:

Uses the gzip command to create gzip files

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.gzip template=jinja /tmp/{{grains.id}}.txt

runas : None
    The user with which to run the gzip command line

options : None
    Pass any additional arguments to gzip

    New in version 2016.3.4

CLI Example:

    # Create /tmp/sourcefile.txt.gz
    salt '*' archive.gzip /tmp/sourcefile.txt
    salt '*' archive.gzip /tmp/sourcefile.txt options='-9 --verbose'

archive.is_encrypted:

New in version 2016.11.0
Changed in version 3005

Returns ``True`` if the zip archive is password-protected, ``False`` if
not. If the specified file is not a ZIP archive, an error will be raised.

name
    The path / URL of the archive to check.

clean : False
    Set this value to ``True`` to delete the path referred to by ``name``
    once the contents have been listed. This option should be used with
    care.

    Note:
        If there is an error listing the archive's contents, the cached
        file will not be removed, to allow for troubleshooting.

saltenv : base
    Specifies the fileserver environment from which to retrieve
    ``archive``. This is only applicable when ``archive`` is a file from
    the ``salt://`` fileserver.

source_hash
    If ``name`` is an http(s)/ftp URL and the file exists in the minion's
    file cache, this option can be passed to keep the minion from
    re-downloading the archive if the cached copy matches the specified
    hash.

    New in version 2018.3.0

use_etag
    If ``True``, remote http/https file sources will attempt to use the
    ETag header to determine if the remote file needs to be downloaded.
    This provides a lightweight mechanism for promptly refreshing files
    changed on a web server without requiring a full hash comparison via
    the ``source_hash`` parameter.

    New in version 3005

CLI Examples:

        salt '*' archive.is_encrypted /path/to/myfile.zip
        salt '*' archive.is_encrypted salt://foo.zip
        salt '*' archive.is_encrypted salt://foo.zip saltenv=dev
        salt '*' archive.is_encrypted https://domain.tld/myfile.zip clean=True
        salt '*' archive.is_encrypted https://domain.tld/myfile.zip source_hash=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
        salt '*' archive.is_encrypted ftp://10.1.2.3/foo.zip

archive.list:

New in version 2016.11.0
Changed in version 2016.11.2,3005
    The rarfile_ Python module is now supported for listing the contents of
    rar archives. This is necessary on minions with older releases of the
    ``rar`` CLI tool, which do not support listing the contents in a
    parsable format.

.. _rarfile: https://pypi.python.org/pypi/rarfile

List the files and directories in an tar, zip, or rar archive.

Note:
    This function will only provide results for XZ-compressed archives if
    the xz_ CLI command is available, as Python does not at this time
    natively support XZ compression in its tarfile_ module. Keep in mind
    however that most Linux distros ship with xz_ already installed.

    To check if a given minion has xz_, the following Salt command can be
    run:

        salt minion_id cmd.which xz

    If ``None`` is returned, then xz_ is not present and must be installed.
    It is widely available and should be packaged as either ``xz`` or
    ``xz-utils``.

name
    Path/URL of archive

archive_format
    Specify the format of the archive (``tar``, ``zip``, or ``rar``). If
    this argument is omitted, the archive format will be guessed based on
    the value of the ``name`` parameter.

options
    **For tar archives only.** This function will, by default, try to use
    the tarfile_ module from the Python standard library to get a list of
    files/directories. If this method fails, then it will fall back to
    using the shell to decompress the archive to stdout and pipe the
    results to ``tar -tf -`` to produce a list of filenames. XZ-compressed
    archives are already supported automatically, but in the event that the
    tar archive uses a different sort of compression not supported natively
    by tarfile_, this option can be used to specify a command that will
    decompress the archive to stdout. For example:

        salt minion_id archive.list /path/to/foo.tar.gz options='gzip --decompress --stdout'

    Note:
        It is not necessary to manually specify options for gzip'ed
        archives, as gzip compression is natively supported by tarfile_.

strip_components
    This argument specifies a number of top-level directories to strip from
    the results. This is similar to the paths that would be extracted if
    ``--strip-components`` (or ``--strip``) were used when extracting tar
    archives.

    New in version 2016.11.2

clean : False
    Set this value to ``True`` to delete the path referred to by ``name``
    once the contents have been listed. This option should be used with
    care.

    Note:
        If there is an error listing the archive's contents, the cached
        file will not be removed, to allow for troubleshooting.

verbose : False
    If ``False``, this function will return a list of files/dirs in the
    archive. If ``True``, it will return a dictionary categorizing the
    paths into separate keys containing the directory names, file names,
    and also directories/files present in the top level of the archive.

    Changed in version 2016.11.2
        This option now includes symlinks in their own list. Before, they
        were included with files.

saltenv : base
    Specifies the fileserver environment from which to retrieve
    ``archive``. This is only applicable when ``archive`` is a file from
    the ``salt://`` fileserver.

source_hash
    If ``name`` is an http(s)/ftp URL and the file exists in the minion's
    file cache, this option can be passed to keep the minion from
    re-downloading the archive if the cached copy matches the specified
    hash.

    New in version 2018.3.0

use_etag
    If ``True``, remote http/https file sources will attempt to use the
    ETag header to determine if the remote file needs to be downloaded.
    This provides a lightweight mechanism for promptly refreshing files
    changed on a web server without requiring a full hash comparison via
    the ``source_hash`` parameter.

    New in version 3005

.. _tarfile: https://docs.python.org/2/library/tarfile.html
.. _xz: http://tukaani.org/xz/

CLI Examples:

        salt '*' archive.list /path/to/myfile.tar.gz
        salt '*' archive.list /path/to/myfile.tar.gz strip_components=1
        salt '*' archive.list salt://foo.tar.gz
        salt '*' archive.list https://domain.tld/myfile.zip
        salt '*' archive.list https://domain.tld/myfile.zip source_hash=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
        salt '*' archive.list ftp://10.1.2.3/foo.rar

archive.rar:

Uses `rar for Linux`_ to create rar files

.. _`rar for Linux`: http://www.rarlab.com/

rarfile
    Path of rar file to be created

sources
    Comma-separated list of sources to include in the rar file. Sources can
    also be passed in a Python list.

    Changed in version 2017.7.0
        Globbing is now supported for this argument

cwd : None
    Run the rar command from the specified directory. Use this argument
    along with relative file paths to create rar files which do not
    contain the leading directories. If not specified, this will default
    to the home directory of the user under which the salt minion process
    is running.

    New in version 2014.7.1

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.rar template=jinja /tmp/rarfile.rar '/tmp/sourcefile1,/tmp/{{grains.id}}.txt'

CLI Example:

    salt '*' archive.rar /tmp/rarfile.rar /tmp/sourcefile1,/tmp/sourcefile2
    # Globbing for sources (2017.7.0 and later)
    salt '*' archive.rar /tmp/rarfile.rar '/tmp/sourcefile*'

archive.tar:

Note:

    This function has changed for version 0.17.0. In prior versions, the
    ``cwd`` and ``template`` arguments must be specified, with the source
    directories/files coming as a space-separated list at the end of the
    command. Beginning with 0.17.0, ``sources`` must be a comma-separated
    list, and the ``cwd`` and ``template`` arguments are optional.

Uses the tar command to pack, unpack, etc. tar files


options
    Options to pass to the tar command

    Changed in version 2015.8.0

        The mandatory `-` prefixing has been removed.  An options string
        beginning with a `--long-option`, would have uncharacteristically
        needed its first `-` removed under the former scheme.

        Also, tar will parse its options differently if short options are
        used with or without a preceding `-`, so it is better to not
        confuse the user into thinking they're using the non-`-` format,
        when really they are using the with-`-` format.

tarfile
    The filename of the tar archive to pack/unpack

sources
    Comma delimited list of files to **pack** into the tarfile. Can also be
    passed as a Python list.

    Changed in version 2017.7.0
        Globbing is now supported for this argument

dest
    The destination directory into which to **unpack** the tarfile

cwd : None
    The directory in which the tar command should be executed. If not
    specified, will default to the home directory of the user under which
    the salt minion process is running.

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.tar cjvf /tmp/salt.tar.bz2 {{grains.saltpath}} template=jinja

CLI Examples:

    # Create a tarfile
    salt '*' archive.tar cjvf /tmp/tarfile.tar.bz2 /tmp/file_1,/tmp/file_2
    # Create a tarfile using globbing (2017.7.0 and later)
    salt '*' archive.tar cjvf /tmp/tarfile.tar.bz2 '/tmp/file_*'
    # Unpack a tarfile
    salt '*' archive.tar xf foo.tar dest=/target/directory

archive.unrar:

Uses `rar for Linux`_ to unpack rar files

.. _`rar for Linux`: http://www.rarlab.com/

rarfile
    Name of rar file to be unpacked

dest
    The destination directory into which to **unpack** the rar file

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.unrar template=jinja /tmp/rarfile.rar /tmp/{{grains.id}}/ excludes=file_1,file_2

trim_output : False
    The number of files we should output on success before the rest are trimmed, if this is
    set to True then it will default to 100

CLI Example:

    salt '*' archive.unrar /tmp/rarfile.rar /home/strongbad/ excludes=file_1,file_2

archive.unzip:

Uses the ``zipfile`` Python module to unpack zip files

Changed in version 2015.5.0
    This function was rewritten to use Python's native zip file support.
    The old functionality has been preserved in the new function
    :mod:`archive.cmd_unzip <salt.modules.archive.cmd_unzip>`. For versions
    2014.7.x and earlier, see the :mod:`archive.cmd_zip
    <salt.modules.archive.cmd_zip>` documentation.

zip_file
    Path of zip file to be unpacked

dest
    The destination directory into which the file should be unpacked

excludes : None
    Comma-separated list of files not to unpack. Can also be passed in a
    Python list.

options
    This options are only used when ``unzip`` binary is used. In this
    function is ignored.

    New in version 2016.3.1

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.unzip template=jinja /tmp/zipfile.zip /tmp/{{grains.id}}/ excludes=file_1,file_2

runas : None
    Unpack the zip file as the specified user. Defaults to the user under
    which the minion is running.

trim_output : False
    The number of files we should output on success before the rest are trimmed, if this is
    set to True then it will default to 100

CLI Example:

    salt '*' archive.unzip /tmp/zipfile.zip /home/strongbad/ excludes=file_1,file_2

password
    Password to use with password protected zip files

    Note:
        The password will be present in the events logged to the minion log
        file at the ``debug`` log level. If the minion is logging at
        ``debug`` (or more verbose), then be advised that the password will
        appear in the log.

    New in version 2016.3.0

extract_perms : True
    The Python zipfile_ module does not extract file/directory attributes
    by default. When this argument is set to ``True``, Salt will attempt to
    apply the file permission attributes to the extracted files/folders.

    On Windows, only the read-only flag will be extracted as set within the
    zip file, other attributes (i.e. user/group permissions) are ignored.

    Set this argument to ``False`` to disable this behavior.

    New in version 2016.11.0

.. _zipfile: https://docs.python.org/2/library/zipfile.html

CLI Example:

    salt '*' archive.unzip /tmp/zipfile.zip /home/strongbad/ password='BadPassword'

archive.zip:

Uses the ``zipfile`` Python module to create zip files

Changed in version 2015.5.0
    This function was rewritten to use Python's native zip file support.
    The old functionality has been preserved in the new function
    :mod:`archive.cmd_zip <salt.modules.archive.cmd_zip>`. For versions
    2014.7.x and earlier, see the :mod:`archive.cmd_zip
    <salt.modules.archive.cmd_zip>` documentation.

zip_file
    Path of zip file to be created

sources
    Comma-separated list of sources to include in the zip file. Sources can
    also be passed in a Python list.

    Changed in version 2017.7.0
        Globbing is now supported for this argument

template : None
    Can be set to 'jinja' or another supported template engine to render
    the command arguments before execution:

        salt '*' archive.zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1,/tmp/{{grains.id}}.txt

cwd : None
    Use this argument along with relative paths in ``sources`` to create
    zip files which do not contain the leading directories. If not
    specified, the zip file will be created as if the cwd was ``/``, and
    creating a zip file of ``/foo/bar/baz.txt`` will contain the parent
    directories ``foo`` and ``bar``. To create a zip file containing just
    ``baz.txt``, the following command would be used:

        salt '*' archive.zip /tmp/baz.zip baz.txt cwd=/foo/bar

runas : None
    Create the zip file as the specified user. Defaults to the user under
    which the minion is running.

zip64 : False
    Used to enable ZIP64 support, necessary to create archives larger than
    4 GByte in size.
    If true, will create ZIP file with the ZIPp64 extension when the zipfile
    is larger than 2 GB.
    ZIP64 extension is disabled by default in the Python native zip support
    because the default zip and unzip commands on Unix (the InfoZIP utilities)
    don't support these extensions.

CLI Example:

    salt '*' archive.zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2
    # Globbing for sources (2017.7.0 and later)
    salt '*' archive.zip /tmp/zipfile.zip '/tmp/sourcefile*'

artifactory.get_latest_release:

Gets the latest release of the artifact

artifactory_url
    URL of artifactory instance
repository
    Release repository in artifactory to retrieve artifact from, for example: libs-releases
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
target_dir
    Target directory to download artifact to (default: /tmp)
target_file
    Target file to download artifact to (by default it is target_dir/artifact_id-version.packaging)
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    Artifactory username. Optional parameter.
password
    Artifactory password. Optional parameter.

artifactory.get_latest_snapshot:

Gets latest snapshot of the given artifact

artifactory_url
    URL of artifactory instance
repository
    Snapshot repository in artifactory to retrieve artifact from, for example: libs-snapshots
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
target_dir
    Target directory to download artifact to (default: /tmp)
target_file
    Target file to download artifact to (by default it is target_dir/artifact_id-snapshot_version.packaging)
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    Artifactory username. Optional parameter.
password
    Artifactory password. Optional parameter.

artifactory.get_release:

Gets the specified release of the artifact

artifactory_url
    URL of artifactory instance
repository
    Release repository in artifactory to retrieve artifact from, for example: libs-releases
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
version
    Version of the artifact
target_dir
    Target directory to download artifact to (default: /tmp)
target_file
    Target file to download artifact to (by default it is target_dir/artifact_id-version.packaging)
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    Artifactory username. Optional parameter.
password
    Artifactory password. Optional parameter.

artifactory.get_snapshot:

Gets snapshot of the desired version of the artifact

artifactory_url
    URL of artifactory instance
repository
    Snapshot repository in artifactory to retrieve artifact from, for example: libs-snapshots
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
version
    Version of the artifact
target_dir
    Target directory to download artifact to (default: /tmp)
target_file
    Target file to download artifact to (by default it is target_dir/artifact_id-snapshot_version.packaging)
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    Artifactory username. Optional parameter.
password
    Artifactory password. Optional parameter.

artifactory.set_basic_auth:

Sets the username and password for a specific url. Helper method.

CLI Example:

baredoc.list_modules:

Walk the Salt install tree for execution modules and return a
dictionary or a list of their functions as well as their arguments.

:param name: specify a specific module to list. If not specified, all modules will be listed.
:param names_only: Return only a list of the callable functions instead of a dictionary with arguments

CLI Example:

    salt myminion baredoc.list_modules

    myminion:
        ----------
    [...]
      at:
    - atq:
        tag: null
    - atrm:
        args: args
    - at:
        args: args
        kwargs: kwargs
    - atc:
        jobid: null
    - jobcheck:
        kwargs: kwargs
    [...]

baredoc.list_states:

Walk the Salt install tree for state modules and return a
dictionary or a list of their functions as well as their arguments.

:param name: specify a specific module to list. If not specified, all modules will be listed.
:param names_only: Return only a list of the callable functions instead of a dictionary with arguments

CLI Example:

(example truncated for brevity)

    salt myminion baredoc.list_states

    myminion:
        ----------
    [...]
      at:
      - present:
          name: null
          timespec: null
          tag: null
          user: null
          job: null
          unique_tag: false
       - absent:
          name: null
          jobid: null
          kwargs: kwargs
       - watch:
          name: null
          timespec: null
          tag: null
          user: null
          job: null
          unique_tag: false
       - mod_watch:
          name: null
          kwargs: kwargs
    [...]

baredoc.module_docs:

Return the docstrings for all modules. Optionally, specify a module or a
function to narrow the selection.

:param name: specify a specific module to list.

CLI Example:

    salt myminion baredoc.module_docs

baredoc.state_docs:

Return the docstrings for all state modules. Optionally, specify a state module or a
function to narrow the selection.

:param name: specify a specific module to list.

CLI Example:

    salt myminion baredoc.state_docs at

beacons.add:

Add a beacon on the minion

:param name:            Name of the beacon to configure
:param beacon_data:     Dictionary or list containing configuration for beacon.
:return:                Boolean and status message on success or failure of add.

CLI Example:

    salt '*' beacons.add ps "[{'processes': {'salt-master': 'stopped', 'apache2': 'stopped'}}]"

beacons.delete:

Delete a beacon item

:param name:            Name of the beacon to delete
:return:                Boolean and status message on success or failure of delete.

CLI Example:

    salt '*' beacons.delete ps

    salt '*' beacons.delete load

beacons.disable:

Disable all beacons jobs on the minion

:return:                Boolean and status message on success or failure of disable.

CLI Example:

    salt '*' beacons.disable

beacons.disable_beacon:

Disable a beacon on the minion

:name:                  Name of the beacon to disable.
:return:                Boolean and status message on success or failure of disable.

CLI Example:

    salt '*' beacons.disable_beacon ps

beacons.enable:

Enable all beacons on the minion

Returns:
    bool: Boolean and status message on success or failure of enable.

CLI Example:

    salt '*' beacons.enable

beacons.enable_beacon:

Enable beacon on the minion

:name:                  Name of the beacon to enable.
:return:                Boolean and status message on success or failure of enable.

CLI Example:

    salt '*' beacons.enable_beacon ps

beacons.list:

List the beacons currently configured on the minion

:param return_yaml:    Whether to return YAML formatted output,
                       default ``True``

:param include_pillar: Whether to include beacons that are
                       configured in pillar, default is ``True``.

:param include_opts:   Whether to include beacons that are
                       configured in opts, default is ``True``.

:return:               List of currently configured Beacons.

CLI Example:

    salt '*' beacons.list

beacons.list_available:

List the beacons currently available on the minion

:param return_yaml:     Whether to return YAML formatted output, default
                        ``True``
:return:                List of currently configured Beacons.

CLI Example:

    salt '*' beacons.list_available

beacons.modify:

Modify an existing beacon

:param name:            Name of the beacon to configure
:param beacon_data:     Dictionary or list containing updated configuration for beacon.
:return:                Boolean and status message on success or failure of modify.

CLI Example:

    salt '*' beacons.modify ps "[{'salt-master': 'stopped'}, {'apache2': 'stopped'}]"

beacons.reset:

Reset beacon configuration on the minion

CLI Example:

    salt '*' beacons.reset

beacons.save:

Save all configured beacons to the minion config

:return:                Boolean and status message on success or failure of save.

CLI Example:

    salt '*' beacons.save

bigip.add_pool_member:

A function to connect to a bigip device and add a new member to an existing pool.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the pool to modify
member
    The name of the member to add
    i.e. 10.1.1.2:80

CLI Example:

    salt '*' bigip.add_pool_members bigip admin admin my-pool 10.2.2.1:80

bigip.commit_transaction:

A function to connect to a bigip device and commit an existing transaction.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
label
    the label of this transaction stored within the grain:
    ``bigip_f5_trans:<label>``

CLI Example:

    salt '*' bigip.commit_transaction bigip admin admin my_transaction

bigip.create_monitor:

A function to connect to a bigip device and create a monitor.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
monitor_type
    The type of monitor to create
name
    The name of the monitor to create
kwargs
    Consult F5 BIGIP user guide for specific options for each monitor type.
    Typically, tmsh arg names are used.

CLI Example:

    salt '*' bigip.create_monitor bigip admin admin http my-http-monitor timeout=10 interval=5

bigip.create_node:

A function to connect to a bigip device and create a node.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the node
address
    The address of the node
trans_label
    The label of the transaction stored within the grain:
    ``bigip_f5_trans:<label>``

CLI Example:

    salt '*' bigip.create_node bigip admin admin 10.1.1.2

bigip.create_pool:

A function to connect to a bigip device and create a pool.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the pool to create.
members
    List of comma delimited pool members to add to the pool.
    i.e. 10.1.1.1:80,10.1.1.2:80,10.1.1.3:80
allow_nat
    [yes | no]
allow_snat
    [yes | no]
description
    [string]
gateway_failsafe_device
    [string]
ignore_persisted_weight
    [enabled | disabled]
ip_tos_to_client
    [pass-through | [integer]]
ip_tos_to_server
    [pass-through | [integer]]
link_qos_to_client
    [pass-through | [integer]]
link_qos_to_server
    [pass-through | [integer]]
load_balancing_mode
    [dynamic-ratio-member | dynamic-ratio-node |
    fastest-app-response | fastest-node |
    least-connections-members |
    least-connections-node |
    least-sessions |
    observed-member | observed-node |
    predictive-member | predictive-node |
    ratio-least-connections-member |
    ratio-least-connections-node |
    ratio-member | ratio-node | ratio-session |
    round-robin | weighted-least-connections-member |
    weighted-least-connections-node]
min_active_members
    [integer]
min_up_members
    [integer]
min_up_members_action
    [failover | reboot | restart-all]
min_up_members_checking
    [enabled | disabled]
monitor
    [name]
profiles
    [none | profile_name]
queue_depth_limit
    [integer]
queue_on_connection_limit
    [enabled | disabled]
queue_time_limit
    [integer]
reselect_tries
    [integer]
service_down_action
    [drop | none | reselect | reset]
slow_ramp_time
    [integer]

CLI Example:

    salt '*' bigip.create_pool bigip admin admin my-pool 10.1.1.1:80,10.1.1.2:80,10.1.1.3:80 monitor=http

bigip.create_profile:

A function to connect to a bigip device and create a profile.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
profile_type
    The type of profile to create
name
    The name of the profile to create
kwargs
    ``[ arg=val ] ... [arg=key1:val1,key2:val2] ...``

    Consult F5 BIGIP user guide for specific options for each monitor type.
    Typically, tmsh arg names are used.

Creating Complex Args
    Profiles can get pretty complicated in terms of the amount of possible
    config options. Use the following shorthand to create complex arguments such
    as lists, dictionaries, and lists of dictionaries. An option is also
    provided to pass raw json as well.

    lists ``[i,i,i]``:
        ``param='item1,item2,item3'``

    Dictionary ``[k:v,k:v,k,v]``:
        ``param='key-1:val-1,key-2:val2,key-3:va-3'``

    List of Dictionaries ``[k:v,k:v|k:v,k:v|k:v,k:v]``:
       ``param='key-1:val-1,key-2:val-2|key-1:val-1,key-2:val-2|key-1:val-1,key-2:val-2'``

    JSON: ``'j{ ... }j'``:
       ``cert-key-chain='j{ "default": { "cert": "default.crt", "chain": "default.crt", "key": "default.key" } }j'``

    Escaping Delimiters:
        Use ``\,`` or ``\:`` or ``\|`` to escape characters which shouldn't
        be treated as delimiters i.e. ``ciphers='DEFAULT\:!SSLv3'``

CLI Example:

    salt '*' bigip.create_profile bigip admin admin http my-http-profile defaultsFrom='/Common/http'
    salt '*' bigip.create_profile bigip admin admin http my-http-profile defaultsFrom='/Common/http' \
        enforcement=maxHeaderCount:3200,maxRequests:10

bigip.create_virtual:

A function to connect to a bigip device and create a virtual server.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the virtual to create
destination
    [ [virtual_address_name:port] | [ipv4:port] | [ipv6.port] ]
pool
    [ [pool_name] | none]
address_status
    [yes | no]
auto_lasthop
    [default | enabled | disabled ]
bwc_policy
    [none] | string]
cmp_enabled
    [yes | no]
dhcp_relay
    [yes | no]
connection_limit
    [integer]
description
    [string]
state
    [disabled | enabled]
fallback_persistence
    [none | [profile name] ]
flow_eviction_policy
    [none | [eviction policy name] ]
gtm_score
    [integer]
ip_forward
    [yes | no]
ip_protocol
    [any | protocol]
internal
    [yes | no]
twelve_forward
    (12-forward)
    [yes | no]
last_hop-pool
    [ [pool_name] | none]
mask
    { [ipv4] | [ipv6] }
mirror
    { [disabled | enabled | none] }
nat64
    [enabled | disabled]
persist
    [none | profile1,profile2,profile3 ... ]
profiles
    [none | default | profile1,profile2,profile3 ... ]
policies
    [none | default | policy1,policy2,policy3 ... ]
rate_class
    [name]
rate_limit
    [integer]
rate_limit_mode
    [destination | object | object-destination |
    object-source | object-source-destination |
    source | source-destination]
rate_limit_dst
    [integer]
rate_limitçsrc
    [integer]
rules
    [none | [rule_one,rule_two ...] ]
related_rules
    [none | [rule_one,rule_two ...] ]
reject
    [yes | no]
source
    { [ipv4[/prefixlen]] | [ipv6[/prefixlen]] }
source_address_translation
    [none | snat:pool_name | lsn | automap ]
source_port
    [change | preserve | preserve-strict]
state
    [enabled | disabled]
traffic_classes
    [none | default | class_one,class_two ... ]
translate_address
    [enabled | disabled]
translate_port
    [enabled | disabled]
vlans
    [none | default | [enabled|disabled]:vlan1,vlan2,vlan3 ... ]

CLI Example:

    salt '*' bigip.create_virtual bigip admin admin my-virtual-3 26.2.2.5:80 \
        pool=my-http-pool-http profiles=http,tcp

    salt '*' bigip.create_virtual bigip admin admin my-virtual-3 43.2.2.5:80 \
        pool=test-http-pool-http profiles=http,websecurity persist=cookie,hash \
        policies=asm_auto_l7_policy__http-virtual \
        rules=_sys_APM_ExchangeSupport_helper,_sys_https_redirect \
        related_rules=_sys_APM_activesync,_sys_APM_ExchangeSupport_helper \
        source_address_translation=snat:my-snat-pool \
        translate_address=enabled translate_port=enabled \
        traffic_classes=my-class,other-class \
        vlans=enabled:external,internal

bigip.delete_monitor:

A function to connect to a bigip device and delete an existing monitor.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
monitor_type
    The type of monitor to delete
name
    The name of the monitor to delete

CLI Example:

    salt '*' bigip.delete_monitor bigip admin admin http my-http-monitor

bigip.delete_node:

A function to connect to a bigip device and delete a specific node.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the node which will be deleted.
trans_label
    The label of the transaction stored within the grain:
    ``bigip_f5_trans:<label>``

CLI Example:

    salt '*' bigip.delete_node bigip admin admin my-node

bigip.delete_pool:

A function to connect to a bigip device and delete a specific pool.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the pool which will be deleted

CLI Example

    salt '*' bigip.delete_node bigip admin admin my-pool

bigip.delete_pool_member:

A function to connect to a bigip device and delete a specific pool.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the pool to modify
member
    The name of the pool member to delete

CLI Example:

    salt '*' bigip.delete_pool_member bigip admin admin my-pool 10.2.2.2:80

bigip.delete_profile:

A function to connect to a bigip device and delete an existing profile.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
profile_type
    The type of profile to delete
name
    The name of the profile to delete

CLI Example:

    salt '*' bigip.delete_profile bigip admin admin http my-http-profile

bigip.delete_transaction:

A function to connect to a bigip device and delete an existing transaction.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
label
    The label of this transaction stored within the grain:
    ``bigip_f5_trans:<label>``

CLI Example:

    salt '*' bigip.delete_transaction bigip admin admin my_transaction

bigip.delete_virtual:

A function to connect to a bigip device and delete a specific virtual.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the virtual to delete

CLI Example:

    salt '*' bigip.delete_virtual bigip admin admin my-virtual

bigip.list_monitor:

A function to connect to a bigip device and list an existing monitor.  If no name is provided than all
monitors of the specified type will be listed.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
monitor_type
    The type of monitor(s) to list
name
    The name of the monitor to list

CLI Example:

    salt '*' bigip.list_monitor bigip admin admin http my-http-monitor

bigip.list_node:

A function to connect to a bigip device and list all nodes or a specific node.


hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the node to list. If no name is specified than all nodes
    will be listed.
trans_label
    The label of the transaction stored within the grain:
    ``bigip_f5_trans:<label>``

CLI Example:

    salt '*' bigip.list_node bigip admin admin my-node

bigip.list_pool:

A function to connect to a bigip device and list all pools or a specific pool.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the pool to list. If no name is specified then all pools
    will be listed.

CLI Example:

    salt '*' bigip.list_pool bigip admin admin my-pool

bigip.list_profile:

A function to connect to a bigip device and list an existing profile.  If no name is provided than all
profiles of the specified type will be listed.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
profile_type
    The type of profile(s) to list
name
    The name of the profile to list

CLI Example:

    salt '*' bigip.list_profile bigip admin admin http my-http-profile

bigip.list_transaction:

A function to connect to a bigip device and list an existing transaction.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
label
    the label of this transaction stored within the grain:
    ``bigip_f5_trans:<label>``

CLI Example:

    salt '*' bigip.list_transaction bigip admin admin my_transaction

bigip.list_virtual:

A function to connect to a bigip device and list all virtuals or a specific virtual.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the virtual to list. If no name is specified than all
    virtuals will be listed.

CLI Example:

    salt '*' bigip.list_virtual bigip admin admin my-virtual

bigip.modify_monitor:

A function to connect to a bigip device and modify an existing monitor.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
monitor_type
    The type of monitor to modify
name
    The name of the monitor to modify
kwargs
    Consult F5 BIGIP user guide for specific options for each monitor type.
    Typically, tmsh arg names are used.

CLI Example:

    salt '*' bigip.modify_monitor bigip admin admin http my-http-monitor  timout=16 interval=6

bigip.modify_node:

A function to connect to a bigip device and modify an existing node.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the node to modify
connection_limit
    [integer]
description
    [string]
dynamic_ratio
    [integer]
logging
    [enabled | disabled]
monitor
    [[name] | none | default]
rate_limit
    [integer]
ratio
    [integer]
session
    [user-enabled | user-disabled]
state
    [user-down | user-up ]
trans_label
    The label of the transaction stored within the grain:
    ``bigip_f5_trans:<label>``

CLI Example:

    salt '*' bigip.modify_node bigip admin admin 10.1.1.2 ratio=2 logging=enabled

bigip.modify_pool:

A function to connect to a bigip device and modify an existing pool.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the pool to modify.
allow_nat
    [yes | no]
allow_snat
    [yes | no]
description
    [string]
gateway_failsafe_device
    [string]
ignore_persisted_weight
    [yes | no]
ip_tos_to_client
    [pass-through | [integer]]
ip_tos_to_server
    [pass-through | [integer]]
link_qos_to_client
    [pass-through | [integer]]
link_qos_to_server
    [pass-through | [integer]]
load_balancing_mode
    [dynamic-ratio-member | dynamic-ratio-node |
    fastest-app-response | fastest-node |
    least-connections-members |
    least-connections-node |
    least-sessions |
    observed-member | observed-node |
    predictive-member | predictive-node |
    ratio-least-connections-member |
    ratio-least-connections-node |
    ratio-member | ratio-node | ratio-session |
    round-robin | weighted-least-connections-member |
    weighted-least-connections-node]
min_active_members
    [integer]
min_up_members
    [integer]
min_up_members_action
    [failover | reboot | restart-all]
min_up_members_checking
    [enabled | disabled]
monitor
    [name]
profiles
    [none | profile_name]
queue_on_connection_limit
    [enabled | disabled]
queue_depth_limit
    [integer]
queue_time_limit
    [integer]
reselect_tries
    [integer]
service_down_action
    [drop | none | reselect | reset]
slow_ramp_time
    [integer]

CLI Example:

    salt '*' bigip.modify_pool bigip admin admin my-pool 10.1.1.1:80,10.1.1.2:80,10.1.1.3:80 min_active_members=1

bigip.modify_pool_member:

A function to connect to a bigip device and modify an existing member of a pool.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the pool to modify
member
    The name of the member to modify i.e. 10.1.1.2:80
connection_limit
    [integer]
description
    [string]
dynamic_ratio
    [integer]
inherit_profile
    [enabled | disabled]
logging
    [enabled | disabled]
monitor
    [name]
priority_group
    [integer]
profiles
    [none | profile_name]
rate_limit
    [integer]
ratio
    [integer]
session
    [user-enabled | user-disabled]
state
    [ user-up | user-down ]

CLI Example:

    salt '*' bigip.modify_pool_member bigip admin admin my-pool 10.2.2.1:80 state=use-down session=user-disabled

bigip.modify_profile:

A function to connect to a bigip device and create a profile.

A function to connect to a bigip device and create a profile.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
profile_type
    The type of profile to create
name
    The name of the profile to create
kwargs
    ``[ arg=val ] ... [arg=key1:val1,key2:val2] ...``

    Consult F5 BIGIP user guide for specific options for each monitor type.
    Typically, tmsh arg names are used.

Creating Complex Args

    Profiles can get pretty complicated in terms of the amount of possible
    config options. Use the following shorthand to create complex arguments such
    as lists, dictionaries, and lists of dictionaries. An option is also
    provided to pass raw json as well.

    lists ``[i,i,i]``:
        ``param='item1,item2,item3'``

    Dictionary ``[k:v,k:v,k,v]``:
        ``param='key-1:val-1,key-2:val2,key-3:va-3'``

    List of Dictionaries ``[k:v,k:v|k:v,k:v|k:v,k:v]``:
       ``param='key-1:val-1,key-2:val-2|key-1:val-1,key-2:val-2|key-1:val-1,key-2:val-2'``

    JSON: ``'j{ ... }j'``:
       ``cert-key-chain='j{ "default": { "cert": "default.crt", "chain": "default.crt", "key": "default.key" } }j'``

    Escaping Delimiters:
        Use ``\,`` or ``\:`` or ``\|`` to escape characters which shouldn't
        be treated as delimiters i.e. ``ciphers='DEFAULT\:!SSLv3'``

CLI Example:

    salt '*' bigip.modify_profile bigip admin admin http my-http-profile defaultsFrom='/Common/http'

    salt '*' bigip.modify_profile bigip admin admin http my-http-profile defaultsFrom='/Common/http' \
        enforcement=maxHeaderCount:3200,maxRequests:10

    salt '*' bigip.modify_profile bigip admin admin client-ssl my-client-ssl-1 retainCertificate=false \
        ciphers='DEFAULT\:!SSLv3'
        cert_key_chain='j{ "default": { "cert": "default.crt", "chain": "default.crt", "key": "default.key" } }j'

bigip.modify_virtual:

A function to connect to a bigip device and modify an existing virtual server.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the virtual to modify
destination
    [ [virtual_address_name:port] | [ipv4:port] | [ipv6.port] ]
pool
    [ [pool_name] | none]
address_status
    [yes | no]
auto_lasthop
    [default | enabled | disabled ]
bwc_policy
    [none] | string]
cmp_enabled
    [yes | no]
dhcp_relay
    [yes | no}
connection_limit
    [integer]
description
    [string]
state
    [disabled | enabled]
fallback_persistence
    [none | [profile name] ]
flow_eviction_policy
    [none | [eviction policy name] ]
gtm_score
    [integer]
ip_forward
    [yes | no]
ip_protocol
    [any | protocol]
internal
    [yes | no]
twelve_forward
    (12-forward)
    [yes | no]
last_hop-pool
    [ [pool_name] | none]
mask
    { [ipv4] | [ipv6] }
mirror
    { [disabled | enabled | none] }
nat64
    [enabled | disabled]
persist
    [none | profile1,profile2,profile3 ... ]
profiles
    [none | default | profile1,profile2,profile3 ... ]
policies
    [none | default | policy1,policy2,policy3 ... ]
rate_class
    [name]
rate_limit
    [integer]
rate_limitr_mode
    [destination | object | object-destination |
    object-source | object-source-destination |
    source | source-destination]
rate_limit_dst
    [integer]
rate_limit_src
    [integer]
rules
    [none | [rule_one,rule_two ...] ]
related_rules
    [none | [rule_one,rule_two ...] ]
reject
    [yes | no]
source
    { [ipv4[/prefixlen]] | [ipv6[/prefixlen]] }
source_address_translation
    [none | snat:pool_name | lsn | automap ]
source_port
    [change | preserve | preserve-strict]
state
    [enabled | disable]
traffic_classes
    [none | default | class_one,class_two ... ]
translate_address
    [enabled | disabled]
translate_port
    [enabled | disabled]
vlans
    [none | default | [enabled|disabled]:vlan1,vlan2,vlan3 ... ]

CLI Example:

    salt '*' bigip.modify_virtual bigip admin admin my-virtual source_address_translation=none
    salt '*' bigip.modify_virtual bigip admin admin my-virtual rules=my-rule,my-other-rule

bigip.replace_pool_members:

A function to connect to a bigip device and replace members of an existing pool with new members.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
name
    The name of the pool to modify
members
    List of comma delimited pool members to replace existing members with.
    i.e. 10.1.1.1:80,10.1.1.2:80,10.1.1.3:80

CLI Example:

    salt '*' bigip.replace_pool_members bigip admin admin my-pool 10.2.2.1:80,10.2.2.2:80,10.2.2.3:80

bigip.start_transaction:

A function to connect to a bigip device and start a new transaction.

hostname
    The host/address of the bigip device
username
    The iControl REST username
password
    The iControl REST password
label
    The name / alias for this transaction.  The actual transaction
    id will be stored within a grain called ``bigip_f5_trans:<label>``

CLI Example:

    salt '*' bigip.start_transaction bigip admin admin my_transaction

bridge.add:

Creates a bridge

CLI Example:

    salt '*' bridge.add br0

bridge.addif:

Adds an interface to a bridge

CLI Example:

    salt '*' bridge.addif br0 eth0

bridge.delete:

Deletes a bridge

CLI Example:

    salt '*' bridge.delete br0

bridge.delif:

Removes an interface from a bridge

CLI Example:

    salt '*' bridge.delif br0 eth0

bridge.find_interfaces:

Returns the bridge to which the interfaces are bond to

CLI Example:

    salt '*' bridge.find_interfaces eth0 [eth1...]

bridge.interfaces:

Returns interfaces attached to a bridge

CLI Example:

    salt '*' bridge.interfaces br0

bridge.list:

Returns the machine's bridges list

CLI Example:

    salt '*' bridge.list

bridge.show:

Returns bridges interfaces along with enslaved physical interfaces. If
no interface is given, all bridges are shown, else only the specified
bridge values are returned.

CLI Example:

    salt '*' bridge.show
    salt '*' bridge.show br0

bridge.stp:

Sets Spanning Tree Protocol state for a bridge

CLI Example:

    salt '*' bridge.stp br0 enable
    salt '*' bridge.stp br0 disable

For BSD-like operating systems, it is required to add the interface on
which to enable the STP.

CLI Example:

    salt '*' bridge.stp bridge0 enable fxp0
    salt '*' bridge.stp bridge0 disable fxp0

btrfs.add:

Add a devices to a BTRFS filesystem.

General options:

* **nodiscard**: Do not perform whole device TRIM
* **force**: Force overwrite existing filesystem on the disk

CLI Example:

    salt '*' btrfs.add /mountpoint /dev/sda1 /dev/sda2

btrfs.convert:

Convert ext2/3/4 to BTRFS. Device should be mounted.

Filesystem can be converted temporarily so the further processing and rollback is possible,
or permanently, where previous extended filesystem image gets deleted. Please note, permanent
conversion takes a while as BTRFS filesystem needs to be properly rebalanced afterwards.

General options:

* **permanent**: Specify if the migration should be permanent (false by default)
* **keeplf**: Keep ``lost+found`` of the partition (removed by default,
              but still in the image, if not permanent migration)

CLI Example:

    salt '*' btrfs.convert /dev/sda1
    salt '*' btrfs.convert /dev/sda1 permanent=True

btrfs.defragment:

Defragment mounted BTRFS filesystem.
In order to defragment a filesystem, device should be properly mounted and writable.

If passed a device name, then defragmented whole filesystem, mounted on in.
If passed a moun tpoint of the filesystem, then only this mount point is defragmented.

CLI Example:

    salt '*' btrfs.defragment /dev/sda1
    salt '*' btrfs.defragment /path/on/filesystem

btrfs.delete:

Remove devices from a BTRFS filesystem.

CLI Example:

    salt '*' btrfs.delete /mountpoint /dev/sda1 /dev/sda2

btrfs.devices:

Get known BTRFS formatted devices on the system.

CLI Example:

    salt '*' btrfs.devices

btrfs.features:

List currently available BTRFS features.

CLI Example:

    salt '*' btrfs.mkfs_features

btrfs.info:

Get BTRFS filesystem information.

CLI Example:

    salt '*' btrfs.info /dev/sda1

btrfs.mkfs:

Create a file system on the specified device. By default wipes out with force.

General options:

* **allocsize**: Specify the BTRFS offset from the start of the device.
* **bytecount**: Specify the size of the resultant filesystem.
* **nodesize**: Node size.
* **leafsize**: Specify the nodesize, the tree block size in which btrfs stores data.
* **noforce**: Prevent force overwrite when an existing filesystem is detected on the device.
* **sectorsize**: Specify the sectorsize, the minimum data block allocation unit.
* **nodiscard**: Do not perform whole device TRIM operation by default.
* **uuid**: Pass UUID or pass True to generate one.


Options:

* **dto**: (raid0|raid1|raid5|raid6|raid10|single|dup)
           Specify how the data must be spanned across the devices specified.
* **mto**: (raid0|raid1|raid5|raid6|raid10|single|dup)
           Specify how metadata must be spanned across the devices specified.
* **fts**: Features (call ``salt <host> btrfs.features`` for full list of available features)

See the ``mkfs.btrfs(8)`` manpage for a more complete description of corresponding options description.

CLI Example:

    salt '*' btrfs.mkfs /dev/sda1
    salt '*' btrfs.mkfs /dev/sda1 noforce=True

btrfs.properties:

List properties for given btrfs object. The object can be path of BTRFS device,
mount point, or any directories/files inside the BTRFS filesystem.

General options:

* **type**: Possible types are s[ubvol], f[ilesystem], i[node] and d[evice].
* **force**: Force overwrite existing filesystem on the disk
* **set**: <key=value,key1=value1...> Options for a filesystem properties.

CLI Example:

    salt '*' btrfs.properties /mountpoint
    salt '*' btrfs.properties /dev/sda1 type=subvol set='ro=false,label="My Storage"'

btrfs.resize:

Resize filesystem.

General options:

* **mountpoint**: Specify the BTRFS mountpoint to resize.
* **size**: ([+/-]<newsize>[kKmMgGtTpPeE]|max) Specify the new size of the target.

CLI Example:

    salt '*' btrfs.resize /mountpoint size=+1g
    salt '*' btrfs.resize /dev/sda1 size=max

btrfs.subvolume_create:

Create subvolume `name` in `dest`.

Return True if the subvolume is created, False is the subvolume is
already there.

name
     Name of the new subvolume

dest
     If not given, the subvolume will be created in the current
     directory, if given will be in /dest/name

qgroupids
     Add the newly created subcolume to a qgroup. This parameter
     is a list

CLI Example:

    salt '*' btrfs.subvolume_create var
    salt '*' btrfs.subvolume_create var dest=/mnt
    salt '*' btrfs.subvolume_create var qgroupids='[200]'

btrfs.subvolume_delete:

Delete the subvolume(s) from the filesystem

The user can remove one single subvolume (name) or multiple of
then at the same time (names). One of the two parameters needs to
specified.

Please, refer to the documentation to understand the implication
on the transactions, and when the subvolume is really deleted.

Return True if the subvolume is deleted, False is the subvolume
was already missing.

name
    Name of the subvolume to remove

names
    List of names of subvolumes to remove

commit
    * 'after': Wait for transaction commit at the end
    * 'each': Wait for transaction commit after each delete

CLI Example:

    salt '*' btrfs.subvolume_delete /var/volumes/tmp
    salt '*' btrfs.subvolume_delete /var/volumes/tmp commit=after

btrfs.subvolume_exists:

Check if a subvolume is present in the filesystem.

path
    Mount point for the subvolume (full path)

CLI Example:

    salt '*' btrfs.subvolume_exists /mnt/var

btrfs.subvolume_find_new:

List the recently modified files in a subvolume

name
    Name of the subvolume

last_gen
    Last transid marker from where to compare

CLI Example:

    salt '*' btrfs.subvolume_find_new /var/volumes/tmp 1024

btrfs.subvolume_get_default:

Get the default subvolume of the filesystem path

path
    Mount point for the subvolume

CLI Example:

    salt '*' btrfs.subvolume_get_default /var/volumes/tmp

btrfs.subvolume_list:

List the subvolumes present in the filesystem.

path
    Mount point for the subvolume

parent_id
    Print parent ID

absolute
    Print all the subvolumes in the filesystem and distinguish
    between absolute and relative path with respect to the given
    <path>

ogeneration
    Print the ogeneration of the subvolume

generation
    Print the generation of the subvolume

subvolumes
    Print only subvolumes below specified <path>

uuid
    Print the UUID of the subvolume

parent_uuid
    Print the parent uuid of subvolumes (and snapshots)

sent_subvolume_uuid
    Print the UUID of the sent subvolume, where the subvolume is
    the result of a receive operation

snapshots
    Only snapshot subvolumes in the filesystem will be listed

readonly
    Only readonly subvolumes in the filesystem will be listed

deleted
    Only deleted subvolumens that are ye not cleaned

generation_cmp
    List subvolumes in the filesystem that its generation is >=,
    <= or = value. '+' means >= value, '-' means <= value, If
    there is neither '+' nor '-', it means = value

ogeneration_cmp
    List subvolumes in the filesystem that its ogeneration is >=,
    <= or = value

sort
    List subvolumes in order by specified items. Possible values:
    * rootid
    * gen
    * ogen
    * path
    You can add '+' or '-' in front of each items, '+' means
    ascending, '-' means descending. The default is ascending. You
    can combite it in a list.

CLI Example:

    salt '*' btrfs.subvolume_list /var/volumes/tmp
    salt '*' btrfs.subvolume_list /var/volumes/tmp path=True
    salt '*' btrfs.subvolume_list /var/volumes/tmp sort='[-rootid]'

btrfs.subvolume_set_default:

Set the subvolume as default

subvolid
    ID of the new default subvolume

path
    Mount point for the filesystem

CLI Example:

    salt '*' btrfs.subvolume_set_default 257 /var/volumes/tmp

btrfs.subvolume_show:

Show information of a given subvolume

path
    Mount point for the filesystem

CLI Example:

    salt '*' btrfs.subvolume_show /var/volumes/tmp

btrfs.subvolume_snapshot:

Create a snapshot of a source subvolume

source
    Source subvolume from where to create the snapshot

dest
    If only dest is given, the subvolume will be named as the
    basename of the source

name
   Name of the snapshot

read_only
    Create a read only snapshot

CLI Example:

    salt '*' btrfs.subvolume_snapshot /var/volumes/tmp dest=/.snapshots
    salt '*' btrfs.subvolume_snapshot /var/volumes/tmp name=backup

btrfs.subvolume_sync:

Wait until given subvolume are completely removed from the
filesystem after deletion.

path
    Mount point for the filesystem

subvolids
    List of IDs of subvolumes to wait for

sleep
    Sleep N seconds betwenn checks (default: 1)

CLI Example:

    salt '*' btrfs.subvolume_sync /var/volumes/tmp
    salt '*' btrfs.subvolume_sync /var/volumes/tmp subvolids='[257]'

btrfs.usage:

Show in which disk the chunks are allocated.

CLI Example:

    salt '*' btrfs.usage /your/mountpoint

btrfs.version:

Return BTRFS version.

CLI Example:

    salt '*' btrfs.version

buildout.bootstrap:

Run the buildout bootstrap dance (python bootstrap.py).

directory
    directory to execute in

config
    alternative buildout configuration file to use

runas
    User used to run buildout as

env
    environment variables to set when running

buildout_ver
    force a specific buildout version (1 | 2)

test_release
    buildout accept test release

offline
    are we executing buildout in offline mode

distribute
    Forcing use of distribute

new_st
    Forcing use of setuptools >= 0.7

python
    path to a python executable to use in place of default (salt one)

onlyif
    Only execute cmd if statement on the host return 0

unless
    Do not execute cmd if statement on the host return 0

use_vt
    Use the new salt VT to stream output [experimental]

CLI Example:

    salt '*' buildout.bootstrap /srv/mybuildout

buildout.buildout:

Run buildout in a directory.

directory
    directory to execute in

config
    buildout config to use

parts
    specific buildout parts to run

runas
    user used to run buildout as

env
    environment variables to set when running

buildout_ver
    force a specific buildout version (1 | 2)

test_release
    buildout accept test release

new_st
    Forcing use of setuptools >= 0.7

distribute
    use distribute over setuptools if possible

offline
    does buildout run offline

python
    python to use

debug
    run buildout with -D debug flag

onlyif
    Only execute cmd if statement on the host return 0

unless
    Do not execute cmd if statement on the host return 0
newest
    run buildout in newest mode

verbose
    run buildout in verbose mode (-vvvvv)

use_vt
    Use the new salt VT to stream output [experimental]

CLI Example:

    salt '*' buildout.buildout /srv/mybuildout

buildout.run_buildout:

Run a buildout in a directory.

directory
    directory to execute in

config
    alternative buildout configuration file to use

offline
    are we executing buildout in offline mode

runas
    user used to run buildout as

env
    environment variables to set when running

onlyif
    Only execute cmd if statement on the host return 0

unless
    Do not execute cmd if statement on the host return 0

newest
    run buildout in newest mode

force
    run buildout unconditionally

verbose
    run buildout in verbose mode (-vvvvv)

use_vt
    Use the new salt VT to stream output [experimental]

CLI Example:

    salt '*' buildout.run_buildout /srv/mybuildout

buildout.upgrade_bootstrap:

Upgrade current bootstrap.py with the last released one.

Indeed, when we first run a buildout, a common source of problem
is to have a locally stale bootstrap, we just try to grab a new copy

directory
    directory to execute in

offline
    are we executing buildout in offline mode

buildout_ver
    forcing to use a specific buildout version (1 | 2)

onlyif
    Only execute cmd if statement on the host return 0

unless
    Do not execute cmd if statement on the host return 0

CLI Example:

    salt '*' buildout.upgrade_bootstrap /srv/mybuildout

chroot.apply:

Apply an state inside a chroot.

This function will call `chroot.highstate` or `chroot.sls` based
on the arguments passed to this function. It exists as a more
intuitive way of applying states.

root
    Path to the chroot environment

For a formal description of the possible parameters accepted in
this function, check `state.apply_` documentation.

CLI Example:

    salt myminion chroot.apply /chroot
    salt myminion chroot.apply /chroot stuff
    salt myminion chroot.apply /chroot stuff pillar='{"foo": "bar"}'

chroot.call:

Executes a Salt function inside a chroot environment.

The chroot does not need to have Salt installed, but Python is
required.

root
    Path to the chroot environment

function
    Salt execution module function

CLI Example:

    salt myminion chroot.call /chroot test.ping
    salt myminion chroot.call /chroot ssh.set_auth_key user key=mykey

chroot.create:

Create a basic chroot environment.

Note that this environment is not functional. The caller needs to
install the minimal required binaries, including Python if
chroot.call is called.

root
    Path to the chroot environment

CLI Example:

    salt myminion chroot.create /chroot

chroot.exist:

Return True if the chroot environment is present.

root
    Path to the chroot environment

CLI Example:

    salt myminion chroot.exist /chroot

chroot.highstate:

Retrieve the state data from the salt master for this minion and
execute it inside the chroot.

root
    Path to the chroot environment

For a formal description of the possible parameters accepted in
this function, check `state.highstate` documentation.

CLI Example:

    salt myminion chroot.highstate /chroot
    salt myminion chroot.highstate /chroot pillar='{"foo": "bar"}'

chroot.in_chroot:

Return True if the process is inside a chroot jail

New in version 3004

CLI Example:

    salt myminion chroot.in_chroot

chroot.sls:

Execute the states in one or more SLS files inside the chroot.

root
    Path to the chroot environment

saltenv
    Specify a salt fileserver environment to be used when applying
    states

mods
    List of states to execute

test
    Run states in test-only (dry-run) mode

exclude
    Exclude specific states from execution. Accepts a list of sls
    names, a comma-separated string of sls names, or a list of
    dictionaries containing ``sls`` or ``id`` keys. Glob-patterns
    may be used to match multiple states.

For a formal description of the possible parameters accepted in
this function, check `state.sls` documentation.

CLI Example:

    salt '*' chroot.sls /chroot stuff pillar='{"foo": "bar"}'

cloud.action:

Execute a single action on the given provider/instance

CLI Example:

    salt minionname cloud.action start instance=myinstance
    salt minionname cloud.action stop instance=myinstance
    salt minionname cloud.action show_image provider=my-ec2-config image=ami-1624987f

cloud.create:

Create an instance using Salt Cloud

CLI Example:

    salt minionname cloud.create my-ec2-config myinstance image=ami-1624987f size='t1.micro' ssh_username=ec2-user securitygroup=default delvol_on_destroy=True

cloud.destroy:

Destroy the named VM(s)

CLI Example:

    salt minionname cloud.destroy myinstance

cloud.full_query:

List all available cloud provider data

CLI Example:

    salt minionname cloud.full_query

cloud.get_instance:

Return details on an instance.

Similar to the cloud action show_instance
but returns only the instance details.

CLI Example:

    salt minionname cloud.get_instance myinstance

SLS Example:

    {{ salt['cloud.get_instance']('myinstance')['mac_address'] }}

cloud.has_instance:

Return true if the instance is found on a provider

CLI Example:

    salt minionname cloud.has_instance myinstance

cloud.list_images:

List cloud provider images for the given providers

CLI Example:

    salt minionname cloud.list_images my-gce-config

cloud.list_locations:

List cloud provider locations for the given providers

CLI Example:

    salt minionname cloud.list_locations my-gce-config

cloud.list_sizes:

List cloud provider sizes for the given providers

CLI Example:

    salt minionname cloud.list_sizes my-gce-config

cloud.map_run:

Execute a salt cloud map file

Cloud Map data can be retrieved from several sources:

- a local file (provide the path to the file to the 'path' argument)
- a JSON-formatted map directly (provide the appropriately formatted to using the 'map_data' argument)
- the Salt Pillar (provide the map name of under 'pillar:cloud:maps' to the 'map_pillar' argument)

Note:
    Only one of these sources can be read at a time. The options are listed
    in their order of precedence.

CLI Examples:

    salt minionname cloud.map_run /path/to/cloud.map
    salt minionname cloud.map_run path=/path/to/cloud.map
    salt minionname cloud.map_run map_pillar='<map_pillar>'
      Changed in version 2018.3.1
    salt minionname cloud.map_run map_data='<actual map data>'

cloud.network_create:

Create private network

CLI Example:

    salt minionname cloud.network_create my-nova names=['salt'] cidr='192.168.100.0/24'

cloud.network_list:

List private networks

CLI Example:

    salt minionname cloud.network_list my-nova

cloud.profile:

Spin up an instance using Salt Cloud

CLI Example:

    salt minionname cloud.profile my-gce-config myinstance

cloud.query:

List cloud provider data for all providers

CLI Examples:

    salt minionname cloud.query
    salt minionname cloud.query list_nodes_full
    salt minionname cloud.query list_nodes_select

cloud.select_query:

List selected nodes

CLI Example:

    salt minionname cloud.select_query

cloud.virtual_interface_create:

Attach private interfaces to a server

CLI Example:

    salt minionname cloud.virtual_interface_create my-nova names=['salt-master'] net_name='salt'

cloud.virtual_interface_list:

List virtual interfaces on a server

CLI Example:

    salt minionname cloud.virtual_interface_list my-nova names=['salt-master']

cloud.volume_attach:

Attach volume to a server

CLI Example:

    salt minionname cloud.volume_attach my-nova myblock server_name=myserver device='/dev/xvdf'

cloud.volume_create:

Create volume

CLI Example:

    salt minionname cloud.volume_create my-nova myblock size=100 voltype=SSD

cloud.volume_delete:

Delete volume

CLI Example:

    salt minionname cloud.volume_delete my-nova myblock

cloud.volume_detach:

Detach volume from a server

CLI Example:

    salt minionname cloud.volume_detach my-nova myblock server_name=myserver

cloud.volume_list:

List block storage volumes

CLI Example:

    salt minionname cloud.volume_list my-nova

cmd.exec_code:

Pass in two strings, the first naming the executable language, aka -
python2, python3, ruby, perl, lua, etc. the second string containing
the code you wish to execute. The stdout will be returned.

All parameters from :mod:`cmd.run_all <salt.modules.cmdmod.run_all>` except python_shell can be used.

CLI Example:

    salt '*' cmd.exec_code ruby 'puts "cheese"'
    salt '*' cmd.exec_code ruby 'puts "cheese"' args='["arg1", "arg2"]' env='{"FOO": "bar"}'

cmd.exec_code_all:

Pass in two strings, the first naming the executable language, aka -
python2, python3, ruby, perl, lua, etc. the second string containing
the code you wish to execute. All cmd artifacts (stdout, stderr, retcode, pid)
will be returned.

All parameters from :mod:`cmd.run_all <salt.modules.cmdmod.run_all>` except python_shell can be used.

CLI Example:

    salt '*' cmd.exec_code_all ruby 'puts "cheese"'
    salt '*' cmd.exec_code_all ruby 'puts "cheese"' args='["arg1", "arg2"]' env='{"FOO": "bar"}'

cmd.has_exec:

Returns true if the executable is available on the minion, false otherwise

CLI Example:

    salt '*' cmd.has_exec cat

cmd.powershell:

Execute the passed PowerShell command and return the output as a dictionary.

Other ``cmd.*`` functions (besides ``cmd.powershell_all``)
return the raw text output of the command. This
function appends ``| ConvertTo-JSON`` to the command and then parses the
JSON into a Python dictionary. If you want the raw textual result of your
PowerShell command you should use ``cmd.run`` with the ``shell=powershell``
option.

For example:

    salt '*' cmd.run '$PSVersionTable.CLRVersion' shell=powershell
    salt '*' cmd.run 'Get-NetTCPConnection' shell=powershell

New in version 2016.3.0

Warning:

    This passes the cmd argument directly to PowerShell
    without any further processing! Be absolutely sure that you
    have properly sanitized the command passed to this function
    and do not use untrusted inputs.

In addition to the normal ``cmd.run`` parameters, this command offers the
``depth`` parameter to change the Windows default depth for the
``ConvertTo-JSON`` powershell command. The Windows default is 2. If you need
more depth, set that here.

Note:
    For some commands, setting the depth to a value greater than 4 greatly
    increases the time it takes for the command to return and in many cases
    returns useless data.

:param str cmd: The powershell command to run.

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
  command to be run using the ``stdin`` parameter. This can be useful in cases
  where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

:param str password: Windows only. Required when specifying ``runas``. This
  parameter will be ignored on non-Windows platforms.

  New in version 2016.3.0

:param str shell: Specify an alternate shell. Defaults to "powershell". Can
    also use "pwsh" for powershell core if present on the system

:param bool python_shell: If False, let python handle the positional
  arguments. Set to True to use shell features, such as pipes or
  redirection.

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.powershell 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
    returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If ``True``, suppress stdout and stderr in the
    return data.

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

    New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to return.

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

:param bool reset_system_locale: Resets the system locale

:param str saltenv: The salt environment to use. Default is 'base'

:param int depth: The number of levels of contained objects to be included.
    Default is 2. Values greater than 4 seem to greatly increase the time
    it takes for the command to complete for some commands. eg: ``dir``

    New in version 2016.3.4

:param bool encode_cmd: Encode the command before executing. Use in cases
    where characters may be dropped or incorrectly converted when executed.
    Default is False.

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

:returns:
    :dict: A dictionary of data returned by the powershell command.

CLI Example:

    salt '*' cmd.powershell "$PSVersionTable.CLRVersion"

cmd.powershell_all:

Execute the passed PowerShell command and return a dictionary with a result
field representing the output of the command, as well as other fields
showing us what the PowerShell invocation wrote to ``stderr``, the process
id, and the exit code of the invocation.

This function appends ``| ConvertTo-JSON`` to the command before actually
invoking powershell.

An unquoted empty string is not valid JSON, but it's very normal for the
Powershell output to be exactly that. Therefore, we do not attempt to parse
empty Powershell output (which would result in an exception). Instead we
treat this as a special case and one of two things will happen:

- If the value of the ``force_list`` parameter is ``True``, then the
  ``result`` field of the return dictionary will be an empty list.

- If the value of the ``force_list`` parameter is ``False``, then the
  return dictionary **will not have a result key added to it**. We aren't
  setting ``result`` to ``None`` in this case, because ``None`` is the
  Python representation of "null" in JSON. (We likewise can't use ``False``
  for the equivalent reason.)

If Powershell's output is not an empty string and Python cannot parse its
content, then a ``CommandExecutionError`` exception will be raised.

If Powershell's output is not an empty string, Python is able to parse its
content, and the type of the resulting Python object is other than ``list``
then one of two things will happen:

- If the value of the ``force_list`` parameter is ``True``, then the
  ``result`` field will be a singleton list with the Python object as its
  sole member.

- If the value of the ``force_list`` parameter is ``False``, then the value
  of ``result`` will be the unmodified Python object.

If Powershell's output is not an empty string, Python is able to parse its
content, and the type of the resulting Python object is ``list``, then the
value of ``result`` will be the unmodified Python object. The
``force_list`` parameter has no effect in this case.

Note:
     An example of why the ``force_list`` parameter is useful is as
     follows: The Powershell command ``dir x | Convert-ToJson`` results in

     - no output when x is an empty directory.
     - a dictionary object when x contains just one item.
     - a list of dictionary objects when x contains multiple items.

     By setting ``force_list`` to ``True`` we will always end up with a
     list of dictionary items, representing files, no matter how many files
     x contains.  Conversely, if ``force_list`` is ``False``, we will end
     up with no ``result`` key in our return dictionary when x is an empty
     directory, and a dictionary object when x contains just one file.

If you want a similar function but with a raw textual result instead of a
Python dictionary, you should use ``cmd.run_all`` in combination with
``shell=powershell``.

The remaining fields in the return dictionary are described in more detail
in the ``Returns`` section.

Example:

    salt '*' cmd.run_all '$PSVersionTable.CLRVersion' shell=powershell
    salt '*' cmd.run_all 'Get-NetTCPConnection' shell=powershell

New in version 2018.3.0

Warning:

    This passes the cmd argument directly to PowerShell without any further
    processing! Be absolutely sure that you have properly sanitized the
    command passed to this function and do not use untrusted inputs.

In addition to the normal ``cmd.run`` parameters, this command offers the
``depth`` parameter to change the Windows default depth for the
``ConvertTo-JSON`` powershell command. The Windows default is 2. If you need
more depth, set that here.

Note:
    For some commands, setting the depth to a value greater than 4 greatly
    increases the time it takes for the command to return and in many cases
    returns useless data.

:param str cmd: The powershell command to run.

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

:param str shell: Specify an alternate shell. Defaults to "powershell". Can
    also use "pwsh" for powershell core if present on the system

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.powershell_all 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
    returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param int timeout: A timeout in seconds for the executed process to
    return.

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

:param bool reset_system_locale: Resets the system locale

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param str saltenv: The salt environment to use. Default is 'base'

:param int depth: The number of levels of contained objects to be included.
    Default is 2. Values greater than 4 seem to greatly increase the time
    it takes for the command to complete for some commands. eg: ``dir``

:param bool encode_cmd: Encode the command before executing. Use in cases
    where characters may be dropped or incorrectly converted when executed.
    Default is False.

:param bool force_list: The purpose of this parameter is described in the
    preamble of this function's documentation. Default value is False.

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

:return: A dictionary with the following entries:

    result
        For a complete description of this field, please refer to this
        function's preamble. **This key will not be added to the dictionary
        when force_list is False and Powershell's output is the empty
        string.**
    stderr
        What the PowerShell invocation wrote to ``stderr``.
    pid
        The process id of the PowerShell invocation
    retcode
        This is the exit code of the invocation of PowerShell.
        If the final execution status (in PowerShell) of our command
        (with ``| ConvertTo-JSON`` appended) is ``False`` this should be non-0.
        Likewise if PowerShell exited with ``$LASTEXITCODE`` set to some
        non-0 value, then ``retcode`` will end up with this value.

:rtype: dict

CLI Example:

    salt '*' cmd.powershell_all "$PSVersionTable.CLRVersion"

CLI Example:

    salt '*' cmd.powershell_all "dir mydirectory" force_list=True

cmd.retcode:

Execute a shell command and return the command's return code.

:param str cmd: The command to run. ex: ``ls -lart /home``

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

    Warning:

        For versions 2018.3.3 and above on macosx while using runas,
        to pass special characters to the command you need to escape
        the characters on the shell.

        Example:

            cmd.retcode 'echo '\''h=\"baz\"'\''' runas=macuser

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param str group: Group to run command as. Not currently supported
  on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.retcode 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
    returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param int timeout: A timeout in seconds for the executed process to return.

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

:rtype: int
:rtype: None
:returns: Return Code as an int or None if there was an exception.

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

CLI Example:

    salt '*' cmd.retcode "file /bin/bash"

The template arg can be set to 'jinja' or another supported template
engine to render the command arguments before execution.
For example:

    salt '*' cmd.retcode template=jinja "file {{grains.pythonpath[0]}}/python"

A string of standard input can be specified for the command to be run using
the ``stdin`` parameter. This can be useful in cases where sensitive
information must be read from standard input.

    salt '*' cmd.retcode "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'

cmd.run:

Execute the passed command and return the output as a string

:param str cmd: The command to run. ex: ``ls -lart /home``

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running.

    Warning:

        For versions 2018.3.3 and above on macosx while using runas,
        on linux while using run, to pass special characters to the
        command you need to escape the characters on the shell.

        Example:

            cmd.run 'echo '\''h=\"baz\"'\''' runas=macuser

:param str group: Group to run command as. Not currently supported
    on Windows.

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If ``False``, let python handle the positional
    arguments. Set to ``True`` to use shell features, such as pipes or
    redirection.

:param bool bg: If ``True``, run command in background and do not await or
    deliver its results

    New in version 2016.3.0

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.run 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not
    necessary) to $PATH

    New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
    returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If ``True``, suppress stdout and stderr in the
    return data.

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

    New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to return.

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

:param bool redirect_stderr: If set to ``True``, then stderr will be
    redirected to stdout. This is helpful for cases where obtaining both
    the retcode and output is desired. Default is ``True``

    New in version 3006.9

:param bool encoded_cmd: Specify if the supplied command is encoded.
    Only applies to shell 'powershell' and 'pwsh'.

    New in version 2018.3.0

    Older versions of powershell seem to return raw xml data in the return.
    To avoid raw xml data in the return, prepend your command with the
    following before encoding:

    `$ProgressPreference='SilentlyContinue'; <your command>`

    The following powershell code block will encode the `Write-Output`
    command so that it will not have the raw xml data in the return:

        # target string
        $Command = '$ProgressPreference="SilentlyContinue"; Write-Output "hello"'

        # Convert to Base64 encoded string
        $Encoded = [convert]::ToBase64String([System.Text.encoding]::Unicode.GetBytes($command))

        Write-Output $Encoded

:param bool raise_err: If ``True`` and the command has a nonzero exit code,
    a CommandExecutionError exception will be raised.

Warning:
    This function does not process commands through a shell
    unless the python_shell flag is set to True. This means that any
    shell-specific functionality such as 'echo' or the use of pipes,
    redirection or &&, should either be migrated to cmd.shell or
    have the python_shell=True flag set here.

    The use of python_shell=True means that the shell will accept _any_ input
    including potentially malicious commands such as 'good_command;rm -rf /'.
    Be absolutely certain that you have sanitized your input prior to using
    python_shell=True

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

:param int windows_codepage: 65001
    Only applies to Windows: the minion uses `C:\Windows\System32\chcp.com` to
    verify or set the code page before the command `cmd` is executed.
    Code page 65001 corresponds with UTF-8 and allows international localization of Windows.

  New in version 3002

CLI Example:

    salt '*' cmd.run "ls -l | awk '/foo/{print \\$2}'"

The template arg can be set to 'jinja' or another supported template
engine to render the command arguments before execution.
For example:

    salt '*' cmd.run template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \\$2}'"

Specify an alternate shell with the shell parameter:

    salt '*' cmd.run "Get-ChildItem C:\\ " shell='powershell'

A string of standard input can be specified for the command to be run using
the ``stdin`` parameter. This can be useful in cases where sensitive
information must be read from standard input.

    salt '*' cmd.run "grep f" stdin='one\\ntwo\\nthree\\nfour\\nfive\\n'

If an equal sign (``=``) appears in an argument to a Salt command it is
interpreted as a keyword argument in the format ``key=val``. That
processing can be bypassed in order to pass an equal sign through to the
remote shell command by manually specifying the kwarg:

    salt '*' cmd.run cmd='sed -e s/=/:/g'

cmd.run_all:

Execute the passed command and return a dict of return data

:param str cmd: The command to run. ex: ``ls -lart /home``

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

    Warning:

        For versions 2018.3.3 and above on macosx while using runas,
        to pass special characters to the command you need to escape
        the characters on the shell.

        Example:

            cmd.run_all 'echo '\''h=\"baz\"'\''' runas=macuser

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param str group: Group to run command as. Not currently supported
  on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.run_all 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not
    necessary) to $PATH

    New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
    returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If ``True``, suppress stdout and stderr in the
    return data.

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

    New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to
    return.

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

:param bool encoded_cmd: Specify if the supplied command is encoded.
    Only applies to shell 'powershell' and 'pwsh'.

    New in version 2018.3.0

    Older versions of powershell seem to return raw xml data in the return.
    To avoid raw xml data in the return, prepend your command with the
    following before encoding:

    `$ProgressPreference='SilentlyContinue'; <your command>`

    The following powershell code block will encode the `Write-Output`
    command so that it will not have the raw xml data in the return:

        # target string
        $Command = '$ProgressPreference="SilentlyContinue"; Write-Output "hello"'

        # Convert to Base64 encoded string
        $Encoded = [convert]::ToBase64String([System.Text.encoding]::Unicode.GetBytes($command))

        Write-Output $Encoded

:param bool redirect_stderr: If set to ``True``, then stderr will be
    redirected to stdout. This is helpful for cases where obtaining both
    the retcode and output is desired, but it is not desired to have the
    output separated into both stdout and stderr.

    New in version 2015.8.2

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

      New in version 2016.3.0

:param bool bg: If ``True``, run command in background and do not await or
    deliver its results

    New in version 2016.3.6

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

CLI Example:

    salt '*' cmd.run_all "ls -l | awk '/foo/{print \$2}'"

The template arg can be set to 'jinja' or another supported template
engine to render the command arguments before execution.
For example:

    salt '*' cmd.run_all template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \$2}'"

A string of standard input can be specified for the command to be run using
the ``stdin`` parameter. This can be useful in cases where sensitive
information must be read from standard input.

    salt '*' cmd.run_all "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'

cmd.run_bg:

New in version 2016.3.0

Execute the passed command in the background and return its PID

Note:

    If the init system is systemd and the backgrounded task should run even
    if the salt-minion process is restarted, prepend ``systemd-run
    --scope`` to the command. This will reparent the process in its own
    scope separate from salt-minion, and will not be affected by restarting
    the minion service.

:param str cmd: The command to run. ex: ``ls -lart /home``

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str group: Group to run command as. Not currently supported
  on Windows.

:param str shell: Shell to execute under. Defaults to the system default
  shell.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

    Warning:

        For versions 2018.3.3 and above on macosx while using runas,
        to pass special characters to the command you need to escape
        the characters on the shell.

        Example:

            cmd.run_bg 'echo '\''h=\"baz\"'\''' runas=macuser

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.run_bg 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not
    necessary) to $PATH

    New in version 2018.3.0

:param str 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.

:param str umask: The umask (in octal) to use when running the command.

:param int timeout: A timeout in seconds for the executed process to return.

Warning:

    This function does not process commands through a shell unless the
    ``python_shell`` argument is set to ``True``. This means that any
    shell-specific functionality such as 'echo' or the use of pipes,
    redirection or &&, should either be migrated to cmd.shell or have the
    python_shell=True flag set here.

    The use of ``python_shell=True`` means that the shell will accept _any_
    input including potentially malicious commands such as 'good_command;rm
    -rf /'.  Be absolutely certain that you have sanitized your input prior
    to using ``python_shell=True``.

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

CLI Example:

    salt '*' cmd.run_bg "fstrim-all"

The template arg can be set to 'jinja' or another supported template
engine to render the command arguments before execution.
For example:

    salt '*' cmd.run_bg template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \\$2}'"

Specify an alternate shell with the shell parameter:

    salt '*' cmd.run_bg "Get-ChildItem C:\\ " shell='powershell'

If an equal sign (``=``) appears in an argument to a Salt command it is
interpreted as a keyword argument in the format ``key=val``. That
processing can be bypassed in order to pass an equal sign through to the
remote shell command by manually specifying the kwarg:

    salt '*' cmd.run_bg cmd='ls -lR / | sed -e s/=/:/g > /tmp/dontwait'

cmd.run_chroot:

New in version 2014.7.0

This function runs :mod:`cmd.run_all <salt.modules.cmdmod.run_all>` wrapped
within a chroot, with dev and proc mounted in the chroot

:param str root: Path to the root of the jail to use.

:param str stdin: A string of standard input can be specified for
    the command to be run using the ``stdin`` parameter. This can
    be useful in cases where sensitive information must be read
    from standard input.:

:param str runas: User to run script as.

:param str group: Group to run script as.

:param str shell: Shell to execute under. Defaults to the system
    default shell.

:param str cmd: The command to run. ex: ``ls -lart /home``

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:parar str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param list binds: List of directories that will be exported inside
    the chroot with the bind option.

    New in version 3000

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.run_chroot 'some command' env='{"FOO": "bar"}'

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

:param dict clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output
    before it is returned.

:param str umask: The umask (in octal) to use when running the
     command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If ``True``, suppress stdout and stderr in the
    return data.

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

    New in version 2018.3.0

:param int timeout:
    A timeout in seconds for the executed process to return.

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

:param success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

CLI Example:

    salt '*' cmd.run_chroot /var/lib/lxc/container_name/rootfs 'sh /tmp/bootstrap.sh'

cmd.run_stderr:

Execute a command and only return the standard error

:param str cmd: The command to run. ex: ``ls -lart /home``

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

    Warning:

        For versions 2018.3.3 and above on macosx while using runas,
        to pass special characters to the command you need to escape
        the characters on the shell.

        Example:

            cmd.run_stderr 'echo '\''h=\"baz\"'\''' runas=macuser

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param str group: Group to run command as. Not currently supported
  on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.run_stderr 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not
    necessary) to $PATH

    New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
    returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If ``True``, suppress stdout and stderr in the
    return data.

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

    New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to
    return.

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

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

CLI Example:

    salt '*' cmd.run_stderr "ls -l | awk '/foo/{print \$2}'"

The template arg can be set to 'jinja' or another supported template
engine to render the command arguments before execution.
For example:

    salt '*' cmd.run_stderr template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \$2}'"

A string of standard input can be specified for the command to be run using
the ``stdin`` parameter. This can be useful in cases where sensitive
information must be read from standard input.

    salt '*' cmd.run_stderr "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'

cmd.run_stdout:

Execute a command, and only return the standard out

:param str cmd: The command to run. ex: ``ls -lart /home``

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

    Warning:

        For versions 2018.3.3 and above on macosx while using runas,
        to pass special characters to the command you need to escape
        the characters on the shell.

        Example:

            cmd.run_stdout 'echo '\''h=\"baz\"'\''' runas=macuser

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param str group: Group to run command as. Not currently supported
  on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.run_stdout 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not necessary)
    to $PATH

    New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
    returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If ``True``, suppress stdout and stderr in the
    return data.

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

    New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to
    return.

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

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

CLI Example:

    salt '*' cmd.run_stdout "ls -l | awk '/foo/{print \$2}'"

The template arg can be set to 'jinja' or another supported template
engine to render the command arguments before execution.
For example:

    salt '*' cmd.run_stdout template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \$2}'"

A string of standard input can be specified for the command to be run using
the ``stdin`` parameter. This can be useful in cases where sensitive
information must be read from standard input.

    salt '*' cmd.run_stdout "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'

cmd.script:

Download a script from a remote location and execute the script locally.
The script can be located on the salt master file server or on an HTTP/FTP
server.

The script will be executed directly, so it can be written in any available
programming language.

:param str source: The location of the script to download. If the file is
    located on the master in the directory named spam, and is called eggs,
    the source string is salt://spam/eggs

:param str args: String of command line args to pass to the script. Only
    used if no args are specified as part of the `name` argument. To pass a
    string containing spaces in YAML, you will need to doubly-quote it:

        salt myminion cmd.script salt://foo.sh "arg1 'arg two' arg3"

:param str cwd: The directory from which to execute the command. Defaults
    to the directory returned from Python's tempfile.mkstemp.

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

    Note:

        For Window's users, specifically Server users, it may be necessary
        to specify your runas user using the User Logon Name instead of the
        legacy logon name. Traditionally, logons would be in the following
        format.

            ``Domain/user``

        In the event this causes issues when executing scripts, use the UPN
        format which looks like the following.

            ``user@domain.local``

        More information <https://github.com/saltstack/salt/issues/55080>

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param str group: Group to run script as. Not currently supported
  on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param bool bg: If True, run script in background and do not await or
    deliver its results

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.script 'some command' env='{"FOO": "bar"}'

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

:param str 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.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If ``True``, suppress stdout and stderr in the
    return data.

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

    New in version 2018.3.0

:param int timeout: If the command has not terminated after timeout
    seconds, send the subprocess sigterm, and if sigterm is ignored, follow
    up with sigkill

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

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

CLI Example:

    salt '*' cmd.script salt://scripts/runme.sh
    salt '*' cmd.script salt://scripts/runme.sh 'arg1 arg2 "arg 3"'
    salt '*' cmd.script salt://scripts/windows_task.ps1 args=' -Input c:\tmp\infile.txt' shell='powershell'


    salt '*' cmd.script salt://scripts/runme.sh stdin='one\ntwo\nthree\nfour\nfive\n'

cmd.script_retcode:

Download a script from a remote location and execute the script locally.
The script can be located on the salt master file server or on an HTTP/FTP
server.

The script will be executed directly, so it can be written in any available
programming language.

The script can also be formatted as a template, the default is jinja.

Only evaluate the script return code and do not block for terminal output

:param str source: The location of the script to download. If the file is
    located on the master in the directory named spam, and is called eggs,
    the source string is salt://spam/eggs

:param str args: String of command line args to pass to the script. Only
    used if no args are specified as part of the `name` argument. To pass a
    string containing spaces in YAML, you will need to doubly-quote it:
    "arg1 'arg two' arg3"

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param str group: Group to run script as. Not currently supported
  on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
    default shell.

:param bool python_shell: If False, let python handle the positional
    arguments. Set to True to use shell features, such as pipes or
    redirection.

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.script_retcode 'some command' env='{"FOO": "bar"}'

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

:param str 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.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param int timeout: If the command has not terminated after timeout
    seconds, send the subprocess sigterm, and if sigterm is ignored, follow
    up with sigkill

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

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

CLI Example:

    salt '*' cmd.script_retcode salt://scripts/runme.sh
    salt '*' cmd.script_retcode salt://scripts/runme.sh 'arg1 arg2 "arg 3"'
    salt '*' cmd.script_retcode salt://scripts/windows_task.ps1 args=' -Input c:\tmp\infile.txt' shell='powershell'

A string of standard input can be specified for the command to be run using
the ``stdin`` parameter. This can be useful in cases where sensitive
information must be read from standard input.

    salt '*' cmd.script_retcode salt://scripts/runme.sh stdin='one\ntwo\nthree\nfour\nfive\n'

cmd.shell:

Execute the passed command and return the output as a string.

New in version 2015.5.0

:param str cmd: The command to run. ex: ``ls -lart /home``

:param str cwd: The directory from which to execute the command. Defaults
    to the home directory of the user specified by ``runas`` (or the user
    under which Salt is running if ``runas`` is not specified).

:param str stdin: A string of standard input can be specified for the
    command to be run using the ``stdin`` parameter. This can be useful in
    cases where sensitive information must be read from standard input.

:param str runas: Specify an alternate user to run the command. The default
    behavior is to run as the user under which Salt is running. If running
    on a Windows minion you must also use the ``password`` argument, and
    the target user account must be in the Administrators group.

    Warning:

        For versions 2018.3.3 and above on macosx while using runas,
        to pass special characters to the command you need to escape
        the characters on the shell.

        Example:

            cmd.shell 'echo '\''h=\"baz\"'\''' runas=macuser

:param str group: Group to run command as. Not currently supported
  on Windows.

:param str password: Windows only. Required when specifying ``runas``. This
    parameter will be ignored on non-Windows platforms.

    New in version 2016.3.0

:param int shell: Shell to execute under. Defaults to the system default
    shell.

:param bool bg: If True, run command in background and do not await or
    deliver its results

:param dict env: Environment variables to be set prior to execution.

    Note:
        When passing environment variables on the CLI, they should be
        passed as the string representation of a dictionary.

            salt myminion cmd.shell 'some command' env='{"FOO": "bar"}'

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

:param bool clean_env: Attempt to clean out all other shell environment
    variables and set only those provided in the 'env' argument to this
    function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not necessary)
    to $PATH

    New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
    returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
    command's output.

    Note:
        This should not need to be used in most cases. By default, Salt
        will try to use the encoding detected from the system locale, and
        will fall back to UTF-8 if this fails. This should only need to be
        used in cases where the output of the command is encoded in
        something other than the system locale or UTF-8.

        To see the encoding Salt has detected from the system locale, check
        the `locale` line in the output of :py:func:`test.versions_report
        <salt.modules.test.versions_report>`.

    New in version 2018.3.0

:param str output_loglevel: 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.

:param bool ignore_retcode: If the exit code of the command is nonzero,
    this is treated as an error condition, and the output from the command
    will be logged to the minion log. However, there are some cases where
    programs use the return code for signaling and a nonzero exit code
    doesn't necessarily mean failure. Pass this argument as ``True`` to
    skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If ``True``, suppress stdout and stderr in the
    return data.

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

    New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to
    return.

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

Warning:

    This passes the cmd argument directly to the shell without any further
    processing! Be absolutely sure that you have properly sanitized the
    command passed to this function and do not use untrusted inputs.

:param list success_retcodes: This parameter will allow a list of
    non-zero return codes that should be considered a success.  If the
    return code returned from the run matches any in the provided list,
    the return code will be overridden with zero.

  New in version 2019.2.0

:param list 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.

  New in version 3004

:param list 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.

  New in version 3004

:param bool stdin_raw_newlines: False
    If ``True``, Salt will not automatically convert the characters ``\n``
    present in the ``stdin`` value to newlines.

  New in version 2019.2.0

CLI Example:

    salt '*' cmd.shell "ls -l | awk '/foo/{print \$2}'"

The template arg can be set to 'jinja' or another supported template
engine to render the command arguments before execution.
For example:

    salt '*' cmd.shell template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \$2}'"

Specify an alternate shell with the shell parameter:

    salt '*' cmd.shell "Get-ChildItem C:\ " shell='powershell'

A string of standard input can be specified for the command to be run using
the ``stdin`` parameter. This can be useful in cases where sensitive
information must be read from standard input.

    salt '*' cmd.shell "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'

If an equal sign (``=``) appears in an argument to a Salt command it is
interpreted as a keyword argument in the format ``key=val``. That
processing can be bypassed in order to pass an equal sign through to the
remote shell command by manually specifying the kwarg:

    salt '*' cmd.shell cmd='sed -e s/=/:/g'

cmd.shell_info:

New in version 2016.11.0

Provides information about a shell or script languages which often use
``#!``. The values returned are dependent on the shell or scripting
languages all return the ``installed``, ``path``, ``version``,
``version_raw``

Args:
    shell (str): Name of the shell. Support shells/script languages include
    bash, cmd, perl, php, powershell, python, ruby and zsh

    list_modules (bool): True to list modules available to the shell.
    Currently only lists powershell modules.

Returns:
    dict: A dictionary of information about the shell

    {'version': '<2 or 3 numeric components dot-separated>',
     'version_raw': '<full version string>',
     'path': '<full path to binary>',
     'installed': <True, False or None>,
     '<attribute>': '<attribute value>'}

Note:
    - ``installed`` is always returned, if ``None`` or ``False`` also
      returns error and may also return ``stdout`` for diagnostics.
    - ``version`` is for use in determine if a shell/script language has a
      particular feature set, not for package management.
    - The shell must be within the executable search path.

CLI Example:

    salt '*' cmd.shell_info bash
    salt '*' cmd.shell_info powershell

:codeauthor: Damon Atkins <https://github.com/damon-atkins>

cmd.shells:

Lists the valid shells on this system via the /etc/shells file

New in version 2015.5.0

CLI Example:

    salt '*' cmd.shells

cmd.tty:

Echo a string to a specific tty

CLI Example:

    salt '*' cmd.tty tty0 'This is a test'
    salt '*' cmd.tty pts3 'This is a test'

cmd.which:

Returns the path of an executable available on the minion, None otherwise

CLI Example:

    salt '*' cmd.which cat

cmd.which_bin:

Returns the first command found in a list of commands

CLI Example:

    salt '*' cmd.which_bin '[pip2, pip, pip-python]'

composer.did_composer_install:

Test to see if the vendor directory exists in this directory

dir
    Directory location of the composer.json file

CLI Example:

    salt '*' composer.did_composer_install /var/www/application

composer.install:

Install composer dependencies for a directory.

If composer has not been installed globally making it available in the
system PATH & making it executable, the ``composer`` and ``php`` parameters
will need to be set to the location of the executables.

directory
    Directory location of the composer.json file.

composer
    Location of the composer.phar file. If not set composer will
    just execute "composer" as if it is installed globally.
    (i.e. /path/to/composer.phar)

php
    Location of the php executable to use with composer.
    (i.e. /usr/bin/php)

runas
    Which system user to run composer as.

prefer_source
    --prefer-source option of composer.

prefer_dist
    --prefer-dist option of composer.

no_scripts
    --no-scripts option of composer.

no_plugins
    --no-plugins option of composer.

optimize
    --optimize-autoloader option of composer. Recommended for production.

no_dev
    --no-dev option for composer. Recommended for production.

quiet
    --quiet option for composer. Whether or not to return output from composer.

composer_home
    $COMPOSER_HOME environment variable

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

CLI Example:

    salt '*' composer.install /var/www/application

    salt '*' composer.install /var/www/application             no_dev=True optimize=True

composer.selfupdate:

Update composer itself.

If composer has not been installed globally making it available in the
system PATH & making it executable, the ``composer`` and ``php`` parameters
will need to be set to the location of the executables.

composer
    Location of the composer.phar file. If not set composer will
    just execute "composer" as if it is installed globally.
    (i.e. /path/to/composer.phar)

php
    Location of the php executable to use with composer.
    (i.e. /usr/bin/php)

runas
    Which system user to run composer as.

quiet
    --quiet option for composer. Whether or not to return output from composer.

composer_home
    $COMPOSER_HOME environment variable

CLI Example:

    salt '*' composer.selfupdate

composer.update:

Update composer dependencies for a directory.

If `composer install` has not yet been run, this runs `composer install`
instead.

If composer has not been installed globally making it available in the
system PATH & making it executable, the ``composer`` and ``php`` parameters
will need to be set to the location of the executables.

directory
    Directory location of the composer.json file.

composer
    Location of the composer.phar file. If not set composer will
    just execute "composer" as if it is installed globally.
    (i.e. /path/to/composer.phar)

php
    Location of the php executable to use with composer.
    (i.e. /usr/bin/php)

runas
    Which system user to run composer as.

prefer_source
    --prefer-source option of composer.

prefer_dist
    --prefer-dist option of composer.

no_scripts
    --no-scripts option of composer.

no_plugins
    --no-plugins option of composer.

optimize
    --optimize-autoloader option of composer. Recommended for production.

no_dev
    --no-dev option for composer. Recommended for production.

quiet
    --quiet option for composer. Whether or not to return output from composer.

composer_home
    $COMPOSER_HOME environment variable

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

CLI Example:

    salt '*' composer.update /var/www/application

    salt '*' composer.update /var/www/application             no_dev=True optimize=True

config.backup_mode:

Return the backup mode

CLI Example:

    salt '*' config.backup_mode

config.dot_vals:

Pass in a configuration value that should be preceded by the module name
and a dot, this will return a list of all read key/value pairs

CLI Example:

    salt '*' config.dot_vals host

config.gather_bootstrap_script:

Download the salt-bootstrap script, and return its location

bootstrap
    URL of alternate bootstrap script

CLI Example:

    salt '*' config.gather_bootstrap_script

config.get:

New in version 0.14.0

Attempt to retrieve the named value from the minion config file, pillar,
grains or the master config. If the named value is not available, return
the value specified by the ``default`` argument. If this argument is not
specified, ``default`` falls back to an empty string.

Values can also be retrieved from nested dictionaries. Assume the below
data structure:

    {'pkg': {'apache': 'httpd'}}

To retrieve the value associated with the ``apache`` key, in the
sub-dictionary corresponding to the ``pkg`` key, the following command can
be used:

    salt myminion config.get pkg:apache

The ``:`` (colon) is used to represent a nested dictionary level.

Changed in version 2015.5.0
    The ``delimiter`` argument was added, to allow delimiters other than
    ``:`` to be used.

This function traverses these data stores in this order, returning the
first match found:

- Minion configuration
- Minion's grains
- Minion's pillar data
- Master configuration (requires :conf_minion:`pillar_opts` to be set to
  ``True`` in Minion config file in order to work)

This means that if there is a value that is going to be the same for the
majority of minions, it can be configured in the Master config file, and
then overridden using the grains, pillar, or Minion config file.

Adding config options to the Master or Minion configuration file is easy:

    my-config-option: value
    cafe-menu:
      - egg and bacon
      - egg sausage and bacon
      - egg and spam
      - egg bacon and spam
      - egg bacon sausage and spam
      - spam bacon sausage and spam
      - spam egg spam spam bacon and spam
      - spam sausage spam spam bacon spam tomato and spam

Note:
    Minion configuration options built into Salt (like those defined
    :ref:`here <configuration-salt-minion>`) will *always* be defined in
    the Minion configuration and thus *cannot be overridden by grains or
    pillar data*. However, additional (user-defined) configuration options
    (as in the above example) will not be in the Minion configuration by
    default and thus can be overridden using grains/pillar data by leaving
    the option out of the minion config file.

**Arguments**

delimiter
    New in version 2015.5.0

    Override the delimiter used to separate nested levels of a data
    structure.

merge
    New in version 2015.5.0

    If passed, this parameter will change the behavior of the function so
    that, instead of traversing each data store above in order and
    returning the first match, the data stores are first merged together
    and then searched. The pillar data is merged into the master config
    data, then the grains are merged, followed by the Minion config data.
    The resulting data structure is then searched for a match. This allows
    for configurations to be more flexible.

    Note:

        The merging described above does not mean that grain data will end
        up in the Minion's pillar data, or pillar data will end up in the
        master config data, etc. The data is just combined for the purposes
        of searching an amalgam of the different data stores.

    The supported merge strategies are as follows:

    - **recurse** - If a key exists in both dictionaries, and the new value
      is not a dictionary, it is replaced. Otherwise, the sub-dictionaries
      are merged together into a single dictionary, recursively on down,
      following the same criteria. For example:

          >>> dict1 = {'foo': {'bar': 1, 'qux': True},
                       'hosts': ['a', 'b', 'c'],
                       'only_x': None}
          >>> dict2 = {'foo': {'baz': 2, 'qux': False},
                       'hosts': ['d', 'e', 'f'],
                       'only_y': None}
          >>> merged
          {'foo': {'bar': 1, 'baz': 2, 'qux': False},
           'hosts': ['d', 'e', 'f'],
           'only_dict1': None,
           'only_dict2': None}

    - **overwrite** - If a key exists in the top level of both
      dictionaries, the new value completely overwrites the old. For
      example:

          >>> dict1 = {'foo': {'bar': 1, 'qux': True},
                       'hosts': ['a', 'b', 'c'],
                       'only_x': None}
          >>> dict2 = {'foo': {'baz': 2, 'qux': False},
                       'hosts': ['d', 'e', 'f'],
                       'only_y': None}
          >>> merged
          {'foo': {'baz': 2, 'qux': False},
           'hosts': ['d', 'e', 'f'],
           'only_dict1': None,
           'only_dict2': None}

CLI Example:

    salt '*' config.get pkg:apache
    salt '*' config.get lxc.container_profile:centos merge=recurse

config.items:

Return the complete config from the currently running minion process.
This includes defaults for values not set in the config file.

CLI Example:

    salt '*' config.items

config.manage_mode:

Return a mode value, normalized to a string

CLI Example:

    salt '*' config.manage_mode

config.merge:

Retrieves an option based on key, merging all matches.

Same as ``option()`` except that it merges all matches, rather than taking
the first match.

CLI Example:

    salt '*' config.merge schedule

config.option:

Returns the setting for the specified config value. The priority for
matches is the same as in :py:func:`config.get <salt.modules.config.get>`,
only this function does not recurse into nested data structures. Another
difference between this function and :py:func:`config.get
<salt.modules.config.get>` is that it comes with a set of "sane defaults".
To view these, you can run the following command:

    salt '*' config.option '*' omit_all=True wildcard=True

default
    The default value if no match is found. If not specified, then the
    fallback default will be an empty string, unless ``wildcard=True``, in
    which case the return will be an empty dictionary.

omit_opts : False
    Pass as ``True`` to exclude matches from the minion configuration file

omit_grains : False
    Pass as ``True`` to exclude matches from the grains

omit_pillar : False
    Pass as ``True`` to exclude matches from the pillar data

omit_master : False
    Pass as ``True`` to exclude matches from the master configuration file

omit_all : True
    Shorthand to omit all of the above and return matches only from the
    "sane defaults".

    New in version 3000

wildcard : False
    If used, this will perform pattern matching on keys. Note that this
    will also significantly change the return data. Instead of only a value
    being returned, a dictionary mapping the matched keys to their values
    is returned. For example, using ``wildcard=True`` with a ``key`` of
    ``'foo.ba*`` could return a dictionary like so:

        {'foo.bar': True, 'foo.baz': False}

    New in version 3000

CLI Example:

    salt '*' config.option redis.host

config.valid_fileproto:

Returns a boolean value based on whether or not the URI passed has a valid
remote file protocol designation

CLI Example:

    salt '*' config.valid_fileproto salt://path/to/file

consul.acl_clone:

Information about an ACL token.

:param consul_url: The Consul server URL.
:param id: Unique identifier for the ACL to update.
:return: Boolean, message of success or
         failure, and new ID of cloned ACL.

CLI Example:

    salt '*' consul.acl_info id='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'

consul.acl_create:

Create a new ACL token.

:param consul_url: The Consul server URL.
:param name: Meaningful indicator of the ACL's purpose.
:param type: Type is either client or management. A management
             token is comparable to a root user and has the
             ability to perform any action including creating,
             modifying, and deleting ACLs.
:param rules: The Consul server URL.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.acl_create

consul.acl_delete:

Delete an ACL token.

:param consul_url: The Consul server URL.
:param id: Unique identifier for the ACL to update.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.acl_delete id='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'

consul.acl_info:

Information about an ACL token.

:param consul_url: The Consul server URL.
:param id: Unique identifier for the ACL to update.
:return: Information about the ACL requested.

CLI Example:

    salt '*' consul.acl_info id='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'

consul.acl_list:

List the ACL tokens.

:param consul_url: The Consul server URL.
:return: List of ACLs

CLI Example:

    salt '*' consul.acl_list

consul.acl_update:

Update an ACL token.

:param consul_url: The Consul server URL.
:param name: Meaningful indicator of the ACL's purpose.
:param id: Unique identifier for the ACL to update.
:param type: Type is either client or management. A management
             token is comparable to a root user and has the
             ability to perform any action including creating,
             modifying, and deleting ACLs.
:param rules: The Consul server URL.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.acl_update

consul.agent_check_deregister:

The agent will take care of deregistering the check from the Catalog.

:param consul_url: The Consul server URL.
:param checkid: The ID of the check to deregister from Consul.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_check_deregister checkid='Memory Utilization'

consul.agent_check_fail:

This endpoint is used with a check that is of the TTL type. When this
is called, the status of the check is set to critical and the
TTL clock is reset.

:param consul_url: The Consul server URL.
:param checkid: The ID of the check to deregister from Consul.
:param note: A human-readable message with the status of the check.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_check_fail checkid='redis_check1' note='Forcing check into critical state.'

consul.agent_check_pass:

This endpoint is used with a check that is of the TTL type. When this
is called, the status of the check is set to passing and the TTL
clock is reset.

:param consul_url: The Consul server URL.
:param checkid: The ID of the check to mark as passing.
:param note: A human-readable message with the status of the check.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_check_pass checkid='redis_check1' note='Forcing check into passing state.'

consul.agent_check_register:

The register endpoint is used to add a new check to the local agent.

:param consul_url: The Consul server URL.
:param name: The description of what the check is for.
:param id: The unique name to use for the check, if not
           provided 'name' is used.
:param notes: Human readable description of the check.
:param script: If script is provided, the check type is
               a script, and Consul will evaluate that script
               based on the interval parameter.
:param http: Check will perform an HTTP GET request against
             the value of HTTP (expected to be a URL) based
             on the interval parameter.
:param ttl: If a TTL type is used, then the TTL update endpoint
            must be used periodically to update the state of the check.
:param interval: Interval at which the check should run.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_check_register name='Memory Utilization' script='/usr/local/bin/check_mem.py' interval='15s'

consul.agent_check_warn:

This endpoint is used with a check that is of the TTL type. When this
is called, the status of the check is set to warning and the TTL
clock is reset.

:param consul_url: The Consul server URL.
:param checkid: The ID of the check to deregister from Consul.
:param note: A human-readable message with the status of the check.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_check_warn checkid='redis_check1' note='Forcing check into warning state.'

consul.agent_checks:

Returns the checks the local agent is managing

:param consul_url: The Consul server URL.
:return: Returns the checks the local agent is managing

CLI Example:

    salt '*' consul.agent_checks

consul.agent_join:

Triggers the local agent to join a node

:param consul_url: The Consul server URL.
:param address: The address for the agent to connect to.
:param wan: Causes the agent to attempt to join using the WAN pool.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_join address='192.168.1.1'

consul.agent_leave:

Used to instruct the agent to force a node into the left state.

:param consul_url: The Consul server URL.
:param node: The node the agent will force into left state
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_leave node='web1.example.com'

consul.agent_maintenance:

Manages node maintenance mode

:param consul_url: The Consul server URL.
:param enable: The enable flag is required.
               Acceptable values are either true
               (to enter maintenance mode) or
               false (to resume normal operation).
:param reason: If provided, its value should be a
               text string explaining the reason for
               placing the node into maintenance mode.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_maintenance enable='False' reason='Upgrade in progress'

consul.agent_members:

Returns the members as seen by the local serf agent

:param consul_url: The Consul server URL.
:return: Returns the members as seen by the local serf agent

CLI Example:

    salt '*' consul.agent_members

consul.agent_self:

Returns the local node configuration

:param consul_url: The Consul server URL.
:return: Returns the local node configuration

CLI Example:

    salt '*' consul.agent_self

consul.agent_service_deregister:

Used to remove a service.

:param consul_url: The Consul server URL.
:param serviceid: A serviceid describing the service.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_service_deregister serviceid='redis'

consul.agent_service_maintenance:

Used to place a service into maintenance mode.

:param consul_url: The Consul server URL.
:param serviceid: A name of the service.
:param enable: Whether the service should be enabled or disabled.
:param reason: A human readable message of why the service was
               enabled or disabled.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_service_deregister serviceid='redis' enable='True' reason='Down for upgrade'

consul.agent_service_register:

The used to add a new service, with an optional
health check, to the local agent.

:param consul_url: The Consul server URL.
:param name: A name describing the service.
:param address: The address used by the service, defaults
                to the address of the agent.
:param port: The port used by the service.
:param id: Unique ID to identify the service, if not
           provided the value of the name parameter is used.
:param tags: Identifying tags for service, string or list.
:param script: If script is provided, the check type is
               a script, and Consul will evaluate that script
               based on the interval parameter.
:param http: Check will perform an HTTP GET request against
             the value of HTTP (expected to be a URL) based
             on the interval parameter.
:param check_ttl: If a TTL type is used, then the TTL update
                  endpoint must be used periodically to update
                  the state of the check.
:param check_interval: Interval at which the check should run.
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.agent_service_register name='redis' tags='["master", "v1"]' address="127.0.0.1" port="8080" check_script="/usr/local/bin/check_redis.py" interval="10s"

consul.agent_services:

Returns the services the local agent is managing

:param consul_url: The Consul server URL.
:return: Returns the services the local agent is managing

CLI Example:

    salt '*' consul.agent_services

consul.catalog_datacenters:

Return list of available datacenters from catalog.

:param consul_url: The Consul server URL.
:return: The list of available datacenters.

CLI Example:

    salt '*' consul.catalog_datacenters

consul.catalog_deregister:

Deregisters a node, service, or check

:param consul_url: The Consul server URL.
:param node: The node to deregister.
:param datacenter: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:param checkid: The ID of the health check to deregister.
:param serviceid: The ID of the service to deregister.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.catalog_register node='node1' serviceid='redis_server1' checkid='redis_check1'

consul.catalog_node:

Information about the registered node.

:param consul_url: The Consul server URL.
:param node: The node to request information about.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:return: Information about the requested node.

CLI Example:

    salt '*' consul.catalog_service service='redis'

consul.catalog_nodes:

Return list of available nodes from catalog.

:param consul_url: The Consul server URL.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:return: The list of available nodes.

CLI Example:

    salt '*' consul.catalog_nodes

consul.catalog_register:

Registers a new node, service, or check

:param consul_url: The Consul server URL.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:param node: The node to register.
:param address: The address of the node.
:param service: The service that will be registered.
:param service_address: The address that the service listens on.
:param service_port: The port for the service.
:param service_id: A unique identifier for the service, if this is not
                   provided "name" will be used.
:param service_tags: Any tags associated with the service.
:param check: The name of the health check to register
:param check_status: The initial status of the check,
                     must be one of unknown, passing, warning, or critical.
:param check_service: The service that the check is performed against.
:param check_id: Unique identifier for the service.
:param check_notes: An opaque field that is meant to hold human-readable text.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.catalog_register node='node1' address='192.168.1.1' service='redis' service_address='127.0.0.1' service_port='8080' service_id='redis_server1'

consul.catalog_service:

Information about the registered service.

:param consul_url: The Consul server URL.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:param tag: Filter returned services with tag parameter.
:return: Information about the requested service.

CLI Example:

    salt '*' consul.catalog_service service='redis'

consul.catalog_services:

Return list of available services rom catalog.

:param consul_url: The Consul server URL.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:return: The list of available services.

CLI Example:

    salt '*' consul.catalog_services

consul.delete:

Delete values from Consul

:param consul_url: The Consul server URL.
:param key: The key to use as the starting point for the list.
:param recurse: Delete values recursively beginning at the value of key.
:param cas: This flag is used to turn the DELETE into
            a Check-And-Set operation.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.delete key='web'
    salt '*' consul.delete key='web' recurse='True'

consul.event_fire:

List the ACL tokens.

:param consul_url: The Consul server URL.
:param name: The name of the event to fire.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:param node: Filter by node name.
:param service: Filter by service name.
:param tag: Filter by tag name.
:return: List of ACLs

CLI Example:

    salt '*' consul.event_fire name='deploy'

consul.event_list:

List the recent events.

:param consul_url: The Consul server URL.
:param name: The name of the event to fire.
:return: List of ACLs

CLI Example:

    salt '*' consul.event_list

consul.get:

Get key from Consul

:param consul_url: The Consul server URL.
:param key: The key to use as the starting point for the list.
:param recurse: Return values recursively beginning at the value of key.
:param decode: By default values are stored as Base64 encoded values,
               decode will return the whole key with the value decoded.
:param raw: Simply return the decoded value of the key.
:return: The keys in Consul.

CLI Example:

    salt '*' consul.get key='web/key1'
    salt '*' consul.get key='web' recurse=True
    salt '*' consul.get key='web' recurse=True decode=True

By default values stored in Consul are base64 encoded, passing the
decode option will show them as the decoded values.

    salt '*' consul.get key='web' recurse=True decode=True raw=True

By default Consult will return other information about the key, the raw
option will return only the raw value.

consul.health_checks:

Health information about the registered service.

:param consul_url: The Consul server URL.
:param service: The service to request health information about.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:return: Health information about the requested node.

CLI Example:

    salt '*' consul.health_checks service='redis1'

consul.health_node:

Health information about the registered node.

:param consul_url: The Consul server URL.
:param node: The node to request health information about.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:return: Health information about the requested node.

CLI Example:

    salt '*' consul.health_node node='node1'

consul.health_service:

Health information about the registered service.

:param consul_url: The Consul server URL.
:param service: The service to request health information about.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:param tag: Filter returned services with tag parameter.
:param passing: Filter results to only nodes with all
                checks in the passing state.
:return: Health information about the requested node.

CLI Example:

    salt '*' consul.health_service service='redis1'

    salt '*' consul.health_service service='redis1' passing='True'

consul.health_state:

Returns the checks in the state provided on the path.

:param consul_url: The Consul server URL.
:param state: The state to show checks for. The supported states
              are any, unknown, passing, warning, or critical.
              The any state is a wildcard that can be used to
              return all checks.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:return: The checks in the provided state.

CLI Example:

    salt '*' consul.health_state state='redis1'

    salt '*' consul.health_state service='redis1' passing='True'

consul.list:

List keys in Consul

:param consul_url: The Consul server URL.
:param key: The key to use as the starting point for the list.
:return: The list of keys.

CLI Example:

    salt '*' consul.list
    salt '*' consul.list key='web'

consul.put:

Put values into Consul

:param consul_url: The Consul server URL.
:param key: The key to use as the starting point for the list.
:param value: The value to set the key to.
:param flags: This can be used to specify an unsigned value
              between 0 and 2^64-1. Clients can choose to use
              this however makes sense for their application.
:param cas: This flag is used to turn the PUT into a
            Check-And-Set operation.
:param acquire: This flag is used to turn the PUT into a
                lock acquisition operation.
:param release: This flag is used to turn the PUT into a
                lock release operation.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.put key='web/key1' value="Hello there"

    salt '*' consul.put key='web/key1' value="Hello there" acquire='d5d371f4-c380-5280-12fd-8810be175592'

    salt '*' consul.put key='web/key1' value="Hello there" release='d5d371f4-c380-5280-12fd-8810be175592'

consul.session_create:

Used to create a session.

:param consul_url: The Consul server URL.
:param lockdelay: Duration string using a "s" suffix for seconds.
                  The default is 15s.
:param node: Must refer to a node that is already registered,
             if specified. By default, the agent's own node
             name is used.
:param name: A human-readable name for the session
:param checks: A list of associated health checks. It is highly
               recommended that, if you override this list, you
               include the default "serfHealth".
:param behavior: Can be set to either release or delete. This controls
                 the behavior when a session is invalidated. By default,
                 this is release, causing any locks that are held to be
                 released. Changing this to delete causes any locks that
                 are held to be deleted. delete is useful for creating
                 ephemeral key/value entries.
:param ttl: Session is invalidated if it is not renewed before
            the TTL expires
:return: Boolean and message indicating success or failure.

CLI Example:

    salt '*' consul.session_create node='node1' name='my-session' behavior='delete' ttl='3600s'

consul.session_destroy:

Destroy session

:param consul_url: The Consul server URL.
:param session: The ID of the session to destroy.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.session_destroy session='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'

consul.session_info:

Information about a session

:param consul_url: The Consul server URL.
:param session: The ID of the session to return information about.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:return: Boolean & message of success or failure.

CLI Example:

    salt '*' consul.session_info session='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'

consul.session_list:

Used to list sessions.

:param consul_url: The Consul server URL.
:param dc: By default, the datacenter of the agent is queried;
           however, the dc can be provided using the "dc" parameter.
:param return_list: By default, all information about the sessions is
                    returned, using the return_list parameter will return
                    a list of session IDs.
:return: A list of all available sessions.

CLI Example:

    salt '*' consul.session_list

consul.status_leader:

Returns the current Raft leader

:param consul_url: The Consul server URL.
:return: The address of the Raft leader.

CLI Example:

    salt '*' consul.status_leader

consul.status_peers:

Returns the current Raft peer set

:param consul_url: The Consul server URL.
:return: Retrieves the Raft peers for the
         datacenter in which the agent is running.

CLI Example:

    salt '*' consul.status_peers

container_resource.cache_file:

Wrapper for cp.cache_file which raises an error if the file was unable to
be cached.

CLI Example:

    salt myminion container_resource.cache_file salt://foo/bar/baz.txt

container_resource.copy_to:

Common logic for copying files to containers

path
    path to the container parent (for LXC only)
    default: /var/lib/lxc (system default)

CLI Example:

    salt myminion container_resource.copy_to mycontainer /local/file/path /container/file/path container_type=docker exec_driver=nsenter

container_resource.run:

Common logic for running shell commands in containers

path
    path to the container parent (for LXC only)
    default: /var/lib/lxc (system default)

CLI Example:

    salt myminion container_resource.run mycontainer 'ps aux' container_type=docker exec_driver=nsenter output=stdout

cp.cache_dest:

New in version 3000

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Returns the expected cache path for the file, if cached using
:py:func:`cp.cache_file <salt.modules.cp.cache_file>`.

Note:
    This only returns the _expected_ path, it does not tell you if the URL
    is really cached. To check if the URL is cached, use
    :py:func:`cp.is_cached <salt.modules.cp.is_cached>` instead.

CLI Examples:

    salt '*' cp.cache_dest https://foo.com/bar.rpm
    salt '*' cp.cache_dest salt://my/file
    salt '*' cp.cache_dest salt://my/file saltenv=dev

cp.cache_dir:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Download and cache everything under a directory from the master


include_pat : None
    Glob or regex to narrow down the files cached from the given path. If
    matching with a regex, the regex must be prefixed with ``E@``,
    otherwise the expression will be interpreted as a glob.

    New in version 2014.7.0

exclude_pat : None
    Glob or regex to exclude certain files from being cached from the given
    path. If matching with a regex, the regex must be prefixed with ``E@``,
    otherwise the expression will be interpreted as a glob.

    Note:

        If used with ``include_pat``, files matching this pattern will be
        excluded from the subset of files defined by ``include_pat``.

    New in version 2014.7.0

CLI Examples:

    salt '*' cp.cache_dir salt://path/to/dir
    salt '*' cp.cache_dir salt://path/to/dir include_pat='E@*.py$'

cp.cache_file:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Used to cache a single file on the Minion

Returns the location of the new cached file on the Minion

source_hash
    If ``name`` is an http(s) or ftp URL and the file exists in the
    minion's file cache, this option can be passed to keep the minion from
    re-downloading the file if the cached copy matches the specified hash.

    New in version 2018.3.0

verify_ssl
    If ``False``, remote https file sources (``https://``) and source_hash
    will not attempt to validate the servers certificate. Default is True.

    New in version 3002

use_etag
    If ``True``, remote http/https file sources will attempt to use the
    ETag header to determine if the remote file needs to be downloaded.
    This provides a lightweight mechanism for promptly refreshing files
    changed on a web server without requiring a full hash comparison via
    the ``source_hash`` parameter.

    New in version 3005

CLI Example:

    salt '*' cp.cache_file salt://path/to/file

There are two ways of defining the fileserver environment (a.k.a.
``saltenv``) from which to cache the file. One is to use the ``saltenv``
parameter, and the other is to use a querystring syntax in the ``salt://``
URL. The below two examples are equivalent:

    salt '*' cp.cache_file salt://foo/bar.conf saltenv=config
    salt '*' cp.cache_file salt://foo/bar.conf?saltenv=config

If the path being cached is a ``salt://`` URI, and the path does not exist,
then ``False`` will be returned.

Note:
    It may be necessary to quote the URL when using the querystring method,
    depending on the shell being used to run the command.

cp.cache_file_ssh:

This function is an alias of cache_file.

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Used to cache a single file on the Minion

Returns the location of the new cached file on the Minion

source_hash
    If ``name`` is an http(s) or ftp URL and the file exists in the
    minion's file cache, this option can be passed to keep the minion from
    re-downloading the file if the cached copy matches the specified hash.

    New in version 2018.3.0

verify_ssl
    If ``False``, remote https file sources (``https://``) and source_hash
    will not attempt to validate the servers certificate. Default is True.

    New in version 3002

use_etag
    If ``True``, remote http/https file sources will attempt to use the
    ETag header to determine if the remote file needs to be downloaded.
    This provides a lightweight mechanism for promptly refreshing files
    changed on a web server without requiring a full hash comparison via
    the ``source_hash`` parameter.

    New in version 3005

CLI Example:

    salt '*' cp.cache_file salt://path/to/file

There are two ways of defining the fileserver environment (a.k.a.
``saltenv``) from which to cache the file. One is to use the ``saltenv``
parameter, and the other is to use a querystring syntax in the ``salt://``
URL. The below two examples are equivalent:

    salt '*' cp.cache_file salt://foo/bar.conf saltenv=config
    salt '*' cp.cache_file salt://foo/bar.conf?saltenv=config

If the path being cached is a ``salt://`` URI, and the path does not exist,
then ``False`` will be returned.

Note:
    It may be necessary to quote the URL when using the querystring method,
    depending on the shell being used to run the command.

cp.cache_files:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Used to gather many files from the Master, the gathered files will be
saved in the minion cachedir reflective to the paths retrieved from the
Master

CLI Example:

    salt '*' cp.cache_files salt://pathto/file1,salt://pathto/file1

There are two ways of defining the fileserver environment (a.k.a.
``saltenv``) from which to cache the files. One is to use the ``saltenv``
parameter, and the other is to use a querystring syntax in the ``salt://``
URL. The below two examples are equivalent:

    salt '*' cp.cache_files salt://foo/bar.conf,salt://foo/baz.conf saltenv=config
    salt '*' cp.cache_files salt://foo/bar.conf?saltenv=config,salt://foo/baz.conf?saltenv=config

The querystring method is less useful when all files are being cached from
the same environment, but is a good way of caching files from multiple
different environments in the same command. For example, the below command
will cache the first file from the ``config1`` environment, and the second
one from the ``config2`` environment.

    salt '*' cp.cache_files salt://foo/bar.conf?saltenv=config1,salt://foo/bar.conf?saltenv=config2

Note:
    It may be necessary to quote the URL when using the querystring method,
    depending on the shell being used to run the command.

cp.cache_local_file:

Cache a local file on the minion in the localfiles cache

CLI Example:

    salt '*' cp.cache_local_file /etc/hosts

cp.cache_master:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Retrieve all of the files on the master and cache them locally

CLI Example:

    salt '*' cp.cache_master

cp.envs:

List available environments for fileserver

CLI Example:

    salt '*' cp.envs

cp.get_dir:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Used to recursively copy a directory from the salt master

CLI Example:

    salt '*' cp.get_dir salt://path/to/dir/ /minion/dest

get_dir supports the same template and gzip arguments as get_file.

cp.get_file:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Changed in version 2018.3.0
    ``dest`` can now be a directory

Used to get a single file from the salt master

CLI Example:

    salt '*' cp.get_file salt://path/to/file /minion/dest

Template rendering can be enabled on both the source and destination file
names like so:

    salt '*' cp.get_file "salt://{{grains.os}}/vimrc" /etc/vimrc template=jinja

This example would instruct all Salt minions to download the vimrc from a
directory with the same name as their os grain and copy it to /etc/vimrc

For larger files, the cp.get_file module also supports gzip compression.
Because gzip is CPU-intensive, this should only be used in scenarios where
the compression ratio is very high (e.g. pretty-printed JSON or YAML
files).

Use the *gzip* named argument to enable it.  Valid values are 1..9, where 1
is the lightest compression and 9 the heaviest.  1 uses the least CPU on
the master (and minion), 9 uses the most.

There are two ways of defining the fileserver environment (a.k.a.
``saltenv``) from which to retrieve the file. One is to use the ``saltenv``
parameter, and the other is to use a querystring syntax in the ``salt://``
URL. The below two examples are equivalent:

    salt '*' cp.get_file salt://foo/bar.conf /etc/foo/bar.conf saltenv=config
    salt '*' cp.get_file salt://foo/bar.conf?saltenv=config /etc/foo/bar.conf

Note:
    It may be necessary to quote the URL when using the querystring method,
    depending on the shell being used to run the command.

cp.get_file_str:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Download a file from a URL to the Minion cache directory and return the
contents of that file

Returns ``False`` if Salt was unable to cache a file from a URL.

CLI Example:

    salt '*' cp.get_file_str salt://my/file

cp.get_template:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Render a file as a template before setting it down.
Warning, order is not the same as in fileclient.cp for
non breaking old API.

CLI Example:

    salt '*' cp.get_template salt://path/to/template /minion/dest

cp.get_url:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Changed in version 2018.3.0
    ``dest`` can now be a directory

Used to get a single file from a URL.

path
    A URL to download a file from. Supported URL schemes are: ``salt://``,
    ``http://``, ``https://``, ``ftp://``, ``s3://``, ``swift://`` and
    ``file://`` (local filesystem). If no scheme was specified, this is
    equivalent of using ``file://``.
    If a ``file://`` URL is given, the function just returns absolute path
    to that file on a local filesystem.
    The function returns ``False`` if Salt was unable to fetch a file from
    a ``salt://`` URL.

dest
    The default behaviour is to write the fetched file to the given
    destination path. If this parameter is omitted or set as empty string
    (``''``), the function places the remote file on the local filesystem
    inside the Minion cache directory and returns the path to that file.

    Note:

        To simply return the file contents instead, set destination to
        ``None``. This works with ``salt://``, ``http://``, ``https://``
        and ``file://`` URLs. The files fetched by ``http://`` and
        ``https://`` will not be cached.

saltenv
    Salt fileserver environment from which to retrieve the file. Ignored if
    ``path`` is not a ``salt://`` URL.

source_hash
    If ``path`` is an http(s) or ftp URL and the file exists in the
    minion's file cache, this option can be passed to keep the minion from
    re-downloading the file if the cached copy matches the specified hash.

    New in version 2018.3.0

CLI Example:

    salt '*' cp.get_url salt://my/file /tmp/this_file_is_mine
    salt '*' cp.get_url http://www.slashdot.org /tmp/index.html

cp.hash_file:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Return the hash of a file, to get the hash of a file on the
salt master file server prepend the path with salt://<file on server>
otherwise, prepend the file with / for a local file.

CLI Example:

    salt '*' cp.hash_file salt://path/to/file

cp.hash_file_ssh:

This function is an alias of hash_file.

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Return the hash of a file, to get the hash of a file on the
salt master file server prepend the path with salt://<file on server>
otherwise, prepend the file with / for a local file.

CLI Example:

    salt '*' cp.hash_file salt://path/to/file

cp.is_cached:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Returns the full path to a file if it is cached locally on the minion
otherwise returns a blank string

CLI Example:

    salt '*' cp.is_cached salt://path/to/file

cp.list_master:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

List all of the files stored on the master

CLI Example:

    salt '*' cp.list_master

cp.list_master_dirs:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

List all of the directories stored on the master

CLI Example:

    salt '*' cp.list_master_dirs

cp.list_master_symlinks:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

List all of the symlinks stored on the master

CLI Example:

    salt '*' cp.list_master_symlinks

cp.list_minion:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

List all of the files cached on the minion

CLI Example:

    salt '*' cp.list_minion

cp.list_states:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

List all of the available state files in an environment

CLI Example:

    salt '*' cp.list_states

cp.push:

WARNING Files pushed to the master will have global read permissions..

Push a file from the minion up to the master, the file will be saved to
the salt master in the master's minion files cachedir
(defaults to ``/var/cache/salt/master/minions/minion-id/files``)

Since this feature allows a minion to push a file up to the master server
it is disabled by default for security purposes. To enable, set
``file_recv`` to ``True`` in the master configuration file, and restart the
master.

keep_symlinks
    Keep the path value without resolving its canonical form

upload_path
    Provide a different path inside the master's minion files cachedir

remove_source
    Remove the source file on the minion

    New in version 2016.3.0

CLI Example:

    salt '*' cp.push /etc/fstab
    salt '*' cp.push /etc/system-release keep_symlinks=True
    salt '*' cp.push /etc/fstab upload_path='/new/path/fstab'
    salt '*' cp.push /tmp/filename remove_source=True

cp.push_dir:

Push a directory from the minion up to the master, the files will be saved
to the salt master in the master's minion files cachedir (defaults to
``/var/cache/salt/master/minions/minion-id/files``).  It also has a glob
for matching specific files using globbing.

New in version 2014.7.0

Since this feature allows a minion to push files up to the master server it
is disabled by default for security purposes. To enable, set ``file_recv``
to ``True`` in the master configuration file, and restart the master.

upload_path
    Provide a different path and directory name inside the master's minion
    files cachedir

CLI Example:

    salt '*' cp.push /usr/lib/mysql
    salt '*' cp.push /usr/lib/mysql upload_path='/newmysql/path'
    salt '*' cp.push_dir /etc/modprobe.d/ glob='*.conf'

cp.recv:

Used with salt-cp, pass the files dict, and the destination.

This function receives small fast copy files from the master via salt-cp.
It does not work via the CLI.

CLI Example:

    salt '*' cp.recv

cp.recv_chunked:

This function receives files copied to the minion using ``salt-cp`` and is
not intended to be used directly on the CLI.

CLI Example:

    salt '*' cp.recv_chunked

cp.stat_file:

Changed in version 3005
    ``saltenv`` will use value from config if not explicitly set

Return the permissions of a file, to get the permissions of a file on the
salt master file server prepend the path with salt://<file on server>
otherwise, prepend the file with / for a local file.

CLI Example:

    salt '*' cp.stat_file salt://path/to/file

cpan.install:

Install a Perl module from CPAN

CLI Example:

    salt '*' cpan.install Template::Alloy

cpan.list:

List installed Perl modules, and the version installed

CLI Example:

    salt '*' cpan.list

cpan.remove:

Attempt to remove a Perl module that was installed from CPAN. Because the
``cpan`` command doesn't actually support "uninstall"-like functionality,
this function will attempt to do what it can, with what it has from CPAN.

Until this function is declared stable, USE AT YOUR OWN RISK!

CLI Example:

    salt '*' cpan.remove Old::Package

cpan.show:

Show information about a specific Perl module

CLI Example:

    salt '*' cpan.show Template::Alloy

cpan.show_config:

Return a dict of CPAN configuration values

CLI Example:

    salt '*' cpan.show_config

cron.get_entry:

Return the specified entry from user's crontab.
identifier will be used if specified, otherwise will lookup cmd
Either identifier or cmd should be specified.

user:
    User's crontab to query

identifier:
    Search for line with identifier

cmd:
    Search for cron line with cmd

CLI Example:

    salt '*' cron.get_entry root identifier=task1

cron.list_tab:

Return the contents of the specified user's crontab

CLI Example:

    salt '*' cron.list_tab root

cron.ls:

This function is an alias of list_tab.

Return the contents of the specified user's crontab

CLI Example:

    salt '*' cron.list_tab root

cron.raw_cron:

Return the contents of the user's crontab

CLI Example:

    salt '*' cron.raw_cron root

cron.rm:

This function is an alias of rm_job.

Remove a cron job for a specified user. If any of the day/time params are
specified, the job will only be removed if the specified params match.

CLI Example:

    salt '*' cron.rm_job root /usr/local/weekly
    salt '*' cron.rm_job root /usr/bin/foo dayweek=1

cron.rm_env:

Remove cron environment variable for a specified user.

CLI Example:

    salt '*' cron.rm_env root MAILTO

cron.rm_job:

Remove a cron job for a specified user. If any of the day/time params are
specified, the job will only be removed if the specified params match.

CLI Example:

    salt '*' cron.rm_job root /usr/local/weekly
    salt '*' cron.rm_job root /usr/bin/foo dayweek=1

cron.rm_special:

Remove a special cron job for a specified user.

CLI Example:

    salt '*' cron.rm_special root /usr/bin/foo

cron.set_env:

Set up an environment variable in the crontab.

CLI Example:

    salt '*' cron.set_env root MAILTO user@example.com

cron.set_job:

Sets a cron job up for a specified user.

CLI Example:

    salt '*' cron.set_job root '*' '*' '*' '*' 1 /usr/local/weekly

cron.set_special:

Set up a special command in the crontab.

CLI Example:

    salt '*' cron.set_special root @hourly 'echo foobar'

cron.write_cron_file:

Writes the contents of a file to a user's crontab

CLI Example:

    salt '*' cron.write_cron_file root /tmp/new_cron

Changed in version 2015.8.9

Note:

    Some OS' do not support specifying user via the `crontab` command i.e. (Solaris, AIX)

cron.write_cron_file_verbose:

Writes the contents of a file to a user's crontab and return error message on error

CLI Example:

    salt '*' cron.write_cron_file_verbose root /tmp/new_cron

Changed in version 2015.8.9

Note:

    Some OS' do not support specifying user via the `crontab` command i.e. (Solaris, AIX)

cryptdev.active:

List existing device-mapper device details.

cryptdev.close:

Close a crypt device using ``cryptsetup``.

CLI Example:

    salt '*' cryptdev.close foo

cryptdev.crypttab:

List the contents of the crypttab

CLI Example:

    salt '*' cryptdev.crypttab

cryptdev.open:

Open a crypt device using ``cryptsetup``. The ``keyfile`` must not be
``None`` or ``'none'``, because ``cryptsetup`` will otherwise ask for the
password interactively.

CLI Example:

    salt '*' cryptdev.open foo /dev/sdz1 /path/to/keyfile

cryptdev.rm_crypttab:

Remove the named mapping from the crypttab. If the described entry does not
exist, nothing is changed, but the command succeeds by returning
``'absent'``. If a line is removed, it returns ``'change'``.

CLI Example:

    salt '*' cryptdev.rm_crypttab foo

cryptdev.set_crypttab:

Verify that this device is represented in the crypttab, change the device to
match the name passed, or add the name if it is not present.

CLI Example:

    salt '*' cryptdev.set_crypttab foo /dev/sdz1 mypassword swap,size=256

data.cas:

Check and set a value in the minion datastore

CLI Example:

    salt '*' data.cas <key> <value> <old_value>

data.clear:

Clear out all of the data in the minion datastore, this function is
destructive!

CLI Example:

    salt '*' data.clear

data.dump:

Replace the entire datastore with a passed data structure

CLI Example:

    salt '*' data.dump '{'eggs': 'spam'}'

data.get:

Get a (list of) value(s) from the minion datastore

New in version 2015.8.0

CLI Example:

    salt '*' data.get key
    salt '*' data.get '["key1", "key2"]'

data.has_key:

Check if key is in the minion datastore

New in version 2015.8.0

CLI Example:

    salt '*' data.has_key <mykey>

data.items:

Get items from the minion datastore

New in version 2015.8.0

CLI Example:

    salt '*' data.items

data.keys:

Get all keys from the minion datastore

New in version 2015.8.0

CLI Example:

    salt '*' data.keys

data.load:

Return all of the data in the minion datastore

CLI Example:

    salt '*' data.load

data.pop:

Pop (return & delete) a value from the minion datastore

New in version 2015.5.2

CLI Example:

    salt '*' data.pop <key> "there was no val"

data.update:

Update a key with a value in the minion datastore

CLI Example:

    salt '*' data.update <key> <value>

data.values:

Get values from the minion datastore

New in version 2015.8.0

CLI Example:

    salt '*' data.values

debconf.get_selections:

Answers to debconf questions for all packages in the following format::

    {'package': [['question', 'type', 'value'], ...]}

CLI Example:

    salt '*' debconf.get_selections

debconf.set:

Set answers to debconf questions for a package.

CLI Example:

    salt '*' debconf.set <package> <question> <type> <value> [<value> ...]

debconf.set_file:

Set answers to debconf questions from a file.

CLI Example:

    salt '*' debconf.set_file salt://pathto/pkg.selections

debconf.set_template:

Set answers to debconf questions from a template.

path
    location of the file containing the package selections

template
    template format

context
    variables to add to the template environment

default
    default values for the template environment

CLI Example:

    salt '*' debconf.set_template salt://pathto/pkg.selections.jinja jinja None None

debconf.show:

Answers to debconf questions for a package in the following format::

    [['question', 'type', 'value'], ...]

If debconf doesn't know about a package, we return None.

CLI Example:

    salt '*' debconf.show <package name>

defaults.deepcopy:

defaults.deepcopy
    Allows deep copy of objects in formulas.

    By default, Python does not copy objects,
    it creates bindings between a target and an object.

It is more typical to use this in a templating language in formulas,
instead of directly on the command-line.

defaults.get:

defaults.get is used much like pillar.get except that it will read
a default value for a pillar from defaults.json or defaults.yaml
files that are stored in the root of a salt formula.

CLI Example:

    salt '*' defaults.get core:users:root

The defaults is computed from pillar key. The first entry is considered as
the formula namespace.

For example, querying ``core:users:root`` will try to load
``salt://core/defaults.yaml`` and ``salt://core/defaults.json``.

defaults.merge:

defaults.merge
    Allows deep merging of dicts in formulas.

merge_lists : False
    If True, it will also merge lists instead of replace their items.

in_place : True
    If True, it will merge into dest dict,
    if not it will make a new copy from that dict and return it.

convert_none : True
    If True, it will convert src and dest to empty dicts if they are None.
    If True and dest is None but in_place is True, raises TypeError.
    If False it will make a new copy from that dict and return it.

    New in version 3005

CLI Example:

    salt '*' defaults.merge '{a: b}' '{d: e}'

It is more typical to use this in a templating language in formulas,
instead of directly on the command-line.

defaults.update:

defaults.update
    Allows setting defaults for group of data set e.g. group for nodes.

    This function is a combination of defaults.merge
    and defaults.deepcopy to avoid redundant in jinja.

    Example:

        group01:
          defaults:
            enabled: True
            extra:
              - test
              - stage
          nodes:
            host01:
              index: foo
              upstream: bar
            host02:
              index: foo2
              upstream: bar2

        {% do salt['defaults.update'](group01.nodes, group01.defaults) %}

    Each node will look like the following:

        host01:
          enabled: True
          index: foo
          upstream: bar
          extra:
            - test
            - stage

merge_lists : True
    If True, it will also merge lists instead of replace their items.

in_place : True
    If True, it will merge into dest dict.
    if not it will make a new copy from that dict and return it.

convert_none : True
    If True, it will convert src and dest to empty dicts if they are None.
    If True and dest is None but in_place is True, raises TypeError.
    If False it will make a new copy from that dict and return it.

    New in version 3005

It is more typical to use this in a templating language in formulas,
instead of directly on the command-line.

devinfo.filter:

Returns a list of devices, filtered under udev keys.

udev_in
    A dictionary of key:values that are expected in the device
    udev information

udev_ex
    A dictionary of key:values that are not expected in the device
    udev information (excluded)

The key is a lower case string, joined by dots, that represent a
path in the udev information dictionary. For example, 'e.id_bus'
will represent the udev entry `udev['E']['ID_BUS']`

If the udev entry is a list, the algorithm will check that at
least one item match one item of the value of the parameters.

Returns list of devices that match `udev_in` and do not match
`udev_ex`.

CLI Example:

   salt '*' devinfo.filter udev_in='{"e.id_bus": "ata"}'

devinfo.hwinfo:

Probe for hardware

items
    List of hardware items to inspect. Default ['bios', 'cpu', 'disk',
    'memory', 'network', 'partition']

short
    Show only a summary. Default True.

listmd
    Report RAID devices. Default False.

devices
    List of devices to show information from. Default None.

CLI Example:

   salt '*' devinfo.hwinfo
   salt '*' devinfo.hwinfo items='["disk"]' short=no
   salt '*' devinfo.hwinfo items='["disk"]' short=no devices='["/dev/sda"]'
   salt '*' devinfo.hwinfo devices=/dev/sda

devmap.multipath_flush:

Device-Mapper Multipath flush

CLI Example:

    salt '*' devmap.multipath_flush mpath1

devmap.multipath_list:

Device-Mapper Multipath list

CLI Example:

    salt '*' devmap.multipath_list

dig.A:

Return the A record for ``host``.

Always returns a list.

CLI Example:

    salt ns1 dig.A www.google.com

dig.AAAA:

Return the AAAA record for ``host``.

Always returns a list.

CLI Example:

    salt ns1 dig.AAAA www.google.com

dig.CNAME:

Return the CNAME record for ``host``.

New in version 3005

CLI Example:

    salt ns1 dig.CNAME mail.google.com

dig.MX:

Return a list of lists for the MX of ``domain``.

If the ``resolve`` argument is True, resolve IPs for the servers.

It's limited to one IP, because although in practice it's very rarely a
round robin, it is an acceptable configuration and pulling just one IP lets
the data be similar to the non-resolved version. If you think an MX has
multiple IPs, don't use the resolver here, resolve them in a separate step.

CLI Example:

    salt ns1 dig.MX google.com

dig.NS:

Return a list of IPs of the nameservers for ``domain``

If ``resolve`` is False, don't resolve names.

CLI Example:

    salt ns1 dig.NS google.com

dig.PTR:

New in version 3006.0

Return the PTR record for ``host``.

Always returns a list.

CLI Example:

    salt ns1 dig.PTR 1.2.3.4

dig.SPF:

Return the allowed IPv4 ranges in the SPF record for ``domain``.

If record is ``SPF`` and the SPF record is empty, the TXT record will be
searched automatically. If you know the domain uses TXT and not SPF,
specifying that will save a lookup.

CLI Example:

    salt ns1 dig.SPF google.com

dig.TXT:

Return the TXT record for ``host``.

Always returns a list.

CLI Example:

    salt ns1 dig.TXT google.com

dig.a:

Return the A record for ``host``.

Always returns a list.

CLI Example:

    salt ns1 dig.A www.google.com

dig.aaaa:

Return the AAAA record for ``host``.

Always returns a list.

CLI Example:

    salt ns1 dig.AAAA www.google.com

dig.check_ip:

Check if address is a valid IP. returns True if valid, otherwise False.

CLI Example:

    salt ns1 dig.check_ip 127.0.0.1
    salt ns1 dig.check_ip 1111:2222:3333:4444:5555:6666:7777:8888

dig.cname:

Return the CNAME record for ``host``.

New in version 3005

CLI Example:

    salt ns1 dig.CNAME mail.google.com

dig.mx:

Return a list of lists for the MX of ``domain``.

If the ``resolve`` argument is True, resolve IPs for the servers.

It's limited to one IP, because although in practice it's very rarely a
round robin, it is an acceptable configuration and pulling just one IP lets
the data be similar to the non-resolved version. If you think an MX has
multiple IPs, don't use the resolver here, resolve them in a separate step.

CLI Example:

    salt ns1 dig.MX google.com

dig.ns:

Return a list of IPs of the nameservers for ``domain``

If ``resolve`` is False, don't resolve names.

CLI Example:

    salt ns1 dig.NS google.com

dig.ptr:

New in version 3006.0

Return the PTR record for ``host``.

Always returns a list.

CLI Example:

    salt ns1 dig.PTR 1.2.3.4

dig.spf:

Return the allowed IPv4 ranges in the SPF record for ``domain``.

If record is ``SPF`` and the SPF record is empty, the TXT record will be
searched automatically. If you know the domain uses TXT and not SPF,
specifying that will save a lookup.

CLI Example:

    salt ns1 dig.SPF google.com

disk.blkid:

Return block device attributes: UUID, LABEL, etc. This function only works
on systems where blkid is available.

device
    Device name from the system

token
    Any valid token used for the search

CLI Example:

    salt '*' disk.blkid
    salt '*' disk.blkid /dev/sda
    salt '*' disk.blkid token='UUID=6a38ee5-7235-44e7-8b22-816a403bad5d'
    salt '*' disk.blkid token='TYPE=ext4'

disk.dump:

Return all contents of dumpe2fs for a specified device

device
    The device path to dump.

args
    A list of attributes to return. Returns all by default.

CLI Example:

    salt '*' disk.dump /dev/sda1

disk.format:

Format a filesystem onto a device

New in version 2016.11.0

device
    The device in which to create the new filesystem

fs_type
    The type of filesystem to create

inode_size
    Size of the inodes

    This option is only enabled for ext and xfs filesystems

lazy_itable_init
    If enabled and the uninit_bg feature is enabled, the inode table will
    not be fully initialized by mke2fs.  This speeds up filesystem
    initialization noticeably, but it requires the kernel to finish
    initializing the filesystem  in  the  background  when  the filesystem
    is first mounted.  If the option value is omitted, it defaults to 1 to
    enable lazy inode table zeroing.

    This option is only enabled for ext filesystems

fat
    FAT size option. Can be 12, 16 or 32, and can only be used on
    fat or vfat filesystems.

force
    Force mke2fs to create a filesystem, even if the specified device is
    not a partition on a block special device. This option is only enabled
    for ext and xfs filesystems

    This option is dangerous, use it with caution.

CLI Example:

    salt '*' disk.format /dev/sdX1

disk.fstype:

Return the filesystem name of the specified device

New in version 2016.11.0

device
    The name of the device

CLI Example:

    salt '*' disk.fstype /dev/sdX1

disk.get_fstype_from_path:

Return the filesystem type of the underlying device for a specified path.

New in version 3006.0

path
    The path for the function to evaluate.

CLI Example:

    salt '*' disk.get_fstype_from_path /root

disk.hdparms:

Retrieve disk parameters.

New in version 2016.3.0

disks
    Single disk or list of disks to query.

args
    Sequence of ``hdparm`` flags to fetch.

CLI Example:

    salt '*' disk.hdparms /dev/sda

disk.hpa:

Get/set Host Protected Area settings

T13 INCITS 346-2001 (1367D) defines the BEER (Boot Engineering Extension Record)
and PARTIES (Protected Area Run Time Interface Extension Services), allowing
for a Host Protected Area on a disk.

It's often used by OEMS to hide parts of a disk, and for overprovisioning SSD's

Warning:
    Setting the HPA might clobber your data, be very careful with this on active disks!

New in version 2016.3.0

CLI Example:

    salt '*' disk.hpa /dev/sda
    salt '*' disk.hpa /dev/sda 5%
    salt '*' disk.hpa /dev/sda 10543256

disk.inodeusage:

Return inode usage information for volumes mounted on this minion

args
    Sequence of flags to pass to the ``df`` command.

CLI Example:

    salt '*' disk.inodeusage

disk.iostat:

Gather and return (averaged) IO stats.

New in version 2016.3.0

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' disk.iostat 1 5 disks=sda

disk.percent:

Return partition information for volumes mounted on this minion

args
    Specify a single partition for which to return data.

CLI Example:

    salt '*' disk.percent /var

disk.resize2fs:

Resizes the filesystem.

CLI Example:

    salt '*' disk.resize2fs /dev/sda1

disk.smart_attributes:

Fetch SMART attributes
Providing attributes will deliver only requested attributes
Providing values will deliver only requested values for attributes

Default is the Backblaze recommended
set (https://www.backblaze.com/blog/hard-drive-smart-stats/):
(5,187,188,197,198)

New in version 2016.3.0

CLI Example:

    salt '*' disk.smart_attributes /dev/sda
    salt '*' disk.smart_attributes /dev/sda attributes=(5,187,188,197,198)

disk.tune:

Set attributes for the specified device

CLI Example:

    salt '*' disk.tune /dev/sda1 read-ahead=1024 read-write=True

Valid options are: ``read-ahead``, ``filesystem-read-ahead``,
``read-only``, ``read-write``.

See the ``blockdev(8)`` manpage for a more complete description of these
options.

disk.usage:

Return usage information for volumes mounted on this minion

args
    Sequence of flags to pass to the ``df`` command.

Changed in version 2019.2.0

    Default for SunOS changed to 1 kilobyte blocks

CLI Example:

    salt '*' disk.usage

disk.wipe:

Remove the filesystem information

CLI Example:

    salt '*' disk.wipe /dev/sda1

django.collectstatic:

Collect static files from each of your applications into a single location
that can easily be served in production.

CLI Example:

    salt '*' django.collectstatic <settings_module>

django.command:

Run arbitrary django management command

CLI Example:

    salt '*' django.command <settings_module> <command>

django.createsuperuser:

Create a super user for the database.
This function defaults to use the ``--noinput`` flag which prevents the
creation of a password for the superuser.

CLI Example:

    salt '*' django.createsuperuser <settings_module> user user@example.com

django.loaddata:

Load fixture data

Fixtures:
    comma separated list of fixtures to load

CLI Example:

    salt '*' django.loaddata <settings_module> <comma delimited list of fixtures>

django.migrate:

Run migrate

Execute the Django-Admin migrate command (requires Django 1.7 or higher).

New in version 3000

settings_module
    Specifies the settings module to use.
    The settings module should be in Python package syntax, e.g. mysite.settings.
    If this isn’t provided, django-admin will use the DJANGO_SETTINGS_MODULE
    environment variable.

app_label
    Specific app to run migrations for, instead of all apps.
    This may involve running other apps’ migrations too, due to dependencies.

migration_name
    Named migration to be applied to a specific app.
    Brings the database schema to a state where the named migration is applied,
    but no later migrations in the same app are applied. This may involve
    unapplying migrations if you have previously migrated past the named migration.
    Use the name zero to unapply all migrations for an app.

bin_env
    Path to pip (or to a virtualenv). This can be used to specify the path
    to the pip to use when more than one Python release is installed (e.g.
    ``/usr/bin/pip-2.7`` or ``/usr/bin/pip-2.6``. If a directory path is
    specified, it is assumed to be a virtualenv.

database
    Database to migrate. Defaults to 'default'.

pythonpath
    Adds the given filesystem path to the Python import search path.
    If this isn’t provided, django-admin will use the PYTHONPATH environment variable.

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

    Example:

        module.run:
          - name: django.migrate
          - settings_module: my_django_app.settings
          - env:
            - DATABASE_USER: 'mydbuser'

noinput
    Suppresses all user prompts. Defaults to True.

runas
    The user name to run the command as.

CLI Example:

    salt '*' django.migrate <settings_module>
    salt '*' django.migrate <settings_module> <app_label>
    salt '*' django.migrate <settings_module> <app_label> <migration_name>

django.syncdb:

Run syncdb

Execute the Django-Admin syncdb command, if South is available on the
minion the ``migrate`` option can be passed as ``True`` calling the
migrations to run after the syncdb completes

NOTE: The syncdb command was deprecated in Django 1.7 and removed in Django 1.9.
For Django versions 1.9 or higher use the `migrate` command instead.

CLI Example:

    salt '*' django.syncdb <settings_module>

dnsmasq.fullversion:

Shows installed version of dnsmasq and compile options.

CLI Example:

    salt '*' dnsmasq.fullversion

dnsmasq.get_config:

Dumps all options from the config file.

config_file
    The location of the config file from which to obtain contents.
    Defaults to ``/etc/dnsmasq.conf``.

CLI Examples:

    salt '*' dnsmasq.get_config
    salt '*' dnsmasq.get_config config_file=/etc/dnsmasq.conf

dnsmasq.set_config:

Sets a value or a set of values in the specified file. By default, if
conf-dir is configured in this file, salt will attempt to set the option
in any file inside the conf-dir where it has already been enabled. If it
does not find it inside any files, it will append it to the main config
file. Setting follow to False will turn off this behavior.

If a config option currently appears multiple times (such as dhcp-host,
which is specified at least once per host), the new option will be added
to the end of the main config file (and not to any includes). If you need
an option added to a specific include file, specify it as the config_file.

:param string config_file: config file where settings should be updated / added.
:param bool follow: attempt to set the config option inside any file within
    the ``conf-dir`` where it has already been enabled.
:param kwargs: key value pairs that contain the configuration settings that you
    want set.

CLI Examples:

    salt '*' dnsmasq.set_config domain=mydomain.com
    salt '*' dnsmasq.set_config follow=False domain=mydomain.com
    salt '*' dnsmasq.set_config config_file=/etc/dnsmasq.conf domain=mydomain.com

dnsmasq.version:

Shows installed version of dnsmasq.

CLI Example:

    salt '*' dnsmasq.version

dnsutil.A:

Return the A record(s) for ``host``.

Always returns a list.

CLI Example:

    salt ns1 dnsutil.A www.google.com

dnsutil.AAAA:

Return the AAAA record(s) for ``host``.

Always returns a list.

New in version 2014.7.5

CLI Example:

    salt ns1 dnsutil.AAAA www.google.com

dnsutil.MX:

Return a list of lists for the MX of ``domain``.

If the 'resolve' argument is True, resolve IPs for the servers.

It's limited to one IP, because although in practice it's very rarely a
round robin, it is an acceptable configuration and pulling just one IP lets
the data be similar to the non-resolved version. If you think an MX has
multiple IPs, don't use the resolver here, resolve them in a separate step.

CLI Example:

    salt ns1 dnsutil.MX google.com

dnsutil.NS:

Return a list of IPs of the nameservers for ``domain``

If 'resolve' is False, don't resolve names.

CLI Example:

    salt ns1 dnsutil.NS google.com

dnsutil.SPF:

Return the allowed IPv4 ranges in the SPF record for ``domain``.

If record is ``SPF`` and the SPF record is empty, the TXT record will be
searched automatically. If you know the domain uses TXT and not SPF,
specifying that will save a lookup.

CLI Example:

    salt ns1 dnsutil.SPF google.com

dnsutil.check_ip:

Check that string ip_addr is a valid IP

CLI Example:

    salt ns1 dnsutil.check_ip 127.0.0.1

dnsutil.hosts_append:

Append a single line to the /etc/hosts file.

CLI Example:

    salt '*' dnsutil.hosts_append /etc/hosts 127.0.0.1 ad1.yuk.co,ad2.yuk.co

dnsutil.hosts_remove:

Remove a host from the /etc/hosts file. If doing so will leave a line
containing only an IP address, then the line will be deleted. This function
will leave comments and blank lines intact.

CLI Examples:

    salt '*' dnsutil.hosts_remove /etc/hosts ad1.yuk.co
    salt '*' dnsutil.hosts_remove /etc/hosts ad2.yuk.co,ad1.yuk.co

dnsutil.parse_hosts:

Parse /etc/hosts file.

CLI Example:

    salt '*' dnsutil.parse_hosts

dnsutil.parse_zone:

Parses a zone file. Can be passed raw zone data on the API level.

CLI Example:

    salt ns1 dnsutil.parse_zone /var/lib/named/example.com.zone

dnsutil.serial:

Return, store and update a dns serial for your zone files.

zone: a keyword for a specific zone

update: store an updated version of the serial in a grain

If ``update`` is False, the function will retrieve an existing serial or
return the current date if no serial is stored. Nothing will be stored

If ``update`` is True, the function will set the serial to the current date
if none exist or if the existing serial is for a previous date. If a serial
for greater than the current date is already stored, the function will
increment it.

This module stores the serial in a grain, you can explicitly set the
stored value as a grain named ``dnsserial_<zone_name>``.

CLI Example:

    salt ns1 dnsutil.serial example.com

drbd.overview:

Show status of the DRBD devices, support two nodes only.
drbd-overview is removed since drbd-utils-9.6.0,
use status instead.

CLI Example:

    salt '*' drbd.overview

drbd.status:

Using drbdadm to show status of the DRBD devices,
available in the latest drbd9.
Support multiple nodes, multiple volumes.

:type name: str
:param name:
    Resource name.

:return: drbd status of resource.
:rtype: list(dict(res))

CLI Example:

    salt '*' drbd.status
    salt '*' drbd.status name=<resource name>

environ.get:

Get a single salt process environment variable.

key
    String used as the key for environment lookup.

default
    If the key is not found in the environment, return this value.
    Default: ''

CLI Example:

    salt '*' environ.get foo
    salt '*' environ.get baz default=False

environ.has_value:

Determine whether the key exists in the current salt process
environment dictionary. Optionally compare the current value
of the environment against the supplied value string.

key
    Must be a string. Used as key for environment lookup.

value:
    Optional. If key exists in the environment, compare the
    current value with this value. Return True if they are equal.

CLI Example:

    salt '*' environ.has_value foo

environ.item:

Get one or more salt process environment variables.
Returns a dict.

keys
    Either a string or a list of strings that will be used as the
    keys for environment lookup.

default
    If the key is not found in the environment, return this value.
    Default: ''

CLI Example:

    salt '*' environ.item foo
    salt '*' environ.item '[foo, baz]' default=None

environ.items:

Return a dict of the entire environment set for the salt process

CLI Example:

    salt '*' environ.items

environ.setenv:

Set multiple salt process environment variables from a dict.
Returns a dict.

environ
    Must be a dict. The top-level keys of the dict are the names
    of the environment variables to set. Each key's value must be
    a string or False. Refer to the 'false_unsets' parameter for
    behavior when a value set to False.

false_unsets
    If a key's value is False and false_unsets is True, then the
    key will be removed from the salt processes environment dict
    entirely. If a key's value is False and false_unsets is not
    True, then the key's value will be set to an empty string.
    Default: False

clear_all
    USE WITH CAUTION! This option can unset environment variables
    needed for salt to function properly.
    If clear_all is True, then any environment variables not
    defined in the environ dict will be deleted.
    Default: False

update_minion
    If True, apply these environ changes to the main salt-minion
    process. If False, the environ changes will only affect the
    current salt subprocess.
    Default: False

permanent
    On Windows minions this will set the environment variable in the
    registry so that it is always added as an environment variable when
    applications open. If you want to set the variable to HKLM instead of
    HKCU just pass in "HKLM" for this parameter. On all other minion types
    this will be ignored. Note: This will only take affect on applications
    opened after this has been set.

CLI Example:

    salt '*' environ.setenv '{"foo": "bar", "baz": "quux"}'
    salt '*' environ.setenv '{"a": "b", "c": False}' false_unsets=True

environ.setval:

Set a single salt process environment variable. Returns True
on success.

key
    The environment key to set. Must be a string.

val
    The value to set. Must be a string or False. Refer to the
    'false_unsets' parameter for behavior when set to False.

false_unsets
    If val is False and false_unsets is True, then the key will be
    removed from the salt processes environment dict entirely.
    If val is False and false_unsets is not True, then the key's
    value will be set to an empty string.
    Default: False.

permanent
    On Windows minions this will set the environment variable in the
    registry so that it is always added as an environment variable when
    applications open. If you want to set the variable to HKLM instead of
    HKCU just pass in "HKLM" for this parameter. On all other minion types
    this will be ignored. Note: This will only take affect on applications
    opened after this has been set.

CLI Example:

    salt '*' environ.setval foo bar
    salt '*' environ.setval baz val=False false_unsets=True
    salt '*' environ.setval baz bar permanent=True
    salt '*' environ.setval baz bar permanent=HKLM

ethtool.set_coalesce:

Changes the coalescing settings of the specified network device

CLI Example:

    salt '*' ethtool.set_coalesce <devname> [adaptive_rx=on|off] [adaptive_tx=on|off] [rx_usecs=N] [rx_frames=N]
        [rx_usecs_irq=N] [rx_frames_irq=N] [tx_usecs=N] [tx_frames=N] [tx_usecs_irq=N] [tx_frames_irq=N]
        [stats_block_usecs=N] [pkt_rate_low=N] [rx_usecs_low=N] [rx_frames_low=N] [tx_usecs_low=N] [tx_frames_low=N]
        [pkt_rate_high=N] [rx_usecs_high=N] [rx_frames_high=N] [tx_usecs_high=N] [tx_frames_high=N]
        [sample_interval=N]

ethtool.set_feature:

New in version 3006.0

Changes the feature parameters of the specified network device

CLI Example:

    salt '*' ethtool.set_feature <devname> sg=off

ethtool.set_offload:

Changes the offload parameters and other features of the specified network device

CLI Example:

    salt '*' ethtool.set_offload <devname> tcp_segmentation_offload=on

ethtool.set_pause:

New in version 3006.0

Changes the pause parameters of the specified network device

CLI Example:

    salt '*' ethtool.set_pause <devname> autoneg=off rx=off tx=off

ethtool.set_ring:

Changes the rx/tx ring parameters of the specified network device

CLI Example:

    salt '*' ethtool.set_ring <devname> [rx=N] [rx_mini=N] [rx_jumbo=N] [tx=N]

ethtool.show_coalesce:

Queries the specified network device for coalescing information

CLI Example:

    salt '*' ethtool.show_coalesce <devname>

ethtool.show_driver:

Queries the specified network device for associated driver information

CLI Example:

    salt '*' ethtool.show_driver <devname>

ethtool.show_features:

New in version 3006.0

Queries the specified network device for associated feature information

CLI Example:

    salt '*' ethtool.show_features <devname>

ethtool.show_offload:

Queries the specified network device for the state of protocol offload and other features

CLI Example:

    salt '*' ethtool.show_offload <devname>

ethtool.show_pause:

New in version 3006.0

Queries the specified network device for associated pause information

CLI Example:

    salt '*' ethtool.show_pause <devname>

ethtool.show_ring:

Queries the specified network device for rx/tx ring parameter information

CLI Example:

    salt '*' ethtool.show_ring <devname>

event.fire:

Fire an event on the local minion event bus. Data must be formed as a dict.

CLI Example:

    salt '*' event.fire '{"data":"my event data"}' 'tag'

event.fire_master:

Fire an event off up to the master server

CLI Example:

    salt '*' event.fire_master '{"data":"my event data"}' 'tag'

event.send:

Send an event to the Salt Master

New in version 2014.7.0

:param tag: A tag to give the event.
    Use slashes to create a namespace for related events. E.g.,
    ``myco/build/buildserver1/start``, ``myco/build/buildserver1/success``,
    ``myco/build/buildserver1/failure``.

:param data: A dictionary of data to send in the event.
    This is free-form. Send any data points that are needed for whoever is
    consuming the event. Arguments on the CLI are interpreted as YAML so
    complex data structures are possible.

:param with_env: Include environment variables from the current shell
    environment in the event data as ``environ``.. This is a short-hand for
    working with systems that seed the environment with relevant data such
    as Jenkins.
:type with_env: Specify ``True`` to include all environment variables, or
    specify a list of strings of variable names to include.

:param with_grains: Include grains from the current minion in the event
    data as ``grains``.
:type with_grains: Specify ``True`` to include all grains, or specify a
    list of strings of grain names to include.

:param with_pillar: Include Pillar values from the current minion in the
    event data as ``pillar``. Remember Pillar data is often sensitive data
    so be careful. This is useful for passing ephemeral Pillar values
    through an event. Such as passing the ``pillar={}`` kwarg in
    :py:func:`state.sls <salt.modules.state.sls>` from the Master, through
    an event on the Minion, then back to the Master.
:type with_pillar: Specify ``True`` to include all Pillar values, or
    specify a list of strings of Pillar keys to include. It is a
    best-practice to only specify a relevant subset of Pillar data.

:param with_env_opts: Include ``saltenv`` and ``pillarenv`` set on minion
    at the moment when event is send into event data.
:type with_env_opts: Specify ``True`` to include ``saltenv`` and
    ``pillarenv`` values or ``False`` to omit them.

:param kwargs: Any additional keyword arguments passed to this function
    will be interpreted as key-value pairs and included in the event data.
    This provides a convenient alternative to YAML for simple values.

CLI Example:

    salt-call event.send myco/mytag foo=Foo bar=Bar
    salt-call event.send 'myco/mytag' '{foo: Foo, bar: Bar}'

extfs.attributes:

Return attributes from dumpe2fs for a specified device

CLI Example:

    salt '*' extfs.attributes /dev/sda1

extfs.blocks:

Return block and inode info from dumpe2fs for a specified device

CLI Example:

    salt '*' extfs.blocks /dev/sda1

extfs.dump:

Return all contents of dumpe2fs for a specified device

CLI Example:

    salt '*' extfs.dump /dev/sda1

extfs.mkfs:

Create a file system on the specified device

full_return : False
    If ``True``, the full ``cmd.run_all`` dictionary will be returned
    instead of just stdout/stderr text. Useful for setting the result of
    the ``module.run`` state.

CLI Example:

    salt '*' extfs.mkfs /dev/sda1 fs_type=ext4 opts='acl,noexec'

Valid options are:

* **block_size**: 1024, 2048 or 4096
* **check**: check for bad blocks
* **direct**: use direct IO
* **ext_opts**: extended file system options (comma-separated)
* **fragment_size**: size of fragments
* **force**: setting force to True will cause mke2fs to specify the -F
  option twice (it is already set once); this is truly dangerous
* **blocks_per_group**: number of blocks in a block group
* **number_of_groups**: ext4 option for a virtual block group
* **bytes_per_inode**: set the bytes/inode ratio
* **inode_size**: size of the inode
* **journal**: set to True to create a journal (default on ext3/4)
* **journal_opts**: options for the fs journal (comma separated)
* **blocks_file**: read bad blocks from file
* **label**: label to apply to the file system
* **reserved**: percentage of blocks reserved for super-user
* **last_dir**: last mounted directory
* **test**: set to True to not actually create the file system (mke2fs -n)
* **number_of_inodes**: override default number of inodes
* **creator_os**: override "creator operating system" field
* **opts**: mount options (comma separated)
* **revision**: set the filesystem revision (default 1)
* **super**: write superblock and group descriptors only
* **fs_type**: set the filesystem type (REQUIRED)
* **usage_type**: how the filesystem is going to be used
* **uuid**: set the UUID for the file system
* **cluster_size**: specify the size of cluster in bytes for file systems using the bigalloc feature
* **root_directory**: copy the contents of the given directory into the root directory of the file system
* **errors_behavior**: change the behavior of the kernel code when errors are detected

See the ``mke2fs(8)`` manpage for a more complete description of these
options.

extfs.tune:

Set attributes for the specified device (using tune2fs)

full_return : False
    If ``True``, the full ``cmd.run_all`` dictionary will be returned
    instead of just stdout/stderr text. Useful for setting the result of
    the ``module.run`` state.

CLI Example:

    salt '*' extfs.tune /dev/sda1 force=True label=wildstallyns opts='acl,noexec'

Valid options are:

* **max**: max mount count
* **count**: mount count
* **error**: error behavior
* **extended_opts**: extended options (comma separated)
* **force**: force, even if there are errors (set to True)
* **group**: group name or gid that can use the reserved blocks
* **interval**: interval between checks
* **journal**: set to True to create a journal (default on ext3/4)
* **journal_opts**: options for the fs journal (comma separated)
* **label**: label to apply to the file system
* **reserved_percentage**: percentage of blocks reserved for super-user
* **last_dir**: last mounted directory
* **opts**: mount options (comma separated)
* **feature**: set or clear a feature (comma separated)
* **mmp_check**: mmp check interval
* **reserved**: reserved blocks count
* **quota_opts**: quota options (comma separated)
* **time**: time last checked
* **user**: user or uid who can use the reserved blocks
* **uuid**: set the UUID for the file system

See the ``mke2fs(8)`` manpage for a more complete description of these
options.

file.access:

New in version 2014.1.0

Test whether the Salt process has the specified access to the file. One of
the following modes must be specified:

    f: Test the existence of the path
    r: Test the readability of the path
    w: Test the writability of the path
    x: Test whether the path can be executed

CLI Example:

    salt '*' file.access /path/to/file f
    salt '*' file.access /path/to/file x

file.append:

New in version 0.9.5

Append text to the end of a file

path
    path to file

`*args`
    strings to append to file

CLI Example:

    salt '*' file.append /etc/motd \
            "With all thine offerings thou shalt offer salt." \
            "Salt is what makes things taste bad when it isn't in them."

.. admonition:: Attention

    If you need to pass a string to append and that string contains
    an equal sign, you **must** include the argument name, args.
    For example:

        salt '*' file.append /etc/motd args='cheese=spam'

        salt '*' file.append /etc/motd args="['cheese=spam','spam=cheese']"

file.apply_template_on_contents:

Return the contents after applying the templating engine

contents
    template string

template
    template format

context
    Overrides default context variables passed to the template.

defaults
    Default context passed to the template.

CLI Example:

    salt '*' file.apply_template_on_contents \
        contents='This is a {{ template }} string.' \
        template=jinja \
        "context={}" "defaults={'template': 'cool'}" \
        saltenv=base

file.basename:

Returns the final component of a pathname

New in version 2015.5.0

This can be useful at the CLI but is frequently useful when scripting.

    {%- set filename = salt['file.basename'](source_file) %}

CLI Example:

    salt '*' file.basename 'test/test.config'

file.blockreplace:

New in version 2014.1.0

Replace content of a text block in a file, delimited by line markers

A block of content delimited by comments can help you manage several lines
entries without worrying about old entries removal.

Note:

    This function will store two copies of the file in-memory (the original
    version and the edited version) in order to detect changes and only
    edit the targeted file if necessary.

path
    Filesystem path to the file to be edited

marker_start
    The line content identifying a line as the start of the content block.
    Note that the whole line containing this marker will be considered, so
    whitespace or extra content before or after the marker is included in
    final output

marker_end
    The line content identifying the end of the content block. As of
    versions 2017.7.5 and 2018.3.1, everything up to the text matching the
    marker will be replaced, so it's important to ensure that your marker
    includes the beginning of the text you wish to replace.

content
    The content to be used between the two lines identified by marker_start
    and marker_stop.

append_if_not_found: False
    If markers are not found and set to ``True`` then, the markers and
    content will be appended to the file.

prepend_if_not_found: False
    If markers are not found and set to ``True`` then, the markers and
    content will be prepended to the file.

insert_before_match
    If markers are not found, this parameter can be set to a regex which will
    insert the block before the first found occurrence in the file.

    New in version 3001

insert_after_match
    If markers are not found, this parameter can be set to a regex which will
    insert the block after the first found occurrence in the file.

    New in version 3001

backup
    The file extension to use for a backup of the file if any edit is made.
    Set to ``False`` to skip making a backup.

dry_run: False
    If ``True``, do not make any edits to the file and simply return the
    changes that *would* be made.

show_changes: True
    Controls how changes are presented. If ``True``, this function will
    return a unified diff of the changes made. If False, then it will
    return a boolean (``True`` if any changes were made, otherwise
    ``False``).

append_newline: False
    Controls whether or not a newline is appended to the content block. If
    the value of this argument is ``True`` then a newline will be added to
    the content block. If it is ``False``, then a newline will *not* be
    added to the content block. If it is ``None`` then a newline will only
    be added to the content block if it does not already end in a newline.

    New in version 2016.3.4
    Changed in version 2017.7.5,2018.3.1
        New behavior added when value is ``None``.
    Changed in version 2019.2.0
        The default value of this argument will change to ``None`` to match
        the behavior of the :py:func:`file.blockreplace state
        <salt.states.file.blockreplace>`

CLI Example:

    salt '*' file.blockreplace /etc/hosts '#-- start managed zone foobar : DO NOT EDIT --' \
    '#-- end managed zone foobar --' $'10.0.1.1 foo.foobar\n10.0.1.2 bar.foobar' True

file.chattr:

New in version 2018.3.0

Change the attributes of files. This function accepts one or more files and
the following options:

operator
    Can be wither ``add`` or ``remove``. Determines whether attributes
    should be added or removed from files

attributes
    One or more of the following characters: ``aAcCdDeijPsStTu``,
    representing attributes to add to/remove from files

version
    a version number to assign to the file(s)

flags
    One or more of the following characters: ``RVf``, representing
    flags to assign to chattr (recurse, verbose, suppress most errors)

CLI Example:

    salt '*' file.chattr foo1.txt foo2.txt operator=add attributes=ai
    salt '*' file.chattr foo3.txt operator=remove attributes=i version=2

file.check_file_meta:

Check for the changes in the file metadata.

CLI Example:

    salt '*' file.check_file_meta /etc/httpd/conf.d/httpd.conf None salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' None base

Note:

    Supported hash types include sha512, sha384, sha256, sha224, sha1, and
    md5.

name
    Path to file destination

sfn
    Template-processed source file contents

source
    URL to file source

source_sum
    File checksum information as a dictionary

        {hash_type: md5, hsum: <md5sum>}

user
    Destination file user owner

group
    Destination file group owner

mode
    Destination file permissions mode

attrs
    Destination file attributes

    New in version 2018.3.0

saltenv
    Salt environment used to resolve source files

contents
    File contents

seuser
    selinux user attribute

    New in version 3001

serole
    selinux role attribute

    New in version 3001

setype
    selinux type attribute

    New in version 3001

serange
    selinux range attribute

    New in version 3001

verify_ssl
    If ``False``, remote https file sources (``https://``)
    will not attempt to validate the servers certificate. Default is True.

    New in version 3002

follow_symlinks
    If the desired path is a symlink, follow it and check the permissions
    of the file to which the symlink points.

    New in version 3005

file.check_hash:

Check if a file matches the given hash string

Returns ``True`` if the hash matches, otherwise ``False``.

path
    Path to a file local to the minion.

hash
    The hash to check against the file specified in the ``path`` argument.

    Changed in version 2016.11.4

    For this and newer versions the hash can be specified without an
    accompanying hash type (e.g. ``e138491e9d5b97023cea823fe17bac22``),
    but for earlier releases it is necessary to also specify the hash type
    in the format ``<hash_type>=<hash_value>`` (e.g.
    ``md5=e138491e9d5b97023cea823fe17bac22``).

CLI Example:

    salt '*' file.check_hash /etc/fstab e138491e9d5b97023cea823fe17bac22
    salt '*' file.check_hash /etc/fstab md5=e138491e9d5b97023cea823fe17bac22

file.check_managed:

Check to see what changes need to be made for a file

follow_symlinks
    If the desired path is a symlink, follow it and check the permissions
    of the file to which the symlink points.

    New in version 3005

CLI Example:

    salt '*' file.check_managed /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' jinja True None None base

file.check_managed_changes:

Return a dictionary of what changes need to be made for a file

Changed in version 3001

    selinux attributes added

verify_ssl
    If ``False``, remote https file sources (``https://``) and source_hash
    will not attempt to validate the servers certificate. Default is True.

    New in version 3002

follow_symlinks
    If the desired path is a symlink, follow it and check the permissions
    of the file to which the symlink points.

    New in version 3005

CLI Example:

    salt '*' file.check_managed_changes /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' jinja True None None base

file.check_perms:

Changed in version 3001

    Added selinux options

Check the permissions on files, modify attributes and chown if needed. File
attributes are only verified if lsattr(1) is installed.

CLI Example:

    salt '*' file.check_perms /etc/sudoers '{}' root root 400 ai

Changed in version 2014.1.3
    ``follow_symlinks`` option added

file.chgrp:

Change the group of a file

path
    path to the file or directory

group
    group owner

CLI Example:

    salt '*' file.chgrp /etc/passwd root

file.chown:

Chown a file, pass the file the desired user and group

path
    path to the file or directory

user
    user owner

group
    group owner

CLI Example:

    salt '*' file.chown /etc/passwd root root

file.comment:

.. deprecated:: 0.17.0
   Use :py:func:`~salt.modules.file.replace` instead.

Comment out specified lines in a file

path
    The full path to the file to be edited
regex
    A regular expression used to find the lines that are to be commented;
    this pattern will be wrapped in parenthesis and will move any
    preceding/trailing ``^`` or ``$`` characters outside the parenthesis
    (e.g., the pattern ``^foo$`` will be rewritten as ``^(foo)$``)
char: ``#``
    The character to be inserted at the beginning of a line in order to
    comment it out
backup: ``.bak``
    The file will be backed up before edit with this file extension

    Warning:

        This backup will be overwritten each time ``sed`` / ``comment`` /
        ``uncomment`` is called. Meaning the backup will only be useful
        after the first invocation.

CLI Example:

    salt '*' file.comment /etc/modules pcspkr

file.comment_line:

Comment or Uncomment a line in a text file.

:param path: string
    The full path to the text file.

:param regex: string
    A regex expression that begins with ``^`` that will find the line you wish
    to comment. Can be as simple as ``^color =``

:param char: string
    The character used to comment a line in the type of file you're referencing.
    Default is ``#``

:param cmnt: boolean
    True to comment the line. False to uncomment the line. Default is True.

:param backup: string
    The file extension to give the backup file. Default is ``.bak``
    Set to False/None to not keep a backup.

:return: boolean
    Returns True if successful, False if not

CLI Example:

The following example will comment out the ``pcspkr`` line in the
``/etc/modules`` file using the default ``#`` character and create a backup
file named ``modules.bak``

    salt '*' file.comment_line '/etc/modules' '^pcspkr'

CLI Example:

The following example will uncomment the ``log_level`` setting in ``minion``
config file if it is set to either ``warning``, ``info``, or ``debug`` using
the ``#`` character and create a backup file named ``minion.bk``

    salt '*' file.comment_line 'C:\salt\conf\minion' '^log_level: (warning|info|debug)' '#' False '.bk'

file.contains:

.. deprecated:: 0.17.0
   Use :func:`search` instead.

Return ``True`` if the file at ``path`` contains ``text``

CLI Example:

    salt '*' file.contains /etc/crontab 'mymaintenance.sh'

file.contains_glob:

.. deprecated:: 0.17.0
   Use :func:`search` instead.

Return ``True`` if the given glob matches a string in the named file

CLI Example:

    salt '*' file.contains_glob /etc/foobar '*cheese*'

file.contains_regex:

.. deprecated:: 0.17.0
   Use :func:`search` instead.

Return True if the given regular expression matches on any line in the text
of a given file.

If the lchar argument (leading char) is specified, it
will strip `lchar` from the left side of each line before trying to match

CLI Example:

    salt '*' file.contains_regex /etc/crontab

file.copy:

Copy a file or directory from source to dst

In order to copy a directory, the recurse flag is required, and
will by default overwrite files in the destination with the same path,
and retain all other existing files. (similar to cp -r on unix)

remove_existing will remove all files in the target directory,
and then copy files from the source.

Note:
    The copy function accepts paths that are local to the Salt minion.
    This function does not support salt://, http://, or the other
    additional file paths that are supported by :mod:`states.file.managed
    <salt.states.file.managed>` and :mod:`states.file.recurse
    <salt.states.file.recurse>`.

CLI Example:

    salt '*' file.copy /path/to/src /path/to/dst
    salt '*' file.copy /path/to/src_dir /path/to/dst_dir recurse=True
    salt '*' file.copy /path/to/src_dir /path/to/dst_dir recurse=True remove_existing=True

file.delete_backup:

New in version 0.17.0

Delete a previous version of a file that was backed up using Salt's
:ref:`file state backup <file-state-backups>` system.

path
    The path on the minion to check for backups
backup_id
    The numeric id for the backup you wish to delete, as found using
    :mod:`file.list_backups <salt.modules.file.list_backups>`

CLI Example:

    salt '*' file.delete_backup /var/cache/salt/minion/file_backup/home/foo/bar/baz.txt 0

file.directory_exists:

Tests to see if path is a valid directory.  Returns True/False.

CLI Example:

    salt '*' file.directory_exists /etc

file.dirname:

Returns the directory component of a pathname

New in version 2015.5.0

This can be useful at the CLI but is frequently useful when scripting.

    {%- from salt['file.dirname'](tpldir) + '/vars.jinja' import parent_vars %}

CLI Example:

    salt '*' file.dirname 'test/path/filename.config'

file.diskusage:

Recursively calculate disk usage of path and return it
in bytes

CLI Example:

    salt '*' file.diskusage /path/to/check

file.extract_hash:

Changed in version 2016.3.5
    Prior to this version, only the ``file_name`` argument was considered
    for filename matches in the hash file. This would be problematic for
    cases in which the user was relying on a remote checksum file that they
    do not control, and they wished to use a different name for that file
    on the minion from the filename on the remote server (and in the
    checksum file). For example, managing ``/tmp/myfile.tar.gz`` when the
    remote file was at ``https://mydomain.tld/different_name.tar.gz``. The
    :py:func:`file.managed <salt.states.file.managed>` state now also
    passes this function the source URI as well as the ``source_hash_name``
    (if specified). In cases where ``source_hash_name`` is specified, it
    takes precedence over both the ``file_name`` and ``source``. When it is
    not specified, ``file_name`` takes precedence over ``source``. This
    allows for better capability for matching hashes.
Changed in version 2016.11.0
    File name and source URI matches are no longer disregarded when
    ``source_hash_name`` is specified. They will be used as fallback
    matches if there is no match to the ``source_hash_name`` value.

This routine is called from the :mod:`file.managed
<salt.states.file.managed>` state to pull a hash from a remote file.
Regular expressions are used line by line on the ``source_hash`` file, to
find a potential candidate of the indicated hash type. This avoids many
problems of arbitrary file layout rules. It specifically permits pulling
hash codes from debian ``*.dsc`` files.

If no exact match of a hash and filename are found, then the first hash
found (if any) will be returned. If no hashes at all are found, then
``None`` will be returned.

For example:

    openerp_7.0-latest-1.tar.gz:
      file.managed:
        - name: /tmp/openerp_7.0-20121227-075624-1_all.deb
        - source: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0-20121227-075624-1.tar.gz
        - source_hash: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0-20121227-075624-1.dsc

CLI Example:

    salt '*' file.extract_hash /path/to/hash/file sha512 /etc/foo

file.file_exists:

Tests to see if path is a valid file.  Returns True/False.

CLI Example:

    salt '*' file.file_exists /etc/passwd

file.find:

Approximate the Unix ``find(1)`` command and return a list of paths that
meet the specified criteria.

The options include match criteria:

    name    = path-glob                 # case sensitive
    iname   = path-glob                 # case insensitive
    regex   = path-regex                # case sensitive
    iregex  = path-regex                # case insensitive
    type    = file-types                # match any listed type
    user    = users                     # match any listed user
    group   = groups                    # match any listed group
    size    = [+-]number[size-unit]     # default unit = byte
    mtime   = interval                  # modified since date
    grep    = regex                     # search file contents

and/or actions:

    delete [= file-types]               # default type = 'f'
    exec    = command [arg ...]         # where {} is replaced by pathname
    print  [= print-opts]

and/or depth criteria:

    maxdepth = maximum depth to transverse in path
    mindepth = minimum depth to transverse before checking files or directories

The default action is ``print=path``

``path-glob``:

    *                = match zero or more chars
    ?                = match any char
    [abc]            = match a, b, or c
    [!abc] or [^abc] = match anything except a, b, and c
    [x-y]            = match chars x through y
    [!x-y] or [^x-y] = match anything except chars x through y
    {a,b,c}          = match a or b or c

``path-regex``: a Python Regex (regular expression) pattern to match pathnames

``file-types``: a string of one or more of the following:

    a: all file types
    b: block device
    c: character device
    d: directory
    p: FIFO (named pipe)
    f: plain file
    l: symlink
    s: socket

``users``: a space and/or comma separated list of user names and/or uids

``groups``: a space and/or comma separated list of group names and/or gids

``size-unit``:

    b: bytes
    k: kilobytes
    m: megabytes
    g: gigabytes
    t: terabytes

interval:

    [<num>w] [<num>d] [<num>h] [<num>m] [<num>s]

    where:
        w: week
        d: day
        h: hour
        m: minute
        s: second

print-opts: a comma and/or space separated list of one or more of the
following:

    group: group name
    md5:   MD5 digest of file contents
    mode:  file permissions (as integer)
    mtime: last modification time (as time_t)
    name:  file basename
    path:  file absolute path
    size:  file size in bytes
    type:  file type
    user:  user name

CLI Examples:

    salt '*' file.find / type=f name=\*.bak size=+10m
    salt '*' file.find /var mtime=+30d size=+10m print=path,size,mtime
    salt '*' file.find /var/log name=\*.[0-9] mtime=+30d size=+10m delete

file.get_devmm:

Get major/minor info from a device

CLI Example:

   salt '*' file.get_devmm /dev/chr

file.get_diff:

Return unified diff of two files

file1
    The first file to feed into the diff utility

    Changed in version 2018.3.0
        Can now be either a local or remote file. In earlier releases,
        thuis had to be a file local to the minion.

file2
    The second file to feed into the diff utility

    Changed in version 2018.3.0
        Can now be either a local or remote file. In earlier releases, this
        had to be a file on the salt fileserver (i.e.
        ``salt://somefile.txt``)

show_filenames: True
    Set to ``False`` to hide the filenames in the top two lines of the
    diff.

show_changes: True
    If set to ``False``, and there are differences, then instead of a diff
    a simple message stating that show_changes is set to ``False`` will be
    returned.

template: False
    Set to ``True`` if two templates are being compared. This is not useful
    except for within states, with the ``obfuscate_templates`` option set
    to ``True``.

    New in version 2018.3.0

source_hash_file1
    If ``file1`` is an http(s)/ftp URL and the file exists in the minion's
    file cache, this option can be passed to keep the minion from
    re-downloading the archive if the cached copy matches the specified
    hash.

    New in version 2018.3.0

source_hash_file2
    If ``file2`` is an http(s)/ftp URL and the file exists in the minion's
    file cache, this option can be passed to keep the minion from
    re-downloading the archive if the cached copy matches the specified
    hash.

    New in version 2018.3.0

CLI Examples:

    salt '*' file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc
    salt '*' file.get_diff /tmp/foo.txt /tmp/bar.txt

file.get_gid:

Return the id of the group that owns a given file

path
    file or directory of which to get the gid

follow_symlinks
    indicated if symlinks should be followed

CLI Example:

    salt '*' file.get_gid /etc/passwd

Changed in version 0.16.4
    ``follow_symlinks`` option added

file.get_group:

Return the group that owns a given file

path
    file or directory of which to get the group

follow_symlinks
    indicated if symlinks should be followed

CLI Example:

    salt '*' file.get_group /etc/passwd

Changed in version 0.16.4
    ``follow_symlinks`` option added

file.get_hash:

Get the hash sum of a file

This is better than ``get_sum`` for the following reasons:
    - It does not read the entire file into memory.
    - It does not return a string on error. The returned value of
        ``get_sum`` cannot really be trusted since it is vulnerable to
        collisions: ``get_sum(..., 'xyz') == 'Hash xyz not supported'``

path
    path to the file or directory

form
    desired sum format

chunk_size
    amount to sum at once

CLI Example:

    salt '*' file.get_hash /etc/shadow

file.get_managed:

Return the managed file data for file.managed

name
    location where the file lives on the server

template
    template format

source
    managed source file

source_hash
    hash of the source file

source_hash_name
    When ``source_hash`` refers to a remote file, this specifies the
    filename to look for in that file.

    New in version 2016.3.5

user
    Owner of file

group
    Group owner of file

mode
    Permissions of file

attrs
    Attributes of file

    New in version 2018.3.0

context
    Variables to add to the template context

defaults
    Default values of for context_dict

skip_verify
    If ``True``, hash verification of remote file sources (``http://``,
    ``https://``, ``ftp://``) will be skipped, and the ``source_hash``
    argument will be ignored.

    New in version 2016.3.0

verify_ssl
    If ``False``, remote https file sources (``https://``) and source_hash
    will not attempt to validate the servers certificate. Default is True.

    New in version 3002

use_etag
    If ``True``, remote http/https file sources will attempt to use the
    ETag header to determine if the remote file needs to be downloaded.
    This provides a lightweight mechanism for promptly refreshing files
    changed on a web server without requiring a full hash comparison via
    the ``source_hash`` parameter.

    New in version 3005

source_hash_sig
    When ``source`` is a remote file source, ``source_hash`` is a file,
    ``skip_verify`` is not true and ``use_etag`` is not true, ensure a
    valid GPG signature exists on the source hash file.
    Set this to ``true`` for an inline (clearsigned) signature, or to a
    file URI retrievable by `:py:func:`cp.cache_file <salt.modules.cp.cache_file>`
    for a detached one.

    New in version 3007.0

signed_by_any
    When verifying ``source_hash_sig``, require at least one valid signature
    from one of a list of key fingerprints. This is passed to :py:func:`gpg.verify
    <salt.modules.gpg.verify>`.

    New in version 3007.0

signed_by_all
    When verifying ``source_hash_sig``, require a valid signature from each
    of the key fingerprints in this list. This is passed to :py:func:`gpg.verify
    <salt.modules.gpg.verify>`.

    New in version 3007.0

keyring
    When verifying ``source_hash_sig``, use this keyring.

    New in version 3007.0

gnupghome
    When verifying ``source_hash_sig``, use this GnuPG home.

    New in version 3007.0

CLI Example:

    salt '*' file.get_managed /etc/httpd/conf.d/httpd.conf jinja salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' None root root '755' base None None

file.get_mode:

Return the mode of a file

path
    file or directory of which to get the mode

follow_symlinks
    indicated if symlinks should be followed

CLI Example:

    salt '*' file.get_mode /etc/passwd

Changed in version 2014.1.0
    ``follow_symlinks`` option added

file.get_selinux_context:

Get an SELinux context from a given path

CLI Example:

    salt '*' file.get_selinux_context /etc/hosts

file.get_source_sum:

New in version 2016.11.0

Used by :py:func:`file.get_managed <salt.modules.file.get_managed>` to
obtain the hash and hash type from the parameters specified below.

file_name
    Optional file name being managed, for matching with
    :py:func:`file.extract_hash <salt.modules.file.extract_hash>`.

source
    Source file, as used in :py:mod:`file <salt.states.file>` and other
    states. If ``source_hash`` refers to a file containing hashes, then
    this filename will be used to match a filename in that file. If the
    ``source_hash`` is a hash expression, then this argument will be
    ignored.

source_hash
    Hash file/expression, as used in :py:mod:`file <salt.states.file>` and
    other states. If this value refers to a remote URL or absolute path to
    a local file, it will be cached and :py:func:`file.extract_hash
    <salt.modules.file.extract_hash>` will be used to obtain a hash from
    it.

source_hash_name
    Specific file name to look for when ``source_hash`` refers to a remote
    file, used to disambiguate ambiguous matches.

saltenv: base
    Salt fileserver environment from which to retrieve the source_hash. This
    value will only be used when ``source_hash`` refers to a file on the
    Salt fileserver (i.e. one beginning with ``salt://``).

verify_ssl
    If ``False``, remote https file sources (``https://``) and source_hash
    will not attempt to validate the servers certificate. Default is True.

    New in version 3002

source_hash_sig
    When ``source`` is a remote file source and ``source_hash`` is a file,
    ensure a valid GPG signature exists on the source hash file.
    Set this to ``true`` for an inline (clearsigned) signature, or to a
    file URI retrievable by `:py:func:`cp.cache_file <salt.modules.cp.cache_file>`
    for a detached one.

    New in version 3007.0

signed_by_any
    When verifying ``source_hash_sig``, require at least one valid signature
    from one of a list of key fingerprints. This is passed to :py:func:`gpg.verify
    <salt.modules.gpg.verify>`.

    New in version 3007.0

signed_by_all
    When verifying ``source_hash_sig``, require a valid signature from each
    of the key fingerprints in this list. This is passed to :py:func:`gpg.verify
    <salt.modules.gpg.verify>`.

    New in version 3007.0

keyring
    When verifying ``source_hash_sig``, use this keyring.

    New in version 3007.0

gnupghome
    When verifying ``source_hash_sig``, use this GnuPG home.

    New in version 3007.0

CLI Example:

    salt '*' file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=499ae16dcae71eeb7c3a30c75ea7a1a6
    salt '*' file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=https://mydomain.tld/hashes.md5
    salt '*' file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=https://mydomain.tld/hashes.md5 source_hash_name=./dir2/foo.tar.gz

file.get_sum:

Return the checksum for the given file. The following checksum algorithms
are supported:

* md5
* sha1
* sha224
* sha256 **(default)**
* sha384
* sha512

path
    path to the file or directory

form
    desired sum format

CLI Example:

    salt '*' file.get_sum /etc/passwd sha512

file.get_uid:

Return the id of the user that owns a given file

path
    file or directory of which to get the uid

follow_symlinks
    indicated if symlinks should be followed

CLI Example:

    salt '*' file.get_uid /etc/passwd

Changed in version 0.16.4
    ``follow_symlinks`` option added

file.get_user:

Return the user that owns a given file

path
    file or directory of which to get the user

follow_symlinks
    indicated if symlinks should be followed

CLI Example:

    salt '*' file.get_user /etc/passwd

Changed in version 0.16.4
    ``follow_symlinks`` option added

file.gid_to_group:

Convert the group id to the group name on this system

gid
    gid to convert to a group name

CLI Example:

    salt '*' file.gid_to_group 0

file.grep:

Grep for a string in the specified file

Note:
    This function's return value is slated for refinement in future
    versions of Salt

    Windows does not support the ``grep`` functionality.

path
    Path to the file to be searched

    Note:
        Globbing is supported (i.e. ``/var/log/foo/*.log``, but if globbing
        is being used then the path should be quoted to keep the shell from
        attempting to expand the glob expression.

pattern
    Pattern to match. For example: ``test``, or ``a[0-5]``

opts
    Additional command-line flags to pass to the grep command. For example:
    ``-v``, or ``-i -B2``

    Note:
        The options should come after a double-dash (as shown in the
        examples below) to keep Salt's own argument parser from
        interpreting them.

CLI Example:

    salt '*' file.grep /etc/passwd nobody
    salt '*' file.grep /etc/sysconfig/network-scripts/ifcfg-eth0 ipaddr -- -i
    salt '*' file.grep /etc/sysconfig/network-scripts/ifcfg-eth0 ipaddr -- -i -B2
    salt '*' file.grep "/etc/sysconfig/network-scripts/*" ipaddr -- -i -l

file.group_to_gid:

Convert the group to the gid on this system

group
    group to convert to its gid

CLI Example:

    salt '*' file.group_to_gid root

file.is_blkdev:

Check if a file exists and is a block device.

CLI Example:

   salt '*' file.is_blkdev /dev/blk

file.is_chrdev:

Check if a file exists and is a character device.

CLI Example:

   salt '*' file.is_chrdev /dev/chr

file.is_fifo:

Check if a file exists and is a FIFO.

CLI Example:

   salt '*' file.is_fifo /dev/fifo

file.is_hardlink:

Check if the path is a hard link by verifying that the number of links
is larger than 1

CLI Example:

   salt '*' file.is_hardlink /path/to/link

file.is_link:

Check if the path is a symbolic link

CLI Example:

   salt '*' file.is_link /path/to/link

file.join:

Return a normalized file system path for the underlying OS

New in version 2014.7.0

This can be useful at the CLI but is frequently useful when scripting
combining path variables:

    {% set www_root = '/var' %}
    {% set app_dir = 'myapp' %}

    myapp_config:
      file:
        - managed
        - name: {{ salt['file.join'](www_root, app_dir, 'config.yaml') }}

CLI Example:

    salt '*' file.join '/' 'usr' 'local' 'bin'

file.lchown:

Chown a file, pass the file the desired user and group without following
symlinks.

path
    path to the file or directory

user
    user owner

group
    group owner

CLI Example:

    salt '*' file.chown /etc/passwd root root

file.line:

New in version 2015.8.0

Line-focused editing of a file.

Note:

    ``file.line`` exists for historic reasons, and is not
    generally recommended. It has a lot of quirks.  You may find
    ``file.replace`` to be more suitable.

``file.line`` is most useful if you have single lines in a file
(potentially a config file) that you would like to manage. It can
remove, add, and replace a single line at a time.

path
    Filesystem path to the file to be edited.

content
    Content of the line. Allowed to be empty if ``mode='delete'``.

match
    Match the target line for an action by
    a fragment of a string or regular expression.

    If neither ``before`` nor ``after`` are provided, and ``match``
    is also ``None``, match falls back to the ``content`` value.

mode
    Defines how to edit a line. One of the following options is
    required:

    - ensure
        If line does not exist, it will be added. If ``before``
        and ``after`` are specified either zero lines, or lines
        that contain the ``content`` line are allowed to be in between
        ``before`` and ``after``. If there are lines, and none of
        them match then it will produce an error.
    - replace
        If line already exists, the entire line will be replaced.
    - delete
        Delete the line, if found.
    - insert
        Nearly identical to ``ensure``. If a line does not exist,
        it will be added.

        The differences are that multiple (and non-matching) lines are
        alloweed between ``before`` and ``after``, if they are
        specified. The line will always be inserted right before
        ``before``. ``insert`` also allows the use of ``location`` to
        specify that the line should be added at the beginning or end of
        the file.

    Note:

        If ``mode='insert'`` is used, at least one of ``location``,
        ``before``, or ``after`` is required.  If ``location`` is used,
        ``before`` and ``after`` are ignored.

location
    In ``mode='insert'`` only, whether to place the ``content`` at the
    beginning or end of a the file. If ``location`` is provided,
    ``before`` and ``after`` are ignored. Valid locations:

    - start
        Place the content at the beginning of the file.
    - end
        Place the content at the end of the file.

before
    Regular expression or an exact case-sensitive fragment of the string.
    Will be tried as **both** a regex **and** a part of the line.  Must
    match **exactly** one line in the file.  This value is only used in
    ``ensure`` and ``insert`` modes. The ``content`` will be inserted just
    before this line, with matching indentation unless ``indent=False``.

after
    Regular expression or an exact case-sensitive fragment of the string.
    Will be tried as **both** a regex **and** a part of the line.  Must
    match **exactly** one line in the file.  This value is only used in
    ``ensure`` and ``insert`` modes. The ``content`` will be inserted
    directly after this line, unless ``before`` is also provided. If
    ``before`` is not provided, indentation will match this line, unless
    ``indent=False``.

show_changes
    Output a unified diff of the old file and the new file.
    If ``False`` return a boolean if any changes were made.
    Default is ``True``

    Note:
        Using this option will store two copies of the file in-memory
        (the original version and the edited version) in order to generate the diff.

backup
    Create a backup of the original file with the extension:
    "Year-Month-Day-Hour-Minutes-Seconds".

quiet
    Do not raise any exceptions. E.g. ignore the fact that the file that is
    tried to be edited does not exist and nothing really happened.

indent
    Keep indentation with the previous line. This option is not considered when
    the ``delete`` mode is specified. Default is ``True``

CLI Example:

    salt '*' file.line /etc/nsswitch.conf "networks: files dns" after="hosts:.*?" mode='ensure'

Note:

    If an equal sign (``=``) appears in an argument to a Salt command, it is
    interpreted as a keyword argument in the format of ``key=val``. That
    processing can be bypassed in order to pass an equal sign through to the
    remote shell command by manually specifying the kwarg:

        salt '*' file.line /path/to/file content="CREATEMAIL_SPOOL=no" match="CREATE_MAIL_SPOOL=yes" mode="replace"

**Examples:**

Here's a simple config file.

    [some_config]
    # Some config file
    # this line will go away

    here=False
    away=True
    goodybe=away

    salt \* file.line /some/file.conf mode=delete match=away

This will produce:

    [some_config]
    # Some config file

    here=False
    away=True
    goodbye=away

If that command is executed 2 more times, this will be the result:

    [some_config]
    # Some config file

    here=False

If we reset the file to its original state and run

    salt \* file.line /some/file.conf mode=replace match=away content=here

Three passes will this state will result in this file:

    [some_config]
    # Some config file
    here

    here=False
    here
    here

Each pass replacing the first line found.

Given this file:

    insert after me
    something
    insert before me

The following command

    salt \* file.line /some/file.txt mode=insert after="insert after me" before="insert before me" content=thrice

If that command is executed 3 times, the result will be:

    insert after me
    something
    thrice
    thrice
    thrice
    insert before me

If the mode is ``ensure`` instead, it will fail each time. To succeed, we
need to remove the incorrect line between before and after:

    insert after me
    insert before me

With an ensure mode, this will insert ``thrice`` the first time and
make no changes for subsequent calls. For something simple this is
fine, but if you have instead blocks like this:

    Begin SomeBlock
        foo = bar
    End

    Begin AnotherBlock
        another = value
    End

And you try to use ensure this way:

    salt \* file.line  /tmp/fun.txt mode="ensure" content="this = should be my content" after="Begin SomeBlock" before="End"

This will fail because there are multiple ``End`` lines. Without that
problem, it still would fail because there is a non-matching line,
``foo = bar``. Ensure **only** allows either zero, or the matching
line present to be present in between ``before`` and ``after``.

file.link:

New in version 2014.1.0

Create a hard link to a file

CLI Example:

    salt '*' file.link /path/to/file /path/to/link

file.list_backup:

This function is an alias of list_backups.

New in version 0.17.0

Lists the previous versions of a file backed up using Salt's :ref:`file
state backup <file-state-backups>` system.

path
    The path on the minion to check for backups
limit
    Limit the number of results to the most recent N backups

CLI Example:

    salt '*' file.list_backups /foo/bar/baz.txt

file.list_backups:

New in version 0.17.0

Lists the previous versions of a file backed up using Salt's :ref:`file
state backup <file-state-backups>` system.

path
    The path on the minion to check for backups
limit
    Limit the number of results to the most recent N backups

CLI Example:

    salt '*' file.list_backups /foo/bar/baz.txt

file.list_backups_dir:

Lists the previous versions of a directory backed up using Salt's :ref:`file
state backup <file-state-backups>` system.

path
    The directory on the minion to check for backups
limit
    Limit the number of results to the most recent N backups

CLI Example:

    salt '*' file.list_backups_dir /foo/bar/baz/

file.lsattr:

New in version 2018.3.0
Changed in version 2018.3.1
    If ``lsattr`` is not installed on the system, ``None`` is returned.
Changed in version 2018.3.4
    If on ``AIX``, ``None`` is returned even if in filesystem as lsattr on ``AIX``
    is not the same thing as the linux version.

Obtain the modifiable attributes of the given file. If path
is to a directory, an empty list is returned.

path
    path to file to obtain attributes of. File/directory must exist.

CLI Example:

    salt '*' file.lsattr foo1.txt

file.lstat:

New in version 2014.1.0

Returns the lstat attributes for the given file or dir. Does not support
symbolic links.

CLI Example:

    salt '*' file.lstat /path/to/file

file.makedirs:

Ensure that the directory containing this path is available.

Note:

    The path must end with a trailing slash otherwise the directory/directories
    will be created up to the parent directory. For example if path is
    ``/opt/code``, then it would be treated as ``/opt/`` but if the path
    ends with a trailing slash like ``/opt/code/``, then it would be
    treated as ``/opt/code/``.

CLI Example:

    salt '*' file.makedirs /opt/code/

file.makedirs_perms:

Taken and modified from os.makedirs to set user, group and mode for each
directory created.

CLI Example:

    salt '*' file.makedirs_perms /opt/code

file.manage_file:

Checks the destination against what was retrieved with get_managed and
makes the appropriate modifications (if necessary).

name
    location to place the file

sfn
    location of cached file on the minion

    This is the path to the file stored on the minion. This file is placed
    on the minion using cp.cache_file.  If the hash sum of that file
    matches the source_sum, we do not transfer the file to the minion
    again.

    This file is then grabbed and if it has template set, it renders the
    file to be placed into the correct place on the system using
    salt.files.utils.copyfile()

ret
    The initial state return data structure. Pass in ``None`` to use the
    default structure.

source
    file reference on the master

source_sum
    sum hash for source

user
    user owner

group
    group owner

backup
    backup_mode

attrs
    attributes to be set on file: '' means remove all of them

    New in version 2018.3.0

makedirs
    make directories if they do not exist

template
    format of templating

show_changes
    Include diff in state return

contents:
    contents to be placed in the file

dir_mode
    mode for directories created with makedirs

skip_verify: False
    If ``True``, hash verification of remote file sources (``http://``,
    ``https://``, ``ftp://``) will be skipped, and the ``source_hash``
    argument will be ignored.

    New in version 2016.3.0

keep_mode: False
    If ``True``, and the ``source`` is a file from the Salt fileserver (or
    a local file on the minion), the mode of the destination file will be
    set to the mode of the source file.

    Note: keep_mode does not work with salt-ssh.

        As a consequence of how the files are transferred to the minion, and
        the inability to connect back to the master with salt-ssh, salt is
        unable to stat the file as it exists on the fileserver and thus
        cannot mirror the mode on the salt-ssh minion

encoding
    If specified, then the specified encoding will be used. Otherwise, the
    file will be encoded using the system locale (usually UTF-8). See
    https://docs.python.org/3/library/codecs.html#standard-encodings for
    the list of available encodings.

    New in version 2017.7.0

encoding_errors: 'strict'
    Default is ```'strict'```.
    See https://docs.python.org/2/library/codecs.html#codec-base-classes
    for the error handling schemes.

    New in version 2017.7.0

seuser
    selinux user attribute

    New in version 3001

serange
    selinux range attribute

    New in version 3001

setype
    selinux type attribute

    New in version 3001

serange
    selinux range attribute

    New in version 3001

verify_ssl
    If ``False``, remote https file sources (``https://``)
    will not attempt to validate the servers certificate. Default is True.

    New in version 3002

use_etag
    If ``True``, remote http/https file sources will attempt to use the
    ETag header to determine if the remote file needs to be downloaded.
    This provides a lightweight mechanism for promptly refreshing files
    changed on a web server without requiring a full hash comparison via
    the ``source_hash`` parameter.

    New in version 3005

signature
    Ensure a valid GPG signature exists on the selected ``source`` file.
    Set this to true for inline signatures, or to a file URI retrievable
    by `:py:func:`cp.cache_file <salt.modules.cp.cache_file>`
    for a detached one.

    Note:

        A signature is only enforced directly after caching the file,
        before it is moved to its final destination. Existing target files
        (with the correct checksum) will neither be checked nor deleted.

        It will be enforced regardless of source type and will be
        required on the final output, therefore this does not lend itself
        well when templates are rendered.
        The file will not be modified, meaning inline signatures are not
        removed.

    New in version 3007.0

source_hash_sig
    When ``source`` is a remote file source, ``source_hash`` is a file,
    ``skip_verify`` is not true and ``use_etag`` is not true, ensure a
    valid GPG signature exists on the source hash file.
    Set this to ``true`` for an inline (clearsigned) signature, or to a
    file URI retrievable by `:py:func:`cp.cache_file <salt.modules.cp.cache_file>`
    for a detached one.

    Note:

        A signature on the ``source_hash`` file is enforced regardless of
        changes since its contents are used to check if an existing file
        is in the correct state - but only for remote sources!
        As for ``signature``, existing target files will not be modified,
        only the cached source_hash and source_hash_sig files will be removed.

    New in version 3007.0

signed_by_any
    When verifying signatures either on the managed file or its source hash file,
    require at least one valid signature from one of a list of key fingerprints.
    This is passed to :py:func:`gpg.verify <salt.modules.gpg.verify>`.

    New in version 3007.0

signed_by_all
    When verifying signatures either on the managed file or its source hash file,
    require a valid signature from each of the key fingerprints in this list.
    This is passed to :py:func:`gpg.verify <salt.modules.gpg.verify>`.

    New in version 3007.0

keyring
    When verifying signatures, use this keyring.

    New in version 3007.0

gnupghome
    When verifying signatures, use this GnuPG home.

    New in version 3007.0

CLI Example:

    salt '*' file.manage_file /etc/httpd/conf.d/httpd.conf '' '{}' salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' '' base ''

Changed in version 2014.7.0
    ``follow_symlinks`` option added

file.mkdir:

Ensure that a directory is available.

CLI Example:

    salt '*' file.mkdir /opt/jetty/context

file.mknod:

New in version 0.17.0

Create a block device, character device, or fifo pipe.
Identical to the gnu mknod.

CLI Examples:

    salt '*' file.mknod /dev/chr c 180 31
    salt '*' file.mknod /dev/blk b 8 999
    salt '*' file.nknod /dev/fifo p

file.mknod_blkdev:

New in version 0.17.0

Create a block device.

CLI Example:

   salt '*' file.mknod_blkdev /dev/blk 8 999

file.mknod_chrdev:

New in version 0.17.0

Create a character device.

CLI Example:

   salt '*' file.mknod_chrdev /dev/chr 180 31

file.mknod_fifo:

New in version 0.17.0

Create a FIFO pipe.

CLI Example:

   salt '*' file.mknod_fifo /dev/fifo

file.move:

Move a file or directory

disallow_copy_and_unlink
    If ``True``, the operation is offloaded to the ``file.rename`` execution
    module function. This will use ``os.rename`` underneath, which will fail
    in the event that ``src`` and ``dst`` are on different filesystems. If
    ``False`` (the default), ``shutil.move`` will be used in order to fall
    back on a "copy then unlink" approach, which is required for moving
    across filesystems.

    New in version 3006.0

CLI Example:

    salt '*' file.move /path/to/src /path/to/dst

file.normpath:

Returns Normalize path, eliminating double slashes, etc.

New in version 2015.5.0

This can be useful at the CLI but is frequently useful when scripting.

    {%- from salt['file.normpath'](tpldir + '/../vars.jinja') import parent_vars %}

CLI Example:

    salt '*' file.normpath 'a/b/c/..'

file.open_files:

Return a list of all physical open files on the system.

CLI Examples:

    salt '*' file.open_files
    salt '*' file.open_files by_pid=True

file.pardir:

Return the relative parent directory path symbol for underlying OS

New in version 2014.7.0

This can be useful when constructing Salt Formulas.

    {% set pardir = salt['file.pardir']() %}
    {% set final_path = salt['file.join']('subdir', pardir, 'confdir') %}

CLI Example:

    salt '*' file.pardir

file.patch:

New in version 0.10.4

Apply a patch to a file or directory.

Equivalent to:

    patch <options> -i <patchfile> <originalfile>

Or, when a directory is patched:

    patch <options> -i <patchfile> -d <originalfile> -p0

originalfile
    The full path to the file or directory to be patched
patchfile
    A patch file to apply to ``originalfile``
options
    Options to pass to patch.

Note:
    Windows now supports using patch as of 3004.

    In order to use this function in Windows, please install the
    patch binary through your own means and ensure it's found
    in the system Path. If installing through git-for-windows,
    please select the optional "Use Git and optional Unix tools
    from the Command Prompt" option when installing Git.

CLI Example:

    salt '*' file.patch /opt/file.txt /tmp/file.txt.patch

    salt '*' file.patch C:\file1.txt C:\file3.patch

file.path_exists_glob:

Tests to see if path after expansion is a valid path (file or directory).
Expansion allows usage of ? * and character ranges []. Tilde expansion
is not supported. Returns True/False.

New in version 2014.7.0

CLI Example:

    salt '*' file.path_exists_glob /etc/pam*/pass*

file.prepend:

New in version 2014.7.0

Prepend text to the beginning of a file

path
    path to file

`*args`
    strings to prepend to the file

CLI Example:

    salt '*' file.prepend /etc/motd \
            "With all thine offerings thou shalt offer salt." \
            "Salt is what makes things taste bad when it isn't in them."

.. admonition:: Attention

    If you need to pass a string to append and that string contains
    an equal sign, you **must** include the argument name, args.
    For example:

        salt '*' file.prepend /etc/motd args='cheese=spam'

        salt '*' file.prepend /etc/motd args="['cheese=spam','spam=cheese']"

file.psed:

.. deprecated:: 0.17.0
   Use :py:func:`~salt.modules.file.replace` instead.

Make a simple edit to a file (pure Python version)

Equivalent to:

    sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"

path
    The full path to the file to be edited
before
    A pattern to find in order to replace with ``after``
after
    Text that will replace ``before``
limit: ``''``
    An initial pattern to search for before searching for ``before``
backup: ``.bak``
    The file will be backed up before edit with this file extension;
    **WARNING:** each time ``sed``/``comment``/``uncomment`` is called will
    overwrite this backup
flags: ``gMS``
    Flags to modify the search. Valid values are:
      - ``g``: Replace all occurrences of the pattern, not just the first.
      - ``I``: Ignore case.
      - ``L``: Make ``\w``, ``\W``, ``\b``, ``\B``, ``\s`` and ``\S``
        dependent on the locale.
      - ``M``: Treat multiple lines as a single line.
      - ``S``: Make `.` match all characters, including newlines.
      - ``U``: Make ``\w``, ``\W``, ``\b``, ``\B``, ``\d``, ``\D``,
        ``\s`` and ``\S`` dependent on Unicode.
      - ``X``: Verbose (whitespace is ignored).
multi: ``False``
    If True, treat the entire file as a single line

Forward slashes and single quotes will be escaped automatically in the
``before`` and ``after`` patterns.

CLI Example:

    salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'

file.read:

New in version 2017.7.0

Return the content of the file.

:param bool binary:
    Whether to read and return binary data

CLI Example:

    salt '*' file.read /path/to/file

file.readdir:

New in version 2014.1.0

Return a list containing the contents of a directory

CLI Example:

    salt '*' file.readdir /path/to/dir/

file.readlink:

New in version 2014.1.0

Return the path that a symlink points to

Args:

    path (str):
        The path to the symlink

    canonicalize (bool):
        Get the canonical path eliminating any symbolic links encountered in
        the path

Returns:

    str: The path that the symlink points to

Raises:

    SaltInvocationError: path is not absolute

    SaltInvocationError: path is not a link

    CommandExecutionError: error reading the symbolic link

CLI Example:

    salt '*' file.readlink /path/to/link

file.remove:

Remove the named file. If a directory is supplied, it will be recursively
deleted.

CLI Example:

    salt '*' file.remove /tmp/foo

Changed in version 3000
    The method now works on all types of file system entries, not just
    files, directories and symlinks.

file.remove_backup:

This function is an alias of delete_backup.

New in version 0.17.0

Delete a previous version of a file that was backed up using Salt's
:ref:`file state backup <file-state-backups>` system.

path
    The path on the minion to check for backups
backup_id
    The numeric id for the backup you wish to delete, as found using
    :mod:`file.list_backups <salt.modules.file.list_backups>`

CLI Example:

    salt '*' file.delete_backup /var/cache/salt/minion/file_backup/home/foo/bar/baz.txt 0

file.rename:

Rename a file or directory

CLI Example:

    salt '*' file.rename /path/to/src /path/to/dst

file.replace:

New in version 0.17.0

Replace occurrences of a pattern in a file. If ``show_changes`` is
``True``, then a diff of what changed will be returned, otherwise a
``True`` will be returned when changes are made, and ``False`` when
no changes are made.

This is a pure Python implementation that wraps Python's :py:func:`~re.sub`.

path
    Filesystem path to the file to be edited. If a symlink is specified, it
    will be resolved to its target.

pattern
    A regular expression, to be matched using Python's
    :py:func:`~re.search`.

repl
    The replacement text

count: 0
    Maximum number of pattern occurrences to be replaced. If count is a
    positive integer ``n``, only ``n`` occurrences will be replaced,
    otherwise all occurrences will be replaced.

flags (list or int)
    A list of flags defined in the ``re`` module documentation from the
    Python standard library. Each list item should be a string that will
    correlate to the human-friendly flag name. E.g., ``['IGNORECASE',
    'MULTILINE']``. Optionally, ``flags`` may be an int, with a value
    corresponding to the XOR (``|``) of all the desired flags. Defaults to
    8 (which supports 'MULTILINE').

bufsize (int or str)
    How much of the file to buffer into memory at once. The
    default value ``1`` processes one line at a time. The special value
    ``file`` may be specified which will read the entire file into memory
    before processing.

append_if_not_found: False
    New in version 2014.7.0

    If set to ``True``, and pattern is not found, then the content will be
    appended to the file.

prepend_if_not_found: False
    New in version 2014.7.0

    If set to ``True`` and pattern is not found, then the content will be
    prepended to the file.

not_found_content
    New in version 2014.7.0

    Content to use for append/prepend if not found. If None (default), uses
    ``repl``. Useful when ``repl`` uses references to group in pattern.

backup: .bak
    The file extension to use for a backup of the file before editing. Set
    to ``False`` to skip making a backup.

dry_run: False
    If set to ``True``, no changes will be made to the file, the function
    will just return the changes that would have been made (or a
    ``True``/``False`` value if ``show_changes`` is set to ``False``).

search_only: False
    If set to true, this no changes will be performed on the file, and this
    function will simply return ``True`` if the pattern was matched, and
    ``False`` if not.

show_changes: True
    If ``True``, return a diff of changes made. Otherwise, return ``True``
    if changes were made, and ``False`` if not.

    Note:
        Using this option will store two copies of the file in memory (the
        original version and the edited version) in order to generate the
        diff. This may not normally be a concern, but could impact
        performance if used with large files.

ignore_if_missing: False
    New in version 2015.8.0

    If set to ``True``, this function will simply return ``False``
    if the file doesn't exist. Otherwise, an error will be thrown.

preserve_inode: True
    New in version 2015.8.0

    Preserve the inode of the file, so that any hard links continue to
    share the inode with the original filename. This works by *copying* the
    file, reading from the copy, and writing to the file at the original
    inode. If ``False``, the file will be *moved* rather than copied, and a
    new file will be written to a new inode, but using the original
    filename. Hard links will then share an inode with the backup, instead
    (if using ``backup`` to create a backup copy).

backslash_literal: False
    New in version 2016.11.7

    Interpret backslashes as literal backslashes for the repl and not
    escape characters.  This will help when using append/prepend so that
    the backslashes are not interpreted for the repl on the second run of
    the state.

If an equal sign (``=``) appears in an argument to a Salt command it is
interpreted as a keyword argument in the format ``key=val``. That
processing can be bypassed in order to pass an equal sign through to the
remote shell command by manually specifying the kwarg:

    salt '*' file.replace /path/to/file pattern='=' repl=':'
    salt '*' file.replace /path/to/file pattern="bind-address\s*=" repl='bind-address:'

CLI Examples:

    salt '*' file.replace /etc/httpd/httpd.conf pattern='LogLevel warn' repl='LogLevel info'
    salt '*' file.replace /some/file pattern='before' repl='after' flags='[MULTILINE, IGNORECASE]'

file.restore_backup:

New in version 0.17.0

Restore a previous version of a file that was backed up using Salt's
:ref:`file state backup <file-state-backups>` system.

path
    The path on the minion to check for backups
backup_id
    The numeric id for the backup you wish to restore, as found using
    :mod:`file.list_backups <salt.modules.file.list_backups>`

CLI Example:

    salt '*' file.restore_backup /foo/bar/baz.txt 0

file.restorecon:

Reset the SELinux context on a given path

CLI Example:

     salt '*' file.restorecon /home/user/.ssh/authorized_keys

file.rmdir:

New in version 2014.1.0
Changed in version 3006.0
    Changed return value for failure to a boolean.

Remove the specified directory. Fails if a directory is not empty.

recurse
    When ``recurse`` is set to ``True``, all empty directories
    within the path are pruned.

    New in version 3006.0

verbose
    When ``verbose`` is set to ``True``, a dictionary is returned
    which contains more information about the removal process.

    New in version 3006.0

older_than
    When ``older_than`` is set to a number, it is used to determine the
    **number of days** which must have passed since the last modification
    timestamp before a directory will be allowed to be removed. Setting
    the value to 0 is equivalent to leaving it at the default of ``None``.

    New in version 3006.0

CLI Example:

    salt '*' file.rmdir /tmp/foo/

file.search:

New in version 0.17.0

Search for occurrences of a pattern in a file

Except for multiline, params are identical to
:py:func:`~salt.modules.file.replace`.

multiline
    If true, inserts 'MULTILINE' into ``flags`` and sets ``bufsize`` to
    'file'.

    New in version 2015.8.0

CLI Example:

    salt '*' file.search /etc/crontab 'mymaintenance.sh'

file.sed:

.. deprecated:: 0.17.0
   Use :py:func:`~salt.modules.file.replace` instead.

Make a simple edit to a file

Equivalent to:

    sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"

path
    The full path to the file to be edited
before
    A pattern to find in order to replace with ``after``
after
    Text that will replace ``before``
limit: ``''``
    An initial pattern to search for before searching for ``before``
backup: ``.bak``
    The file will be backed up before edit with this file extension;
    **WARNING:** each time ``sed``/``comment``/``uncomment`` is called will
    overwrite this backup
options: ``-r -e``
    Options to pass to sed
flags: ``g``
    Flags to modify the sed search; e.g., ``i`` for case-insensitive pattern
    matching
negate_match: False
    Negate the search command (``!``)

    New in version 0.17.0

Forward slashes and single quotes will be escaped automatically in the
``before`` and ``after`` patterns.

CLI Example:

    salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'

file.sed_contains:

.. deprecated:: 0.17.0
   Use :func:`search` instead.

Return True if the file at ``path`` contains ``text``. Utilizes sed to
perform the search (line-wise search).

Note: the ``p`` flag will be added to any flags you pass in.

CLI Example:

    salt '*' file.contains /etc/crontab 'mymaintenance.sh'

file.seek_read:

New in version 2014.1.0

Seek to a position on a file and read it

path
    path to file

seek
    amount to read at once

offset
    offset to start into the file

CLI Example:

    salt '*' file.seek_read /path/to/file 4096 0

file.seek_write:

New in version 2014.1.0

Seek to a position on a file and write to it

path
    path to file

data
    data to write to file

offset
    position in file to start writing

CLI Example:

    salt '*' file.seek_write /path/to/file 'some data' 4096

file.set_mode:

Set the mode of a file

path
    file or directory of which to set the mode

mode
    mode to set the path to

CLI Example:

    salt '*' file.set_mode /etc/passwd 0644

file.set_selinux_context:

Changed in version 3001

    Added persist option

Set a specific SELinux label on a given path

CLI Example:

    salt '*' file.set_selinux_context path <user> <role> <type> <range>
    salt '*' file.set_selinux_context /etc/yum.repos.d/epel.repo system_u object_r system_conf_t s0

file.source_list:

Check the source list and return the source to use

CLI Example:

    salt '*' file.source_list salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' base

file.stats:

Return a dict containing the stats for a given file

CLI Example:

    salt '*' file.stats /etc/passwd

file.statvfs:

New in version 2014.1.0

Perform a statvfs call against the filesystem that the file resides on

CLI Example:

    salt '*' file.statvfs /path/to/file

file.symlink:

Create a symbolic link (symlink, soft link) to a file

Args:

    src (str): The path to a file or directory

    path (str): The path to the link. Must be an absolute path

    force (bool):
        Overwrite an existing symlink with the same name
        New in version 3005

    atomic (bool):
        Use atomic file operations to create the symlink
        New in version 3006.0

    follow_symlinks (bool):
        If set to ``False``, use ``os.path.lexists()`` for existence checks
        instead of ``os.path.exists()``.
        New in version 3007.0

Returns:
    bool: ``True`` if successful, otherwise raises ``CommandExecutionError``

CLI Example:

    salt '*' file.symlink /path/to/file /path/to/link

file.touch:

New in version 0.9.5

Just like the ``touch`` command, create a file if it doesn't exist or
simply update the atime and mtime if it already does.

atime:
    Access time in Unix epoch time. Set it to 0 to set atime of the
    file with Unix date of birth. If this parameter isn't set, atime
    will be set with current time.
mtime:
    Last modification in Unix epoch time. Set it to 0 to set mtime of
    the file with Unix date of birth. If this parameter isn't set,
    mtime will be set with current time.

CLI Example:

    salt '*' file.touch /var/log/emptyfile

file.truncate:

New in version 2014.1.0

Seek to a position on a file and delete everything after that point

path
    path to file

length
    offset into file to truncate

CLI Example:

    salt '*' file.truncate /path/to/file 512

file.uid_to_user:

Convert a uid to a user name

uid
    uid to convert to a username

CLI Example:

    salt '*' file.uid_to_user 0

file.uncomment:

.. deprecated:: 0.17.0
   Use :py:func:`~salt.modules.file.replace` instead.

Uncomment specified commented lines in a file

path
    The full path to the file to be edited
regex
    A regular expression used to find the lines that are to be uncommented.
    This regex should not include the comment character. A leading ``^``
    character will be stripped for convenience (for easily switching
    between comment() and uncomment()).
char: ``#``
    The character to remove in order to uncomment a line
backup: ``.bak``
    The file will be backed up before edit with this file extension;
    **WARNING:** each time ``sed``/``comment``/``uncomment`` is called will
    overwrite this backup

CLI Example:

    salt '*' file.uncomment /etc/hosts.deny 'ALL: PARANOID'

file.user_to_uid:

Convert user name to a uid

user
    user name to convert to its uid

CLI Example:

    salt '*' file.user_to_uid root

file.write:

New in version 2014.7.0

Write text to a file, overwriting any existing contents.

path
    path to file

`*args`
    strings to write to the file

CLI Example:

    salt '*' file.write /etc/motd \
            "With all thine offerings thou shalt offer salt."

.. admonition:: Attention

    If you need to pass a string to append and that string contains
    an equal sign, you **must** include the argument name, args.
    For example:

        salt '*' file.write /etc/motd args='cheese=spam'

        salt '*' file.write /etc/motd args="['cheese=spam','spam=cheese']"

freezer.compare:

Display the difference between two frozen states. The results are shown as
as a dictionary with keys for packages and repositories. Each key may
contain a changes dictionary showing items that differ between the two
frozen states. Items shown in the "old" changes but not the "new" were
removed. Items in "new" but not "old" were added. Items shown in both
probably updated/changed versions between freezes.

old
    Name of the "old" frozen state. Required.

new
    Name of the "new" frozen state. Required.

CLI Example:

    salt '*' freezer.freeze pre_install post_install

freezer.freeze:

Save the list of package and repos in a freeze file.

As this module is build on top of the pkg module, the user can
send extra attributes to the underlying pkg module via kwargs.
This function will call ``pkg.list_pkgs`` and ``pkg.list_repos``,
and any additional arguments will be passed through to those
functions.

name
    Name of the frozen state. Optional.

force
    If true, overwrite the state. Optional.

CLI Example:

    salt '*' freezer.freeze
    salt '*' freezer.freeze pre_install
    salt '*' freezer.freeze force=True root=/chroot

freezer.list:

Return the list of frozen states.

CLI Example:

    salt '*' freezer.list

freezer.restore:

Make sure that the system contains the packages and repos from a
frozen state.

Read the list of packages and repositories from the freeze file,
and compare it with the current list of packages and repos. If
there is any difference, all the missing packages are repos will
be installed, and all the extra packages and repos will be
removed.

As this module is build on top of the pkg module, the user can
send extra attributes to the underlying pkg module via kwargs.
This function will call ``pkg.list_repos``, ``pkg.mod_repo``,
``pkg.list_pkgs``, ``pkg.install``, ``pkg.remove`` and
``pkg.del_repo``, and any additional arguments will be passed
through to those functions.

name
    Name of the frozen state. Optional.

clean
    If True remove the frozen information YAML from the cache

    New in version 3000

CLI Example:

    salt '*' freezer.restore
    salt '*' freezer.restore root=/chroot

freezer.status:

Return True if there is already a frozen state.

A frozen state is merely a list of packages (including the
version) in a specific time. This information can be used to
compare with the current list of packages, and revert the
installation of some extra packages that are in the system.

name
    Name of the frozen state. Optional.

CLI Example:

    salt '*' freezer.status
    salt '*' freezer.status pre_install

gem.install:

Installs one or several gems.

:param gems: string
    The gems to install
:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.
:param version: string : None
    Specify the version to install for the gem.
    Doesn't play nice with multiple gems at once
:param rdoc: boolean : False
    Generate RDoc documentation for the gem(s).
    For rubygems > 3 this is interpreted as the --no-document arg and the
    ri option will then be ignored
:param ri: boolean : False
    Generate RI documentation for the gem(s).
    For rubygems > 3 this is interpreted as the --no-document arg and the
    rdoc option will then be ignored
:param pre_releases: boolean : False
    Include pre-releases in the available versions
:param proxy: string : None
    Use the specified HTTP proxy server for all outgoing traffic.
    Format: http://hostname[:port]

source : None
    Use the specified HTTP gem source server to download gem.
    Format: http://hostname[:port]

CLI Example:

    salt '*' gem.install vagrant

    salt '*' gem.install redphone gem_bin=/opt/sensu/embedded/bin/gem

gem.list:

List locally installed gems.

:param prefix: string :
    Only list gems when the name matches this prefix.
:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.

CLI Example:

    salt '*' gem.list

gem.list_upgrades:

New in version 2015.8.0

Check if an upgrade is available for installed gems

gem_bin : None
    Full path to ``gem`` binary to use.
ruby : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
runas : None
    The user to run gem as.

CLI Example:

    salt '*' gem.list_upgrades

gem.sources_add:

Add a gem source.

:param source_uri: string
    The source URI to add.
:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.

CLI Example:

    salt '*' gem.sources_add http://rubygems.org/

gem.sources_list:

List the configured gem sources.

:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.

CLI Example:

    salt '*' gem.sources_list

gem.sources_remove:

Remove a gem source.

:param source_uri: string
    The source URI to remove.
:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.

CLI Example:

    salt '*' gem.sources_remove http://rubygems.org/

gem.uninstall:

Uninstall one or several gems.

:param gems: string
    The gems to uninstall.
:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.

CLI Example:

    salt '*' gem.uninstall vagrant

gem.update:

Update one or several gems.

:param gems: string
    The gems to update.
:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.

CLI Example:

    salt '*' gem.update vagrant

gem.update_system:

Update rubygems.

:param version: string : (newest)
    The version of rubygems to install.
:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.

CLI Example:

    salt '*' gem.update_system

gem.version:

Print out the version of gem

:param gem_bin: string : None
    Full path to ``gem`` binary to use.
:param ruby: string : None
    If RVM or rbenv are installed, the ruby version and gemset to use.
    Ignored if ``gem_bin`` is specified.
:param runas: string : None
    The user to run gem as.

CLI Example:

    salt '*' gem.version

genesis.avail_platforms:

Return which platforms are available

CLI Example:

    salt myminion genesis.avail_platforms

genesis.bootstrap:

Create an image for a specific platform.

Please note that this function *MUST* be run as root, as images that are
created make files belonging to root.

platform
    Which platform to use to create the image. Currently supported platforms
    are rpm, deb and pacman.

root
    Local path to create the root of the image filesystem.

img_format
    Which format to create the image in. By default, just copies files into
    a directory on the local filesystem (``dir``). Future support will exist
    for ``sparse``.

fs_format
    When using a non-``dir`` ``img_format``, which filesystem to format the
    image to. By default, ``ext2``.

fs_opts
    When using a non-``dir`` ``img_format``, a dict of opts may be
    specified.

arch
    Architecture to install packages for, if supported by the underlying
    bootstrap tool. Currently only used for deb.

flavor
    Which flavor of operating system to install. This correlates to a
    specific directory on the distribution repositories. For instance,
    ``wheezy`` on Debian.

repo_url
    Mainly important for Debian-based repos. Base URL for the mirror to
    install from. (e.x.: http://ftp.debian.org/debian/)

static_qemu
    Local path to the static qemu binary required for this arch.
    (e.x.: /usr/bin/qemu-amd64-static)

pkg_confs
    The location of the conf files to copy into the image, to point the
    installer to the right repos and configuration.

img_size
    If img_format is not ``dir``, then the size of the image must be
    specified.

mount_dir
    If img_format is not ``dir``, then the image must be mounted somewhere.
    If the ``mount_dir`` is not specified, then it will be created at
    ``/opt/salt-genesis.<random_uuid>``. This directory will be unmounted
    and removed when the process is finished.

pkg_cache
    This points to a directory containing a cache of package files to be
    copied to the image. It does not need to be specified.

pkgs
    A list of packages to be installed on this image. For RedHat, this
    will include ``yum``, ``centos-release`` and ``iputils`` by default.

exclude_pkgs
    A list of packages to be excluded. If you do not want to install the
    defaults, you need to include them in this list.

epel_url
    The URL to download the EPEL release package from.

CLI Examples:

    salt myminion genesis.bootstrap pacman /root/arch
    salt myminion genesis.bootstrap rpm /root/redhat
    salt myminion genesis.bootstrap deb /root/wheezy arch=amd64             flavor=wheezy static_qemu=/usr/bin/qemu-x86_64-static

genesis.ldd_deps:

Recurse through a set of dependencies reported by ``ldd``, to find
associated dependencies.

Please note that this does not necessarily resolve all (non-package)
dependencies for a file; but it does help.

CLI Example:

    salt myminion genesis.ldd_deps bash
    salt myminion genesis.ldd_deps /bin/bash

genesis.mksls:

Convert an installation file/script to an SLS file. Currently supports
``kickstart``, ``preseed``, and ``autoyast``.

CLI Examples:

    salt <minion> genesis.mksls kickstart /path/to/kickstart.cfg
    salt <minion> genesis.mksls kickstart /path/to/kickstart.cfg /path/to/dest.sls

New in version 2015.8.0

genesis.pack:

Pack up a directory structure, into a specific format

CLI Examples:

    salt myminion genesis.pack centos /root/centos
    salt myminion genesis.pack centos /root/centos pack_format='tar'

genesis.unpack:

Unpack an image into a directory structure

CLI Example:

    salt myminion genesis.unpack centos /root/centos

git.add:

Changed in version 2015.8.0
    The ``--verbose`` command line argument is now implied

Interface to `git-add(1)`_

cwd
    The path to the git checkout

filename
    The location of the file/directory to add, relative to ``cwd``

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``add``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-add(1)`: http://git-scm.com/docs/git-add

CLI Examples:

    salt myminion git.add /path/to/repo foo/bar.py
    salt myminion git.add /path/to/repo foo/bar.py opts='--dry-run'

git.archive:

Changed in version 2015.8.0
    Returns ``True`` if successful, raises an error if not.

Interface to `git-archive(1)`_, exports a tarball/zip file of the
repository

cwd
    The path to be archived

    Note:
        ``git archive`` permits a partial archive to be created. Thus, this
        path does not need to be the root of the git repository. Only the
        files within the directory specified by ``cwd`` (and its
        subdirectories) will be in the resulting archive. For example, if
        there is a git checkout at ``/tmp/foo``, then passing
        ``/tmp/foo/bar`` as the ``cwd`` will result in just the files
        underneath ``/tmp/foo/bar`` to be exported as an archive.

output
    The path of the archive to be created

overwrite : False
    Unless set to ``True``, Salt will over overwrite an existing archive at
    the path specified by the ``output`` argument.

    New in version 2015.8.0

rev : HEAD
    The revision from which to create the archive

format
    Manually specify the file format of the resulting archive. This
    argument can be omitted, and ``git archive`` will attempt to guess the
    archive type (and compression) from the filename. ``zip``, ``tar``,
    ``tar.gz``, and ``tgz`` are extensions that are recognized
    automatically, and git can be configured to support other archive types
    with the addition of git configuration keys.

    See the `git-archive(1)`_ manpage explanation of the
    ``--format`` argument (as well as the ``CONFIGURATION`` section of the
    manpage) for further information.

    New in version 2015.8.0

prefix
    Prepend ``<prefix>`` to every filename in the archive. If unspecified,
    the name of the directory at the top level of the repository will be
    used as the prefix (e.g. if ``cwd`` is set to ``/foo/bar/baz``, the
    prefix will be ``baz``, and the resulting archive will contain a
    top-level directory by that name).

    Note:
        The default behavior if the ``--prefix`` option for ``git archive``
        is not specified is to not prepend a prefix, so Salt's behavior
        differs slightly from ``git archive`` in this respect. Use
        ``prefix=''`` to create an archive with no prefix.

    Changed in version 2015.8.0
        The behavior of this argument has been changed slightly. As of
        this version, it is necessary to include the trailing slash when
        specifying a prefix, if the prefix is intended to create a
        top-level directory.

git_opts
    Any additional options to add to git command itself (not the
    ``archive`` subcommand), in a single string. This is useful for passing
    ``-c`` to run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-archive(1)`: http://git-scm.com/docs/git-archive

CLI Example:

    salt myminion git.archive /path/to/repo /path/to/archive.tar

git.branch:

Interface to `git-branch(1)`_

cwd
    The path to the git checkout

name
    Name of the branch on which to operate. If not specified, the current
    branch will be assumed.

opts
    Any additional options to add to the command line, in a single string

    Note:
        To create a branch based on something other than HEAD, pass the
        name of the revision as ``opts``. If the revision is in the format
        ``remotename/branch``, then this will also set the remote tracking
        branch.

        Additionally, on the Salt CLI, if the opts are preceded with a
        dash, it is necessary to precede them with ``opts=`` (as in the CLI
        examples below) to avoid causing errors with Salt's own argument
        parsing.

git_opts
    Any additional options to add to git command itself (not the ``branch``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-branch(1)`: http://git-scm.com/docs/git-branch

CLI Examples:

    # Set remote tracking branch
    salt myminion git.branch /path/to/repo mybranch opts='--set-upstream-to origin/mybranch'
    # Create new branch
    salt myminion git.branch /path/to/repo mybranch upstream/somebranch
    # Delete branch
    salt myminion git.branch /path/to/repo mybranch opts='-d'
    # Rename branch (2015.8.0 and later)
    salt myminion git.branch /path/to/repo newbranch opts='-m oldbranch'

git.checkout:

Interface to `git-checkout(1)`_

cwd
    The path to the git checkout

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the
    ``checkout`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

rev
    The remote branch or revision to checkout.

    Changed in version 2015.8.0
        Optional when using ``-b`` or ``-B`` in ``opts``.

force : False
    Force a checkout even if there might be overwritten changes

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-checkout(1)`: http://git-scm.com/docs/git-checkout

CLI Examples:

    # Checking out local local revisions
    salt myminion git.checkout /path/to/repo somebranch user=jeff
    salt myminion git.checkout /path/to/repo opts='testbranch -- conf/file1 file2'
    salt myminion git.checkout /path/to/repo rev=origin/mybranch opts='--track'
    # Checking out remote revision into new branch
    salt myminion git.checkout /path/to/repo upstream/master opts='-b newbranch'
    # Checking out current revision into new branch (2015.8.0 and later)
    salt myminion git.checkout /path/to/repo opts='-b newbranch'

git.clone:

Interface to `git-clone(1)`_

cwd
    Location of git clone

    Changed in version 2015.8.0
        If ``name`` is passed, then the clone will be made *within* this
        directory.

url
    The URL of the repository to be cloned

    Changed in version 2015.8.0
        Argument renamed from ``repository`` to ``url``

name
    Optional alternate name for the top-level directory to be created by
    the clone

    New in version 2015.8.0

opts
    Any additional options to add to the command line, in a single string

git_opts
    Any additional options to add to git command itself (not the ``clone``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs

    Warning:

        Unless Salt is invoked from the minion using ``salt-call``, the
        key(s) must be passphraseless. For greater security with
        passphraseless private keys, see the `sshd(8)`_ manpage for
        information on securing the keypair from the remote side in the
        ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    Changed in version 2015.8.7

        Salt will no longer attempt to use passphrase-protected keys unless
        invoked from the minion using ``salt-call``, to prevent blocking
        waiting for user input.

    Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file

    Changed in version 2016.3.0

https_user
    Set HTTP Basic Auth username. Only accepted for HTTPS URLs.

    New in version 2015.5.0

https_pass
    Set HTTP Basic Auth password. Only accepted for HTTPS URLs.

    New in version 2015.5.0

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

saltenv
    The default salt environment to pull sls files from

    New in version 2016.3.1

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-clone(1)`: http://git-scm.com/docs/git-clone

CLI Example:

    salt myminion git.clone /path/to/repo_parent_dir git://github.com/saltstack/salt.git

git.commit:

Interface to `git-commit(1)`_

cwd
    The path to the git checkout

message
    Commit message

opts
    Any additional options to add to the command line, in a single string.
    These opts will be added to the end of the git command being run.

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

        The ``-m`` option should not be passed here, as the commit message
        will be defined by the ``message`` argument.

git_opts
    Any additional options to add to git command itself (not the ``commit``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

filename
    The location of the file/directory to commit, relative to ``cwd``.
    This argument is optional, and can be used to commit a file without
    first staging it.

    Note:
        This argument only works on files which are already tracked by the
        git repository.

    New in version 2015.8.0

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-commit(1)`: http://git-scm.com/docs/git-commit

CLI Examples:

    salt myminion git.commit /path/to/repo 'The commit message'
    salt myminion git.commit /path/to/repo 'The commit message' filename=foo/bar.py

git.config_get:

Get the value of a key in the git configuration file

key
    The name of the configuration key to get

    Changed in version 2015.8.0
        Argument renamed from ``setting_name`` to ``key``

cwd
    The path to the git checkout

    Changed in version 2015.8.0
        Now optional if ``global`` is set to ``True``

global : False
    If ``True``, query the global git configuration. Otherwise, only the
    local git configuration will be queried.

    New in version 2015.8.0

all : False
    If ``True``, return a list of all values set for ``key``. If the key
    does not exist, ``None`` will be returned.

    New in version 2015.8.0

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    salt myminion git.config_get user.name cwd=/path/to/repo
    salt myminion git.config_get user.email global=True
    salt myminion git.config_get core.gitproxy cwd=/path/to/repo all=True

git.config_get_regex:

This function is an alias of config_get_regexp.

New in version 2015.8.0

Get the value of a key or keys in the git configuration file using regexes
for more flexible matching. The return data is a dictionary mapping keys to
lists of values matching the ``value_regex``. If no values match, an empty
dictionary will be returned.

key
    Regex on which key names will be matched

value_regex
    If specified, return all values matching this regex. The return data
    will be a dictionary mapping keys to lists of values matching the
    regex.

    .. important::
        Only values matching the ``value_regex`` will be part of the return
        data. So, if ``key`` matches a multivar, then it is possible that
        not all of the values will be returned. To get all values set for a
        multivar, simply omit the ``value_regex`` argument.

cwd
    The path to the git checkout

global : False
    If ``True``, query the global git configuration. Otherwise, only the
    local git configuration will be queried.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    # Matches any values for key 'foo.bar'
    salt myminion git.config_get_regexp /path/to/repo foo.bar
    # Matches any value starting with 'baz' set for key 'foo.bar'
    salt myminion git.config_get_regexp /path/to/repo foo.bar 'baz.*'
    # Matches any key starting with 'user.'
    salt myminion git.config_get_regexp '^user\.' global=True

git.config_get_regexp:

New in version 2015.8.0

Get the value of a key or keys in the git configuration file using regexes
for more flexible matching. The return data is a dictionary mapping keys to
lists of values matching the ``value_regex``. If no values match, an empty
dictionary will be returned.

key
    Regex on which key names will be matched

value_regex
    If specified, return all values matching this regex. The return data
    will be a dictionary mapping keys to lists of values matching the
    regex.

    .. important::
        Only values matching the ``value_regex`` will be part of the return
        data. So, if ``key`` matches a multivar, then it is possible that
        not all of the values will be returned. To get all values set for a
        multivar, simply omit the ``value_regex`` argument.

cwd
    The path to the git checkout

global : False
    If ``True``, query the global git configuration. Otherwise, only the
    local git configuration will be queried.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    # Matches any values for key 'foo.bar'
    salt myminion git.config_get_regexp /path/to/repo foo.bar
    # Matches any value starting with 'baz' set for key 'foo.bar'
    salt myminion git.config_get_regexp /path/to/repo foo.bar 'baz.*'
    # Matches any key starting with 'user.'
    salt myminion git.config_get_regexp '^user\.' global=True

git.config_set:

Changed in version 2015.8.0
    Return the value(s) of the key being set

Set a key in the git configuration file

cwd
    The path to the git checkout. Must be an absolute path, or the word
    ``global`` to indicate that a global key should be set.

    Changed in version 2014.7.0
        Made ``cwd`` argument optional if ``is_global=True``

key
    The name of the configuration key to set

    Changed in version 2015.8.0
        Argument renamed from ``setting_name`` to ``key``

value
    The value to set for the specified key. Incompatible with the
    ``multivar`` argument.

    Changed in version 2015.8.0
        Argument renamed from ``setting_value`` to ``value``

add : False
    Add a value to a key, creating/updating a multivar

    New in version 2015.8.0

multivar
    Set a multivar all at once. Values can be comma-separated or passed as
    a Python list. Incompatible with the ``value`` argument.

    New in version 2015.8.0

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

global : False
    If ``True``, set a global variable

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    salt myminion git.config_set user.email me@example.com cwd=/path/to/repo
    salt myminion git.config_set user.email foo@bar.com global=True

git.config_unset:

New in version 2015.8.0

Unset a key in the git configuration file

cwd
    The path to the git checkout. Must be an absolute path, or the word
    ``global`` to indicate that a global key should be unset.

key
    The name of the configuration key to unset

value_regex
    Regular expression that matches exactly one key, used to delete a
    single value from a multivar. Ignored if ``all`` is set to ``True``.

all : False
    If ``True`` unset all values for a multivar. If ``False``, and ``key``
    is a multivar, an error will be raised.

global : False
    If ``True``, unset set a global variable. Otherwise, a local variable
    will be unset.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Example:

    salt myminion git.config_unset /path/to/repo foo.bar
    salt myminion git.config_unset /path/to/repo foo.bar all=True

git.current_branch:

Returns the current branch name of a local checkout. If HEAD is detached,
return the SHA1 of the revision which is currently checked out.

cwd
    The path to the git checkout

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Example:

    salt myminion git.current_branch /path/to/repo

git.describe:

Returns the `git-describe(1)`_ string (or the SHA1 hash if there are no
tags) for the given revision.

cwd
    The path to the git checkout

rev : HEAD
    The revision to describe

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-describe(1)`: http://git-scm.com/docs/git-describe

CLI Examples:

    salt myminion git.describe /path/to/repo
    salt myminion git.describe /path/to/repo develop

git.diff:

New in version 2015.8.12,2016.3.3,2016.11.0

Interface to `git-diff(1)`_

cwd
    The path to the git checkout

item1 and item2
    Revision(s) to pass to the ``git diff`` command. One or both of these
    arguments may be ignored if some of the options below are set to
    ``True``. When ``cached`` is ``False``, and no revisions are passed
    to this function, then the current working tree will be compared
    against the index (i.e. unstaged changes). When two revisions are
    passed, they will be compared to each other.

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``diff``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

no_index : False
    When it is necessary to diff two files in the same repo against each
    other, and not diff two different revisions, set this option to
    ``True``. If this is left ``False`` in these instances, then a normal
    ``git diff`` will be performed against the index (i.e. unstaged
    changes), and files in the ``paths`` option will be used to narrow down
    the diff output.

    Note:
        Requires Git 1.5.1 or newer. Additionally, when set to ``True``,
        ``item1`` and ``item2`` will be ignored.

cached : False
    If ``True``, compare staged changes to ``item1`` (if specified),
    otherwise compare them to the most recent commit.

    Note:
        ``item2`` is ignored if this option is is set to ``True``.

paths
    File paths to pass to the ``git diff`` command. Can be passed as a
    comma-separated list or a Python list.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-diff(1)`: http://git-scm.com/docs/git-diff

CLI Example:

    # Perform diff against the index (staging area for next commit)
    salt myminion git.diff /path/to/repo
    # Compare staged changes to the most recent commit
    salt myminion git.diff /path/to/repo cached=True
    # Compare staged changes to a specific revision
    salt myminion git.diff /path/to/repo mybranch cached=True
    # Perform diff against the most recent commit (includes staged changes)
    salt myminion git.diff /path/to/repo HEAD
    # Diff two commits
    salt myminion git.diff /path/to/repo abcdef1 aabbccd
    # Diff two commits, only showing differences in the specified paths
    salt myminion git.diff /path/to/repo abcdef1 aabbccd paths=path/to/file1,path/to/file2
    # Diff two files with one being outside the working tree
    salt myminion git.diff /path/to/repo no_index=True paths=path/to/file1,/absolute/path/to/file2

git.discard_local_changes:

New in version 2019.2.0

Runs a ``git checkout -- <path>`` from the directory specified by ``cwd``.

cwd
    The path to the git checkout

path
    path relative to cwd (defaults to ``.``)

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

CLI Example:

    salt myminion git.discard_local_changes /path/to/repo
    salt myminion git.discard_local_changes /path/to/repo path=foo

git.fetch:

Changed in version 2015.8.2
    Return data is now a dictionary containing information on branches and
    tags that were added/updated

Interface to `git-fetch(1)`_

cwd
    The path to the git checkout

remote
    Optional remote name to fetch. If not passed, then git will use its
    default behavior (as detailed in `git-fetch(1)`_).

    New in version 2015.8.0

force
    Force the fetch even when it is not a fast-forward.

    New in version 2015.8.0

refspecs
    Override the refspec(s) configured for the remote with this argument.
    Multiple refspecs can be passed, comma-separated.

    New in version 2015.8.0

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``fetch``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs

    Warning:

        Unless Salt is invoked from the minion using ``salt-call``, the
        key(s) must be passphraseless. For greater security with
        passphraseless private keys, see the `sshd(8)`_ manpage for
        information on securing the keypair from the remote side in the
        ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    Changed in version 2015.8.7

        Salt will no longer attempt to use passphrase-protected keys unless
        invoked from the minion using ``salt-call``, to prevent blocking
        waiting for user input.

    Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file

    Changed in version 2016.3.0

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

saltenv
    The default salt environment to pull sls files from

    New in version 2016.3.1

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-fetch(1)`: http://git-scm.com/docs/git-fetch

CLI Example:

    salt myminion git.fetch /path/to/repo upstream
    salt myminion git.fetch /path/to/repo identity=/root/.ssh/id_rsa

git.init:

Interface to `git-init(1)`_

cwd
    The path to the directory to be initialized

bare : False
    If ``True``, init a bare repository

    New in version 2015.8.0

template
    Set this argument to specify an alternate `template directory`_

    New in version 2015.8.0

separate_git_dir
    Set this argument to specify an alternate ``$GIT_DIR``

    New in version 2015.8.0

shared
    Set sharing permissions on git repo. See `git-init(1)`_ for more
    details.

    New in version 2015.8.0

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``init``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-init(1)`: http://git-scm.com/docs/git-init
.. _`template directory`: http://git-scm.com/docs/git-init#_template_directory

CLI Examples:

    salt myminion git.init /path/to/repo
    # Init a bare repo (before 2015.8.0)
    salt myminion git.init /path/to/bare/repo.git opts='--bare'
    # Init a bare repo (2015.8.0 and later)
    salt myminion git.init /path/to/bare/repo.git bare=True

git.is_worktree:

New in version 2015.8.0

This function will attempt to determine if ``cwd`` is part of a
worktree by checking its ``.git`` to see if it is a file containing a
reference to another gitdir.

cwd
    path to the worktree to be removed

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Example:

    salt myminion git.is_worktree /path/to/repo

git.list_branches:

New in version 2015.8.0

Return a list of branches

cwd
    The path to the git checkout

remote : False
    If ``True``, list remote branches. Otherwise, local branches will be
    listed.

    Warning:

        This option will only return remote branches of which the local
        checkout is aware, use :py:func:`git.fetch
        <salt.modules.git.fetch>` to update remotes.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    salt myminion git.list_branches /path/to/repo
    salt myminion git.list_branches /path/to/repo remote=True

git.list_tags:

New in version 2015.8.0

Return a list of tags

cwd
    The path to the git checkout

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    salt myminion git.list_tags /path/to/repo

git.list_worktrees:

New in version 2015.8.0

Returns information on worktrees

Changed in version 2015.8.4
    Version 2.7.0 added the ``list`` subcommand to `git-worktree(1)`_ which
    provides a lot of additional information. The return data has been
    changed to include this information, even for pre-2.7.0 versions of
    git. In addition, if a worktree has a detached head, then any tags
    which point to the worktree's HEAD will be included in the return data.

Note:
    By default, only worktrees for which the worktree directory is still
    present are returned, but this can be changed using the ``all`` and
    ``stale`` arguments (described below).

cwd
    The path to the git checkout

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

all : False
    If ``True``, then return all worktrees tracked under
    $GIT_DIR/worktrees, including ones for which the gitdir is no longer
    present.

stale : False
    If ``True``, return *only* worktrees whose gitdir is no longer present.

Note:
    Only one of ``all`` and ``stale`` can be set to ``True``.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-worktree(1)`: http://git-scm.com/docs/git-worktree

CLI Examples:

    salt myminion git.list_worktrees /path/to/repo
    salt myminion git.list_worktrees /path/to/repo all=True
    salt myminion git.list_worktrees /path/to/repo stale=True

git.ls_remote:

Interface to `git-ls-remote(1)`_. Returns the upstream hash for a remote
reference.

cwd
    The path to the git checkout. Optional (and ignored if present) when
    ``remote`` is set to a URL instead of a remote name.

remote : origin
    The name of the remote to query. Can be the name of a git remote
    (which exists in the git checkout defined by the ``cwd`` parameter),
    or the URL of a remote repository.

    Changed in version 2015.8.0
        Argument renamed from ``repository`` to ``remote``

ref
    The name of the ref to query. Optional, if not specified, all refs are
    returned. Can be a branch or tag name, or the full name of the
    reference (for example, to get the hash for a Github pull request number
    1234, ``ref`` can be set to ``refs/pull/1234/head``

    Changed in version 2015.8.0
        Argument renamed from ``branch`` to ``ref``

    Changed in version 2015.8.4
        Defaults to returning all refs instead of master.

opts
    Any additional options to add to the command line, in a single string

    New in version 2015.8.0

git_opts
    Any additional options to add to git command itself (not the
    ``ls-remote`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs

    Warning:

        Unless Salt is invoked from the minion using ``salt-call``, the
        key(s) must be passphraseless. For greater security with
        passphraseless private keys, see the `sshd(8)`_ manpage for
        information on securing the keypair from the remote side in the
        ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    Changed in version 2015.8.7

        Salt will no longer attempt to use passphrase-protected keys unless
        invoked from the minion using ``salt-call``, to prevent blocking
        waiting for user input.

    Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file

    Changed in version 2016.3.0

https_user
    Set HTTP Basic Auth username. Only accepted for HTTPS URLs.

    New in version 2015.5.0

https_pass
    Set HTTP Basic Auth password. Only accepted for HTTPS URLs.

    New in version 2015.5.0

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

saltenv
    The default salt environment to pull sls files from

    New in version 2016.3.1

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-ls-remote(1)`: http://git-scm.com/docs/git-ls-remote

CLI Example:

    salt myminion git.ls_remote /path/to/repo origin master
    salt myminion git.ls_remote remote=https://mydomain.tld/repo.git ref=mytag opts='--tags'

git.merge:

Interface to `git-merge(1)`_

cwd
    The path to the git checkout

rev
    Revision to merge into the current branch. If not specified, the remote
    tracking branch will be merged.

    New in version 2015.8.0

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``merge``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs. Salt will not attempt to use
    passphrase-protected keys unless invoked from the minion using
    ``salt-call``, to prevent blocking waiting for user input. Key can also
    be specified as a SaltStack file server URL, eg.
    ``salt://location/identity_file``.

    Note:
        For greater security with passphraseless private keys, see the
        `sshd(8)`_ manpage for information on securing the keypair from the
        remote side in the ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    New in version 2018.3.5,2019.2.1,3000

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-merge(1)`: http://git-scm.com/docs/git-merge

CLI Example:

    # Fetch first...
    salt myminion git.fetch /path/to/repo
    # ... then merge the remote tracking branch
    salt myminion git.merge /path/to/repo
    # .. or merge another rev
    salt myminion git.merge /path/to/repo rev=upstream/foo

git.merge_base:

New in version 2015.8.0

Interface to `git-merge-base(1)`_.

cwd
    The path to the git checkout

refs
    Any refs/commits to check for a merge base. Can be passed as a
    comma-separated list or a Python list.

all : False
    Return a list of all matching merge bases. Not compatible with any of
    the below options except for ``octopus``.

octopus : False
    If ``True``, then this function will determine the best common
    ancestors of all specified commits, in preparation for an n-way merge.
    See here_ for a description of how these bases are determined.

    Set ``all`` to ``True`` with this option to return all computed merge
    bases, otherwise only the "best" will be returned.

is_ancestor : False
    If ``True``, then instead of returning the merge base, return a
    boolean telling whether or not the first commit is an ancestor of the
    second commit.

    Note:
        This option requires two commits to be passed.

    Changed in version 2015.8.2
        Works properly in git versions older than 1.8.0, where the
        ``--is-ancestor`` CLI option is not present.

independent : False
    If ``True``, this function will return the IDs of the refs/commits
    passed which cannot be reached by another commit.

fork_point
    If passed, then this function will return the commit where the
    commit diverged from the ref specified by ``fork_point``. If no fork
    point is found, ``None`` is returned.

    Note:
        At most one commit is permitted to be passed if a ``fork_point`` is
        specified. If no commits are passed, then ``HEAD`` is assumed.

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

        This option should not be necessary unless new CLI arguments are
        added to `git-merge-base(1)`_ and are not yet supported in Salt.

git_opts
    Any additional options to add to git command itself (not the
    ``merge-base`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    if ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-merge-base(1)`: http://git-scm.com/docs/git-merge-base
.. _here: http://git-scm.com/docs/git-merge-base#_discussion

CLI Examples:

    salt myminion git.merge_base /path/to/repo HEAD upstream/mybranch
    salt myminion git.merge_base /path/to/repo 8f2e542,4ad8cab,cdc9886 octopus=True
    salt myminion git.merge_base /path/to/repo refs=8f2e542,4ad8cab,cdc9886 independent=True
    salt myminion git.merge_base /path/to/repo refs=8f2e542,4ad8cab is_ancestor=True
    salt myminion git.merge_base /path/to/repo fork_point=upstream/master
    salt myminion git.merge_base /path/to/repo refs=mybranch fork_point=upstream/master

git.merge_tree:

New in version 2015.8.0

Interface to `git-merge-tree(1)`_, shows the merge results and conflicts
from a 3-way merge without touching the index.

cwd
    The path to the git checkout

ref1
    First ref/commit to compare

ref2
    Second ref/commit to compare

base
    The base tree to use for the 3-way-merge. If not provided, then
    :py:func:`git.merge_base <salt.modules.git.merge_base>` will be invoked
    on ``ref1`` and ``ref2`` to determine the merge base to use.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    if ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-merge-tree(1)`: http://git-scm.com/docs/git-merge-tree

CLI Examples:

    salt myminion git.merge_tree /path/to/repo HEAD upstream/dev
    salt myminion git.merge_tree /path/to/repo HEAD upstream/dev base=aaf3c3d

git.pull:

Interface to `git-pull(1)`_

cwd
    The path to the git checkout

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``pull``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs

    Warning:

        Unless Salt is invoked from the minion using ``salt-call``, the
        key(s) must be passphraseless. For greater security with
        passphraseless private keys, see the `sshd(8)`_ manpage for
        information on securing the keypair from the remote side in the
        ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    Changed in version 2015.8.7

        Salt will no longer attempt to use passphrase-protected keys unless
        invoked from the minion using ``salt-call``, to prevent blocking
        waiting for user input.

    Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file

    Changed in version 2016.3.0

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

saltenv
    The default salt environment to pull sls files from

    New in version 2016.3.1

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-pull(1)`: http://git-scm.com/docs/git-pull

CLI Example:

    salt myminion git.pull /path/to/repo opts='--rebase origin master'

git.push:

Interface to `git-push(1)`_

cwd
    The path to the git checkout

remote
    Name of the remote to which the ref should being pushed

    New in version 2015.8.0

ref : master
    Name of the ref to push

    Note:
        Being a refspec_, this argument can include a colon to define local
        and remote ref names.

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``push``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs

    Warning:

        Unless Salt is invoked from the minion using ``salt-call``, the
        key(s) must be passphraseless. For greater security with
        passphraseless private keys, see the `sshd(8)`_ manpage for
        information on securing the keypair from the remote side in the
        ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    Changed in version 2015.8.7

        Salt will no longer attempt to use passphrase-protected keys unless
        invoked from the minion using ``salt-call``, to prevent blocking
        waiting for user input.

    Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file

    Changed in version 2016.3.0

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

saltenv
    The default salt environment to pull sls files from

    New in version 2016.3.1

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-push(1)`: http://git-scm.com/docs/git-push
.. _refspec: http://git-scm.com/book/en/v2/Git-Internals-The-Refspec

CLI Example:

    # Push master as origin/master
    salt myminion git.push /path/to/repo origin master
    # Push issue21 as upstream/develop
    salt myminion git.push /path/to/repo upstream issue21:develop
    # Delete remote branch 'upstream/temp'
    salt myminion git.push /path/to/repo upstream :temp

git.rebase:

Interface to `git-rebase(1)`_

cwd
    The path to the git checkout

rev : master
    The revision to rebase onto the current branch

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``rebase``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-rebase(1)`: http://git-scm.com/docs/git-rebase

CLI Example:

    salt myminion git.rebase /path/to/repo master
    salt myminion git.rebase /path/to/repo 'origin master'
    salt myminion git.rebase /path/to/repo origin/master opts='--onto newbranch'

git.remote_get:

Get the fetch and push URL for a specific remote

cwd
    The path to the git checkout

remote : origin
    Name of the remote to query

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

redact_auth : True
    Set to ``False`` to include the username/password if the remote uses
    HTTPS Basic Auth. Otherwise, this information will be redacted.

    Warning:
        Setting this to ``False`` will not only reveal any HTTPS Basic Auth
        that is configured, but the return data will also be written to the
        job cache. When possible, it is recommended to use SSH for
        authentication.

    New in version 2015.5.6

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    salt myminion git.remote_get /path/to/repo
    salt myminion git.remote_get /path/to/repo upstream

git.remote_refs:

New in version 2015.8.0

Return the remote refs for the specified URL by running ``git ls-remote``.

url
    URL of the remote repository

filter
    Optionally provide a ref name to ``git ls-remote``. This can be useful
    to make this function run faster on repositories with many
    branches/tags.

    New in version 2019.2.0

heads : False
    Restrict output to heads. Can be combined with ``tags``.

tags : False
    Restrict output to tags. Can be combined with ``heads``.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs

    Warning:

        Unless Salt is invoked from the minion using ``salt-call``, the
        key(s) must be passphraseless. For greater security with
        passphraseless private keys, see the `sshd(8)`_ manpage for
        information on securing the keypair from the remote side in the
        ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    Changed in version 2015.8.7

        Salt will no longer attempt to use passphrase-protected keys unless
        invoked from the minion using ``salt-call``, to prevent blocking
        waiting for user input.

    Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file

    Changed in version 2016.3.0

https_user
    Set HTTP Basic Auth username. Only accepted for HTTPS URLs.

https_pass
    Set HTTP Basic Auth password. Only accepted for HTTPS URLs.

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

saltenv
    The default salt environment to pull sls files from

    New in version 2016.3.1

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Example:

    salt myminion git.remote_refs https://github.com/saltstack/salt.git
    salt myminion git.remote_refs https://github.com/saltstack/salt.git filter=develop

git.remote_set:

cwd
    The path to the git checkout

url
    Remote URL to set

remote : origin
    Name of the remote to set

push_url
    If unset, the push URL will be identical to the fetch URL.

    New in version 2015.8.0

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

https_user
    Set HTTP Basic Auth username. Only accepted for HTTPS URLs.

    New in version 2015.5.0

https_pass
    Set HTTP Basic Auth password. Only accepted for HTTPS URLs.

    New in version 2015.5.0

push_https_user
    Set HTTP Basic Auth user for ``push_url``. Ignored if ``push_url`` is
    unset. Only accepted for HTTPS URLs.

    New in version 2015.8.0

push_https_pass
    Set HTTP Basic Auth password for ``push_url``. Ignored if ``push_url``
    is unset. Only accepted for HTTPS URLs.

    New in version 2015.8.0

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    salt myminion git.remote_set /path/to/repo git@github.com:user/repo.git
    salt myminion git.remote_set /path/to/repo git@github.com:user/repo.git remote=upstream
    salt myminion git.remote_set /path/to/repo https://github.com/user/repo.git remote=upstream push_url=git@github.com:user/repo.git

git.remotes:

Get fetch and push URLs for each remote in a git checkout

cwd
    The path to the git checkout

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

redact_auth : True
    Set to ``False`` to include the username/password for authenticated
    remotes in the return data. Otherwise, this information will be
    redacted.

    Warning:
        Setting this to ``False`` will not only reveal any HTTPS Basic Auth
        that is configured, but the return data will also be written to the
        job cache. When possible, it is recommended to use SSH for
        authentication.

    New in version 2015.5.6

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Example:

    salt myminion git.remotes /path/to/repo

git.reset:

Interface to `git-reset(1)`_, returns the stdout from the git command

cwd
    The path to the git checkout

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``reset``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs. Salt will not attempt to use
    passphrase-protected keys unless invoked from the minion using
    ``salt-call``, to prevent blocking waiting for user input. Key can also
    be specified as a SaltStack file server URL, eg.
    ``salt://location/identity_file``.

    Note:
        For greater security with passphraseless private keys, see the
        `sshd(8)`_ manpage for information on securing the keypair from the
        remote side in the ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    New in version 2018.3.5,2019.2.1,3000

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-reset(1)`: http://git-scm.com/docs/git-reset

CLI Examples:

    # Soft reset to a specific commit ID
    salt myminion git.reset /path/to/repo ac3ee5c
    # Hard reset
    salt myminion git.reset /path/to/repo opts='--hard origin/master'

git.rev_parse:

New in version 2015.8.0

Interface to `git-rev-parse(1)`_

cwd
    The path to the git checkout

rev
    Revision to parse. See the `SPECIFYING REVISIONS`_ section of the
    `git-rev-parse(1)`_ manpage for details on how to format this argument.

    This argument is optional when using the options in the `Options for
    Files` section of the `git-rev-parse(1)`_ manpage.

opts
    Any additional options to add to the command line, in a single string

git_opts
    Any additional options to add to git command itself (not the
    ``rev-parse`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-rev-parse(1)`: http://git-scm.com/docs/git-rev-parse
.. _`SPECIFYING REVISIONS`: http://git-scm.com/docs/git-rev-parse#_specifying_revisions
.. _`Options for Files`: http://git-scm.com/docs/git-rev-parse#_options_for_files

CLI Examples:

    # Get the full SHA1 for HEAD
    salt myminion git.rev_parse /path/to/repo HEAD
    # Get the short SHA1 for HEAD
    salt myminion git.rev_parse /path/to/repo HEAD opts='--short'
    # Get the develop branch's upstream tracking branch
    salt myminion git.rev_parse /path/to/repo 'develop@{upstream}' opts='--abbrev-ref'
    # Get the SHA1 for the commit corresponding to tag v1.2.3
    salt myminion git.rev_parse /path/to/repo 'v1.2.3^{commit}'
    # Find out whether or not the repo at /path/to/repo is a bare repository
    salt myminion git.rev_parse /path/to/repo opts='--is-bare-repository'

git.revision:

Returns the SHA1 hash of a given identifier (hash, branch, tag, HEAD, etc.)

cwd
    The path to the git checkout

rev : HEAD
    The revision

short : False
    If ``True``, return an abbreviated SHA1 git hash

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Example:

    salt myminion git.revision /path/to/repo mybranch

git.rm:

Interface to `git-rm(1)`_

cwd
    The path to the git checkout

filename
    The location of the file/directory to remove, relative to ``cwd``

    Note:
        To remove a directory, ``-r`` must be part of the ``opts``
        parameter.

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the ``rm``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-rm(1)`: http://git-scm.com/docs/git-rm

CLI Examples:

    salt myminion git.rm /path/to/repo foo/bar.py
    salt myminion git.rm /path/to/repo foo/bar.py opts='--dry-run'
    salt myminion git.rm /path/to/repo foo/baz opts='-r'

git.stash:

Interface to `git-stash(1)`_, returns the stdout from the git command

cwd
    The path to the git checkout

opts
    Any additional options to add to the command line, in a single string.
    Use this to complete the ``git stash`` command by adding the remaining
    arguments (i.e.  ``'save <stash comment>'``, ``'apply stash@{2}'``,
    ``'show'``, etc.).  Omitting this argument will simply run ``git
    stash``.

git_opts
    Any additional options to add to git command itself (not the ``stash``
    subcommand), in a single string. This is useful for passing ``-c`` to
    run git with temporary changes to the git configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-stash(1)`: http://git-scm.com/docs/git-stash

CLI Examples:

    salt myminion git.stash /path/to/repo save opts='work in progress'
    salt myminion git.stash /path/to/repo apply opts='stash@{1}'
    salt myminion git.stash /path/to/repo drop opts='stash@{1}'
    salt myminion git.stash /path/to/repo list

git.status:

Changed in version 2015.8.0
    Return data has changed from a list of lists to a dictionary

Returns the changes to the repository

cwd
    The path to the git checkout

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Example:

    salt myminion git.status /path/to/repo

git.submodule:

Changed in version 2015.8.0
    Added the ``command`` argument to allow for operations other than
    ``update`` to be run on submodules, and deprecated the ``init``
    argument. To do a submodule update with ``init=True`` moving forward,
    use ``command=update opts='--init'``

Interface to `git-submodule(1)`_

cwd
    The path to the submodule

command
    Submodule command to run, see `git-submodule(1) <git submodule>` for
    more information. Any additional arguments after the command (such as
    the URL when adding a submodule) must be passed in the ``opts``
    parameter.

    New in version 2015.8.0

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` (as in the CLI examples
        below) to avoid causing errors with Salt's own argument parsing.

git_opts
    Any additional options to add to git command itself (not the
    ``submodule`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

init : False
    If ``True``, ensures that new submodules are initialized

    .. deprecated:: 2015.8.0
        Pass ``init`` as the ``command`` parameter, or include ``--init``
        in the ``opts`` param with ``command`` set to update.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

identity
    Path to a private key to use for ssh URLs

    Warning:

        Unless Salt is invoked from the minion using ``salt-call``, the
        key(s) must be passphraseless. For greater security with
        passphraseless private keys, see the `sshd(8)`_ manpage for
        information on securing the keypair from the remote side in the
        ``authorized_keys`` file.

        .. _`sshd(8)`: http://www.man7.org/linux/man-pages/man8/sshd.8.html#AUTHORIZED_KEYS_FILE_FORMAT

    Changed in version 2015.8.7

        Salt will no longer attempt to use passphrase-protected keys unless
        invoked from the minion using ``salt-call``, to prevent blocking
        waiting for user input.

    Key can also be specified as a SaltStack file server URL, eg. salt://location/identity_file

    Changed in version 2016.3.0

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

saltenv
    The default salt environment to pull sls files from

    New in version 2016.3.1

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-submodule(1)`: http://git-scm.com/docs/git-submodule

CLI Example:

    # Update submodule and ensure it is initialized (before 2015.8.0)
    salt myminion git.submodule /path/to/repo/sub/repo init=True
    # Update submodule and ensure it is initialized (2015.8.0 and later)
    salt myminion git.submodule /path/to/repo/sub/repo update opts='--init'

    # Rebase submodule (2015.8.0 and later)
    salt myminion git.submodule /path/to/repo/sub/repo update opts='--rebase'

    # Add submodule (2015.8.0 and later)
    salt myminion git.submodule /path/to/repo/sub/repo add opts='https://mydomain.tld/repo.git'

    # Unregister submodule (2015.8.0 and later)
    salt myminion git.submodule /path/to/repo/sub/repo deinit

git.symbolic_ref:

New in version 2015.8.0

Interface to `git-symbolic-ref(1)`_

cwd
    The path to the git checkout

ref
    Symbolic ref to read/modify

value
    If passed, then the symbolic ref will be set to this value and an empty
    string will be returned.

    If not passed, then the ref to which ``ref`` points will be returned,
    unless ``--delete`` is included in ``opts`` (in which case the symbolic
    ref will be deleted).

opts
    Any additional options to add to the command line, in a single string

git_opts
    Any additional options to add to git command itself (not the
    ``symbolic-refs`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-symbolic-ref(1)`: http://git-scm.com/docs/git-symbolic-ref

CLI Examples:

    # Get ref to which HEAD is pointing
    salt myminion git.symbolic_ref /path/to/repo HEAD
    # Set/overwrite symbolic ref 'FOO' to local branch 'foo'
    salt myminion git.symbolic_ref /path/to/repo FOO refs/heads/foo
    # Delete symbolic ref 'FOO'
    salt myminion git.symbolic_ref /path/to/repo FOO opts='--delete'

git.tag:

New in version 2018.3.4

Interface to `git-tag(1)`_, adds and removes tags.

cwd
    The path to the main git checkout or a linked worktree

name
    Name of the tag

ref : HEAD
    Which ref to tag (defaults to local clone's HEAD)

    Note:
        This argument is ignored when either ``-d`` or ``--delete`` is
        present in the ``opts`` passed to this function.

message
    Optional message to include with the tag. If provided, an annotated tag
    will be created.

opts
    Any additional options to add to the command line, in a single string

    Note:
        Additionally, on the Salt CLI, if the opts are preceded with a
        dash, it is necessary to precede them with ``opts=`` (as in the CLI
        examples below) to avoid causing errors with Salt's own argument
        parsing.

git_opts
    Any additional options to add to git command itself (not the
    ``worktree`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

.. _`git-tag(1)`: http://git-scm.com/docs/git-tag

CLI Example:

    # Create an non-annotated tag
    salt myminion git.tag /path/to/repo v1.2
    # Create an annotated tag
    salt myminion git.tag /path/to/repo v1.2 message='Version 1.2'
    # Delete the tag
    salt myminion git.tag /path/to/repo v1.2 opts='-d'

git.version:

New in version 2015.8.0

Returns the version of Git installed on the minion

versioninfo : False
    If ``True``, return the version in a versioninfo list (e.g. ``[2, 5, 0]``)

CLI Example:

    salt myminion git.version

git.worktree_add:

New in version 2015.8.0

Interface to `git-worktree(1)`_, adds a worktree

cwd
    The path to the git checkout

worktree_path
    Path to the new worktree. Can be either absolute, or relative to
    ``cwd``.

branch
    Name of new branch to create. If omitted, will be set to the basename
    of the ``worktree_path``. For example, if the ``worktree_path`` is
    ``/foo/bar/baz``, then ``branch`` will be ``baz``.

ref
    Name of the ref on which to base the new worktree. If omitted, then
    ``HEAD`` is use, and a new branch will be created, named for the
    basename of the ``worktree_path``. For example, if the
    ``worktree_path`` is ``/foo/bar/baz`` then a new branch ``baz`` will be
    created, and pointed at ``HEAD``.

reset_branch : False
    If ``False``, then `git-worktree(1)`_ will fail to create the worktree
    if the targeted branch already exists. Set this argument to ``True`` to
    reset the targeted branch to point at ``ref``, and checkout the
    newly-reset branch into the new worktree.

force : False
    By default, `git-worktree(1)`_ will not permit the same branch to be
    checked out in more than one worktree. Set this argument to ``True`` to
    override this.

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` to avoid causing errors
        with Salt's own argument parsing.

        All CLI options for adding worktrees as of Git 2.5.0 are already
        supported by this function as of Salt 2015.8.0, so using this
        argument is unnecessary unless new CLI arguments are added to
        `git-worktree(1)`_ and are not yet supported in Salt.

git_opts
    Any additional options to add to git command itself (not the
    ``worktree`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-worktree(1)`: http://git-scm.com/docs/git-worktree

CLI Examples:

    salt myminion git.worktree_add /path/to/repo/main ../hotfix ref=origin/master
    salt myminion git.worktree_add /path/to/repo/main ../hotfix branch=hotfix21 ref=v2.1.9.3

git.worktree_prune:

New in version 2015.8.0

Interface to `git-worktree(1)`_, prunes stale worktree administrative data
from the gitdir

cwd
    The path to the main git checkout or a linked worktree

dry_run : False
    If ``True``, then this function will report what would have been
    pruned, but no changes will be made.

verbose : True
    Report all changes made. Set to ``False`` to suppress this output.

expire
    Only prune unused worktree data older than a specific period of time.
    The date format for this parameter is described in the documentation
    for the ``gc.pruneWorktreesExpire`` config param in the
    `git-config(1)`_ manpage.

opts
    Any additional options to add to the command line, in a single string

    Note:
        On the Salt CLI, if the opts are preceded with a dash, it is
        necessary to precede them with ``opts=`` to avoid causing errors
        with Salt's own argument parsing.

        All CLI options for pruning worktrees as of Git 2.5.0 are already
        supported by this function as of Salt 2015.8.0, so using this
        argument is unnecessary unless new CLI arguments are added to
        `git-worktree(1)`_ and are not yet supported in Salt.

git_opts
    Any additional options to add to git command itself (not the
    ``worktree`` subcommand), in a single string. This is useful for
    passing ``-c`` to run git with temporary changes to the git
    configuration.

    New in version 2017.7.0

    Note:
        This is only supported in git 1.7.2 and newer.

user
    User under which to run the git command. By default, the command is run
    by the user under which the minion is running.

password
    Windows only. Required when specifying ``user``. This parameter will be
    ignored on non-Windows platforms.

  New in version 2016.3.4

ignore_retcode : False
    If ``True``, do not log an error to the minion log if the git command
    returns a nonzero exit status.

    New in version 2015.8.0

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

.. _`git-worktree(1)`: http://git-scm.com/docs/git-worktree
.. _`git-config(1)`: http://git-scm.com/docs/git-config/2.5.1

CLI Examples:

    salt myminion git.worktree_prune /path/to/repo
    salt myminion git.worktree_prune /path/to/repo dry_run=True
    salt myminion git.worktree_prune /path/to/repo expire=1.day.ago

git.worktree_rm:

New in version 2015.8.0

Recursively removes the worktree located at ``cwd``, returning ``True`` if
successful. This function will attempt to determine if ``cwd`` is actually
a worktree by invoking :py:func:`git.is_worktree
<salt.modules.git.is_worktree>`. If the path does not correspond to a
worktree, then an error will be raised and no action will be taken.

Warning:

    There is no undoing this action. Be **VERY** careful before running
    this function.

cwd
    Path to the worktree to be removed

user
    Used for path expansion when ``cwd`` is not an absolute path. By
    default, when ``cwd`` is not absolute, the path will be assumed to be
    relative to the home directory of the user under which the minion is
    running. Setting this option will change the home directory from which
    path expansion is performed.

output_encoding
    Use this option to specify which encoding to use to decode the output
    from any git commands which are run. This should not be needed in most
    cases.

    Note:
        This should only be needed if the files in the repository were
        created with filenames using an encoding other than UTF-8 to handle
        Unicode characters.

    New in version 2018.3.1

CLI Examples:

    salt myminion git.worktree_rm /path/to/worktree

glassfish.create_admin_object_resource:

Create a JMS destination

glassfish.create_connector_c_pool:

Create a connection pool

glassfish.create_connector_resource:

Create a connection resource

glassfish.create_jdbc_connection_pool:

Create a connection resource

glassfish.create_jdbc_resource:

Create a JDBC resource

glassfish.delete_admin_object_resource:

Delete a JMS destination

glassfish.delete_connector_c_pool:

Delete a connection pool

glassfish.delete_connector_resource:

Delete a connection resource

glassfish.delete_jdbc_connection_pool:

Delete a JDBC pool

glassfish.delete_jdbc_resource:

Delete a JDBC resource

glassfish.delete_system_properties:

Delete a system property

glassfish.enum_admin_object_resource:

Enum JMS destinations

glassfish.enum_connector_c_pool:

Enum connection pools

glassfish.enum_connector_resource:

Enum connection resources

glassfish.enum_jdbc_connection_pool:

Enum JDBC pools

glassfish.enum_jdbc_resource:

Enum JDBC resources

glassfish.get_admin_object_resource:

Get a specific JMS destination

glassfish.get_connector_c_pool:

Get a specific connection pool

glassfish.get_connector_resource:

Get a specific connection resource

glassfish.get_jdbc_connection_pool:

Get a specific JDBC pool

glassfish.get_jdbc_resource:

Get a specific JDBC resource

glassfish.get_system_properties:

Get system properties

glassfish.update_admin_object_resource:

Update a JMS destination

glassfish.update_connector_c_pool:

Update a connection pool

glassfish.update_connector_resource:

Update a connection resource

glassfish.update_jdbc_connection_pool:

Update a JDBC pool

glassfish.update_jdbc_resource:

Update a JDBC resource

glassfish.update_system_properties:

Update system properties

google_chat.send_message:

Send a message to the google chat room specified in the webhook url.

    salt '*' google_chat.send_message "https://chat.googleapis.com/v1/spaces/example_space/messages?key=example_key" "This is a test message"

gpg.create_key:

Create a key in the GPG keychain

Note:

    GPG key generation requires *a lot* of entropy and randomness.
    Difficult to do over a remote connection, consider having
    another process available which is generating randomness for
    the machine. Also especially difficult on virtual machines,
    consider the `rng-tools
    <http://www.gnu.org/software/hurd/user/tlecarrour/rng-tools.html>`_
    package.

    The create_key process takes awhile so increasing the timeout
    may be necessary, e.g. -t 15.

key_type
    The type of the primary key to generate. It must be capable of signing.
    'RSA' or 'DSA'.

key_length
    The length of the primary key in bits.

name_real
    The real name of the user identity which is represented by the key.

name_comment
    A comment to attach to the user id.

name_email
    An email address for the user.

subkey_type
    The type of the secondary key to generate.

subkey_length
    The length of the secondary key in bits.

expire_date
    The expiration date for the primary and any secondary key.
    You can specify an ISO date, A number of days/weeks/months/years,
    an epoch value, or 0 for a non-expiring key.

use_passphrase
    Whether to use a passphrase with the signing key. The passphrase is
    retrieved from the Pillar key ``gpg_passphrase``.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt -t 15 '*' gpg.create_key

gpg.decrypt:

Decrypt a message or a file

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

text
    The encrypted text to decrypt.

filename
    The path of the encrypted file to decrypt.

output
    Instead of printing to standard out, write the output to this path.

use_passphrase
    Whether to use a passphrase with the signing key. The passphrase is retrieved
    from Pillar value ``gpg_passphrase``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

bare
    If ``True``, return the (armored) decrypted block as a string without the
    standard comment/res dict.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.decrypt filename='/path/to/important.file.gpg'

    salt '*' gpg.decrypt filename='/path/to/important.file.gpg' use_passphrase=True

gpg.delete_key:

Delete a key from the GPG keychain.

keyid
    The keyid of the key to be deleted.

fingerprint
    The fingerprint of the key to be deleted.

delete_secret
    Whether to delete a corresponding secret key prior to deleting the public key.
    Secret keys must be deleted before deleting any corresponding public keys.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

use_passphrase
    Whether to use a passphrase with the signing key. The passphrase is retrieved
    from the Pillar key ``gpg_passphrase``. Note that this defaults to True here,
    contrary to the rest of the module functions that provide this parameter.

    New in version 3003

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.delete_key keyid=3FAD9F1E

    salt '*' gpg.delete_key fingerprint=53C96788253E58416D20BCD352952C84C3252192

    salt '*' gpg.delete_key keyid=3FAD9F1E user=username

    salt '*' gpg.delete_key keyid=3FAD9F1E user=username delete_secret=True

gpg.encrypt:

Encrypt a message or a file

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

recipients
    The key ID, fingerprint, user ID or email address associated with the recipients
    key can be used.

text
    The text to encrypt.

filename
    The path of the file to encrypt.

output
    Instead of printing to standard out, write the output to this path.

sign
    Whether to sign, in addition to encrypt, the data. ``True`` to use
    default key or fingerprint to specify a different key to sign with.

use_passphrase
    Whether to use a passphrase with the signing key.
    The passphrase is retrieved from the Pillar key ``gpg_passphrase``.

always_trust
    Skip key validation and assume that used keys are fully trusted.

    New in version 3006.0

gnupghome
    Specify the location where the GPG keyring and related files are stored.

bare
    If ``True``, return the (armored) encrypted block as a string without
    the standard comment/res dict.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.encrypt text='Hello there.  How are you?' recipients=recipient@example.com

    salt '*' gpg.encrypt filename='/path/to/important.file' recipients=recipient@example.com

    salt '*' gpg.encrypt filename='/path/to/important.file' sign=True use_passphrase=True \
                         recipients=recipient@example.com

gpg.export_key:

Export a key from the GPG keychain

keyids
    The key ID(s) of the key(s) to be exported. Can be specified as a comma
    separated string or a list. Anything which GnuPG itself accepts to identify a key
    for example, the key ID, fingerprint, user ID or email address could be used.

secret
    Export the secret key identified by the ``keyids`` information passed.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

use_passphrase
    Whether to use a passphrase to export the secret key.
    The passphrase is retrieved from the Pillar key ``gpg_passphrase``.

    New in version 3003

output
    Instead of printing to standard out, write the output to this path.

    New in version 3006.0

bare
    If ``True``, return the (armored) exported key block as a string without the
    standard comment/res dict.

    New in version 3006.0

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.export_key keyids=3FAD9F1E

    salt '*' gpg.export_key keyids=3FAD9F1E secret=True

    salt '*' gpg.export_key keyids="['3FAD9F1E','3FBD8F1E']" user=username

gpg.get_key:

Get a key from the GPG keychain

keyid
    The key ID (short or long) of the key to be retrieved.

fingerprint
    The fingerprint of the key to be retrieved.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.get_key keyid=3FAD9F1E

    salt '*' gpg.get_key fingerprint=53C96788253E58416D20BCD352952C84C3252192

    salt '*' gpg.get_key keyid=3FAD9F1E user=username

gpg.get_secret_key:

Get a secret key from the GPG keychain

keyid
    The key ID (short or long) of the key to be retrieved.

fingerprint
    The fingerprint of the key to be retrieved.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.get_secret_key keyid=3FAD9F1E

    salt '*' gpg.get_secret_key fingerprint=53C96788253E58416D20BCD352952C84C3252192

    salt '*' gpg.get_secret_key keyid=3FAD9F1E user=username

gpg.import_key:

Import a key from text or a file

text
    The text containing the key to import.

filename
    The path of the file containing the key to import.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.import_key text='-----BEGIN PGP PUBLIC KEY BLOCK-----\n ... -----END PGP PUBLIC KEY BLOCK-----'
    salt '*' gpg.import_key filename='/path/to/public-key-file'

gpg.list_keys:

List keys in GPG keychain

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.list_keys

gpg.list_secret_keys:

List secret keys in GPG keychain

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.list_secret_keys

gpg.receive_keys:

Receive key(s) from keyserver and add them to the keychain

keyserver
    Keyserver to use for searching for GPG keys, defaults to keys.openpgp.org

keys
    The keyID(s) to retrieve from the keyserver. Can be specified as a comma
    separated string or a list.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.receive_keys keys='3FAD9F1E'

    salt '*' gpg.receive_keys keys="['3FAD9F1E','3FBD9F2E']"

    salt '*' gpg.receive_keys keys=3FAD9F1E user=username

gpg.search_keys:

Search for keys on a keyserver

text
    Text to search the keyserver for, e.g. email address, keyID or fingerprint.

keyserver
    Keyserver to use for searching for GPG keys, defaults to keys.openpgp.org.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

    New in version 3007.0

CLI Example:

    salt '*' gpg.search_keys user@example.com

    salt '*' gpg.search_keys user@example.com keyserver=keyserver.ubuntu.com

    salt '*' gpg.search_keys user@example.com keyserver=keyserver.ubuntu.com user=username

gpg.sign:

Sign a message or a file

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

keyid
    The keyid of the key to use for signing, defaults to the
    first key in the secret keyring.

text
    The text to sign.

filename
    The path of the file to sign.

output
    Instead of printing to standard out, write the output to this path.

use_passphrase
    Whether to use a passphrase with the signing key. The passphrase is
    retrieved from the Pillar key ``gpg_passphrase``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.sign text='Hello there.  How are you?'

    salt '*' gpg.sign filename='/path/to/important.file'

    salt '*' gpg.sign filename='/path/to/important.file' use_passphrase=True

gpg.trust_key:

Set the trust level for a key in the GPG keychain

keyid
    The keyid of the key to set the trust level for.

fingerprint
    The fingerprint of the key to set the trust level for.

trust_level
    The trust level to set for the specified key, must be one
    of the following:
    expired, unknown, not_trusted, marginally, fully, ultimately

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

    New in version 3007.0

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.trust_key keyid='3FAD9F1E' trust_level='marginally'
    salt '*' gpg.trust_key fingerprint='53C96788253E58416D20BCD352952C84C3252192' trust_level='not_trusted'
    salt '*' gpg.trust_key keys=3FAD9F1E trust_level='ultimately' user='username'

gpg.verify:

Verify a message or a file

text
    The text to verify.

filename
    The path of the file to verify.

user
    Which user's keychain to access, defaults to user Salt is running as.
    Passing the user as ``salt`` will set the GnuPG home directory to
    ``/etc/salt/gpgkeys``.

gnupghome
    Specify the location where the GPG keyring and related files are stored.

signature
    Specify the path of a detached signature.

    New in version 2018.3.0

trustmodel
    Explicitly define the used trust model. One of:
      - pgp
      - classic
      - tofu
      - tofu+pgp
      - direct
      - always
      - auto

    New in version 2019.2.0

signed_by_any
    A list of key fingerprints from which any valid signature
    will mark verification as passed. If none of the provided
    keys signed the data, verification will fail. Optional.
    Note that this does not take into account trust.

    New in version 3007.0

signed_by_all
    A list of key fingerprints whose signatures are required
    for verification to pass. If a single provided key did
    not sign the data, verification will fail. Optional.
    Note that this does not take into account trust.

    New in version 3007.0

keyring
    Limit the operation to this specific keyring, specified as
    a local filesystem path.

    New in version 3007.0

CLI Example:

    salt '*' gpg.verify text='Hello there.  How are you?'
    salt '*' gpg.verify filename='/path/to/important.file'
    salt '*' gpg.verify filename='/path/to/important.file' trustmodel=direct

grafana4.create_datasource:

Create a new datasource in an organisation.

name
    Name of the data source.

type
    Type of the datasource ('graphite', 'influxdb' etc.).

access
    Use proxy or direct.

url
    The URL to the data source API.

user
    Optional - user to authenticate with the data source.

password
    Optional - password to authenticate with the data source.

database
    Optional - database to use with the data source.

basicAuth
    Optional - set to True to use HTTP basic auth to authenticate with the
    data source.

basicAuthUser
    Optional - HTTP basic auth username.

basicAuthPassword
    Optional - HTTP basic auth password.

jsonData
    Optional - additional json data to post (eg. "timeInterval").

isDefault
    Optional - set data source as default.

withCredentials
    Optional - Whether credentials such as cookies or auth headers should
    be sent with cross-site requests.

typeLogoUrl
    Optional - Logo to use for this datasource.

orgname
    Name of the organization in which the data source should be created.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.create_datasource

grafana4.create_org:

Create a new organization.

name
    Name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.create_org <name>

grafana4.create_org_user:

Add user to the organization.

loginOrEmail
    Login or email of the user.

role
    Role of the user for this organization. Should be one of:
        - Admin
        - Editor
        - Read Only Editor
        - Viewer

orgname
    Name of the organization in which users are added.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.create_org_user <orgname> loginOrEmail=<loginOrEmail> role=<role>

grafana4.create_update_dashboard:

Create or update a dashboard.

dashboard
    A dict that defines the dashboard to create/update.

overwrite
    Whether the dashboard should be overwritten if already existing.

orgname
    Name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.create_update_dashboard dashboard=<dashboard> overwrite=True orgname=<orgname>

grafana4.create_user:

Create a new user.

login
    Login of the new user.

password
    Password of the new user.

email
    Email of the new user.

name
    Optional - Full name of the new user.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.create_user login=<login> password=<password> email=<email>

grafana4.delete_dashboard:

Delete a dashboard.

slug
    Slug (name) of the dashboard.

orgname
    Name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.delete_dashboard <slug>

grafana4.delete_datasource:

Delete a datasource.

datasourceid
    Id of the datasource.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.delete_datasource <datasource_id>

grafana4.delete_org:

Delete an organization.

orgid
    Id of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.delete_org <org_id>

grafana4.delete_org_user:

Remove user from the organization.

userid
    Id of the user.

orgname
    Name of the organization in which users are updated.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.delete_org_user <user_id> <orgname>

grafana4.delete_user:

Delete a user.

userid
    Id of the user.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.delete_user <user_id>

grafana4.delete_user_org:

Remove a user from an organization.

userid
    Id of the user.

orgid
    Id of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.delete_user_org <user_id> <org_id>

grafana4.get_dashboard:

Get a dashboard.

slug
    Slug (name) of the dashboard.

orgname
    Name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_dashboard <slug>

grafana4.get_datasource:

Show a single datasource in an organisation.

name
    Name of the datasource.

orgname
    Name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_datasource <name> <orgname>

grafana4.get_datasources:

List all datasources in an organisation.

orgname
    Name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_datasources <orgname>

grafana4.get_org:

Show a single organization.

name
    Name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_org <name>

grafana4.get_org_address:

Get the organization address.

orgname
    Name of the organization in which users are updated.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_org_address <orgname>

grafana4.get_org_prefs:

Get the organization preferences.

orgname
    Name of the organization in which users are updated.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_org_prefs <orgname>

grafana4.get_org_users:

Get the list of users that belong to the organization.

orgname
    Name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_org_users <orgname>

grafana4.get_orgs:

List all organizations.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_orgs

grafana4.get_user:

Show a single user.

login
    Login of the user.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_user <login>

grafana4.get_user_data:

Get user data.

userid
    Id of the user.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_user_data <user_id>

grafana4.get_user_orgs:

Get the list of organisations a user belong to.

userid
    Id of the user.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_user_orgs <user_id>

grafana4.get_users:

List all users.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.get_users

grafana4.switch_org:

Switch the current organization.

name
    Name of the organization to switch to.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.switch_org <name>

grafana4.update_datasource:

Update a datasource.

datasourceid
    Id of the datasource.

name
    Name of the data source.

type
    Type of the datasource ('graphite', 'influxdb' etc.).

access
    Use proxy or direct.

url
    The URL to the data source API.

user
    Optional - user to authenticate with the data source.

password
    Optional - password to authenticate with the data source.

database
    Optional - database to use with the data source.

basicAuth
    Optional - set to True to use HTTP basic auth to authenticate with the
    data source.

basicAuthUser
    Optional - HTTP basic auth username.

basicAuthPassword
    Optional - HTTP basic auth password.

jsonData
    Optional - additional json data to post (eg. "timeInterval").

isDefault
    Optional - set data source as default.

withCredentials
    Optional - Whether credentials such as cookies or auth headers should
    be sent with cross-site requests.

typeLogoUrl
    Optional - Logo to use for this datasource.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.update_datasource <datasourceid>

grafana4.update_org:

Update an existing organization.

orgid
    Id of the organization.

name
    New name of the organization.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.update_org <org_id> name=<name>

grafana4.update_org_address:

Update the organization address.

orgname
    Name of the organization in which users are updated.

address1
    Optional - address1 of the org.

address2
    Optional - address2 of the org.

city
    Optional - city of the org.

zip_code
    Optional - zip_code of the org.

state
    Optional - state of the org.

country
    Optional - country of the org.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.update_org_address <orgname> country=<country>

grafana4.update_org_prefs:

Update the organization preferences.

orgname
    Name of the organization in which users are updated.

theme
    Selected theme for the org.

homeDashboardId
    Home dashboard for the org.

timezone
    Timezone for the org (one of: "browser", "utc", or "").

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.update_org_prefs <orgname> theme=<theme> timezone=<timezone>

grafana4.update_org_user:

Update user role in the organization.

userid
    Id of the user.

loginOrEmail
    Login or email of the user.

role
    Role of the user for this organization. Should be one of:
        - Admin
        - Editor
        - Read Only Editor
        - Viewer

orgname
    Name of the organization in which users are updated.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.update_org_user <user_id> <orgname> loginOrEmail=<loginOrEmail> role=<role>

grafana4.update_user:

Update an existing user.

userid
    Id of the user.

login
    Optional - Login of the user.

email
    Optional - Email of the user.

name
    Optional - Full name of the user.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.update_user <user_id> login=<login> email=<email>

grafana4.update_user_password:

Update a user password.

userid
    Id of the user.

password
    New password of the user.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.update_user_password <user_id> password=<password>

grafana4.update_user_permissions:

Update a user password.

userid
    Id of the user.

isGrafanaAdmin
    Whether user is a Grafana admin.

profile
    Configuration profile used to connect to the Grafana instance.
    Default is 'grafana'.

CLI Example:

    salt '*' grafana4.update_user_permissions <user_id> isGrafanaAdmin=<true|false>

grains.append:

New in version 0.17.0

Append a value to a list in the grains config file. If the grain doesn't
exist, the grain key is added and the value is appended to the new grain
as a list item.

key
    The grain key to be appended to

val
    The value to append to the grain key

convert
    If convert is True, convert non-list contents into a list.
    If convert is False and the grain contains non-list contents, an error
    is given. Defaults to False.

delimiter
    The key can be a nested dict key. Use this parameter to
    specify the delimiter you use, instead of the default ``:``.
    You can now append values to a list in nested dictionary grains. If the
    list doesn't exist at this level, it will be created.

    New in version 2014.7.6

CLI Example:

    salt '*' grains.append key val

grains.delkey:

New in version 2017.7.0

Remove a grain completely from the grain system, this will remove the
grain key and value

key
    The grain key from which to delete the value.

force
    Force remove the grain even when it is a mapped value.
    Defaults to False

CLI Example:

    salt '*' grains.delkey key

grains.delval:

New in version 0.17.0

Delete a grain value from the grains config file. This will just set the
grain value to ``None``. To completely remove the grain, run ``grains.delkey``
or pass ``destructive=True`` to ``grains.delval``.

key
    The grain key from which to delete the value.

destructive
    Delete the key, too. Defaults to False.

force
    Force remove the grain even when it is a mapped value.
    Defaults to False

CLI Example:

    salt '*' grains.delval key

grains.equals:

Used to make sure the minion's grain key/value matches.

Returns ``True`` if matches otherwise ``False``.

New in version 2017.7.0

CLI Example:

    salt '*' grains.equals fqdn <expected_fqdn>
    salt '*' grains.equals systemd:version 219

grains.fetch:

Attempt to retrieve the named value from grains, if the named value is not
available return the passed default. The default return is an empty string.

The value can also represent a value in a nested dict using a ":" delimiter
for the dict. This means that if a dict in grains looks like this::

    {'pkg': {'apache': 'httpd'}}

To retrieve the value associated with the apache key in the pkg dict this
key can be passed::

    pkg:apache


:param delimiter:
    Specify an alternate delimiter to use when traversing a nested dict.
    This is useful for when the desired key contains a colon. See CLI
    example below for usage.

    New in version 2014.7.0

:param ordered:
    Outputs an ordered dict if applicable (default: True)

    New in version 2016.11.0

CLI Example:

    salt '*' grains.get pkg:apache
    salt '*' grains.get abc::def|ghi delimiter='|'

grains.filter_by:

New in version 0.17.0

Look up the given grain in a given dictionary for the current OS and return
the result

Although this may occasionally be useful at the CLI, the primary intent of
this function is for use in Jinja to make short work of creating lookup
tables for OS-specific data. For example:

    {% set apache = salt['grains.filter_by']({
        'Debian': {'pkg': 'apache2', 'srv': 'apache2'},
        'RedHat': {'pkg': 'httpd', 'srv': 'httpd'},
    }, default='Debian') %}

    myapache:
      pkg.installed:
        - name: {{ apache.pkg }}
      service.running:
        - name: {{ apache.srv }}

Values in the lookup table may be overridden by values in Pillar. An
example Pillar to override values in the example above could be as follows:

    apache:
      lookup:
        pkg: apache_13
        srv: apache

The call to ``filter_by()`` would be modified as follows to reference those
Pillar values:

    {% set apache = salt['grains.filter_by']({
        ...
    }, merge=salt['pillar.get']('apache:lookup')) %}


:param lookup_dict: A dictionary, keyed by a grain, containing a value or
    values relevant to systems matching that grain. For example, a key
    could be the grain for an OS and the value could the name of a package
    on that particular OS.

    Changed in version 2016.11.0

        The dictionary key could be a globbing pattern. The function will
        return the corresponding ``lookup_dict`` value where grain value
        matches the pattern. For example:

            # this will render 'got some salt' if Minion ID begins from 'salt'
            salt '*' grains.filter_by '{salt*: got some salt, default: salt is not here}' id

:param grain: The name of a grain to match with the current system's
    grains. For example, the value of the "os_family" grain for the current
    system could be used to pull values from the ``lookup_dict``
    dictionary.

    Changed in version 2016.11.0

        The grain value could be a list. The function will return the
        ``lookup_dict`` value for a first found item in the list matching
        one of the ``lookup_dict`` keys.

:param merge: A dictionary to merge with the results of the grain selection
    from ``lookup_dict``. This allows Pillar to override the values in the
    ``lookup_dict``. This could be useful, for example, to override the
    values for non-standard package names such as when using a different
    Python version from the default Python version provided by the OS
    (e.g., ``python26-mysql`` instead of ``python-mysql``).

:param default: default lookup_dict's key used if the grain does not exists
    or if the grain value has no match on lookup_dict.  If unspecified
    the value is "default".

    New in version 2014.1.0

:param base: A lookup_dict key to use for a base dictionary.  The
    grain-selected ``lookup_dict`` is merged over this and then finally
    the ``merge`` dictionary is merged.  This allows common values for
    each case to be collected in the base and overridden by the grain
    selection dictionary and the merge dictionary.  Default is unset.

    New in version 2015.5.0

CLI Example:

    salt '*' grains.filter_by '{Debian: Debheads rule, RedHat: I love my hat}'
    # this one will render {D: {E: I, G: H}, J: K}
    salt '*' grains.filter_by '{A: B, C: {D: {E: F, G: H}}}' 'xxx' '{D: {E: I}, J: K}' 'C'
    # next one renders {A: {B: G}, D: J}
    salt '*' grains.filter_by '{default: {A: {B: C}, D: E}, F: {A: {B: G}}, H: {D: I}}' 'xxx' '{D: J}' 'F' 'default'
    # next same as above when default='H' instead of 'F' renders {A: {B: C}, D: J}

grains.get:

Attempt to retrieve the named value from grains, if the named value is not
available return the passed default. The default return is an empty string.

The value can also represent a value in a nested dict using a ":" delimiter
for the dict. This means that if a dict in grains looks like this::

    {'pkg': {'apache': 'httpd'}}

To retrieve the value associated with the apache key in the pkg dict this
key can be passed::

    pkg:apache


:param delimiter:
    Specify an alternate delimiter to use when traversing a nested dict.
    This is useful for when the desired key contains a colon. See CLI
    example below for usage.

    New in version 2014.7.0

:param ordered:
    Outputs an ordered dict if applicable (default: True)

    New in version 2016.11.0

CLI Example:

    salt '*' grains.get pkg:apache
    salt '*' grains.get abc::def|ghi delimiter='|'

grains.has_value:

Determine whether a key exists in the grains dictionary.

Given a grains dictionary that contains the following structure::

    {'pkg': {'apache': 'httpd'}}

One would determine if the apache key in the pkg dict exists by::

    pkg:apache

CLI Example:

    salt '*' grains.has_value pkg:apache

grains.item:

Return one or more grains

CLI Example:

    salt '*' grains.item os
    salt '*' grains.item os osrelease oscodename

Sanitized CLI Example:

    salt '*' grains.item host sanitize=True

grains.items:

Return all of the minion's grains

CLI Example:

    salt '*' grains.items

Sanitized CLI Example:

    salt '*' grains.items sanitize=True

grains.ls:

Return a list of all available grains

CLI Example:

    salt '*' grains.ls

grains.remove:

New in version 0.17.0

Remove a value from a list in the grains config file

key
    The grain key to remove.

val
    The value to remove.

delimiter
    The key can be a nested dict key. Use this parameter to
    specify the delimiter you use, instead of the default ``:``.
    You can now append values to a list in nested dictionary grains. If the
    list doesn't exist at this level, it will be created.

    New in version 2015.8.2

CLI Example:

    salt '*' grains.remove key val

grains.set:

Set a key to an arbitrary value. It is used like setval but works
with nested keys.

This function is conservative. It will only overwrite an entry if
its value and the given one are not a list or a dict. The ``force``
parameter is used to allow overwriting in all cases.

New in version 2015.8.0

:param force: Force writing over existing entry if given or existing
              values are list or dict. Defaults to False.
:param destructive: If an operation results in a key being removed,
              delete the key, too. Defaults to False.
:param delimiter:
    Specify an alternate delimiter to use when traversing a nested dict,
    the default being ``:``

CLI Example:

    salt '*' grains.set 'apps:myApp:port' 2209
    salt '*' grains.set 'apps:myApp' '{port: 2209}'

grains.setval:

Set a grains value in the grains config file

key
    The grain key to be set.

val
    The value to set the grain key to.

destructive
    If an operation results in a key being removed, delete the key, too.
    Defaults to False.

refresh_pillar
    Whether pillar will be refreshed.
    Defaults to True.

CLI Example:

    salt '*' grains.setval key val
    salt '*' grains.setval key "{'sub-key': 'val', 'sub-key2': 'val2'}"

grains.setvals:

Set new grains values in the grains config file

destructive
    If an operation results in a key being removed, delete the key, too.
    Defaults to False.

refresh_pillar
    Whether pillar will be refreshed.
    Defaults to True.

CLI Example:

    salt '*' grains.setvals "{'key1': 'val1', 'key2': 'val2'}"

group.add:

Changed in version 3006.0

Add the specified group

name
    Name of the new group

gid
    Use GID for the new group

system
    Create a system account

root
    Directory to chroot into

non_unique
    Allow creating groups with duplicate (non-unique) GIDs

    New in version 3006.0

local
    Specifically add the group locally rather than through remote providers (e.g. LDAP)

    New in version 3007.0

CLI Example:

    salt '*' group.add foo 3456

group.adduser:

Add a user in the group.

name
    Name of the group to modify

username
    Username to add to the group

root
    Directory to chroot into

CLI Example:

     salt '*' group.adduser foo bar

Verifies if a valid username 'bar' as a member of an existing group 'foo',
if not then adds it.

group.chgid:

Changed in version 3006.0

Change the gid for a named group

name
    Name of the group to modify

gid
    Change the group ID to GID

root
    Directory to chroot into

non_unique
    Allow modifying groups with duplicate (non-unique) GIDs

    New in version 3006.0

CLI Example:

    salt '*' group.chgid foo 4376

group.delete:

Remove the named group

name
    Name group to delete

root
    Directory to chroot into

local (Only on systems with lgroupdel available):
    Ensure the group account is removed locally ignoring global
    account management (default is False).

    New in version 3007.0

CLI Example:

    salt '*' group.delete foo

group.deluser:

Remove a user from the group.

name
    Name of the group to modify

username
    Username to delete from the group

root
    Directory to chroot into

CLI Example:

     salt '*' group.deluser foo bar

Removes a member user 'bar' from a group 'foo'. If group is not present
then returns True.

group.getent:

Return info on all groups

refresh
    Force a refresh of group information

root
    Directory to chroot into

CLI Example:

    salt '*' group.getent

group.info:

Return information about a group

name
    Name of the group

root
    Directory to chroot into

CLI Example:

    salt '*' group.info foo

group.members:

Replaces members of the group with a provided list.

name
    Name of the group to modify

members_list
    Username list to set into the group

root
    Directory to chroot into

CLI Example:

    salt '*' group.members foo 'user1,user2,user3,...'

Replaces a membership list for a local group 'foo'.
    foo:x:1234:user1,user2,user3,...

hashutil.base64_b64decode:

Decode a base64-encoded string using the "modern" Python interface

New in version 2016.3.0

CLI Example:

    salt '*' hashutil.base64_b64decode 'Z2V0IHNhbHRlZA=='

hashutil.base64_b64encode:

Encode a string as base64 using the "modern" Python interface.

Among other possible differences, the "modern" encoder does not include
newline ('\n') characters in the encoded output.

New in version 2016.3.0

CLI Example:

    salt '*' hashutil.base64_b64encode 'get salted'

hashutil.base64_decodefile:

Decode a base64-encoded string and write the result to a file

New in version 2016.3.0

CLI Example:

    salt '*' hashutil.base64_decodefile instr='Z2V0IHNhbHRlZAo=' outfile='/path/to/binary_file'

hashutil.base64_decodestring:

Decode a base64-encoded byte-like object using the "modern" Python interface

New in version 3000

CLI Example:

    salt '*' hashutil.base64_decodestring instr='Z2V0IHNhbHRlZAo='

hashutil.base64_encodefile:

Read a file from the file system and return as a base64 encoded string

New in version 2016.3.0

Pillar example:

    path:
      to:
        data: |
          {{ salt.hashutil.base64_encodefile('/path/to/binary_file') | indent(6) }}

The :py:func:`file.decode <salt.states.file.decode>` state function can be
used to decode this data and write it to disk.

CLI Example:

    salt '*' hashutil.base64_encodefile /path/to/binary_file

hashutil.base64_encodestring:

Encode a byte-like object as base64 using the "modern" Python interface.

Among other possible differences, the "modern" encoder includes
a newline ('\n') character after every 76 characters and always
at the end of the encoded byte-like object.

New in version 3000

CLI Example:

    salt '*' hashutil.base64_encodestring 'get salted'

hashutil.digest:

Return a checksum digest for a string

instr
    A string
checksum : ``md5``
    The hashing algorithm to use to generate checksums. Valid options: md5,
    sha256, sha512.

CLI Example:

    salt '*' hashutil.digest 'get salted'

hashutil.digest_file:

Return a checksum digest for a file

infile
    A file path
checksum : ``md5``
    The hashing algorithm to use to generate checksums. Wraps the
    :py:func:`hashutil.digest <salt.modules.hashutil.digest>` execution
    function.

CLI Example:

    salt '*' hashutil.digest_file /path/to/file

hashutil.github_signature:

Verify a challenging hmac signature against a string / shared-secret for
github webhooks.

New in version 2017.7.0

Returns a boolean if the verification succeeded or failed.

CLI Example:

    salt '*' hashutil.github_signature '{"ref":....} ' 'shared secret' 'sha1=bc6550fc290acf5b42283fa8deaf55cea0f8c206'

hashutil.hmac_compute:

New in version 3000

Compute a HMAC SHA256 digest using a string and secret.

CLI Example:

    salt '*' hashutil.hmac_compute 'get salted' 'shared secret'

hashutil.hmac_signature:

Verify a challenging hmac signature against a string / shared-secret

New in version 2014.7.0

Returns a boolean if the verification succeeded or failed.

CLI Example:

    salt '*' hashutil.hmac_signature 'get salted' 'shared secret' 'eBWf9bstXg+NiP5AOwppB5HMvZiYMPzEM9W5YMm/AmQ='

hashutil.md5_digest:

Generate an md5 hash of a given string

New in version 2014.7.0

CLI Example:

    salt '*' hashutil.md5_digest 'get salted'

hashutil.sha256_digest:

Generate an sha256 hash of a given string

New in version 2014.7.0

CLI Example:

    salt '*' hashutil.sha256_digest 'get salted'

hashutil.sha512_digest:

Generate an sha512 hash of a given string

New in version 2014.7.0

CLI Example:

    salt '*' hashutil.sha512_digest 'get salted'

helm.completion:

Generate auto-completions script for Helm for the specified shell (bash or zsh).
Return the shell auto-completion content.

shell
    (string) One of ['bash', 'zsh'].

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.completion bash

helm.create:

Creates a chart directory along with the common files and directories used in a chart.
Return True if succeed, else the error message.

name
    (string) The chart name to create.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.create NAME

helm.dependency_build:

Build out the charts/ directory from the Chart.lock file.
Return True if succeed, else the error message.

chart
    (string) The chart name to build dependency.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.dependency_build CHART

helm.dependency_list:

List all of the dependencies declared in a chart.
Return chart dependencies if succeed, else the error message.

chart
    (string) The chart name to list dependency.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.dependency_list CHART

helm.dependency_update:

Update the on-disk dependencies to mirror Chart.yaml.
Return True if succeed, else the error message.

chart
    (string) The chart name to update dependency.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.dependency_update CHART

helm.env:

Prints out all the environment information in use by Helm.
Return Helm environments variables if succeed, else the error message.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.env

helm.get_all:

Prints a human readable collection of information about the notes, hooks, supplied values, and generated manifest file of the given release.
Return release information if succeed, else the error message.

release
    (string) Release name to get information from.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.get_all RELEASE

helm.get_hooks:

Prints a human readable collection of information about the hooks of the given release.
Return release hooks information if succeed, else the error message.

release
    (string) Release name to get hooks information from.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.get_hooks RELEASE

helm.get_manifest:

Prints a human readable collection of information about the manifest of the given release.
Return release manifest information if succeed, else the error message.

release
    (string) Release name to get manifest information from.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.get_manifest RELEASE

helm.get_notes:

Prints a human readable collection of information about the notes of the given release.
Return release notes information if succeed, else the error message.

release
    (string) Release name to get notes information from.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.get_notes RELEASE

helm.get_values:

Prints a human readable collection of information about the values of the given release.
Return release values information if succeed, else the error message.

release
    (string) Release name to get values information from.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.get_values RELEASE

    # In YAML format
    salt '*' helm.get_values RELEASE kvflags="{'output': 'yaml'}"

helm.help:

Provides help for any command in the application.
Return the full help if succeed, else the error message.

command
    (string) Command to get help. ex: 'get'

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.help COMMAND

helm.history:

Prints historical revisions for a given release.
Return release historic if succeed, else the error message.

release
    (string) Release name to get history from.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.history RELEASE

    # In YAML format
    salt '*' helm.history RELEASE kvflags="{'output': 'yaml'}"

helm.install:

Installs a chart archive.
Return True if succeed, else the error message.

release
    (string) Release name to get values information from.

chart
    (string) Chart name to install.

values
    (string) Absolute path to the values.yaml file.

version
    (string) The exact chart version to install. If this is not specified, the latest version is installed.

namespace
    (string) The namespace scope for this request.

set
    (string or list) Set a values on the command line.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.install RELEASE CHART

    # With values file.
    salt '*' helm.install RELEASE CHART values='/path/to/values.yaml'

helm.lint:

Takes a path to a chart and runs a series of tests to verify that the chart is well-formed.
Return True if succeed, else the error message.

path
    (string) The path to the chart to lint.

values
    (string) Absolute path to the values.yaml file.

namespace
    (string) The namespace scope for this request.

set
    (string or list) Set a values on the command line.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.lint PATH

helm.list:

Lists all of the releases. By default, it lists only releases that are deployed or failed.
Return the list of release if succeed, else the error message.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.list

    # In YAML format
    salt '*' helm.list kvflags="{'output': 'yaml'}"

helm.package:

Packages a chart into a versioned chart archive file. If a path is given, this will look at that path for a chart
(which must contain a Chart.yaml file) and then package that directory.
Return True if succeed, else the error message.

chart
    (string) Chart name to package. Can be an absolute path.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.package CHART

    # With destination path.
    salt '*' helm.package CHART kvflags="{'destination': '/path/to/the/package'}"

helm.plugin_install:

Install a Helm plugin from a url to a VCS repo or a local path.
Return True if succeed, else the error message.

path
    (string) Path to the local plugin. Can be an url.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.plugin_install PATH

helm.plugin_list:

List installed Helm plugins.
Return the plugin list if succeed, else the error message.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.plugin_list

helm.plugin_uninstall:

Uninstall a Helm plugin.
Return True if succeed, else the error message.

plugin
    (string) The plugin to uninstall.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.plugin_uninstall PLUGIN

helm.plugin_update:

Update a Helm plugin.
Return True if succeed, else the error message.

plugin
    (string) The plugin to update.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.plugin_update PLUGIN

helm.pull:

Retrieve a package from a package repository, and download it locally.
Return True if succeed, else the error message.

pkg
    (string) The package to pull. Can be url or repo/chartname.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.pull PKG

    # With destination path to write the chart.
    salt '*' helm.pull PKG kvflags="{'destination': '/path/to/the/chart'}"

helm.repo_add:

Add a chart repository.
Return True if succeed, else the error message.

name
    (string) The local name of the repository to install. Have to be unique.

url
    (string) The url to the repository.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.repo_add NAME URL

helm.repo_index:

Read the current directory and generate an index file based on the charts found.
Return True if succeed, else the error message.

directory
    (string) The path to the index.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.index DIRECTORY

helm.repo_list:

List a chart repository.
Return the repository list if succeed, else the error message.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.repo_list

    # In YAML format
    salt '*' helm.repo_list kvflags="{'output': 'yaml'}"

helm.repo_manage:

Manage charts repository.
Return the summery of all actions.

present
    (list) List of repository to be present. It's a list of dict: [{'name': 'local_name', 'url': 'repository_url'}]

absent
    (list) List of local name repository to be absent.

prune
    (boolean - default: False) If True, all repository already present but not in the present list would be removed.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.repo_manage present="[{'name': 'LOCAL_NAME', 'url': 'REPO_URL'}]" absent="['LOCAL_NAME']"

helm.repo_remove:

Remove a chart repository.
Return True if succeed, else the error message.

name
    (string) The local name of the repository to remove.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.repo_remove NAME

helm.repo_update:

Update all charts repository.
Return True if succeed, else the error message.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.repo_update

helm.rollback:

Rolls back a release to a previous revision.
To see release revision number, execute the history module.
Return True if succeed, else the error message.

release
    (string) The name of the release to managed.

revision
    (string) The revision number to roll back to.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.rollback RELEASE REVISION

    # In dry-run mode.
    salt '*' helm.rollback RELEASE REVISION flags=['dry-run']

helm.search_hub:

Search the Helm Hub or an instance of Monocular for Helm charts.
Return the research result if succeed, else the error message.

keyword
    (string) The keyword to search in the hub.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.search_hub KEYWORD

    # In YAML format
    salt '*' helm.search_hub KEYWORD kvflags="{'output': 'yaml'}"

helm.search_repo:

Search reads through all of the repositories configured on the system, and looks for matches. Search of these
repositories uses the metadata stored on the system.
Return the research result if succeed, else the error message.

keyword
    (string) The keyword to search in the repo.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.search_hub KEYWORD

    # In YAML format
    salt '*' helm.search_hub KEYWORD kvflags="{'output': 'yaml'}"

helm.show_all:

Inspects a chart (directory, file, or URL) and displays all its content (values.yaml, Charts.yaml, README).
Return chart information if succeed, else the error message.

chart
    (string) The chart to inspect.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.show_all CHART

helm.show_chart:

Inspects a chart (directory, file, or URL) and displays the contents of the Charts.yaml file.
Return chart information if succeed, else the error message.

chart
    (string) The chart to inspect.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.show_chart CHART

helm.show_readme:

Inspects a chart (directory, file, or URL) and displays the contents of the README file.
Return chart information if succeed, else the error message.

chart
    (string) The chart to inspect.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.show_readme CHART

helm.show_values:

Inspects a chart (directory, file, or URL) and displays the contents of the values.yaml file.
Return chart information if succeed, else the error message.

chart
    (string) The chart to inspect.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.show_values CHART

helm.status:

Show the status of the release.
Return the release status if succeed, else the error message.

release
    (string) The release to status.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.status RELEASE

    # In YAML format
    salt '*' helm.status RELEASE kvflags="{'output': 'yaml'}"

helm.template:

Render chart templates locally and display the output.
Return the chart renderer if succeed, else the error message.

name
    (string) The template name.

chart
    (string) The chart to template.

values
    (string) Absolute path to the values.yaml file.

output_dir
    (string) Absolute path to the output directory.

set
    (string or list) Set a values on the command line.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.template NAME CHART

    # With values file.
    salt '*' helm.template NAME CHART values='/path/to/values.yaml' output_dir='path/to/output/dir'

helm.test:

Runs the tests for a release.
Return the test result if succeed, else the error message.

release
    (string) The release name to test.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.test RELEASE

helm.uninstall:

Uninstall the release name.
Return True if succeed, else the error message.

release
    (string) The name of the release to managed.

namespace
    (string) The namespace scope for this request.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.uninstall RELEASE

    # In dry-run mode.
    salt '*' helm.uninstall RELEASE flags=['dry-run']

helm.upgrade:

Upgrades a release to a new version of a chart.
Return True if succeed, else the error message.

release
    (string) The name of the release to managed.

chart
    (string) The chart to managed.

values
    (string) Absolute path to the values.yaml file.

version
    (string) The exact chart version to install. If this is not specified, the latest version is installed.

namespace
    (string) The namespace scope for this request.

set
    (string or list) Set a values on the command line.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.upgrade RELEASE CHART

    # In dry-run mode.
    salt '*' helm.upgrade RELEASE CHART flags=['dry-run']

    # With values file.
    salt '*' helm.upgrade RELEASE CHART values='/path/to/values.yaml'

helm.verify:

Verify that the given chart has a valid provenance file.
Return True if succeed, else the error message.

path
    (string) The path to the chart file.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.verify PATH

helm.version:

Show the version for Helm.
Return version information if succeed, else the error message.

flags
    (list) Flags in argument of the command without values. ex: ['help', '--help']

kvflags
    (dict) Flags in argument of the command with values. ex: {'v': 2, '--v': 4}

CLI Example:

    salt '*' helm.version

highstate_doc.markdown_basic_jinja_template:

Return text for a simple markdown jinja template

This function can be used from the `highstate_doc.render` modules `jinja_template_function` option.

highstate_doc.markdown_default_jinja_template:

Return text for a markdown jinja template that included a header

This function can be used from the `highstate_doc.render` modules `jinja_template_function` option.

highstate_doc.markdown_full_jinja_template:

Return text for an advanced markdown jinja template

This function can be used from the `highstate_doc.render` modules `jinja_template_function` option.

highstate_doc.process_lowstates:

return processed lowstate data that was not blacklisted

render_module_function is used to provide your own.
defaults to from_lowstate

highstate_doc.processor_markdown:

Takes low state data and returns a dict of processed data
that is by default used in a jinja template when rendering a markdown highstate_doc.

This `lowstate_item_markdown` given a lowstate item, returns a dict like:

    vars:       # the raw lowstate_item that was processed
    id:         # the 'id' of the state.
    id_full:    # combo of the state type and id "state: id"
    state:      # name of the salt state module
    function:   # name of the state function
    name:       # value of 'name:' passed to the salt state module
    state_function:    # the state name and function name
    markdown:          # text data to describe a state
        requisites:    # requisite like [watch_in, require_in]
        details:       # state name, parameters and other details like file contents

highstate_doc.read_file:

output the contents of a file:

this is a workaround if the cp.push module does not work.
https://github.com/saltstack/salt/issues/37133

help the master output the contents of a document
that might be saved on the minions filesystem.

    #!/bin/python
    import os
    import salt.client
    s = salt.client.LocalClient()
    o = s.cmd('*', 'highstate_doc.read_file', ['/root/README.md'])
    for m in o:
        d = o.get(m)
        if d and not d.endswith('is not available.'):
            # mkdir m
            #directory = os.path.dirname(file_path)
            if not os.path.exists(m):
                os.makedirs(m)
            with open(m + '/README.md','wb') as fin:
                fin.write(d)
            print('ADDED: ' + m + '/README.md')

highstate_doc.render:

Render highstate to a text format (default Markdown)

if `jinja_template_text` is not set, `jinja_template_function` is used.

jinja_template_text: jinja text that the render uses to create the document.
jinja_template_function: a salt module call that returns template text.

:options:
    highstate_doc.markdown_basic_jinja_template
    highstate_doc.markdown_default_jinja_template
    highstate_doc.markdown_full_jinja_template

hosts.add_host:

Add a host to an existing entry, if the entry is not in place then create
it with the given host

CLI Example:

    salt '*' hosts.add_host <ip> <alias>

hosts.get_alias:

Return the list of aliases associated with an ip

Aliases (host names) are returned in the order in which they
appear in the hosts file.  If there are no aliases associated with
the IP, an empty list is returned.

CLI Example:

    salt '*' hosts.get_alias <ip addr>

hosts.get_ip:

Return the ip associated with the named host

CLI Example:

    salt '*' hosts.get_ip <hostname>

hosts.has_pair:

Return true if the alias is set

CLI Example:

    salt '*' hosts.has_pair <ip> <alias>

hosts.list_hosts:

Return the hosts found in the hosts file in this format::

    {'<ip addr>': ['alias1', 'alias2', ...]}

CLI Example:

    salt '*' hosts.list_hosts

hosts.rm_host:

Remove a host entry from the hosts file

CLI Example:

    salt '*' hosts.rm_host <ip> <alias>

hosts.set_comment:

Set the comment for a host to an existing entry,
if the entry is not in place then return False

CLI Example:

    salt '*' hosts.set_comment <ip> <comment>

hosts.set_host:

Set the host entry in the hosts file for the given ip, this will overwrite
any previous entry for the given ip

Changed in version 2016.3.0
    If ``alias`` does not include any host names (it is the empty
    string or contains only whitespace), all entries for the given
    IP address are removed.

CLI Example:

    salt '*' hosts.set_host <ip> <alias>

http.query:

New in version 2015.5.0

Query a resource, and decode the return data

Passes through all the parameters described in the
:py:func:`utils.http.query function <salt.utils.http.query>`:

.. autofunction:: salt.utils.http.query

raise_error : True
    If ``False``, and if a connection cannot be made, the error will be
    suppressed and the body of the return will simply be ``None``.

CLI Example:

    salt '*' http.query http://somelink.com/
    salt '*' http.query http://somelink.com/ method=POST             params='{"key1": "val1", "key2": "val2"}'
    salt '*' http.query http://somelink.com/ method=POST             data='<xml>somecontent</xml>'

http.update_ca_bundle:

Update the local CA bundle file from a URL

New in version 2015.5.0

CLI Example:

    salt '*' http.update_ca_bundle
    salt '*' http.update_ca_bundle target=/path/to/cacerts.pem
    salt '*' http.update_ca_bundle source=https://example.com/cacerts.pem

If the ``target`` is not specified, it will be pulled from the ``ca_cert``
configuration variable available to the minion. If it cannot be found there,
it will be placed at ``<<FILE_ROOTS>>/cacerts.pem``.

If the ``source`` is not specified, it will be pulled from the
``ca_cert_url`` configuration variable available to the minion. If it cannot
be found, it will be downloaded from the cURL website, using an http (not
https) URL. USING THE DEFAULT URL SHOULD BE AVOIDED!

``merge_files`` may also be specified, which includes a string or list of
strings representing a file or files to be appended to the end of the CA
bundle, once it is downloaded.

CLI Example:

    salt '*' http.update_ca_bundle merge_files=/path/to/mycert.pem

http.wait_for_successful_query:

Query a resource until a successful response, and decode the return data

CLI Example:

    salt '*' http.wait_for_successful_query http://somelink.com/ wait_for=160 request_interval=1

incron.list_tab:

Return the contents of the specified user's incrontab

CLI Example:

    salt '*' incron.list_tab root

incron.ls:

This function is an alias of list_tab.

Return the contents of the specified user's incrontab

CLI Example:

    salt '*' incron.list_tab root

incron.raw_incron:

Return the contents of the user's incrontab

CLI Example:

    salt '*' incron.raw_incron root

incron.raw_system_incron:

Return the contents of the system wide incrontab

CLI Example:

    salt '*' incron.raw_system_incron

incron.rm:

This function is an alias of rm_job.

Remove a incron job for a specified user. If any of the day/time params are
specified, the job will only be removed if the specified params match.

CLI Example:

    salt '*' incron.rm_job root /path

incron.rm_job:

Remove a incron job for a specified user. If any of the day/time params are
specified, the job will only be removed if the specified params match.

CLI Example:

    salt '*' incron.rm_job root /path

incron.set_job:

Sets an incron job up for a specified user.

CLI Example:

    salt '*' incron.set_job root '/root' 'IN_MODIFY' 'echo "$$ $@ $# $% $&"'

incron.write_incron_file:

Writes the contents of a file to a user's incrontab

CLI Example:

    salt '*' incron.write_incron_file root /tmp/new_incron

incron.write_incron_file_verbose:

Writes the contents of a file to a user's incrontab and return error message on error

CLI Example:

    salt '*' incron.write_incron_file_verbose root /tmp/new_incron

ini.get_ini:

Retrieve the whole structure from an ini file and return it as a dictionary.

Args:

    file_name (str):
        The full path to the ini file.

    separator (str):
        The character used to separate keys and values. Standard ini files
        use the "=" character. The default is ``=``.

        New in version 2016.11.0

    encoding (str):
        A string value representing encoding of the target ini file. If
        ``None`` is passed, it uses the system default which is likely
        ``utf-8``. Default is ``None``

        New in version 3006.6

Returns:
    dict: A dictionary containing the sections along with the values and
        names contained in each section

API Example:

    import salt.client
    with salt.client.get_local_client() as sc:
        sc.cmd('target', 'ini.get_ini', [path_to_ini_file])

CLI Example:

    salt '*' ini.get_ini /path/to/ini

ini.get_option:

Get value of a key from a section in an ini file. Returns ``None`` if
no matching key was found.

Args:

    file_name (str):
        The full path to the ini file.

    section (str):
        A string value representing the section of the ini that the option
        is in. If the option is not in a section, leave this empty.

    option (str):
        A string value representing the option to search for.

    separator (str):
        The character used to separate keys and values. Standard ini files
        use the "=" character. The default is ``=``.

        New in version 2016.11.0

    encoding (str):
        A string value representing encoding of the target ini file. If
        ``None`` is passed, it uses the system default which is likely
        ``utf-8``. Default is ``None``

        New in version 3006.6

Returns:
    str: The value as defined in the ini file, or ``None`` if empty or not
        found

API Example:

    import salt.client
    with salt.client.get_local_client() as sc:
        sc.cmd('target', 'ini.get_option', [path_to_ini_file, section_name, option])

CLI Example:

    salt '*' ini.get_option /path/to/ini section_name option_name

ini.get_section:

Retrieve a section from an ini file. Returns the section as a dictionary. If
the section is not found, an empty dictionary is returned.

Args:

    file_name (str):
        The full path to the ini file.

    section (str):
        A string value representing name of the section to search for.

    separator (str):
        The character used to separate keys and values. Standard ini files
        use the "=" character. The default is ``=``.

        New in version 2016.11.0

    encoding (str):
        A string value representing encoding of the target ini file. If
        ``None`` is passed, it uses the system default which is likely
        ``utf-8``. Default is ``None``

        New in version 3006.6

Returns:
    dict: A dictionary containing the names and values of all items in the
        section of the ini file. If the section is not found, an empty
        dictionary is returned

API Example:

    import salt.client
    with salt.client.get_local_client() as sc:
        sc.cmd('target', 'ini.get_section', [path_to_ini_file, section_name])

CLI Example:

    salt '*' ini.get_section /path/to/ini section_name

ini.remove_option:

Remove a key/value pair from a section in an ini file. Returns the value of
the removed key, or ``None`` if nothing was removed.

Args:

    file_name (str):
        The full path to the ini file.

    section (str):
        A string value representing the section of the ini that the option
        is in. If the option is not in a section, leave this empty.

    option (str):
        A string value representing the option to search for.

    separator (str):
        The character used to separate keys and values. Standard ini files
        use the "=" character. The default is ``=``.

        New in version 2016.11.0

    encoding (str):
        A string value representing encoding of the target ini file. If
        ``None`` is passed, it uses the system default which is likely
        ``utf-8``. Default is ``None``

        New in version 3006.6

Returns:
    str: A string value representing the option that was removed or ``None``
        if nothing was removed

API Example:

    import salt
    sc = salt.client.get_local_client()
    sc.cmd('target', 'ini.remove_option', [path_to_ini_file, section_name, option])

CLI Example:

    salt '*' ini.remove_option /path/to/ini section_name option_name

ini.remove_section:

Remove a section in an ini file. Returns the removed section as a
dictionary, or ``None`` if nothing is removed.

Args:

    file_name (str):
        The full path to the ini file.

    section (str):
        A string value representing the name of the section search for.

    separator (str):
        The character used to separate keys and values. Standard ini files
        use the "=" character. The default is ``=``.

        New in version 2016.11.0

    encoding (str):
        A string value representing encoding of the target ini file. If
        ``None`` is passed, it uses the system default which is likely
        ``utf-8``. Default is ``None``

        New in version 3006.6

Returns:
    dict: A dictionary containing the names and values of all items in the
        section that was removed or ``None`` if nothing was removed

API Example:

    import salt.client
    with  salt.client.get_local_client() as sc:
        sc.cmd('target', 'ini.remove_section', [path_to_ini_file, section_name])

CLI Example:

    salt '*' ini.remove_section /path/to/ini section_name

ini.set_option:

Edit an ini file, replacing one or more sections. Returns a dictionary
containing the changes made.

Args:

    file_name (str):
        The full path to the ini file.

    sections (dict):
        A dictionary representing the sections to be edited in the ini file.
        The keys are the section names and the values are a dictionary
        containing the options. If the ini file does not contain sections
        the keys and values represent the options. The default is ``None``.

    separator (str):
        The character used to separate keys and values. Standard ini files
        use the "=" character. The default is ``=``.

        New in version 2016.11.0

    encoding (str):
        A string value representing encoding of the target ini file. If
        ``None`` is passed, it uses the system default which is likely
        ``utf-8``. Default is ``None``

        New in version 3006.6

Returns:
    dict: A dictionary representing the changes made to the ini file

API Example:

    import salt.client
    with salt.client.get_local_client() as sc:
        sc.cmd(
            'target', 'ini.set_option', ['path_to_ini_file', '{"section_to_change": {"key": "value"}}']
        )

CLI Example:

    salt '*' ini.set_option /path/to/ini '{section_foo: {key: value}}'

inspector.build:

Build an image from a current system description.
The image is a system image can be output in bootable ISO or QCOW2 formats.

Node uses the image building library Kiwi to perform the actual build.

Parameters:

* **format**: Specifies output format: "qcow2" or "iso. Default: `qcow2`.
* **path**: Specifies output path where to store built image. Default: `/tmp`.

CLI Example:

    salt myminion inspector.build
    salt myminion inspector.build format=iso path=/opt/builds/

inspector.delete:

Remove description snapshots from the system.

::parameter: all. Default: False. Remove all snapshots, if set to True.

CLI Example:

    salt myminion inspector.delete <ID> <ID1> <ID2>..
    salt myminion inspector.delete all=True

inspector.export:

Export an image description for Kiwi.

Parameters:

* **local**: Specifies True or False if the export has to be in the local file. Default: False.
* **path**: If `local=True`, then specifies the path where file with the Kiwi description is written.
            Default: `/tmp`.

CLI Example:

    salt myminion inspector.export
    salt myminion inspector.export format=iso path=/opt/builds/

inspector.inspect:

Start node inspection and save the data to the database for further query.

Parameters:

* **mode**: Clarify inspection mode: configuration, payload, all (default)

  payload
    * **filter**: Comma-separated directories to track payload.

* **priority**: (advanced) Set priority of the inspection. Default is low priority.

CLI Example:

    salt '*' inspector.inspect
    salt '*' inspector.inspect configuration
    salt '*' inspector.inspect payload filter=/opt,/ext/oracle

inspector.query:

Query the node for specific information.

Parameters:

* **scope**: Specify scope of the query.

   * **System**: Return system data.

   * **Software**: Return software information.

   * **Services**: Return known services.

   * **Identity**: Return user accounts information for this system.
      accounts
        Can be either 'local', 'remote' or 'all' (equal to "local,remote").
        Remote accounts cannot be resolved on all systems, but only
        those, which supports 'passwd -S -a'.

      disabled
        True (or False, default) to return only disabled accounts.

   * **payload**: Payload scope parameters:
      filter
        Include only results which path starts from the filter string.

      time
        Display time in Unix ticks or format according to the configured TZ (default)
        Values: ticks, tz (default)

      size
        Format size. Values: B, KB, MB, GB

      type
        Include payload type.
        Values (comma-separated): directory (or dir), link, file (default)
        Example (returns everything): type=directory,link,file

      owners
        Resolve UID/GID to an actual names or leave them numeric (default).
        Values: name (default), id

      brief
        Return just a list of payload elements, if True. Default: False.

   * **all**: Return all information (default).

CLI Example:

    salt '*' inspector.query scope=system
    salt '*' inspector.query scope=payload type=file,link filter=/etc size=Kb brief=False

inspector.snapshots:

List current description snapshots.

CLI Example:

    salt myminion inspector.snapshots

introspect.enabled_service_owners:

Return which packages own each of the services that are currently enabled.

CLI Example:

    salt myminion introspect.enabled_service_owners

introspect.running_service_owners:

Determine which packages own the currently running services. By default,
excludes files whose full path starts with ``/dev``, ``/home``, ``/media``,
``/proc``, ``/run``, ``/sys``, ``/tmp`` and ``/var``. This can be
overridden by passing in a new list to ``exclude``.

CLI Example:

    salt myminion introspect.running_service_owners

introspect.service_highstate:

Return running and enabled services in a highstate structure. By default
also returns package dependencies for those services, which means that
package definitions must be created outside this function. To drop the
package dependencies, set ``requires`` to False.

CLI Example:

    salt myminion introspect.service_highstate
    salt myminion introspect.service_highstate requires=False

iosconfig.clean:

Return a clean version of the config, without any special signs (such as
``!`` as an individual line) or empty lines, but just lines with significant
value in the configuration of the network device.

config
    The configuration sent as text. This argument is ignored when ``path``
    is configured.

path
    Absolute or remote path from where to load the configuration text. This
    argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

saltenv: ``base``
    Salt fileserver environment from which to retrieve the file.
    Ignored if ``path`` is not a ``salt://`` URL.

CLI Example:

    salt '*' iosconfig.clean path=salt://path/to/my/config.txt
    salt '*' iosconfig.clean path=https://bit.ly/2mAdq7z

iosconfig.diff_text:

Return the diff, as text, between the candidate and the running config.

candidate_config
    The candidate configuration sent as text. This argument is ignored when
    ``candidate_path`` is set.

candidate_path
    Absolute or remote path from where to load the candidate configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

running_config
    The running configuration sent as text. This argument is ignored when
    ``running_path`` is set.

running_path
    Absolute or remote path from where to load the running configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

saltenv: ``base``
    Salt fileserver environment from which to retrieve the file.
    Ignored if ``candidate_path`` or ``running_path`` is not a
    ``salt://`` URL.

CLI Example:

    salt '*' iosconfig.diff_text candidate_path=salt://path/to/candidate.cfg running_path=salt://path/to/running.cfg

iosconfig.diff_tree:

Return the diff, as Python dictionary, between the candidate and the running
configuration.

candidate_config
    The candidate configuration sent as text. This argument is ignored when
    ``candidate_path`` is set.

candidate_path
    Absolute or remote path from where to load the candidate configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

running_config
    The running configuration sent as text. This argument is ignored when
    ``running_path`` is set.

running_path
    Absolute or remote path from where to load the running configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

saltenv: ``base``
    Salt fileserver environment from which to retrieve the file.
    Ignored if ``candidate_path`` or ``running_path`` is not a
    ``salt://`` URL.

CLI Example:

    salt '*' iosconfig.diff_tree candidate_path=salt://path/to/candidate.cfg running_path=salt://path/to/running.cfg

iosconfig.merge_diff:

Return the merge diff, as text, after merging the merge config into the
initial config.

initial_config
    The initial configuration sent as text. This argument is ignored when
    ``initial_path`` is set.

initial_path
    Absolute or remote path from where to load the initial configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

merge_config
    The config to be merged into the initial config, sent as text. This
    argument is ignored when ``merge_path`` is set.

merge_path
    Absolute or remote path from where to load the merge configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

saltenv: ``base``
    Salt fileserver environment from which to retrieve the file.
    Ignored if ``initial_path`` or ``merge_path`` is not a ``salt://`` URL.

CLI Example:

    salt '*' iosconfig.merge_diff initial_path=salt://path/to/running.cfg merge_path=salt://path/to/merge.cfg

iosconfig.merge_text:

Return the merge result of the ``initial_config`` with the ``merge_config``,
as plain text.

initial_config
    The initial configuration sent as text. This argument is ignored when
    ``initial_path`` is set.

initial_path
    Absolute or remote path from where to load the initial configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

merge_config
    The config to be merged into the initial config, sent as text. This
    argument is ignored when ``merge_path`` is set.

merge_path
    Absolute or remote path from where to load the merge configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

saltenv: ``base``
    Salt fileserver environment from which to retrieve the file.
    Ignored if ``initial_path`` or ``merge_path`` is not a ``salt://`` URL.

CLI Example:

    salt '*' iosconfig.merge_text initial_path=salt://path/to/running.cfg merge_path=salt://path/to/merge.cfg

iosconfig.merge_tree:

Return the merge tree of the ``initial_config`` with the ``merge_config``,
as a Python dictionary.

initial_config
    The initial configuration sent as text. This argument is ignored when
    ``initial_path`` is set.

initial_path
    Absolute or remote path from where to load the initial configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

merge_config
    The config to be merged into the initial config, sent as text. This
    argument is ignored when ``merge_path`` is set.

merge_path
    Absolute or remote path from where to load the merge configuration
    text. This argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

saltenv: ``base``
    Salt fileserver environment from which to retrieve the file.
    Ignored if ``initial_path`` or ``merge_path`` is not a ``salt://`` URL.

CLI Example:

    salt '*' iosconfig.merge_tree initial_path=salt://path/to/running.cfg merge_path=salt://path/to/merge.cfg

iosconfig.tree:

Transform Cisco IOS style configuration to structured Python dictionary.
Depending on the value of the ``with_tags`` argument, this function may
provide different views, valuable in different situations.

config
    The configuration sent as text. This argument is ignored when ``path``
    is configured.

path
    Absolute or remote path from where to load the configuration text. This
    argument allows any URI supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`), e.g., ``salt://``,
    ``https://``, ``s3://``, ``ftp:/``, etc.

with_tags: ``False``
    Whether this function should return a detailed view, with tags.

saltenv: ``base``
    Salt fileserver environment from which to retrieve the file.
    Ignored if ``path`` is not a ``salt://`` URL.

CLI Example:

    salt '*' iosconfig.tree path=salt://path/to/my/config.txt
    salt '*' iosconfig.tree path=https://bit.ly/2mAdq7z

ip.apply_network_settings:

Apply global network configuration.

CLI Example:

    salt '*' ip.apply_network_settings

ip.build_bond:

Create a bond script in /etc/modprobe.d with the passed settings
and load the bonding kernel module.

CLI Example:

    salt '*' ip.build_bond bond0 mode=balance-alb

ip.build_interface:

Build an interface script for a network interface.

CLI Example:

    salt '*' ip.build_interface eth0 eth <settings>

ip.build_network_settings:

Build the global network script.

CLI Example:

    salt '*' ip.build_network_settings <settings>

ip.build_routes:

Add route scripts for a network interface using up commands.

CLI Example:

    salt '*' ip.build_routes eth0 <settings>

ip.down:

Shutdown a network interface

CLI Example:

    salt '*' ip.down eth0 eth

ip.get_bond:

Return the content of a bond script

CLI Example:

    salt '*' ip.get_bond bond0

ip.get_interface:

Return the contents of an interface script

CLI Example:

    salt '*' ip.get_interface eth0

ip.get_network_settings:

Return the contents of the global network script.

CLI Example:

    salt '*' ip.get_network_settings

ip.get_routes:

Return the routes for the interface

CLI Example:

    salt '*' ip.get_routes eth0

ip.up:

Start up a network interface

CLI Example:

    salt '*' ip.up eth0 eth

iptables.append:

Append a rule to the specified table/chain.

This function accepts a rule in a standard iptables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

CLI Example:

    salt '*' iptables.append filter INPUT \
        rule='-m state --state RELATED,ESTABLISHED -j ACCEPT'

    IPv6:
    salt '*' iptables.append filter INPUT \
        rule='-m state --state RELATED,ESTABLISHED -j ACCEPT' \
        family=ipv6

iptables.build_rule:

Build a well-formatted iptables rule based on kwargs. A `table` and `chain`
are not required, unless `full` is True.

If `full` is `True`, then `table`, `chain` and `command` are required.
`command` may be specified as either a short option ('I') or a long option
(`--insert`). This will return the iptables command, exactly as it would
be used from the command line.

If a position is required (as with `-I` or `-D`), it may be specified as
`position`. This will only be useful if `full` is True.

If `state` is passed, it will be ignored, use `connstate`.
If `connstate` is passed in, it will automatically be changed to `state`.

To pass in jump options that doesn't take arguments, pass in an empty
string.

Note:

    Whereas iptables will accept ``-p``, ``--proto[c[o[l]]]`` as synonyms
    of ``--protocol``, if ``--proto`` appears in an iptables command after
    the appearance of ``-m policy``, it is interpreted as the ``--proto``
    option of the policy extension (see the iptables-extensions(8) man
    page).

CLI Examples:

    salt '*' iptables.build_rule match=state \
        connstate=RELATED,ESTABLISHED jump=ACCEPT

    salt '*' iptables.build_rule filter INPUT command=I position=3 \
        full=True match=state connstate=RELATED,ESTABLISHED jump=ACCEPT

    salt '*' iptables.build_rule filter INPUT command=A \
        full=True match=state connstate=RELATED,ESTABLISHED \
        source='127.0.0.1' jump=ACCEPT

    .. Invert Rules
    salt '*' iptables.build_rule filter INPUT command=A \
        full=True match=state connstate=RELATED,ESTABLISHED \
        source='!127.0.0.1' jump=ACCEPT

    salt '*' iptables.build_rule filter INPUT command=A \
        full=True match=state connstate=RELATED,ESTABLISHED \
        destination='not 127.0.0.1' jump=ACCEPT

    IPv6:
    salt '*' iptables.build_rule match=state \
        connstate=RELATED,ESTABLISHED jump=ACCEPT \
        family=ipv6
    salt '*' iptables.build_rule filter INPUT command=I position=3 \
        full=True match=state connstate=RELATED,ESTABLISHED jump=ACCEPT \
        family=ipv6

iptables.check:

Check for the existence of a rule in the table and chain

This function accepts a rule in a standard iptables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

CLI Example:

    salt '*' iptables.check filter INPUT \
        rule='-m state --state RELATED,ESTABLISHED -j ACCEPT'

    IPv6:
    salt '*' iptables.check filter INPUT \
        rule='-m state --state RELATED,ESTABLISHED -j ACCEPT' \
        family=ipv6

iptables.check_chain:

New in version 2014.1.0

Check for the existence of a chain in the table

CLI Example:

    salt '*' iptables.check_chain filter INPUT

    IPv6:
    salt '*' iptables.check_chain filter INPUT family=ipv6

iptables.delete:

Delete a rule from the specified table/chain, specifying either the rule
    in its entirety, or the rule's position in the chain.

This function accepts a rule in a standard iptables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

CLI Examples:

    salt '*' iptables.delete filter INPUT position=3
    salt '*' iptables.delete filter INPUT \
        rule='-m state --state RELATED,ESTABLISHED -j ACCEPT'

    IPv6:
    salt '*' iptables.delete filter INPUT position=3 family=ipv6
    salt '*' iptables.delete filter INPUT \
        rule='-m state --state RELATED,ESTABLISHED -j ACCEPT' \
        family=ipv6

iptables.delete_chain:

New in version 2014.1.0

Delete custom chain to the specified table.

CLI Example:

    salt '*' iptables.delete_chain filter CUSTOM_CHAIN

    IPv6:
    salt '*' iptables.delete_chain filter CUSTOM_CHAIN family=ipv6

iptables.flush:

Flush the chain in the specified table, flush all chains in the specified
table if not specified chain.

CLI Example:

    salt '*' iptables.flush filter INPUT

    IPv6:
    salt '*' iptables.flush filter INPUT family=ipv6

iptables.get_policy:

Return the current policy for the specified table/chain

CLI Example:

    salt '*' iptables.get_policy filter INPUT

    IPv6:
    salt '*' iptables.get_policy filter INPUT family=ipv6

iptables.get_rules:

Return a data structure of the current, in-memory rules

CLI Example:

    salt '*' iptables.get_rules

    IPv6:
    salt '*' iptables.get_rules family=ipv6

iptables.get_saved_policy:

Return the current policy for the specified table/chain

CLI Examples:

    salt '*' iptables.get_saved_policy filter INPUT
    salt '*' iptables.get_saved_policy filter INPUT \
        conf_file=/etc/iptables.saved

    IPv6:
    salt '*' iptables.get_saved_policy filter INPUT family=ipv6
    salt '*' iptables.get_saved_policy filter INPUT \
        conf_file=/etc/iptables.saved family=ipv6

iptables.get_saved_rules:

Return a data structure of the rules in the conf file

CLI Example:

    salt '*' iptables.get_saved_rules

    IPv6:
    salt '*' iptables.get_saved_rules family=ipv6

iptables.insert:

Insert a rule into the specified table/chain, at the specified position.

This function accepts a rule in a standard iptables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

If the position specified is a negative number, then the insert will be
    performed counting from the end of the list. For instance, a position
    of -1 will insert the rule as the second to last rule. To insert a rule
    in the last position, use the append function instead.

CLI Examples:

    salt '*' iptables.insert filter INPUT position=3 \
        rule='-m state --state RELATED,ESTABLISHED -j ACCEPT'

    IPv6:
    salt '*' iptables.insert filter INPUT position=3 \
        rule='-m state --state RELATED,ESTABLISHED -j ACCEPT' \
        family=ipv6

iptables.new_chain:

New in version 2014.1.0

Create new custom chain to the specified table.

CLI Example:

    salt '*' iptables.new_chain filter CUSTOM_CHAIN

    IPv6:
    salt '*' iptables.new_chain filter CUSTOM_CHAIN family=ipv6

iptables.save:

Save the current in-memory rules to disk

CLI Example:

    salt '*' iptables.save /etc/sysconfig/iptables

    IPv6:
    salt '*' iptables.save /etc/sysconfig/iptables family=ipv6

iptables.set_policy:

Set the current policy for the specified table/chain

CLI Example:

    salt '*' iptables.set_policy filter INPUT ACCEPT

    IPv6:
    salt '*' iptables.set_policy filter INPUT ACCEPT family=ipv6

iptables.version:

Return version from iptables --version

CLI Example:

    salt '*' iptables.version

    IPv6:
    salt '*' iptables.version family=ipv6

jboss7.create_datasource:

Create datasource in running jboss instance

jboss_config
    Configuration dictionary with properties specified above.
name
    Datasource name
datasource_properties
    A dictionary of datasource properties to be created:
      - driver-name: mysql
      - connection-url: 'jdbc:mysql://localhost:3306/sampleDatabase'
      - jndi-name: 'java:jboss/datasources/sampleDS'
      - user-name: sampleuser
      - password: secret
      - min-pool-size: 3
      - use-java-context: True
profile
    The profile name (JBoss domain mode only)

CLI Example:

    salt '*' jboss7.create_datasource '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' 'my_datasource' '{"driver-name": "mysql", "connection-url": "jdbc:mysql://localhost:3306/sampleDatabase", "jndi-name": "java:jboss/datasources/sampleDS", "user-name": "sampleuser", "password": "secret", "min-pool-size": 3, "use-java-context": True}'

jboss7.create_simple_binding:

Create a simple jndi binding in the running jboss instance

jboss_config
    Configuration dictionary with properties specified above.
binding_name
    Binding name to be created
value
    Binding value
profile
    The profile name (JBoss domain mode only)

CLI Example:

    salt '*' jboss7.create_simple_binding \
            '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", \
            "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' \
            my_binding_name my_binding_value

jboss7.deploy:

Deploy the application on the jboss instance from the local file system where minion is running.

jboss_config
    Configuration dictionary with properties specified above.
source_file
    Source file to deploy from

CLI Example:

    salt '*' jboss7.deploy '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' /opt/deploy_files/my_deploy

jboss7.list_deployments:

List all deployments on the jboss instance

jboss_config
    Configuration dictionary with properties specified above.

 CLI Example:

     salt '*' jboss7.list_deployments '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}'

jboss7.read_datasource:

Read datasource properties in the running jboss instance.

jboss_config
    Configuration dictionary with properties specified above.
name
    Datasource name
profile
    Profile name (JBoss domain mode only)

CLI Example:

    salt '*' jboss7.read_datasource '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}'

jboss7.read_simple_binding:

Read jndi binding in the running jboss instance

jboss_config
    Configuration dictionary with properties specified above.
binding_name
    Binding name to be created
profile
    The profile name (JBoss domain mode only)

CLI Example:

    salt '*' jboss7.read_simple_binding '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' my_binding_name

jboss7.reload:

Reload running jboss instance

jboss_config
    Configuration dictionary with properties specified above.
host
    The name of the host. JBoss domain mode only - and required if running in domain mode.
    The host name is the "name" attribute of the "host" element in host.xml

CLI Example:

    salt '*' jboss7.reload '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}'

jboss7.remove_datasource:

Remove an existing datasource from the running jboss instance.

jboss_config
    Configuration dictionary with properties specified above.
name
    Datasource name
profile
    The profile (JBoss domain mode only)

CLI Example:

    salt '*' jboss7.remove_datasource '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' my_datasource_name

jboss7.status:

Get status of running jboss instance.

jboss_config
    Configuration dictionary with properties specified above.
host
    The name of the host. JBoss domain mode only - and required if running in domain mode.
    The host name is the "name" attribute of the "host" element in host.xml
server_config
    The name of the Server Configuration. JBoss Domain mode only - and required
    if running in domain mode.

CLI Example:

    salt '*' jboss7.status '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}'

jboss7.stop_server:

Stop running jboss instance

jboss_config
    Configuration dictionary with properties specified above.
host
    The name of the host. JBoss domain mode only - and required if running in domain mode.
    The host name is the "name" attribute of the "host" element in host.xml

CLI Example:

    salt '*' jboss7.stop_server '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}'

jboss7.undeploy:

Undeploy the application from jboss instance

jboss_config
    Configuration dictionary with properties specified above.
deployment
    Deployment name to undeploy

CLI Example:

    salt '*' jboss7.undeploy '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' my_deployment

jboss7.update_datasource:

Update an existing datasource in running jboss instance.
If the property doesn't exist if will be created, if it does, it will be updated with the new value

jboss_config
    Configuration dictionary with properties specified above.
name
    Datasource name
new_properties
    A dictionary of datasource properties to be updated. For example:
      - driver-name: mysql
      - connection-url: 'jdbc:mysql://localhost:3306/sampleDatabase'
      - jndi-name: 'java:jboss/datasources/sampleDS'
      - user-name: sampleuser
      - password: secret
      - min-pool-size: 3
      - use-java-context: True
profile
    The profile name (JBoss domain mode only)

CLI Example:

    salt '*' jboss7.update_datasource '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' 'my_datasource' '{"driver-name": "mysql", "connection-url": "jdbc:mysql://localhost:3306/sampleDatabase", "jndi-name": "java:jboss/datasources/sampleDS", "user-name": "sampleuser", "password": "secret", "min-pool-size": 3, "use-java-context": True}'

jboss7.update_simple_binding:

Update the simple jndi binding in the running jboss instance

jboss_config
    Configuration dictionary with properties specified above.
binding_name
    Binding name to be updated
value
    New binding value
profile
    The profile name (JBoss domain mode only)

CLI Example:

    salt '*' jboss7.update_simple_binding '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' my_binding_name my_binding_value

jboss7_cli.run_command:

Execute a command against jboss instance through the CLI interface.

jboss_config
       Configuration dictionary with properties specified above.
command
       Command to execute against jboss instance
fail_on_error (default=True)
       Is true, raise CommandExecutionError exception if execution fails.
       If false, 'success' property of the returned dictionary is set to False

CLI Example:

    salt '*' jboss7_cli.run_command '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' my_command

jboss7_cli.run_operation:

Execute an operation against jboss instance through the CLI interface.

jboss_config
       Configuration dictionary with properties specified above.
operation
       An operation to execute against jboss instance

fail_on_error (default=True)
       Is true, raise CommandExecutionError exception if execution fails.
       If false, 'success' property of the returned dictionary is set to False
retries:
       Number of retries in case of "JBAS012144: Could not connect to remote" error.

CLI Example:

    salt '*' jboss7_cli.run_operation '{"cli_path": "integration.modules.sysmod.SysModuleTest.test_valid_docs", "controller": "10.11.12.13:9999", "cli_user": "jbossadm", "cli_password": "jbossadm"}' my_operation

jinja.import_json:

Loads JSON data from the specified path

CLI Example:

    salt myminion jinja.import_JSON myformula/foo.json

jinja.import_yaml:

Loads YAML data from the specified path

CLI Example:

    salt myminion jinja.import_yaml myformula/foo.yaml

jinja.load_map:

Loads the map at the specified path, and returns the specified value from
that map.

CLI Example:

    # Assuming the map is loaded in your formula SLS as follows:
    #
    # {% from "myformula/map.jinja" import myformula with context %}
    #
    # the following syntax can be used to load the map and check the
    # results:
    salt myminion jinja.load_map myformula/map.jinja myformula

k8s.create_namespace:

New in version 2016.3.0

Create kubernetes namespace from the name, similar to the functionality added to kubectl since v.1.2.0:
    kubectl create namespaces namespace-name

CLI Example:

    salt '*' k8s.create_namespace namespace_name

    salt '*' k8s.create_namespace namespace_name http://kube-master.cluster.local

k8s.create_secret:

New in version 2016.3.0

Create k8s secrets in the defined namespace from the list of files

CLI Example:

    salt '*' k8s.create_secret namespace_name secret_name sources

    salt '*' k8s.create_secret namespace_name secret_name sources
    http://kube-master.cluster.local

sources are either dictionary of {name: path, name1: path} pairs or array of strings defining paths.

Example of paths array:

['/full/path/filename', "file:///full/path/filename", "salt://secret/storage/file.txt", "http://user:password@securesite.com/secret-file.json"]

Example of dictionaries:

{"nameit": '/full/path/fiename', name2: "salt://secret/storage/file.txt"}

optional parameters accepted:

update=[false] default value is false
if set to false, and secret is already present on the cluster - warning will be returned and no changes to the secret will be done.
In case it is set to "true" and secret is present but data is differ - secret will be updated.

force=[true] default value is true
if the to False, secret will not be created in case one of the files is not
valid kubernetes secret. e.g. capital letters in secret name or _
in case force is set to True, wrong files will be skipped but secret will be created any way.

saltenv=['base'] default value is base
in case 'salt://' path is used, this parameter can change the visibility of files

k8s.delete_secret:

New in version 2016.3.0

Delete kubernetes secret in the defined namespace. Namespace is the mandatory parameter as well as name.

CLI Example:

    salt '*' k8s.delete_secret namespace_name secret_name

    salt '*' k8s.delete_secret namespace_name secret_name http://kube-master.cluster.local

k8s.get_labels:

New in version 2016.3.0

Get labels from the current node

CLI Example:

    salt '*' k8s.get_labels
    salt '*' k8s.get_labels kube-node.cluster.local http://kube-master.cluster.local

k8s.get_namespaces:

New in version 2016.3.0

Get one or all kubernetes namespaces.

If namespace parameter is omitted, all namespaces will be returned back to user, similar to following kubectl example:

    kubectl get namespaces -o json

In case namespace is set by user, the output will be similar to the one from kubectl:

    kubectl get namespaces namespace_name -o json

CLI Example:

    salt '*' k8s.get_namespaces
    salt '*' k8s.get_namespaces namespace_name http://kube-master.cluster.local

k8s.get_secrets:

Get k8s namespaces

CLI Example:

    salt '*' k8s.get_secrets namespace_name
    salt '*' k8s.get_secrets namespace_name secret_name http://kube-master.cluster.local

k8s.label_absent:

New in version 2016.3.0

Delete label to the current node

CLI Example:

    salt '*' k8s.label_absent hw/disktype
    salt '*' k8s.label_absent hw/disktype kube-node.cluster.local http://kube-master.cluster.local

k8s.label_folder_absent:

New in version 2016.3.0

Delete label folder to the current node

CLI Example:

    salt '*' k8s.label_folder_absent hw
    salt '*' k8s.label_folder_absent hw/ kube-node.cluster.local http://kube-master.cluster.local

k8s.label_present:

New in version 2016.3.0

Set label to the current node

CLI Example:

    salt '*' k8s.label_present hw/disktype ssd

    salt '*' k8s.label_present hw/disktype ssd kube-node.cluster.local http://kube-master.cluster.local

k8s.update_secret:

New in version 2016.3.0

alias to k8s.create_secret with update=true

CLI Example:

    salt '*' k8s.update_secret namespace_name secret_name sources [apiserver_url] [force=true] [update=false] [saltenv='base']

sources are either dictionary of {name: path, name1: path} pairs or array of strings defining paths.

Example of paths array:

['/full/path/filename', "file:///full/path/filename", "salt://secret/storage/file.txt", "http://user:password@securesite.com/secret-file.json"]

Example of dictionaries:

{"nameit": '/full/path/fiename', name2: "salt://secret/storage/file.txt"}

optional parameters accepted:

force=[true] default value is true
if the to False, secret will not be created in case one of the files is not
valid kubernetes secret. e.g. capital letters in secret name or _
in case force is set to True, wrong files will be skipped but secret will be created any way.

saltenv=['base'] default value is base
in case 'salt://' path is used, this parameter can change the visibility of files

kernelpkg.active:

Return the version of the running kernel.

CLI Example:

    salt '*' kernelpkg.active

kernelpkg.cleanup:

Remove all unused kernel packages from the system.

keep_latest : True
    In the event that the active kernel is not the latest one installed, setting this to True
    will retain the latest kernel package, in addition to the active one. If False, all kernel
    packages other than the active one will be removed.

CLI Example:

    salt '*' kernelpkg.cleanup

kernelpkg.latest_available:

Return the version of the latest kernel from the package repositories.

CLI Example:

    salt '*' kernelpkg.latest_available

kernelpkg.latest_installed:

Return the version of the latest installed kernel.

CLI Example:

    salt '*' kernelpkg.latest_installed

Note:
    This function may not return the same value as
    :py:func:`~salt.modules.kernelpkg_linux_apt.active` if a new kernel
    has been installed and the system has not yet been rebooted.
    The :py:func:`~salt.modules.kernelpkg_linux_apt.needs_reboot` function
    exists to detect this condition.

kernelpkg.list_installed:

Return a list of all installed kernels.

CLI Example:

    salt '*' kernelpkg.list_installed

kernelpkg.needs_reboot:

Detect if a new kernel version has been installed but is not running.
Returns True if a new kernel is installed, False otherwise.

CLI Example:

    salt '*' kernelpkg.needs_reboot

kernelpkg.remove:

Remove a specific version of the kernel.

release
    The release number of an installed kernel. This must be the entire release
    number as returned by :py:func:`~salt.modules.kernelpkg_linux_apt.list_installed`,
    not the package name.

CLI Example:

    salt '*' kernelpkg.remove 4.4.0-70-generic

kernelpkg.upgrade:

Upgrade the kernel and optionally reboot the system.

reboot : False
    Request a reboot if a new kernel is available.

at_time : immediate
    Schedule the reboot at some point in the future. This argument
    is ignored if ``reboot=False``. See
    :py:func:`~salt.modules.system.reboot` for more details
    on this argument.

CLI Example:

    salt '*' kernelpkg.upgrade
    salt '*' kernelpkg.upgrade reboot=True at_time=1

Note:
    An immediate reboot often shuts down the system before the minion has a
    chance to return, resulting in errors. A minimal delay (1 minute) is
    useful to ensure the result is delivered to the master.

kernelpkg.upgrade_available:

Detect if a new kernel version is available in the repositories.
Returns True if a new kernel is available, False otherwise.

CLI Example:

    salt '*' kernelpkg.upgrade_available

key.finger:

Return the minion's public key fingerprint

hash_type
    The hash algorithm used to calculate the fingerprint

CLI Example:

    salt '*' key.finger

key.finger_master:

Return the fingerprint of the master's public key on the minion.

hash_type
    The hash algorithm used to calculate the fingerprint

CLI Example:

    salt '*' key.finger_master

keyboard.get_sys:

Get current system keyboard setting

CLI Example:

    salt '*' keyboard.get_sys

keyboard.get_x:

Get current X keyboard setting

CLI Example:

    salt '*' keyboard.get_x

keyboard.set_sys:

Set current system keyboard setting

CLI Example:

    salt '*' keyboard.set_sys dvorak

keyboard.set_x:

Set current X keyboard setting

CLI Example:

    salt '*' keyboard.set_x dvorak

kmod.available:

Return a list of all available kernel modules

CLI Example:

    salt '*' kmod.available

kmod.check_available:

Check to see if the specified kernel module is available

CLI Example:

    salt '*' kmod.check_available kvm

kmod.is_loaded:

Check to see if the specified kernel module is loaded

CLI Example:

    salt '*' kmod.is_loaded kvm

kmod.load:

Load the specified kernel module

mod
    Name of module to add

persist
    Write module to /etc/modules to make it load on system reboot

CLI Example:

    salt '*' kmod.load kvm

kmod.lsmod:

Return a dict containing information about currently loaded modules

CLI Example:

    salt '*' kmod.lsmod

kmod.mod_list:

Return a list of the loaded module names

only_persist
    Only return the list of loaded persistent modules

CLI Example:

    salt '*' kmod.mod_list

kmod.remove:

Remove the specified kernel module

mod
    Name of module to remove

persist
    Also remove module from /etc/modules

comment
    If persist is set don't remove line from /etc/modules but only
    comment it

CLI Example:

    salt '*' kmod.remove kvm

kubeadm.alpha_certs_renew:

New in version 3001

Renews certificates for a Kubernetes cluster

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.alpha_certs_renew

kubeadm.alpha_kubeconfig_user:

New in version 3001

Outputs a kubeconfig file for an additional user

client_name
   The name of the user. It will be used as the CN if client
   certificates are created

apiserver_advertise_address
   The IP address the API server is accessible on

apiserver_bind_port
   The port the API server is accessible on (default 6443)

cert_dir
   The path where certificates are stored (default
   "/etc/kubernetes/pki")

org
   The organization of the client certificate

token
   The token that show be used as the authentication mechanism for
   this kubeconfig, instead of client certificates

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.alpha_kubeconfig_user client_name=user

kubeadm.alpha_kubelet_config_download:

New in version 3001

Downloads the kubelet configuration from the cluster ConfigMap
kubelet-config-1.X

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

kubelet_version
   The desired version for the kubelet

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.alpha_kubelet_config_download
   salt '*' kubeadm.alpha_kubelet_config_download kubelet_version='1.14.0'

kubeadm.alpha_kubelet_config_enable_dynamic:

New in version 3001

Enables or updates dynamic kubelet configuration for a node

node_name
   Name of the node that should enable the dynamic kubelet
   configuration

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

kubelet_version
   The desired version for the kubelet

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.alpha_kubelet_config_enable_dynamic node-1

kubeadm.alpha_selfhosting_pivot:

New in version 3001

Converts a static Pod-hosted control plane into a selt-hosted one

cert_dir
   The path where certificates are stored (default
   "/etc/kubernetes/pki")

config
   Path to kubeadm configuration file

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

store_certs_in_secrets
   Enable storing certs in secrets

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.alpha_selfhost_pivot

kubeadm.config_images_list:

New in version 3001

Print a list of images kubeadm will use

config
   Path to kubeadm configuration file

feature_gates
   A set of key=value pairs that describe feature gates for
   various features

kubernetes_version
   Choose a specifig Kubernetes version for the control plane
   (default "stable-1")

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.config_images_list

kubeadm.config_images_pull:

New in version 3001

Pull images used by kubeadm

config
   Path to kubeadm configuration file

cri_socket
   Path to the CRI socket to connect

feature_gates
   A set of key=value pairs that describe feature gates for
   various features

kubernetes_version
   Choose a specifig Kubernetes version for the control plane
   (default "stable-1")

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.config_images_pull

kubeadm.config_migrate:

New in version 3001

Read an older version of the kubeadm configuration API types from
a file, and output the similar config object for the newer version

old_config
   Path to the kubeadm config file that is usin the old API
   version and should be converted

new_config
   Path to the resulting equivalent kubeadm config file using the
   new API version. If not specified the output will be returned

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.config_migrate /oldconfig.cfg

kubeadm.config_print_init_defaults:

New in version 3001

Return default init configuration, that can be used for 'kubeadm
init'

component_config
   A comma-separated list for component config API object to print
   the default values for (valid values: KubeProxyConfiguration,
   KubeletConfiguration)

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.config_print_init_defaults

kubeadm.config_print_join_defaults:

New in version 3001

Return default join configuration, that can be used for 'kubeadm
join'

component_config
   A comma-separated list for component config API object to print
   the default values for (valid values: KubeProxyConfiguration,
   KubeletConfiguration)

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.config_print_join_defaults

kubeadm.config_upload_from_file:

New in version 3001

Upload a configuration file to the in-cluster ConfigMap for
kubeadm configuration

config
   Path to a kubeadm configuration file

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.config_upload_from_file /config.cfg

kubeadm.config_upload_from_flags:

New in version 3001

Create the in-cluster configuration file for the first time using
flags

apiserver_advertise_address
   The IP address the API server will advertise it's listening on

apiserver_bind_port
   The port the API server is accessible on (default 6443)

apiserver_cert_extra_sans
   Optional extra Subject Alternative Names (SANs) to use for the
   API Server serving certificate

cert_dir
   The path where to save and store the certificates (default
   "/etc/kubernetes/pki")

cri_socket
   Path to the CRI socket to connect

feature_gates
   A set of key=value pairs that describe feature gates for
   various features

kubernetes_version
   Choose a specifig Kubernetes version for the control plane
   (default "stable-1")

node_name
   Specify the node name

pod_network_cidr
   Specify range of IP addresses for the pod network

service_cidr
   Use alternative range of IP address for service VIPs (default
   "10.96.0.0/12")

service_dns_domain
   Use alternative domain for services (default "cluster.local")

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.config_upload_from_flags

kubeadm.config_view:

New in version 3001

View the kubeadm configuration stored inside the cluster

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.config_view

kubeadm.init:

New in version 3001

Command to set up the Kubernetes control plane

apiserver_advertise_address
   The IP address the API server will advertise it's listening on

apiserver_bind_port
   The port the API server is accessible on (default 6443)

apiserver_cert_extra_sans
   Optional extra Subject Alternative Names (SANs) to use for the
   API Server serving certificate

cert_dir
   The path where to save and store the certificates (default
   "/etc/kubernetes/pki")

certificate_key
   Key used to encrypt the control-plane certificates in the
   kubeadm-certs Secret

config
   Path to a kubeadm configuration file

control_plane_endpoint
   Specify a stable IP address or DNS name for the control plane

cri_socket
   Path to the CRI socket to connect

experimental_upload_certs
   Upload control-plane certificate to the kubeadm-certs Secret. ( kubeadm version =< 1.16 )

upload_certs
   Upload control-plane certificate to the kubeadm-certs Secret. ( kubeadm version > 1.16 )

feature_gates
   A set of key=value pairs that describe feature gates for
   various features

ignore_preflight_errors
   A list of checks whose errors will be shown as warnings

image_repository
   Choose a container registry to pull control plane images from

kubernetes_version
   Choose a specifig Kubernetes version for the control plane
   (default "stable-1")

node_name
   Specify the node name

pod_network_cidr
   Specify range of IP addresses for the pod network

service_cidr
   Use alternative range of IP address for service VIPs (default
   "10.96.0.0/12")

service_dns_domain
   Use alternative domain for services (default "cluster.local")

skip_certificate_key_print
   Don't print the key used to encrypt the control-plane
   certificates

skip_phases
   List of phases to be skipped

skip_token_print
   Skip printing of the default bootstrap token generated by
   'kubeadm init'

token
   The token to use for establishing bidirectional trust between
   nodes and control-plane nodes. The token must match a regular
   expression, that by default is [a-z0-9]{6}.[a-z0-9]{16}

token_ttl
   The duration defore the token is automatically deleted (1s, 2m,
   3h). If set to '0' the token will never expire. Default value
   is 24h0m0s

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.init pod_network_cidr='10.244.0.0/16'

kubeadm.join:

New in version 3001

Command to join to an existing cluster

api_server_endpoint
   IP address or domain name and port of the API Server

apiserver_advertise_address
   If the node should host a new control plane instance, the IP
   address the API Server will advertise it's listening on

apiserver_bind_port
   If the node should host a new control plane instance, the port
   the API Server to bind to (default 6443)

certificate_key
   Use this key to decrypt the certificate secrets uploaded by
   init

config
   Path to a kubeadm configuration file

cri_socket
   Path to the CRI socket to connect

discovery_file
   For file-based discovery, a file or URL from which to load
   cluster information

discovery_token
   For token-based discovery, the token used to validate cluster
   information fetched from the API Server

discovery_token_ca_cert_hash
   For token-based discovery, validate that the root CA public key
   matches this hash (format: "<type>:<value>")

discovery_token_unsafe_skip_ca_verification
   For token-based discovery, allow joining without
   'discovery-token-ca-cert-hash' pinning

experimental_control_plane
   Create a new control plane instance on this node (kubeadm version =< 1.16)

control_plane
   Create a new control plane instance on this node (kubeadm version > 1.16)

ignore_preflight_errors
   A list of checks whose errors will be shown as warnings

node_name
   Specify the node name

skip_phases
   List of phases to be skipped

tls_bootstrap_token
   Specify the token used to temporarily authenticate with the
   Kubernetes Control Plane while joining the node

token
   Use this token for both discovery-token and tls-bootstrap-token
   when those values are not provided

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.join 10.160.65.165:6443 token='token'

kubeadm.join_params:

New in version 3001

Return the parameters required for joining into the cluster

create_if_needed
   If the token bucket is empty and this parameter is True, a new
   token will be created.

CLI Example:

   salt '*' kubeadm.join_params
   salt '*' kubeadm.join_params create_if_needed=True

kubeadm.reset:

New in version 3001

Revert any changes made to this host by 'kubeadm init' or 'kubeadm
join'

cert_dir
   The path to the directory where the certificates are stored
   (default "/etc/kubernetes/pki")

cri_socket
   Path to the CRI socket to connect

ignore_preflight_errors
   A list of checks whose errors will be shown as warnings

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.join 10.160.65.165:6443 token='token'

kubeadm.token_create:

New in version 3001

Create bootstrap tokens on the server

token
   Token to write, if None one will be generated. The token must
   match a regular expression, that by default is
   [a-z0-9]{6}.[a-z0-9]{16}

config
   Path to kubeadm configuration file

description
   A human friendly description of how this token is used

groups
   List of extra groups that this token will authenticate, default
   to ['system:bootstrappers:kubeadm:default-node-token']

ttl
   The duration defore the token is automatically deleted (1s, 2m,
   3h). If set to '0' the token will never expire. Default value
   is 24h0m0s

usages
   Describes the ways in which this token can be used. The default
   value is ['signing', 'authentication']

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.token_create
   salt '*' kubeadm.token_create a1b2c.0123456789abcdef
   salt '*' kubeadm.token_create ttl='6h'
   salt '*' kubeadm.token_create usages="['signing']"

kubeadm.token_delete:

New in version 3001

Delete bootstrap tokens on the server

token
   Token to write, if None one will be generated. The token must
   match a regular expression, that by default is
   [a-z0-9]{6}.[a-z0-9]{16}

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.token_delete a1b2c
   salt '*' kubeadm.token_create a1b2c.0123456789abcdef

kubeadm.token_generate:

New in version 3001

Generate and return a bootstrap token, but do not create it on the
server

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.token_generate

kubeadm.token_list:

New in version 3001

List bootstrap tokens on the server

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.token_list

kubeadm.version:

New in version 3001

Return the version of kubeadm

kubeconfig
   The kubeconfig file to use when talking to the cluster. The
   default values in /etc/kubernetes/admin.conf

rootfs
   The path to the real host root filesystem

CLI Example:

   salt '*' kubeadm.version

locale.avail:

Check if a locale is available.

New in version 2014.7.0

CLI Example:

    salt '*' locale.avail 'en_US.UTF-8'

locale.gen_locale:

Generate a locale. Options:

New in version 2014.7.0

:param locale: Any locale listed in /usr/share/i18n/locales or
    /usr/share/i18n/SUPPORTED for Debian and Gentoo based distributions,
    which require the charmap to be specified as part of the locale
    when generating it.

verbose
    Show extra warnings about errors that are normally ignored.

CLI Example:

    salt '*' locale.gen_locale en_US.UTF-8
    salt '*' locale.gen_locale 'en_IE.UTF-8 UTF-8'    # Debian/Gentoo only

locale.get_locale:

Get the current system locale

CLI Example:

    salt '*' locale.get_locale

locale.list_avail:

Lists available (compiled) locales

CLI Example:

    salt '*' locale.list_avail

locale.set_locale:

Sets the current system locale

CLI Example:

    salt '*' locale.set_locale 'en_US.UTF-8'

locate.locate:

Performs a file lookup. Valid options (and their defaults) are::

    basename=False
    count=False
    existing=False
    follow=True
    ignore=False
    nofollow=False
    wholename=True
    regex=False
    database=<locate's default database>
    limit=<integer, not set by default>

See the manpage for ``locate(1)`` for further explanation of these options.

CLI Example:

    salt '*' locate.locate

locate.stats:

Returns statistics about the locate database

CLI Example:

    salt '*' locate.stats

locate.updatedb:

Updates the locate database

CLI Example:

    salt '*' locate.updatedb

locate.version:

Returns the version of locate

CLI Example:

    salt '*' locate.version

log.critical:

Log message at level CRITICAL.

log.debug:

Log message at level DEBUG.

log.error:

Log message at level ERROR.

log.exception:

Log message at level EXCEPTION.

log.info:

Log message at level INFO.

log.warning:

Log message at level WARNING.

logrotate.get:

Get the value for a specific configuration line.

:param str key: The command or stanza block to configure.
:param str value: The command value or command of the block specified by the key parameter.
:param str conf_file: The logrotate configuration file.

:return: The value for a specific configuration line.
:rtype: bool|int|str

CLI Example:

    salt '*' logrotate.get rotate

    salt '*' logrotate.get /var/log/wtmp rotate /etc/logrotate.conf

logrotate.set:

Set a new value for a specific configuration line.

:param str key: The command or block to configure.
:param str value: The command value or command of the block specified by the key parameter.
:param str setting: The command value for the command specified by the value parameter.
:param str conf_file: The logrotate configuration file.

:return: A boolean representing whether all changes succeeded.
:rtype: bool

CLI Example:

    salt '*' logrotate.set rotate 2

Can also be used to set a single value inside a multiline configuration
block. For instance, to change rotate in the following block:

    /var/log/wtmp {
        monthly
        create 0664 root root
        rotate 1
    }

Use the following command:

    salt '*' logrotate.set /var/log/wtmp rotate 2

This module also has the ability to scan files inside an include directory,
and make changes in the appropriate file.

logrotate.show_conf:

Show parsed configuration

:param str conf_file: The logrotate configuration file.

:return: The parsed configuration.
:rtype: dict

CLI Example:

    salt '*' logrotate.show_conf

lowpkg.bin_pkg_info:

New in version 2015.8.0

Parses DEB metadata and returns a dictionary of information about the
package (name, version, etc.).

path
    Path to the file. Can either be an absolute path to a file on the
    minion, or a salt fileserver URL (e.g. ``salt://path/to/file.deb``).
    If a salt fileserver URL is passed, the file will be cached to the
    minion so that it can be examined.

saltenv : base
    Salt fileserver environment from which to retrieve the package. Ignored
    if ``path`` is a local file path on the minion.

CLI Example:

    salt '*' lowpkg.bin_pkg_info /root/foo-1.2.3-1ubuntu1_all.deb
    salt '*' lowpkg.bin_pkg_info salt://foo-1.2.3-1ubuntu1_all.deb

lowpkg.file_dict:

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:

    salt '*' lowpkg.file_dict hostname
    salt '*' lowpkg.file_dict hostname mount
    salt '*' lowpkg.file_dict

lowpkg.file_list:

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:

    salt '*' lowpkg.file_list hostname
    salt '*' lowpkg.file_list hostname mount
    salt '*' lowpkg.file_list

lowpkg.info:

Returns a detailed summary of package information for provided package names.
If no packages are specified, all packages will be returned.

New in version 2015.8.1

packages
    The names of the packages for which to return information.

failhard
    Whether to throw an exception if none of the packages are installed.
    Defaults to True.

    New in version 2016.11.3

CLI Example:

    salt '*' lowpkg.info
    salt '*' lowpkg.info apache2 bash
    salt '*' lowpkg.info 'php5*' failhard=false

lowpkg.list_pkgs:

List the packages currently installed in a dict::

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

External dependencies::

    Virtual package resolution requires aptitude. Because this function
    uses dpkg, virtual packages will be reported as not installed.

CLI Example:

    salt '*' lowpkg.list_pkgs
    salt '*' lowpkg.list_pkgs hostname
    salt '*' lowpkg.list_pkgs hostname mount

lowpkg.unpurge:

Change package selection for each package specified to 'install'

CLI Example:

    salt '*' lowpkg.unpurge curl

mandrill.send:

Send out the email using the details from the ``message`` argument.

message
    The information on the message to send. This argument must be
    sent as dictionary with at fields as specified in the Mandrill API
    documentation.

asynchronous: ``False``
    Enable a background sending mode that is optimized for bulk sending.
    In asynchronous mode, messages/send will immediately return a status of
    "queued" for every recipient. To handle rejections when sending in asynchronous
    mode, set up a webhook for the 'reject' event. Defaults to false for
    messages with no more than 10 recipients; messages with more than 10
    recipients are always sent asynchronously, regardless of the value of
    asynchronous.

ip_pool
    The name of the dedicated ip pool that should be used to send the
    message. If you do not have any dedicated IPs, this parameter has no
    effect. If you specify a pool that does not exist, your default pool
    will be used instead.

send_at
    When this message should be sent as a UTC timestamp in
    ``YYYY-MM-DD HH:MM:SS`` format. If you specify a time in the past,
    the message will be sent immediately. An additional fee applies for
    scheduled email, and this feature is only available to accounts with a
    positive balance.

Note:
    Fur further details please consult the `API documentation <https://mandrillapp.com/api/docs/messages.dart.html>`_.

CLI Example:

    salt '*' mandrill.send message="{'subject': 'Hi', 'from_email': 'test@example.com', 'to': [{'email': 'recv@example.com', 'type': 'to'}]}"

``message`` structure example (as YAML for readability):

    message:
        text: |
            This is the body of the email.
            This is the second line.
        subject: Email subject
        from_name: Test At Example Dot Com
        from_email: test@example.com
        to:
          - email: recv@example.com
            type: to
            name: Recv At Example Dot Com
          - email: cc@example.com
            type: cc
            name: CC At Example Dot Com
        important: true
        track_clicks: true
        track_opens: true
        attachments:
          - type: text/x-yaml
            name: yaml_file.yml
            content: aV9hbV9zdXBlcl9jdXJpb3VzOiB0cnVl

Output example:

    minion:
        ----------
        comment:
        out:
            |_
              ----------
              _id:
                  c4353540a3c123eca112bbdd704ab6
              email:
                  recv@example.com
              reject_reason:
                  None
              status:
                  sent
        result:
            True

match.compound:

Return True if the minion ID matches the given compound target

minion_id
    Specify the minion ID to match against the target expression

    New in version 2014.7.0

CLI Example:

    salt '*' match.compound 'L@cheese,foo and *'

match.data:

Return True if the minion matches the given data target

CLI Example:

    salt '*' match.data 'spam:eggs'

match.filter_by:

Return the first match in a dictionary of target patterns

New in version 2014.7.0

CLI Example:

    salt '*' match.filter_by '{foo*: Foo!, bar*: Bar!}' minion_id=bar03

Pillar Example:

    # Filter the data for the current minion into a variable:
    {% set roles = salt['match.filter_by']({
        'web*': ['app', 'caching'],
        'db*': ['db'],
    }, minion_id=grains['id'], default='web*') %}

    # Make the filtered data available to Pillar:
    roles: {{ roles | yaml() }}

match.glob:

Return True if the minion ID matches the given glob target

minion_id
    Specify the minion ID to match against the target expression

    New in version 2014.7.0

CLI Example:

    salt '*' match.glob '*'

match.grain:

Return True if the minion matches the given grain target. The ``delimiter``
argument can be used to specify a different delimiter.

CLI Example:

    salt '*' match.grain 'os:Ubuntu'
    salt '*' match.grain 'ipv6|2001:db8::ff00:42:8329' delimiter='|'

delimiter
    Specify an alternate delimiter to use when traversing a nested dict

    New in version 2014.7.0

delim
    Specify an alternate delimiter to use when traversing a nested dict

    New in version 0.16.4
    .. deprecated:: 2015.8.0

match.grain_pcre:

Return True if the minion matches the given grain_pcre target. The
``delimiter`` argument can be used to specify a different delimiter.

CLI Example:

    salt '*' match.grain_pcre 'os:Fedo.*'
    salt '*' match.grain_pcre 'ipv6|2001:.*' delimiter='|'

delimiter
    Specify an alternate delimiter to use when traversing a nested dict

    New in version 2014.7.0

delim
    Specify an alternate delimiter to use when traversing a nested dict

    New in version 0.16.4
    .. deprecated:: 2015.8.0

match.ifelse:

New in version 3006.0

Evaluate each pair of arguments up to the last one as a (matcher, value)
tuple, returning ``value`` if matched.  If none match, returns the last
argument.

The ``ifelse`` function is like a multi-level if-else statement. It was
inspired by CFEngine's ``ifelse`` function which in turn was inspired by
Oracle's ``DECODE`` function. It must have an odd number of arguments (from
1 to N). The last argument is the default value, like the ``else`` clause in
standard programming languages. Every pair of arguments before the last one
are evaluated as a pair. If the first one evaluates true then the second one
is returned, as if you had used the first one in a compound match
expression. Boolean values can also be used as the first item in a pair,
as it will be translated to a match that will always match ("*") or never
match ("SALT_IFELSE_MATCH_NOTHING") a target system.

This is essentially another way to express the ``filter_by`` functionality
in way that's familiar to CFEngine or Oracle users. Consider using
``filter_by`` unless this function fits your workflow.

CLI Example:

    salt '*' match.ifelse 'foo*' 'Foo!' 'bar*' 'Bar!' minion_id=bar03

match.ipcidr:

Return True if the minion matches the given ipcidr target

CLI Example:

    salt '*' match.ipcidr '192.168.44.0/24'

delimiter
Pillar Example:

   '172.16.0.0/12':
     - match: ipcidr
     - nodeclass: internal

match.list:

Return True if the minion ID matches the given list target

minion_id
    Specify the minion ID to match against the target expression

    New in version 2014.7.0

CLI Example:

    salt '*' match.list 'server1,server2'

match.pcre:

Return True if the minion ID matches the given pcre target

minion_id
    Specify the minion ID to match against the target expression

    New in version 2014.7.0

CLI Example:

    salt '*' match.pcre '.*'

match.pillar:

Return True if the minion matches the given pillar target. The
``delimiter`` argument can be used to specify a different delimiter.

CLI Example:

    salt '*' match.pillar 'cheese:foo'
    salt '*' match.pillar 'clone_url|https://github.com/saltstack/salt.git' delimiter='|'

delimiter
    Specify an alternate delimiter to use when traversing a nested dict

    New in version 2014.7.0

delim
    Specify an alternate delimiter to use when traversing a nested dict

    New in version 0.16.4
    .. deprecated:: 2015.8.0

match.pillar_pcre:

Return True if the minion matches the given pillar_pcre target. The
``delimiter`` argument can be used to specify a different delimiter.

CLI Example:

    salt '*' match.pillar_pcre 'cheese:(swiss|american)'
    salt '*' match.pillar_pcre 'clone_url|https://github\.com/.*\.git' delimiter='|'

delimiter
    Specify an alternate delimiter to use when traversing a nested dict

    New in version 2014.7.0

delim
    Specify an alternate delimiter to use when traversing a nested dict

    New in version 0.16.4
    .. deprecated:: 2015.8.0

match.search_by:

Search a dictionary of target strings for matching targets

This is the inverse of :py:func:`match.filter_by
<salt.modules.match.filter_by>` and allows matching values instead of
matching keys. A minion can be matched by multiple entries.

New in version 2017.7.0

CLI Example:

    salt '*' match.search_by '{web: [node1, node2], db: [node2, node]}'

Pillar Example:

    {% set roles = salt.match.search_by({
        'web': ['G@os_family:Debian not nodeX'],
        'db': ['L@node2,node3 and G@datacenter:west'],
        'caching': ['node3', 'node4'],
    }) %}

    # Make the filtered data available to Pillar:
    roles: {{ roles | yaml() }}

mattermost.post_message:

Send a message to a Mattermost channel.

:param channel:     The channel name, either will work.
:param username:    The username of the poster.
:param message:     The message to send to the Mattermost channel.
:param api_url:     The Mattermost api url, if not specified in the configuration.
:param hook:        The Mattermost hook, if not specified in the configuration.
:return:            Boolean if message was sent successfully.

CLI Example:

    salt '*' mattermost.post_message message='Build is done'

mine.delete:

Remove specific function contents of minion.

:param str fun: The name of the function.
:rtype: bool
:return: True on success.

CLI Example:

    salt '*' mine.delete 'network.interfaces'

mine.flush:

Remove all mine contents of minion.

:rtype: bool
:return: True on success

CLI Example:

    salt '*' mine.flush

mine.get:

Get data from the mine.

:param str tgt: Target whose mine data to get.
:param fun: Function to get the mine data of. You can specify multiple functions
    to retrieve using either a list or a comma-separated string of functions.
:type fun: str or list
:param str tgt_type: Default ``glob``. Target type to use with ``tgt``.
    See :ref:`targeting` for more information.
    Note that all pillar matches, whether using the compound matching system or
    the pillar matching system, will be exact matches, with globbing disabled.
:param bool exclude_minion: Excludes the current minion from the result set.

CLI Example:

    salt '*' mine.get '*' network.interfaces
    salt '*' mine.get 'os:Fedora' network.interfaces grain
    salt '*' mine.get 'G@os:Fedora and S@192.168.5.0/24' network.ipaddrs compound

.. seealso:: Retrieving Mine data from Pillar and Orchestrate

    This execution module is intended to be executed on minions.
    Master-side operations such as Pillar or Orchestrate that require Mine
    data should use the :py:mod:`Mine Runner module <salt.runners.mine>`
    instead; it can be invoked from a Pillar SLS file using the
    :py:func:`saltutil.runner <salt.modules.saltutil.runner>` module. For
    example:

        {% set minion_ips = salt.saltutil.runner('mine.get',
            tgt='*',
            fun='network.ip_addrs',
            tgt_type='glob') %}

mine.get_docker:

Changed in version 2017.7.8,2018.3.3
    When :conf_minion:`docker.update_mine` is set to ``False`` for a given
    minion, no mine data will be populated for that minion, and thus none
    will be returned for it.
Changed in version 2019.2.0
    :conf_minion:`docker.update_mine` now defaults to ``False``

Get all mine data for :py:func:`docker.ps <salt.modules.dockermod.ps_>` and
run an aggregation routine. The ``interfaces`` parameter allows for
specifying the network interfaces from which to select IP addresses. The
``cidrs`` parameter allows for specifying a list of subnets which the IP
address must match.

with_container_id
    Boolean, to expose container_id in the list of results

    New in version 2015.8.2

CLI Example:

    salt '*' mine.get_docker
    salt '*' mine.get_docker interfaces='eth0'
    salt '*' mine.get_docker interfaces='["eth0", "eth1"]'
    salt '*' mine.get_docker cidrs='107.170.147.0/24'
    salt '*' mine.get_docker cidrs='["107.170.147.0/24", "172.17.42.0/24"]'
    salt '*' mine.get_docker interfaces='["eth0", "eth1"]' cidrs='["107.170.147.0/24", "172.17.42.0/24"]'

mine.send:

Send a specific function and its result to the salt mine.
This gets stored in either the local cache, or the salt master's cache.

:param str name: Name of the function to add to the mine.

The following pameters are extracted from kwargs if present:

:param str mine_function: The name of the execution_module.function to run
    and whose value will be stored in the salt mine. Defaults to ``name``.
:param str allow_tgt: Targeting specification for ACL. Specifies which minions
    are allowed to access this function. Please note both your master and
    minion need to be on, at least, version 3000 for this to work properly.

:param str allow_tgt_type: Type of the targeting specification. This value will
    be ignored if ``allow_tgt`` is not specified. Please note both your
    master and minion need to be on, at least, version 3000 for this to work
    properly.

Remaining args and kwargs will be passed on to the function to run.

:rtype: bool
:return: Whether executing the function and storing the information was successful.

Changed in version 3000

    Added ``allow_tgt``- and ``allow_tgt_type``-parameters to specify which
    minions are allowed to access this function.
    See :ref:`targeting` for more information about targeting.

CLI Example:

    salt '*' mine.send network.ip_addrs interface=eth0
    salt '*' mine.send eth0_ip_addrs mine_function=network.ip_addrs interface=eth0
    salt '*' mine.send eth0_ip_addrs mine_function=network.ip_addrs interface=eth0 allow_tgt='G@grain:value' allow_tgt_type=compound

mine.update:

Call the configured functions and send the data back up to the master.
The functions to be called are merged from the master config, pillar and
minion config under the option `mine_functions`:

    mine_functions:
      network.ip_addrs:
        - eth0
      disk.usage: []

This function accepts the following arguments:

:param bool clear: Default: ``False``
    Specifies whether updating will clear the existing values (``True``), or
    whether it will update them (``False``).

:param dict mine_functions:
    Update (or clear, see ``clear``) the mine data on these functions only.
    This will need to have the structure as defined on
    https://docs.saltproject.io/en/latest/topics/mine/index.html#mine-functions

    This feature can be used when updating the mine for functions
    that require a refresh at different intervals than the rest of
    the functions specified under `mine_functions` in the
    minion/master config or pillar.
    A potential use would be together with the `scheduler`, for example:

        schedule:
          lldp_mine_update:
            function: mine.update
            kwargs:
                mine_functions:
                  net.lldp: []
            hours: 12

    In the example above, the mine for `net.lldp` would be refreshed
    every 12 hours, while  `network.ip_addrs` would continue to be updated
    as specified in `mine_interval`.

The function cache will be populated with information from executing these
functions

CLI Example:

    salt '*' mine.update

mine.valid:

List valid entries in mine configuration.

CLI Example:

    salt '*' mine.valid

minion.kill:

Kill the salt minion.

timeout
    int seconds to wait for the minion to die.

If you have a monitor that restarts ``salt-minion`` when it dies then this is
a great way to restart after a minion upgrade.

CLI Example:

    salt minion[12] minion.kill

    minion1:
        ----------
        killed:
            7874
        retcode:
            0
    minion2:
        ----------
        killed:
            29071
        retcode:
            0

The result of the salt command shows the process ID of the minions and the
results of a kill signal to the minion in as the ``retcode`` value: ``0``
is success, anything else is a failure.

minion.list:

Return a list of accepted, denied, unaccepted and rejected keys.
This is the same output as `salt-key -L`

CLI Example:

    salt 'master' minion.list

minion.restart:

Kill and restart the salt minion.

The configuration key ``minion_restart_command`` is an argv list for the
command to restart the minion.  If ``minion_restart_command`` is not
specified or empty then the ``argv`` of the current process will be used.

if the configuration value ``minion_restart_command`` is not set and the
``-d`` (daemonize) argument is missing from ``argv`` then the minion
*will* be killed but will *not* be restarted and will require the parent
process to perform the restart.  This behavior is intended for managed
salt minion processes.

CLI Example:

    salt minion[12] minion.restart

    minion1:
        ----------
        comment:
            - Restart using process argv:
            -     /home/omniture/install/bin/salt-minion
            -     -d
            -     -c
            -     /home/omniture/install/etc/salt
        killed:
            10070
        restart:
            ----------
            stderr:
            stdout:
        retcode:
            0
    minion2:
        ----------
        comment:
            - Using configuration minion_restart_command:
            -     /home/omniture/install/bin/salt-minion
            -     --not-an-option
            -     -d
            -     -c
            -     /home/omniture/install/etc/salt
            - Restart failed
        killed:
            10896
        restart:
            ----------
            stderr:
                Usage: salt-minion

                salt-minion: error: no such option: --not-an-option
            stdout:
        retcode:
            64

The result of the command shows the process ID of ``minion1`` that is
shutdown (killed) and the results of the restart.  If there is a failure
in the restart it will be reflected in a non-zero ``retcode`` and possibly
output in the ``stderr`` and/or ``stdout`` values along with addition
information in the ``comment`` field as is demonstrated with ``minion2``.

modjk.bulk_activate:

Activate all the given workers in the specific load balancer

CLI Examples:

    salt '*' modjk.bulk_activate node1,node2,node3 loadbalancer1
    salt '*' modjk.bulk_activate node1,node2,node3 loadbalancer1 other-profile

    salt '*' modjk.bulk_activate ["node1","node2","node3"] loadbalancer1
    salt '*' modjk.bulk_activate ["node1","node2","node3"] loadbalancer1 other-profile

modjk.bulk_disable:

Disable all the given workers in the specific load balancer

CLI Examples:

    salt '*' modjk.bulk_disable node1,node2,node3 loadbalancer1
    salt '*' modjk.bulk_disable node1,node2,node3 loadbalancer1 other-profile

    salt '*' modjk.bulk_disable ["node1","node2","node3"] loadbalancer1
    salt '*' modjk.bulk_disable ["node1","node2","node3"] loadbalancer1 other-profile

modjk.bulk_recover:

Recover all the given workers in the specific load balancer

CLI Examples:

    salt '*' modjk.bulk_recover node1,node2,node3 loadbalancer1
    salt '*' modjk.bulk_recover node1,node2,node3 loadbalancer1 other-profile

    salt '*' modjk.bulk_recover ["node1","node2","node3"] loadbalancer1
    salt '*' modjk.bulk_recover ["node1","node2","node3"] loadbalancer1 other-profile

modjk.bulk_stop:

Stop all the given workers in the specific load balancer

CLI Examples:

    salt '*' modjk.bulk_stop node1,node2,node3 loadbalancer1
    salt '*' modjk.bulk_stop node1,node2,node3 loadbalancer1 other-profile

    salt '*' modjk.bulk_stop ["node1","node2","node3"] loadbalancer1
    salt '*' modjk.bulk_stop ["node1","node2","node3"] loadbalancer1 other-profile

modjk.dump_config:

Dump the original configuration that was loaded from disk

CLI Examples:

    salt '*' modjk.dump_config
    salt '*' modjk.dump_config other-profile

modjk.get_running:

Get the current running config (not from disk)

CLI Examples:

    salt '*' modjk.get_running
    salt '*' modjk.get_running other-profile

modjk.lb_edit:

Edit the loadbalancer settings

Note: http://tomcat.apache.org/connectors-doc/reference/status.html
Data Parameters for the standard Update Action

CLI Examples:

    salt '*' modjk.lb_edit loadbalancer1 "{'vlr': 1, 'vlt': 60}"
    salt '*' modjk.lb_edit loadbalancer1 "{'vlr': 1, 'vlt': 60}" other-profile

modjk.list_configured_members:

Return a list of member workers from the configuration files

CLI Examples:

    salt '*' modjk.list_configured_members loadbalancer1
    salt '*' modjk.list_configured_members loadbalancer1 other-profile

modjk.recover_all:

Set the all the workers in lbn to recover and activate them if they are not

CLI Examples:

    salt '*' modjk.recover_all loadbalancer1
    salt '*' modjk.recover_all loadbalancer1 other-profile

modjk.reset_stats:

Reset all runtime statistics for the load balancer

CLI Examples:

    salt '*' modjk.reset_stats loadbalancer1
    salt '*' modjk.reset_stats loadbalancer1 other-profile

modjk.version:

Return the modjk version

CLI Examples:

    salt '*' modjk.version
    salt '*' modjk.version other-profile

modjk.worker_activate:

Set the worker to activate state in the lbn load balancer

CLI Examples:

    salt '*' modjk.worker_activate node1 loadbalancer1
    salt '*' modjk.worker_activate node1 loadbalancer1 other-profile

modjk.worker_disable:

Set the worker to disable state in the lbn load balancer

CLI Examples:

    salt '*' modjk.worker_disable node1 loadbalancer1
    salt '*' modjk.worker_disable node1 loadbalancer1 other-profile

modjk.worker_edit:

Edit the worker settings

Note: http://tomcat.apache.org/connectors-doc/reference/status.html
Data Parameters for the standard Update Action

CLI Examples:

    salt '*' modjk.worker_edit node1 loadbalancer1 "{'vwf': 500, 'vwd': 60}"
    salt '*' modjk.worker_edit node1 loadbalancer1 "{'vwf': 500, 'vwd': 60}" other-profile

modjk.worker_recover:

Set the worker to recover
this module will fail if it is in OK state

CLI Examples:

    salt '*' modjk.worker_recover node1 loadbalancer1
    salt '*' modjk.worker_recover node1 loadbalancer1 other-profile

modjk.worker_status:

Return the state of the worker

CLI Examples:

    salt '*' modjk.worker_status node1
    salt '*' modjk.worker_status node1 other-profile

modjk.worker_stop:

Set the worker to stopped state in the lbn load balancer

CLI Examples:

    salt '*' modjk.worker_activate node1 loadbalancer1
    salt '*' modjk.worker_activate node1 loadbalancer1 other-profile

modjk.workers:

Return a list of member workers and their status

CLI Examples:

    salt '*' modjk.workers
    salt '*' modjk.workers other-profile

mount.active:

List the active mounts.

CLI Example:

    salt '*' mount.active

mount.automaster:

List the contents of the auto master

CLI Example:

    salt '*' mount.automaster

mount.delete_mount_cache:

New in version 2018.3.0

Provide information if the path is mounted

CLI Example:

    salt '*' mount.delete_mount_cache /mnt/share

mount.filesystems:

New in version 2018.3.3

List the contents of the filesystems

CLI Example:

    salt '*' mount.filesystems

mount.fstab:

Changed in version 2016.3.2

List the contents of the fstab

CLI Example:

    salt '*' mount.fstab

mount.get_device_from_path:

Return the underlying device for a specified path.

New in version 3006.0

path
    The path for the function to evaluate.

CLI Example:

    salt '*' mount.get_device_from_path /

mount.get_mount_from_path:

Return the mount providing a specified path.

New in version 3006.0

path
    The path for the function to evaluate.

CLI Example:

    salt '*' mount.get_mount_from_path /opt/some/nested/path

mount.is_fuse_exec:

Returns true if the command passed is a fuse mountable application.

CLI Example:

    salt '*' mount.is_fuse_exec sshfs

mount.is_mounted:

New in version 2014.7.0

Provide information if the path is mounted

CLI Example:

    salt '*' mount.is_mounted /mnt/share

mount.mount:

Mount a device

CLI Example:

    salt '*' mount.mount /mnt/foo /dev/sdz1 True

mount.read_mount_cache:

New in version 2018.3.0

Provide information if the path is mounted

CLI Example:

    salt '*' mount.read_mount_cache /mnt/share

mount.remount:

Attempt to remount a device, if the device is not already mounted, mount
is called

CLI Example:

    salt '*' mount.remount /mnt/foo /dev/sdz1 True

mount.rm_automaster:

Remove the mount point from the auto_master

CLI Example:

    salt '*' mount.rm_automaster /mnt/foo /dev/sdg

mount.rm_filesystems:

New in version 2018.3.3

Remove the mount point from the filesystems

CLI Example:

    salt '*' mount.rm_filesystems /mnt/foo /dev/sdg

mount.rm_fstab:

Changed in version 2016.3.2

Remove the mount point from the fstab

CLI Example:

    salt '*' mount.rm_fstab /mnt/foo /dev/sdg

mount.rm_vfstab:

New in version 2016.3.2

Remove the mount point from the vfstab

CLI Example:

    salt '*' mount.rm_vfstab /mnt/foo /device/c0t0d0p0

mount.set_automaster:

Verify that this mount is represented in the auto_salt, change the mount
to match the data passed, or add the mount if it is not present.

CLI Example:

    salt '*' mount.set_automaster /mnt/foo /dev/sdz1 ext4

mount.set_filesystems:

New in version 2018.3.3

Verify that this mount is represented in the filesystems, change the mount
to match the data passed, or add the mount if it is not present on AIX

If the entry is found via `match_on` and `not_change` is True, the
current line will be preserved.

    Provide information if the path is mounted

:param name:          The name of the mount point where the device is mounted.
:param device:        The device that is being mounted.
:param vfstype:       The file system that is used (AIX has two fstypes, fstype and vfstype - similar to Linux fstype)
:param opts:          Additional options used when mounting the device.
:param mount:         Mount if not mounted, default True.
:param config:        Configuration file, default /etc/filesystems.
:param match:         File systems type to match on, default auto

CLI Example:

    salt '*' mount.set_filesystems /mnt/foo /dev/sdz1 jfs2

mount.set_fstab:

Verify that this mount is represented in the fstab, change the mount
to match the data passed, or add the mount if it is not present.

If the entry is found via `match_on` and `not_change` is True, the
current line will be preserved.

CLI Example:

    salt '*' mount.set_fstab /mnt/foo /dev/sdz1 ext4

mount.set_vfstab:

New in version 2016.3.2

Verify that this mount is represented in the fstab, change the mount
to match the data passed, or add the mount if it is not present.

If the entry is found via `match_on` and `not_change` is True, the
current line will be preserved.

CLI Example:

    salt '*' mount.set_vfstab /mnt/foo /device/c0t0d0p0 ufs

mount.swapoff:

Deactivate a named swap mount

Changed in version 2016.3.2

CLI Example:

    salt '*' mount.swapoff /root/swapfile

mount.swapon:

Activate a swap disk

Changed in version 2016.3.2

CLI Example:

    salt '*' mount.swapon /root/swapfile

mount.swaps:

Return a dict containing information on active swap

Changed in version 2016.3.2

CLI Example:

    salt '*' mount.swaps

mount.umount:

Attempt to unmount a device by specifying the directory it is mounted on

CLI Example:

    salt '*' mount.umount /mnt/foo

New in version 2015.5.0

    salt '*' mount.umount /mnt/foo /dev/xvdc1

mount.vfstab:

New in version 2016.3.2

List the contents of the vfstab

CLI Example:

    salt '*' mount.vfstab

mount.write_mount_cache:

New in version 2018.3.0

Provide information if the path is mounted

:param real_name:     The real name of the mount point where the device is mounted.
:param device:        The device that is being mounted.
:param mkmnt:         Whether or not the mount point should be created.
:param fstype:        The file system that is used.
:param mount_opts:    Additional options used when mounting the device.
:return:              Boolean if message was sent successfully.

CLI Example:

    salt '*' mount.write_mount_cache /mnt/share /dev/sda1 False ext4 defaults,nosuid

msteams.post_card:

Send a message to an MS Teams channel.
:param message:     The message to send to the MS Teams channel.
:param hook_url:    The Teams webhook URL, if not specified in the configuration.
:param title:       Optional title for the posted card
:param theme_color:  Optional hex color highlight for the posted card
:return:            Boolean if message was sent successfully.

CLI Example:

    salt '*' msteams.post_card message="Build is done"

nagios_rpc.host_status:

Check status of a particular host By default
statuses are returned in a numeric format.

Parameters:

hostname
    The hostname to check the status of the service in Nagios.

numeric
    Turn to false in order to return status in text format
    ('OK' instead of 0, 'Warning' instead of 1 etc)

:return: status:     'OK', 'Warning', 'Critical' or 'Unknown'

CLI Example:

    salt '*' nagios_rpc.host_status hostname=webserver.domain.com
    salt '*' nagios_rpc.host_status hostname=webserver.domain.com numeric=False

nagios_rpc.service_status:

Check status of a particular service on a host on it in Nagios.
By default statuses are returned in a numeric format.

Parameters:

hostname
    The hostname to check the status of the service in Nagios.

service
    The service to check the status of in Nagios.

numeric
    Turn to false in order to return status in text format
    ('OK' instead of 0, 'Warning' instead of 1 etc)

:return: status:     'OK', 'Warning', 'Critical' or 'Unknown'

CLI Example:

    salt '*' nagios_rpc.service_status hostname=webserver.domain.com service='HTTP'
    salt '*' nagios_rpc.service_status hostname=webserver.domain.com service='HTTP' numeric=False

namecheap_domains.check:

Checks the availability of domains

domains_to_check
    array of strings  List of domains to check

Returns a dictionary mapping the each domain name to a boolean denoting
whether or not it is available.

CLI Example:

    salt 'my-minion' namecheap_domains.check domain-to-check

namecheap_domains.create:

Try to register the specified domain name

domain_name
    The domain name to be registered

years
    Number of years to register

Returns the following information:

- Whether or not the domain was renewed successfully
- Whether or not WhoisGuard is enabled
- Whether or not registration is instant
- The amount charged for registration
- The domain ID
- The order ID
- The transaction ID

CLI Example:

    salt 'my-minion' namecheap_domains.create my-domain-name 2

namecheap_domains.get_info:

Returns information about the requested domain

returns a dictionary of information about the domain_name

domain_name
    string  Domain name to get information about

CLI Example:

    salt 'my-minion' namecheap_domains.get_info my-domain-name

namecheap_domains.get_list:

Returns a list of domains for the particular user as a list of objects
offset by ``page`` length of ``page_size``

list_type : ALL
    One of ``ALL``, ``EXPIRING``, ``EXPIRED``

search_term
    Keyword to look for on the domain list

page : 1
    Number of result page to return

page_size : 20
    Number of domains to be listed per page (minimum: ``10``, maximum:
    ``100``)

sort_by
    One of ``NAME``, ``NAME_DESC``, ``EXPIREDATE``, ``EXPIREDATE_DESC``,
    ``CREATEDATE``, or ``CREATEDATE_DESC``

CLI Example:

    salt 'my-minion' namecheap_domains.get_list

namecheap_domains.get_tld_list:

Returns a list of TLDs as objects

CLI Example:

    salt 'my-minion' namecheap_domains.get_tld_list

namecheap_domains.reactivate:

Try to reactivate the expired domain name

Returns the following information:

- Whether or not the domain was reactivated successfully
- The amount charged for reactivation
- The order ID
- The transaction ID

CLI Example:

    salt 'my-minion' namecheap_domains.reactivate my-domain-name

namecheap_domains.renew:

Try to renew the specified expiring domain name for a specified number of years

domain_name
    The domain name to be renewed

years
    Number of years to renew

Returns the following information:

- Whether or not the domain was renewed successfully
- The domain ID
- The order ID
- The transaction ID
- The amount charged for renewal

CLI Example:

    salt 'my-minion' namecheap_domains.renew my-domain-name 5

namecheap_domains_dns.get_hosts:

Retrieves DNS host record settings for the requested domain.

returns a dictionary of information about the requested domain

sld
    SLD of the domain name

tld
    TLD of the domain name

CLI Example:

    salt 'my-minion' namecheap_domains_dns.get_hosts sld tld

namecheap_domains_dns.get_list:

Gets a list of DNS servers associated with the requested domain.

returns a dictionary of information about requested domain

sld
    SLD of the domain name

tld
    TLD of the domain name

CLI Example:

    salt 'my-minion' namecheap_domains_dns.get_list sld tld

namecheap_domains_dns.set_custom:

Sets domain to use custom DNS servers.

returns True if the custom nameservers were set successfully

sld
    SLD of the domain name

tld
    TLD of the domain name

nameservers
    array of strings  List of nameservers to be associated with this domain

CLI Example:

    salt 'my-minion' namecheap_domains_dns.set_custom sld tld nameserver

namecheap_domains_dns.set_default:

Sets domain to use namecheap default DNS servers. Required for free
services like Host record management, URL forwarding, email forwarding,
dynamic DNS and other value added services.

sld
    SLD of the domain name

tld
    TLD of the domain name

Returns ``True`` if the domain was successfully pointed at the default DNS
servers.

CLI Example:

    salt 'my-minion' namecheap_domains_dns.set_default sld tld

namecheap_domains_dns.set_hosts:

Sets DNS host records settings for the requested domain.

returns True if the host records were set successfully

sld
    SLD of the domain name

tld
    TLD of the domain name

hosts
    Must be passed as a list of Python dictionaries, with each dictionary
    containing the following keys:

    - **hostname**
    - **recordtype** - One of ``A``, ``AAAA``, ``CNAME``, ``MX``, ``MXE``,
      ``TXT``, ``URL``, ``URL301``, or ``FRAME``
    - **address** - URL or IP address
    - **ttl** - An integer between 60 and 60000 (default: ``1800``)

    Additionally, the ``mxpref`` key can be present, but must be accompanied
    by an ``emailtype`` key.

CLI Example:

    salt 'my-minion' namecheap_domains_dns.set_hosts sld tld hosts

namecheap_domains_ns.create:

Creates a new nameserver. Returns ``True`` if the nameserver was created
successfully.

sld
    SLD of the domain name

tld
    TLD of the domain name

nameserver
    Nameserver to create

ip
    Nameserver IP address

CLI Example:

    salt '*' namecheap_domains_ns.create sld tld nameserver ip

namecheap_domains_ns.delete:

Deletes a nameserver. Returns ``True`` if the nameserver was deleted
successfully

sld
    SLD of the domain name

tld
    TLD of the domain name

nameserver
    Nameserver to delete

CLI Example:

    salt '*' namecheap_domains_ns.delete sld tld nameserver

namecheap_domains_ns.get_info:

Retrieves information about a registered nameserver. Returns the following
information:

- IP Address set for the nameserver
- Domain name which was queried
- A list of nameservers and their statuses

sld
    SLD of the domain name

tld
    TLD of the domain name

nameserver
    Nameserver to retrieve

CLI Example:

    salt '*' namecheap_domains_ns.get_info sld tld nameserver

namecheap_domains_ns.update:

Deletes a nameserver. Returns ``True`` if the nameserver was updated
successfully.

sld
    SLD of the domain name

tld
    TLD of the domain name

nameserver
    Nameserver to create

old_ip
    Current ip address

new_ip
    New ip address

CLI Example:

    salt '*' namecheap_domains_ns.update sld tld nameserver old_ip new_ip

namecheap_ssl.activate:

Activates a newly-purchased SSL certificate. Returns a dictionary of result
values.

csr_file
    Path to Certificate Signing Request file

certificate_id
    Unique ID of the SSL certificate you wish to activate

web_server_type
    The type of certificate format to return. Possible values include:

    - apache2
    - apacheapachessl
    - apacheopenssl
    - apacheraven
    - apachessl
    - apachessleay
    - c2net
    - cobaltseries
    - cpanel
    - domino
    - dominogo4625
    - dominogo4626
    - ensim
    - hsphere
    - ibmhttp
    - iis
    - iis4
    - iis5
    - iplanet
    - ipswitch
    - netscape
    - other
    - plesk
    - tomcat
    - weblogic
    - website
    - webstar
    - zeusv3

approver_email
    The email ID which is on the approver email list.

    Note:
        ``http_dc_validation`` must be set to ``False`` if this option is
        used.

http_dc_validation : False
    Whether or not to activate using HTTP-based validation.

Note:
    For other parameters which may be required, see here__.

    .. __: https://www.namecheap.com/support/api/methods/ssl/activate.aspx

CLI Example:

    salt 'my-minion' namecheap_ssl.activate my-csr-file my-cert-id apachessl

namecheap_ssl.create:

Creates a new SSL certificate. Returns the following information:

- Whether or not the SSL order was successful
- The certificate ID
- The order ID
- The transaction ID
- The amount charged for the order
- The date on which the certificate was created
- The date on which the certificate will expire
- The type of SSL certificate
- The number of years for which the certificate was purchased
- The current status of the SSL certificate

years : 1
    Number of years to register

certificate_type
    Type of SSL Certificate. Possible values include:

    - EV Multi Domain SSL
    - EV SSL
    - EV SSL SGC
    - EssentialSSL
    - EssentialSSL Wildcard
    - InstantSSL
    - InstantSSL Pro
    - Multi Domain SSL
    - PositiveSSL
    - PositiveSSL Multi Domain
    - PositiveSSL Wildcard
    - PremiumSSL
    - PremiumSSL Wildcard
    - QuickSSL Premium
    - RapidSSL
    - RapidSSL Wildcard
    - SGC Supercert
    - SSL Web Server
    - SSL Webserver EV
    - SSL123
    - Secure Site
    - Secure Site Pro
    - Secure Site Pro with EV
    - Secure Site with EV
    - True BusinessID
    - True BusinessID Multi Domain
    - True BusinessID Wildcard
    - True BusinessID with EV
    - True BusinessID with EV Multi Domain
    - Unified Communications

promotional_code
    An optional promo code to use when creating the certificate

sans_to_add : 0
    This parameter defines the number of add-on domains to be purchased in
    addition to the default number of domains included with a multi-domain
    certificate. Each certificate that supports SANs has the default number
    of domains included. You may check the default number of domains
    included and the maximum number of domains that can be added to it in
    the table below.

+----------+----------------+----------------------+-------------------+----------------+
| Provider | Product name   | Default number of    | Maximum number of | Maximum number |
|          |                | domains (domain from | total domains     | of domains     |
|          |                | CSR is counted here) |                   | that can be    |
|          |                |                      |                   | passed in      |
|          |                |                      |                   | sans_to_add    |
|          |                |                      |                   | parameter      |
+----------+----------------+----------------------+-------------------+----------------+
| Comodo   | PositiveSSL    | 3                    | 100               | 97             |
|          | Multi-Domain   |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| Comodo   | Multi-Domain   | 3                    | 100               | 97             |
|          | SSL            |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| Comodo   | EV Multi-      | 3                    | 100               | 97             |
|          | Domain SSL     |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| Comodo   | Unified        | 3                    | 100               | 97             |
|          | Communications |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| GeoTrust | QuickSSL       | 1                    | 1 domain +        | The only       |
|          | Premium        |                      | 4 subdomains      | supported      |
|          |                |                      |                   | value is 4     |
+----------+----------------+----------------------+-------------------+----------------+
| GeoTrust | True           | 5                    | 25                | 20             |
|          | BusinessID     |                      |                   |                |
|          | with EV        |                      |                   |                |
|          | Multi-Domain   |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| GeoTrust | True Business  | 5                    | 25                | 20             |
|          | ID Multi-      |                      |                   |                |
|          | Domain         |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| Thawte   | SSL Web        | 1                    | 25                | 24             |
|          | Server         |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| Thawte   | SSL Web        | 1                    | 25                | 24             |
|          | Server with    |                      |                   |                |
|          | EV             |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| Thawte   | SGC Supercerts | 1                    | 25                | 24             |
+----------+----------------+----------------------+-------------------+----------------+
| Symantec | Secure Site    | 1                    | 25                | 24             |
|          | Pro with EV    |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| Symantec | Secure Site    | 1                    | 25                | 24             |
|          | with EV        |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+
| Symantec | Secure Site    | 1                    | 25                | 24             |
+----------+----------------+----------------------+-------------------+----------------+
| Symantec | Secure Site    | 1                    | 25                | 24             |
|          | Pro            |                      |                   |                |
+----------+----------------+----------------------+-------------------+----------------+

CLI Example:

    salt 'my-minion' namecheap_ssl.create 2 RapidSSL

namecheap_ssl.get_info:

Retrieves information about the requested SSL certificate. Returns a
dictionary of information about the SSL certificate with two keys:

- **ssl** - Contains the metadata information
- **certificate** - Contains the details for the certificate such as the
  CSR, Approver, and certificate data

certificate_id
    Unique ID of the SSL certificate

returncertificate : False
    Set to ``True`` to ask for the certificate in response

returntype
    Optional type for the returned certificate. Can be either "Individual"
    (for X.509 format) or "PKCS7"

    Note:
        Required if ``returncertificate`` is ``True``

CLI Example:

    salt 'my-minion' namecheap_ssl.get_info my-cert-id

namecheap_ssl.get_list:

Returns a list of SSL certificates for a particular user

ListType : All
    Possible values:

    - All
    - Processing
    - EmailSent
    - TechnicalProblem
    - InProgress
    - Completed
    - Deactivated
    - Active
    - Cancelled
    - NewPurchase
    - NewRenewal

    SearchTerm
        Keyword to look for on the SSL list

    Page : 1
        Page number to return

    PageSize : 20
        Total number of SSL certificates to display per page (minimum:
        ``10``, maximum: ``100``)

    SoryBy
        One of ``PURCHASEDATE``, ``PURCHASEDATE_DESC``, ``SSLTYPE``,
        ``SSLTYPE_DESC``, ``EXPIREDATETIME``, ``EXPIREDATETIME_DESC``,
        ``Host_Name``, or ``Host_Name_DESC``

CLI Example:

    salt 'my-minion' namecheap_ssl.get_list Processing

namecheap_ssl.parse_csr:

Parses the CSR. Returns a dictionary of result values.

csr_file
    Path to Certificate Signing Request file

certificate_type
    Type of SSL Certificate. Possible values include:

    - EV Multi Domain SSL
    - EV SSL
    - EV SSL SGC
    - EssentialSSL
    - EssentialSSL Wildcard
    - InstantSSL
    - InstantSSL Pro
    - Multi Domain SSL
    - PositiveSSL
    - PositiveSSL Multi Domain
    - PositiveSSL Wildcard
    - PremiumSSL
    - PremiumSSL Wildcard
    - QuickSSL Premium
    - RapidSSL
    - RapidSSL Wildcard
    - SGC Supercert
    - SSL Web Server
    - SSL Webserver EV
    - SSL123
    - Secure Site
    - Secure Site Pro
    - Secure Site Pro with EV
    - Secure Site with EV
    - True BusinessID
    - True BusinessID Multi Domain
    - True BusinessID Wildcard
    - True BusinessID with EV
    - True BusinessID with EV Multi Domain
    - Unified Communications

http_dc_validation : False
    Set to ``True`` if a Comodo certificate and validation should be
    done with files instead of emails and to return the info to do so

CLI Example:

    salt 'my-minion' namecheap_ssl.parse_csr my-csr-file PremiumSSL

namecheap_ssl.reissue:

Reissues a purchased SSL certificate. Returns a dictionary of result
values.

csr_file
    Path to Certificate Signing Request file

certificate_id
    Unique ID of the SSL certificate you wish to activate

web_server_type
    The type of certificate format to return. Possible values include:

    - apache2
    - apacheapachessl
    - apacheopenssl
    - apacheraven
    - apachessl
    - apachessleay
    - c2net
    - cobaltseries
    - cpanel
    - domino
    - dominogo4625
    - dominogo4626
    - ensim
    - hsphere
    - ibmhttp
    - iis
    - iis4
    - iis5
    - iplanet
    - ipswitch
    - netscape
    - other
    - plesk
    - tomcat
    - weblogic
    - website
    - webstar
    - zeusv3

approver_email
    The email ID which is on the approver email list.

    Note:
        ``http_dc_validation`` must be set to ``False`` if this option is
        used.

http_dc_validation : False
    Whether or not to activate using HTTP-based validation.

Note:
    For other parameters which may be required, see here__.

    .. __: https://www.namecheap.com/support/api/methods/ssl/reissue.aspx

CLI Example:

    salt 'my-minion' namecheap_ssl.reissue my-csr-file my-cert-id apachessl

namecheap_ssl.renew:

Renews an SSL certificate if it is ACTIVE and Expires <= 30 days. Returns
the following information:

- The certificate ID
- The order ID
- The transaction ID
- The amount charged for the order

years : 1
    Number of years to register

certificate_id
    Unique ID of the SSL certificate you wish to renew

certificate_type
    Type of SSL Certificate. Possible values include:

    - EV Multi Domain SSL
    - EV SSL
    - EV SSL SGC
    - EssentialSSL
    - EssentialSSL Wildcard
    - InstantSSL
    - InstantSSL Pro
    - Multi Domain SSL
    - PositiveSSL
    - PositiveSSL Multi Domain
    - PositiveSSL Wildcard
    - PremiumSSL
    - PremiumSSL Wildcard
    - QuickSSL Premium
    - RapidSSL
    - RapidSSL Wildcard
    - SGC Supercert
    - SSL Web Server
    - SSL Webserver EV
    - SSL123
    - Secure Site
    - Secure Site Pro
    - Secure Site Pro with EV
    - Secure Site with EV
    - True BusinessID
    - True BusinessID Multi Domain
    - True BusinessID Wildcard
    - True BusinessID with EV
    - True BusinessID with EV Multi Domain
    - Unified Communications

promotional_code
    An optional promo code to use when renewing the certificate

CLI Example:

    salt 'my-minion' namecheap_ssl.renew 1 my-cert-id RapidSSL

namecheap_users.check_balances:

Checks if the provided minimum value is present in the user's account.

Returns a boolean. Returns ``False`` if the user's account balance is less
than the provided minimum or ``True`` if greater than the minimum.

minimum : 100
    The value to check

CLI Example:

    salt 'my-minion' namecheap_users.check_balances
    salt 'my-minion' namecheap_users.check_balances minimum=150

namecheap_users.get_balances:

Gets information about fund in the user's account. This method returns the
following information: Available Balance, Account Balance, Earned Amount,
Withdrawable Amount and Funds Required for AutoRenew.

Note:
    If a domain setup with automatic renewal is expiring within the next 90
    days, the FundsRequiredForAutoRenew attribute shows the amount needed
    in your Namecheap account to complete auto renewal.

CLI Example:

    salt 'my-minion' namecheap_users.get_balances

network.active_tcp:

Return a dict containing information on all of the running TCP connections (currently linux and solaris only)

Changed in version 2015.8.4

    Added support for SunOS

CLI Example:

    salt '*' network.active_tcp

network.arp:

Return the arp table from the minion

Changed in version 2015.8.0
    Added support for SunOS

CLI Example:

    salt '*' network.arp

network.calc_net:

Returns the CIDR of a subnet based on
an IP address (CIDR notation supported)
and optional netmask.

CLI Example:

    salt '*' network.calc_net 172.17.0.5 255.255.255.240
    salt '*' network.calc_net 2a02:f6e:a000:80:84d8:8332:7866:4e07/64

New in version 2015.8.0

network.connect:

Test connectivity to a host using a particular
port from the minion.

New in version 2014.7.0

CLI Example:

    salt '*' network.connect archlinux.org 80

    salt '*' network.connect archlinux.org 80 timeout=3

    salt '*' network.connect archlinux.org 80 timeout=3 family=ipv4

    salt '*' network.connect google-public-dns-a.google.com port=53 proto=udp timeout=3

network.convert_cidr:

returns the network address, subnet mask and broadcast address of a cidr address

New in version 2016.3.0

CLI Example:

    salt '*' network.convert_cidr 172.31.0.0/16

network.default_route:

Return default route(s) from routing table

Changed in version 2015.8.0
    Added support for SunOS (Solaris 10, Illumos, SmartOS)

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' network.default_route

network.dig:

Performs a DNS lookup with dig

CLI Example:

    salt '*' network.dig archlinux.org

network.fqdns:

Return all known FQDNs for the system by enumerating all interfaces and
then trying to reverse resolve them (excluding 'lo' interface).

CLI Example:

    salt '*' network.fqdns

network.get_bufsize:

Return network buffer sizes as a dict (currently linux only)

CLI Example:

    salt '*' network.get_bufsize eth0

network.get_fqdn:

Get fully qualified domain name

CLI Example:

    salt '*' network.get_fqdn

network.get_hostname:

Get hostname

CLI Example:

    salt '*' network.get_hostname

network.get_route:

Return routing information for given destination ip

New in version 2015.5.3

Changed in version 2015.8.0
    Added support for SunOS (Solaris 10, Illumos, SmartOS)
    Added support for OpenBSD

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' network.get_route 10.10.10.10

network.hw_addr:

Return the hardware address (a.k.a. MAC address) for a given interface

CLI Example:

    salt '*' network.hw_addr eth0

network.hwaddr:

This function is an alias of hw_addr.

Return the hardware address (a.k.a. MAC address) for a given interface

CLI Example:

    salt '*' network.hw_addr eth0

network.ifacestartswith:

Retrieve the interface name from a specific CIDR

New in version 2016.11.0

CLI Example:

    salt '*' network.ifacestartswith 10.0

network.in_subnet:

Returns True if host is within specified subnet, otherwise False.

CLI Example:

    salt '*' network.in_subnet 10.0.0.0/16

network.interface:

Return the inet address for a given interface

New in version 2014.7.0

CLI Example:

    salt '*' network.interface eth0

network.interface_ip:

Return the inet address for a given interface

New in version 2014.7.0

CLI Example:

    salt '*' network.interface_ip eth0

network.interfaces:

Return a dictionary of information about all the interfaces on the minion

CLI Example:

    salt '*' network.interfaces

network.ip_addrs:

Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is
ignored, unless 'include_loopback=True' is indicated. If 'interface' is
provided, then only IP addresses from that interface will be returned.
Providing a CIDR via 'cidr="10.0.0.0/8"' will return only the addresses
which are within that subnet. If 'type' is 'public', then only public
addresses will be returned. Ditto for 'type'='private'.

Changed in version 3001
    ``interface`` can now be a single interface name or a list of
    interfaces. Globbing is also supported.

CLI Example:

    salt '*' network.ip_addrs

network.ip_addrs6:

Returns a list of IPv6 addresses assigned to the host. ::1 is ignored,
unless 'include_loopback=True' is indicated. If 'interface' is provided,
then only IP addresses from that interface will be returned.
Providing a CIDR via 'cidr="2000::/3"' will return only the addresses
which are within that subnet.

Changed in version 3001
    ``interface`` can now be a single interface name or a list of
    interfaces. Globbing is also supported.

CLI Example:

    salt '*' network.ip_addrs6

network.ip_in_subnet:

Returns True if given IP is within specified subnet, otherwise False.

CLI Example:

    salt '*' network.ip_in_subnet 172.17.0.4 172.16.0.0/12

network.ip_neighs:

Return the ip neighbour (arp) table from the minion for IPv4 addresses

New in version 3007.0

CLI Example:

    salt '*' network.ip_neighs

network.ip_neighs6:

Return the ip neighbour (arp) table from the minion for IPv6 addresses

New in version 3007.0

CLI Example:

    salt '*' network.ip_neighs6

network.ip_networks:

New in version 3001

Returns a list of IPv4 networks to which the minion belongs.

interface
    Restrict results to the specified interface(s). This value can be
    either a single interface name or a list of interfaces. Globbing is
    also supported.

CLI Example:

    salt '*' network.ip_networks
    salt '*' network.ip_networks interface=docker0
    salt '*' network.ip_networks interface=docker0,enp*
    salt '*' network.ip_networks interface=eth*

network.ip_networks6:

New in version 3001

Returns a list of IPv6 networks to which the minion belongs.

interface
    Restrict results to the specified interface(s). This value can be
    either a single interface name or a list of interfaces. Globbing is
    also supported.

CLI Example:

    salt '*' network.ip_networks6
    salt '*' network.ip_networks6 interface=docker0
    salt '*' network.ip_networks6 interface=docker0,enp*
    salt '*' network.ip_networks6 interface=eth*

network.ipaddrs:

This function is an alias of ip_addrs.

Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is
ignored, unless 'include_loopback=True' is indicated. If 'interface' is
provided, then only IP addresses from that interface will be returned.
Providing a CIDR via 'cidr="10.0.0.0/8"' will return only the addresses
which are within that subnet. If 'type' is 'public', then only public
addresses will be returned. Ditto for 'type'='private'.

Changed in version 3001
    ``interface`` can now be a single interface name or a list of
    interfaces. Globbing is also supported.

CLI Example:

    salt '*' network.ip_addrs

network.ipaddrs6:

This function is an alias of ip_addrs6.

Returns a list of IPv6 addresses assigned to the host. ::1 is ignored,
unless 'include_loopback=True' is indicated. If 'interface' is provided,
then only IP addresses from that interface will be returned.
Providing a CIDR via 'cidr="2000::/3"' will return only the addresses
which are within that subnet.

Changed in version 3001
    ``interface`` can now be a single interface name or a list of
    interfaces. Globbing is also supported.

CLI Example:

    salt '*' network.ip_addrs6

network.iphexval:

Retrieve the hexadecimal representation of an IP address

New in version 2016.11.0

CLI Example:

    salt '*' network.iphexval 10.0.0.1

network.ipneighs:

This function is an alias of ip_neighs.

Return the ip neighbour (arp) table from the minion for IPv4 addresses

New in version 3007.0

CLI Example:

    salt '*' network.ip_neighs

network.ipneighs6:

This function is an alias of ip_neighs6.

Return the ip neighbour (arp) table from the minion for IPv6 addresses

New in version 3007.0

CLI Example:

    salt '*' network.ip_neighs6

network.is_loopback:

Check if the given IP address is a loopback address

New in version 2014.7.0
Changed in version 2015.8.0
    IPv6 support

CLI Example:

    salt '*' network.is_loopback 127.0.0.1

network.is_private:

Check if the given IP address is a private address

New in version 2014.7.0
Changed in version 2015.8.0
    IPv6 support

CLI Example:

    salt '*' network.is_private 10.0.0.3

network.mod_bufsize:

Modify network interface buffers (currently linux only)

CLI Example:

    salt '*' network.mod_bufsize tx=<val> rx=<val> rx-mini=<val> rx-jumbo=<val>

network.mod_hostname:

Modify hostname

Changed in version 2015.8.0
    Added support for SunOS (Solaris 10, Illumos, SmartOS)

CLI Example:

    salt '*' network.mod_hostname master.saltstack.com

network.netstat:

Return information on open ports and states

Note:
    On BSD minions, the output contains PID info (where available) for each
    netstat entry, fetched from sockstat/fstat output.

Changed in version 2014.1.4
    Added support for OpenBSD, FreeBSD, and NetBSD

Changed in version 2015.8.0
    Added support for SunOS

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' network.netstat

network.ping:

Performs an ICMP ping to a host

Changed in version 2015.8.0
    Added support for SunOS

CLI Example:

    salt '*' network.ping archlinux.org

New in version 2015.5.0

Return a True or False instead of ping output.

    salt '*' network.ping archlinux.org return_boolean=True

Set the time to wait for a response in seconds.

    salt '*' network.ping archlinux.org timeout=3

network.reverse_ip:

Returns the reversed IP address

Changed in version 2015.8.0
    IPv6 support

CLI Example:

    salt '*' network.reverse_ip 172.17.0.4

network.routes:

Return currently configured routes from routing table

Changed in version 2015.8.0
    Added support for SunOS (Solaris 10, Illumos, SmartOS)

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' network.routes

network.subnets:

Returns a list of IPv4 subnets to which the host belongs

CLI Example:

    salt '*' network.subnets
    salt '*' network.subnets interfaces=eth1

network.subnets6:

Returns a list of IPv6 subnets to which the host belongs

CLI Example:

    salt '*' network.subnets

network.traceroute:

Performs a traceroute to a 3rd party host

Changed in version 2015.8.0
    Added support for SunOS

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' network.traceroute archlinux.org

network.wol:

Send Wake On Lan packet to a host

CLI Example:

    salt '*' network.wol 08-00-27-13-69-77
    salt '*' network.wol 080027136977 255.255.255.255 7
    salt '*' network.wol 08:00:27:13:69:77 255.255.255.255 7

nexus.get_latest_release:

Gets the latest release of the artifact

nexus_url
    URL of nexus instance
repository
    Release repository in nexus to retrieve artifact from, for example: libs-releases
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
target_dir
    Target directory to download artifact to (default: /tmp)
target_file
    Target file to download artifact to (by default it is target_dir/artifact_id-version.packaging)
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    nexus username. Optional parameter.
password
    nexus password. Optional parameter.

nexus.get_latest_snapshot:

Gets latest snapshot of the given artifact

nexus_url
    URL of nexus instance
repository
    Snapshot repository in nexus to retrieve artifact from, for example: libs-snapshots
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
target_dir
    Target directory to download artifact to (default: /tmp)
target_file
    Target file to download artifact to (by default it is target_dir/artifact_id-snapshot_version.packaging)
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    nexus username. Optional parameter.
password
    nexus password. Optional parameter.

nexus.get_release:

Gets the specified release of the artifact

nexus_url
    URL of nexus instance
repository
    Release repository in nexus to retrieve artifact from, for example: libs-releases
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
version
    Version of the artifact
target_dir
    Target directory to download artifact to (default: /tmp)
target_file
    Target file to download artifact to (by default it is target_dir/artifact_id-version.packaging)
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    nexus username. Optional parameter.
password
    nexus password. Optional parameter.

nexus.get_snapshot:

Gets snapshot of the desired version of the artifact

nexus_url
    URL of nexus instance
repository
    Snapshot repository in nexus to retrieve artifact from, for example: libs-snapshots
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
version
    Version of the artifact
target_dir
    Target directory to download artifact to (default: /tmp)
target_file
    Target file to download artifact to (by default it is target_dir/artifact_id-snapshot_version.packaging)
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    nexus username. Optional parameter.
password
    nexus password. Optional parameter.

nexus.get_snapshot_version_string:

Gets the specific version string of a snapshot of the desired version of the artifact

nexus_url
    URL of nexus instance
repository
    Snapshot repository in nexus to retrieve artifact from, for example: libs-snapshots
group_id
    Group Id of the artifact
artifact_id
    Artifact Id of the artifact
packaging
    Packaging type (jar,war,ear,etc)
version
    Version of the artifact
classifier
    Artifact classifier name (ex: sources,javadoc,etc). Optional parameter.
username
    nexus username. Optional parameter.
password
    nexus password. Optional parameter.

nftables.append:

Append a rule to the specified table & chain.

This function accepts a rule in a standard nftables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

CLI Example:

    salt '*' nftables.append filter input \
        rule='tcp dport 22 log accept'

    IPv6:
    salt '*' nftables.append filter input \
        rule='tcp dport 22 log accept' \
        family=ipv6

nftables.build_rule:

Build a well-formatted nftables rule based on kwargs.
A `table` and `chain` are not required, unless `full` is True.

If `full` is `True`, then `table`, `chain` and `command` are required.
`command` may be specified as either insert, append, or delete.
This will return the nftables command, exactly as it would
be used from the command line.

If a position is required (as with `insert` or `delete`), it may be specified as
`position`. This will only be useful if `full` is True.

If `connstate` is passed in, it will automatically be changed to `state`.

CLI Examples:

    salt '*' nftables.build_rule match=state \
        connstate=RELATED,ESTABLISHED jump=ACCEPT
    salt '*' nftables.build_rule filter input command=insert position=3 \
        full=True match=state state=related,established jump=accept

    IPv6:
    salt '*' nftables.build_rule match=state \
        connstate=related,established jump=accept \
        family=ipv6
    salt '*' nftables.build_rule filter input command=insert position=3 \
        full=True match=state state=related,established jump=accept \
        family=ipv6

nftables.check:

Check for the existence of a rule in the table and chain

This function accepts a rule in a standard nftables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

CLI Example:

    salt '*' nftables.check filter input \
        rule='tcp dport 22 log accept'

    IPv6:
    salt '*' nftables.check filter input \
        rule='tcp dport 22 log accept' \
        family=ipv6

nftables.check_chain:

New in version 2014.7.0

Check for the existence of a chain in the table

CLI Example:

    salt '*' nftables.check_chain filter input

    IPv6:
    salt '*' nftables.check_chain filter input family=ipv6

nftables.check_table:

Check for the existence of a table

CLI Example:

    salt '*' nftables.check_table nat

nftables.delete:

Delete a rule from the specified table & chain, specifying either the rule
    in its entirety, or the rule's position in the chain.

This function accepts a rule in a standard nftables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

CLI Examples:

    salt '*' nftables.delete filter input position=3

    salt '*' nftables.delete filter input \
        rule='tcp dport 22 log accept'

    IPv6:
    salt '*' nftables.delete filter input position=3 family=ipv6

    salt '*' nftables.delete filter input \
        rule='tcp dport 22 log accept' \
        family=ipv6

nftables.delete_chain:

New in version 2014.7.0

Delete the chain from the specified table.

CLI Example:

    salt '*' nftables.delete_chain filter input

    salt '*' nftables.delete_chain filter foo

    IPv6:
    salt '*' nftables.delete_chain filter input family=ipv6

    salt '*' nftables.delete_chain filter foo family=ipv6

nftables.delete_table:

New in version 2014.7.0

Create new custom table.

CLI Example:

    salt '*' nftables.delete_table filter

    IPv6:
    salt '*' nftables.delete_table filter family=ipv6

nftables.flush:

Flush the chain in the specified table, flush all chains in the specified
table if chain is not specified.

CLI Example:

    salt '*' nftables.flush filter

    salt '*' nftables.flush filter input

    IPv6:
    salt '*' nftables.flush filter input family=ipv6

nftables.get_policy:

New in version 3002

Return the current policy for the specified table/chain

table
    Name of the table containing the chain to check

chain
    Name of the chain to get the policy for

family
    Networking family, either ipv4 or ipv6

CLI Example:

    salt '*' nftables.get_policy filter input

    IPv6:
    salt '*' nftables.get_policy filter input family=ipv6

nftables.get_rule_handle:

Get the handle for a particular rule

This function accepts a rule in a standard nftables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

CLI Example:

    salt '*' nftables.get_rule_handle filter input \
        rule='tcp dport 22 log accept'

    IPv6:
    salt '*' nftables.get_rule_handle filter input \
        rule='tcp dport 22 log accept' \
        family=ipv6

nftables.get_rules:

Return a data structure of the current, in-memory rules

CLI Example:

    salt '*' nftables.get_rules

    salt '*' nftables.get_rules family=ipv6

nftables.get_rules_json:

New in version 3002

Return a list of dictionaries comprising the current, in-memory rules

family
    Networking family, either ipv4 or ipv6

CLI Example:

    salt '*' nftables.get_rules_json

    salt '*' nftables.get_rules_json family=ipv6

nftables.get_saved_rules:

Return a data structure of the rules in the conf file

CLI Example:

    salt '*' nftables.get_saved_rules

nftables.insert:

Insert a rule into the specified table & chain, at the specified position.

If position is not specified, rule will be inserted in first position.

This function accepts a rule in a standard nftables command format,
    starting with the chain. Trying to force users to adapt to a new
    method of creating rules would be irritating at best, and we
    already have a parser that can handle it.

CLI Examples:

    salt '*' nftables.insert filter input \
        rule='tcp dport 22 log accept'

    salt '*' nftables.insert filter input position=3 \
        rule='tcp dport 22 log accept'

    IPv6:
    salt '*' nftables.insert filter input \
        rule='tcp dport 22 log accept' \
        family=ipv6

    salt '*' nftables.insert filter input position=3 \
        rule='tcp dport 22 log accept' \
        family=ipv6

nftables.list_tables:

Return a data structure of the current, in-memory tables

CLI Example:

    salt '*' nftables.list_tables

    salt '*' nftables.list_tables family=ipv6

nftables.new_chain:

New in version 2014.7.0

Create new chain to the specified table.

CLI Example:

    salt '*' nftables.new_chain filter input

    salt '*' nftables.new_chain filter input \
            table_type=filter hook=input priority=0

    salt '*' nftables.new_chain filter foo

    IPv6:
    salt '*' nftables.new_chain filter input family=ipv6

    salt '*' nftables.new_chain filter input \
            table_type=filter hook=input priority=0 family=ipv6

    salt '*' nftables.new_chain filter foo family=ipv6

nftables.new_table:

New in version 2014.7.0

Create new custom table.

CLI Example:

    salt '*' nftables.new_table filter

    IPv6:
    salt '*' nftables.new_table filter family=ipv6

nftables.save:

Changed in version 3002

Save the current in-memory rules to disk. On systems where /etc/nftables is
a directory, a file named salt-all-in-one.nft will be dropped inside by default.
The main nftables configuration will need to include this file.

CLI Example:

    salt '*' nftables.save /etc/nftables

nftables.set_policy:

New in version 3002

Set the current policy for the specified table/chain. This only works on
chains with an existing base chain.

table
    Name of the table containing the chain to modify

chain
    Name of the chain to set the policy for

policy
    accept or drop

family
    Networking family, either ipv4 or ipv6

CLI Example:

    salt '*' nftables.set_policy filter input accept

    IPv6:
    salt '*' nftables.set_policy filter input accept family=ipv6

nftables.version:

Return version from nftables --version

CLI Example:

    salt '*' nftables.version

nova.boot:

Boot (create) a new instance

name
    Name of the new instance (must be first)

flavor_id
    Unique integer ID for the flavor

image_id
    Unique integer ID for the image

timeout
    How long to wait, after creating the instance, for the provider to
    return information about it (default 300 seconds).

    New in version 2014.1.0

CLI Example:

    salt '*' nova.boot myinstance flavor_id=4596 image_id=2

The flavor_id and image_id are obtained from nova.flavor_list and
nova.image_list

    salt '*' nova.flavor_list
    salt '*' nova.image_list

nova.delete:

Delete an instance

instance_id
    ID of the instance to be deleted

CLI Example:

    salt '*' nova.delete 1138

nova.flavor_create:

Add a flavor to nova (nova flavor-create). The following parameters are
required:

name
    Name of the new flavor (must be first)
flavor_id
    Unique integer ID for the new flavor
ram
    Memory size in MB
disk
    Disk size in GB
vcpus
    Number of vcpus

CLI Example:

    salt '*' nova.flavor_create myflavor flavor_id=6 ram=4096 disk=10 vcpus=1

nova.flavor_delete:

Delete a flavor from nova by id (nova flavor-delete)

CLI Example:

    salt '*' nova.flavor_delete 7

nova.flavor_list:

Return a list of available flavors (nova flavor-list)

CLI Example:

    salt '*' nova.flavor_list

nova.image_list:

Return a list of available images (nova images-list + nova image-show)
If a name is provided, only that image will be displayed.

CLI Examples:

    salt '*' nova.image_list
    salt '*' nova.image_list myimage

nova.image_meta_delete:

Delete a key=value pair from the metadata for an image
(nova image-meta set)

CLI Examples:

    salt '*' nova.image_meta_delete 6f52b2ff-0b31-4d84-8fd1-af45b84824f6 keys=cheese
    salt '*' nova.image_meta_delete name=myimage keys=salad,beans

nova.image_meta_set:

Sets a key=value pair in the metadata for an image (nova image-meta set)

CLI Examples:

    salt '*' nova.image_meta_set 6f52b2ff-0b31-4d84-8fd1-af45b84824f6 cheese=gruyere
    salt '*' nova.image_meta_set name=myimage salad=pasta beans=baked

nova.keypair_add:

Add a keypair to nova (nova keypair-add)

CLI Examples:

    salt '*' nova.keypair_add mykey pubfile=/home/myuser/.ssh/id_rsa.pub
    salt '*' nova.keypair_add mykey pubkey='ssh-rsa <key> myuser@mybox'

nova.keypair_delete:

Add a keypair to nova (nova keypair-delete)

CLI Example:

    salt '*' nova.keypair_delete mykey

nova.keypair_list:

Return a list of available keypairs (nova keypair-list)

CLI Example:

    salt '*' nova.keypair_list

nova.list:

To maintain the feel of the nova command line, this function simply calls
the server_list function.

CLI Example:

    salt '*' nova.list

nova.lock:

Lock an instance

instance_id
    ID of the instance to be locked

CLI Example:

    salt '*' nova.lock 1138

nova.resume:

Resume an instance

instance_id
    ID of the instance to be resumed

CLI Example:

    salt '*' nova.resume 1138

nova.secgroup_create:

Add a secgroup to nova (nova secgroup-create)

CLI Example:

    salt '*' nova.secgroup_create mygroup 'This is my security group'

nova.secgroup_delete:

Delete a secgroup to nova (nova secgroup-delete)

CLI Example:

    salt '*' nova.secgroup_delete mygroup

nova.secgroup_list:

Return a list of available security groups (nova items-list)

CLI Example:

    salt '*' nova.secgroup_list

nova.server_by_name:

Return information about a server

name
    Server Name

CLI Example:

    salt '*' nova.server_by_name myserver profile=openstack

nova.server_list:

Return list of active servers

CLI Example:

    salt '*' nova.server_list

nova.server_list_detailed:

Return detailed list of active servers

CLI Example:

    salt '*' nova.server_list_detailed

nova.server_show:

Return detailed information for an active server

CLI Example:

    salt '*' nova.server_show <server_id>

nova.show:

To maintain the feel of the nova command line, this function simply calls
the server_show function.

CLI Example:

    salt '*' nova.show

nova.suspend:

Suspend an instance

instance_id
    ID of the instance to be suspended

CLI Example:

    salt '*' nova.suspend 1138

nova.volume_attach:

Attach a block storage volume

name
    Name of the new volume to attach

server_name
    Name of the server to attach to

device
    Name of the device on the server

profile
    Profile to build on

CLI Example:

    salt '*' nova.volume_attach myblock slice.example.com profile=openstack
    salt '*' nova.volume_attach myblock server.example.com device='/dev/xvdb' profile=openstack

nova.volume_create:

Create a block storage volume

name
    Name of the new volume (must be first)

size
    Volume size

snapshot
    Block storage snapshot id

voltype
    Type of storage

profile
    Profile to build on

CLI Example:

    salt '*' nova.volume_create myblock size=300 profile=openstack

nova.volume_delete:

Destroy the volume

name
    Name of the volume

profile
    Profile to build on

CLI Example:

    salt '*' nova.volume_delete myblock profile=openstack

nova.volume_detach:

Attach a block storage volume

name
    Name of the new volume to attach

server_name
    Name of the server to detach from

profile
    Profile to build on

CLI Example:

    salt '*' nova.volume_detach myblock profile=openstack

nova.volume_list:

List storage volumes

search_opts
    Dictionary of search options

profile
    Profile to use

CLI Example:

    salt '*' nova.volume_list search_opts='{"display_name": "myblock"}' profile=openstack

nova.volume_show:

Create a block storage volume

name
    Name of the volume

profile
    Profile to use

CLI Example:

    salt '*' nova.volume_show myblock profile=openstack

npm.cache_clean:

Clean cached NPM packages.

If no path for a specific package is provided the entire cache will be cleared.

path
    The cache subpath to delete, or None to clear the entire cache

runas
    The user to run NPM with

env
    Environment variables to set when invoking npm. Uses the same ``env``
    format as the :py:func:`cmd.run <salt.modules.cmdmod.run>` execution
    function.

force
    Force cleaning of cache.  Required for npm@5 and greater

    New in version 2016.11.6

CLI Example:

    salt '*' npm.cache_clean force=True

npm.cache_list:

List NPM cached packages.

If no path for a specific package is provided this will list all the cached packages.

path
    The cache subpath to list, or None to list the entire cache

runas
    The user to run NPM with

env
    Environment variables to set when invoking npm. Uses the same ``env``
    format as the :py:func:`cmd.run <salt.modules.cmdmod.run>` execution
    function.

CLI Example:

    salt '*' npm.cache_clean

npm.cache_path:

List path of the NPM cache directory.

runas
    The user to run NPM with

env
    Environment variables to set when invoking npm. Uses the same ``env``
    format as the :py:func:`cmd.run <salt.modules.cmdmod.run>` execution
    function.

CLI Example:

    salt '*' npm.cache_path

npm.install:

Install an NPM package.

If no directory is specified, the package will be installed globally. If
no package is specified, the dependencies (from package.json) of the
package in the given directory will be installed.

pkg
    A package name in any format accepted by NPM, including a version
    identifier

pkgs
    A list of package names in the same format as the ``name`` parameter

    New in version 2014.7.0

dir
    The target directory in which to install the package, or None for
    global installation

runas
    The user to run NPM with

registry
    The NPM registry to install the package from.

    New in version 2014.7.0

env
    Environment variables to set when invoking npm. Uses the same ``env``
    format as the :py:func:`cmd.run <salt.modules.cmdmod.run>` execution
    function.

    New in version 2014.7.0

silent
    Whether or not to run NPM install with --silent flag.

    New in version 2016.3.0

dry_run
    Whether or not to run NPM install with --dry-run flag.

    New in version 2015.8.4

silent
    Whether or not to run NPM install with --silent flag.

    New in version 2015.8.5

CLI Example:

    salt '*' npm.install coffee-script

    salt '*' npm.install coffee-script@1.0.1

npm.list:

List installed NPM packages.

If no directory is specified, this will return the list of globally-
installed packages.

pkg
    Limit package listing by name

dir
    The directory whose packages will be listed, or None for global
    installation

runas
    The user to run NPM with

    New in version 2014.7.0

env
    Environment variables to set when invoking npm. Uses the same ``env``
    format as the :py:func:`cmd.run <salt.modules.cmdmod.run>` execution
    function.

    New in version 2014.7.0

depth
    Limit the depth of the packages listed

    New in version 2016.11.6,2017.7.0

CLI Example:

    salt '*' npm.list

npm.uninstall:

Uninstall an NPM package.

If no directory is specified, the package will be uninstalled globally.

pkg
    A package name in any format accepted by NPM

dir
    The target directory from which to uninstall the package, or None for
    global installation

runas
    The user to run NPM with

env
    Environment variables to set when invoking npm. Uses the same ``env``
    format as the :py:func:`cmd.run <salt.modules.cmdmod.run>` execution
    function.

    New in version 2015.5.3

CLI Example:

    salt '*' npm.uninstall coffee-script

nspawn.bootstrap_container:

Bootstrap a container from package servers, if dist is None the os the
minion is running as will be created, otherwise the needed bootstrapping
tools will need to be available on the host.

CLI Example:

    salt myminion nspawn.bootstrap_container <name>

nspawn.bootstrap_salt:

Bootstrap a container from package servers, if dist is None the os the
minion is running as will be created, otherwise the needed bootstrapping
tools will need to be available on the host.

CLI Example:

    salt '*' nspawn.bootstrap_salt arch1

nspawn.copy_to:

Copy a file from the host into a container

name
    Container name

source
    File to be copied to the container

dest
    Destination on the container. Must be an absolute path.

overwrite : False
    Unless this option is set to ``True``, then if a file exists at the
    location specified by the ``dest`` argument, an error will be raised.

makedirs : False

    Create the parent directory on the container if it does not already
    exist.

CLI Example:

    salt 'minion' nspawn.copy_to /tmp/foo /root/foo

nspawn.cp:

This function is an alias of copy_to.

Copy a file from the host into a container

name
    Container name

source
    File to be copied to the container

dest
    Destination on the container. Must be an absolute path.

overwrite : False
    Unless this option is set to ``True``, then if a file exists at the
    location specified by the ``dest`` argument, an error will be raised.

makedirs : False

    Create the parent directory on the container if it does not already
    exist.

CLI Example:

    salt 'minion' nspawn.copy_to /tmp/foo /root/foo

nspawn.destroy:

This function is an alias of remove.

Remove the named container

Warning:

    This function will remove all data associated with the container. It
    will not, however, remove the btrfs subvolumes created by pulling
    container images (:mod:`nspawn.pull_raw
    <salt.modules.nspawn.pull_raw>`, :mod:`nspawn.pull_tar
    <salt.modules.nspawn.pull_tar>`, :mod:`nspawn.pull_dkr
    <salt.modules.nspawn.pull_dkr>`).

stop : False
    If ``True``, the container will be destroyed even if it is
    running/frozen.

CLI Examples:

    salt '*' nspawn.remove foo
    salt '*' nspawn.remove foo stop=True

nspawn.disable:

Set the named container to *not* be launched at boot

CLI Example:

    salt myminion nspawn.enable <name>

nspawn.enable:

Set the named container to be launched at boot

CLI Example:

    salt myminion nspawn.enable <name>

nspawn.exists:

Returns true if the named container exists

CLI Example:

    salt myminion nspawn.exists <name>

nspawn.info:

Return info about a container

Note:

    The container must be running for ``machinectl`` to gather information
    about it. If the container is stopped, then this function will start
    it.

start : False
    If ``True``, then the container will be started to retrieve the info. A
    ``Started`` key will be in the return data if the container was
    started.

CLI Example:

    salt myminion nspawn.info arch1
    salt myminion nspawn.info arch1 force_start=False

nspawn.list:

This function is an alias of list_running.

Lists running nspawn containers

Note:

    ``nspawn.list`` also works to list running containers

CLI Example:

    salt myminion nspawn.list_running
    salt myminion nspawn.list

nspawn.list_all:

Lists all nspawn containers

CLI Example:

    salt myminion nspawn.list_all

nspawn.list_running:

Lists running nspawn containers

Note:

    ``nspawn.list`` also works to list running containers

CLI Example:

    salt myminion nspawn.list_running
    salt myminion nspawn.list

nspawn.list_stopped:

Lists stopped nspawn containers

CLI Example:

    salt myminion nspawn.list_stopped

nspawn.pid:

Returns the PID of a container

name
    Container name

CLI Example:

    salt myminion nspawn.pid arch1

nspawn.poweroff:

Issue a clean shutdown to the container.  Equivalent to running
``machinectl poweroff`` on the named container.

For convenience, running ``nspawn.stop``(as shown in the CLI examples
below) is equivalent to running ``nspawn.poweroff``.

Note:

    ``machinectl poweroff`` is only supported in systemd >= 219. On earlier
    systemd versions, running this function will simply issue a clean
    shutdown via ``systemctl``.

CLI Examples:

    salt myminion nspawn.poweroff arch1
    salt myminion nspawn.stop arch1

nspawn.pull_dkr:

Execute a ``machinectl pull-dkr`` to download a docker image and add it to
/var/lib/machines as a new container.

Note:

    **Requires systemd >= 219**

url
    URL from which to download the container

name
    Name for the new container

index
    URL of the Docker index server from which to pull (must be an
    ``http://`` or ``https://`` URL).

CLI Examples:

    salt myminion nspawn.pull_dkr centos/centos6 cent6 index=https://get.docker.com
    salt myminion nspawn.pull_docker centos/centos6 cent6 index=https://get.docker.com

nspawn.pull_docker:

This function is an alias of pull_dkr.

Execute a ``machinectl pull-dkr`` to download a docker image and add it to
/var/lib/machines as a new container.

Note:

    **Requires systemd >= 219**

url
    URL from which to download the container

name
    Name for the new container

index
    URL of the Docker index server from which to pull (must be an
    ``http://`` or ``https://`` URL).

CLI Examples:

    salt myminion nspawn.pull_dkr centos/centos6 cent6 index=https://get.docker.com
    salt myminion nspawn.pull_docker centos/centos6 cent6 index=https://get.docker.com

nspawn.pull_raw:

Execute a ``machinectl pull-raw`` to download a .qcow2 or raw disk image,
and add it to /var/lib/machines as a new container.

Note:

    **Requires systemd >= 219**

url
    URL from which to download the container

name
    Name for the new container

verify : False
    Perform signature or checksum verification on the container. See the
    ``machinectl(1)`` man page (section titled "Image Transfer Commands")
    for more information on requirements for image verification. To perform
    signature verification, use ``verify=signature``. For checksum
    verification, use ``verify=checksum``. By default, no verification will
    be performed.

CLI Examples:

    salt myminion nspawn.pull_raw http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz fedora21

nspawn.pull_tar:

Execute a ``machinectl pull-raw`` to download a .tar container image,
and add it to /var/lib/machines as a new container.

Note:

    **Requires systemd >= 219**

url
    URL from which to download the container

name
    Name for the new container

verify : False
    Perform signature or checksum verification on the container. See the
    ``machinectl(1)`` man page (section titled "Image Transfer Commands")
    for more information on requirements for image verification. To perform
    signature verification, use ``verify=signature``. For checksum
    verification, use ``verify=checksum``. By default, no verification will
    be performed.

CLI Examples:

    salt myminion nspawn.pull_tar http://foo.domain.tld/containers/archlinux-2015.02.01.tar.gz arch2

nspawn.reboot:

Reboot the container by sending a SIGINT to its init process. Equivalent
to running ``machinectl reboot`` on the named container.

For convenience, running ``nspawn.restart`` (as shown in the CLI examples
below) is equivalent to running ``nspawn.reboot``.

Note:

    ``machinectl reboot`` is only supported in systemd >= 219. On earlier
    systemd versions, running this function will instead restart the
    container via ``systemctl``.

CLI Examples:

    salt myminion nspawn.reboot arch1
    salt myminion nspawn.restart arch1

nspawn.remove:

Remove the named container

Warning:

    This function will remove all data associated with the container. It
    will not, however, remove the btrfs subvolumes created by pulling
    container images (:mod:`nspawn.pull_raw
    <salt.modules.nspawn.pull_raw>`, :mod:`nspawn.pull_tar
    <salt.modules.nspawn.pull_tar>`, :mod:`nspawn.pull_dkr
    <salt.modules.nspawn.pull_dkr>`).

stop : False
    If ``True``, the container will be destroyed even if it is
    running/frozen.

CLI Examples:

    salt '*' nspawn.remove foo
    salt '*' nspawn.remove foo stop=True

nspawn.restart:

This is a compatibility function which simply calls nspawn.reboot.

nspawn.retcode:

Run :mod:`cmd.retcode <salt.modules.cmdmod.retcode>` within a container

name
    Name of the container in which to run the command

cmd
    Command to run

no_start : False
    If the container is not running, don't start it

preserve_state : True
    After running the command, return the container to its previous state

stdin : None
    Standard input to be used for the command

output_loglevel : debug
    Level at which to log the output from the command. Set to ``quiet`` to
    suppress logging.

use_vt : False
    Use SaltStack's utils.vt to stream output to console. Assumes
    ``output=all``.

keep_env : None
    If not passed, only a sane default PATH environment variable will be
    set. If ``True``, all environment variables from the container's host
    will be kept. Otherwise, a comma-separated list (or Python list) of
    environment variable names can be passed, and those environment
    variables will be kept.

CLI Example:

    salt myminion nspawn.retcode mycontainer 'ip addr show'

nspawn.run:

Run :mod:`cmd.run <salt.modules.cmdmod.run>` within a container

name
    Name of the container in which to run the command

cmd
    Command to run

no_start : False
    If the container is not running, don't start it

preserve_state : True
    After running the command, return the container to its previous state

stdin : None
    Standard input to be used for the command

output_loglevel : debug
    Level at which to log the output from the command. Set to ``quiet`` to
    suppress logging.

use_vt : False
    Use SaltStack's utils.vt to stream output to console.

keep_env : None
    If not passed, only a sane default PATH environment variable will be
    set. If ``True``, all environment variables from the container's host
    will be kept. Otherwise, a comma-separated list (or Python list) of
    environment variable names can be passed, and those environment
    variables will be kept.

CLI Example:

    salt myminion nspawn.run mycontainer 'ip addr show'

nspawn.run_all:

Run :mod:`cmd.run_all <salt.modules.cmdmod.run_all>` within a container

Note:

    While the command is run within the container, it is initiated from the
    host. Therefore, the PID in the return dict is from the host, not from
    the container.

name
    Name of the container in which to run the command

cmd
    Command to run

no_start : False
    If the container is not running, don't start it

preserve_state : True
    After running the command, return the container to its previous state

stdin : None
    Standard input to be used for the command

output_loglevel : debug
    Level at which to log the output from the command. Set to ``quiet`` to
    suppress logging.

use_vt : False
    Use SaltStack's utils.vt to stream output to console. Assumes
    ``output=all``.

keep_env : None
    If not passed, only a sane default PATH environment variable will be
    set. If ``True``, all environment variables from the container's host
    will be kept. Otherwise, a comma-separated list (or Python list) of
    environment variable names can be passed, and those environment
    variables will be kept.

CLI Example:

    salt myminion nspawn.run_all mycontainer 'ip addr show'

nspawn.run_stderr:

Run :mod:`cmd.run_stderr <salt.modules.cmdmod.run_stderr>` within a container

name
    Name of the container in which to run the command

cmd
    Command to run

no_start : False
    If the container is not running, don't start it

preserve_state : True
    After running the command, return the container to its previous state

stdin : None
    Standard input to be used for the command

output_loglevel : debug
    Level at which to log the output from the command. Set to ``quiet`` to
    suppress logging.

use_vt : False
    Use SaltStack's utils.vt to stream output to console. Assumes
    ``output=all``.

keep_env : None
    If not passed, only a sane default PATH environment variable will be
    set. If ``True``, all environment variables from the container's host
    will be kept. Otherwise, a comma-separated list (or Python list) of
    environment variable names can be passed, and those environment
    variables will be kept.

CLI Example:

    salt myminion nspawn.run_stderr mycontainer 'ip addr show'

nspawn.run_stdout:

Run :mod:`cmd.run_stdout <salt.modules.cmdmod.run_stdout>` within a container

name
    Name of the container in which to run the command

cmd
    Command to run

no_start : False
    If the container is not running, don't start it

preserve_state : True
    After running the command, return the container to its previous state

stdin : None
    Standard input to be used for the command

output_loglevel : debug
    Level at which to log the output from the command. Set to ``quiet`` to
    suppress logging.

use_vt : False
    Use SaltStack's utils.vt to stream output to console. Assumes
    ``output=all``.

keep_env : None
    If not passed, only a sane default PATH environment variable will be
    set. If ``True``, all environment variables from the container's host
    will be kept. Otherwise, a comma-separated list (or Python list) of
    environment variable names can be passed, and those environment
    variables will be kept.

CLI Example:

    salt myminion nspawn.run_stdout mycontainer 'ip addr show'

nspawn.start:

Start the named container

CLI Example:

    salt myminion nspawn.start <name>

nspawn.state:

Return state of container (running or stopped)

CLI Example:

    salt myminion nspawn.state <name>

nspawn.stop:

This is a compatibility function which provides the logic for
nspawn.poweroff and nspawn.terminate.

nspawn.terminate:

Kill all processes in the container without issuing a clean shutdown.
Equivalent to running ``machinectl terminate`` on the named container.

For convenience, running ``nspawn.stop`` and passing ``kill=True`` (as
shown in the CLI examples below) is equivalent to running
``nspawn.terminate``.

Note:

    ``machinectl terminate`` is only supported in systemd >= 219. On
    earlier systemd versions, running this function will simply issue a
    clean shutdown via ``systemctl``.

CLI Examples:

    salt myminion nspawn.terminate arch1
    salt myminion nspawn.stop arch1 kill=True

nxos.add_config:

Add one or more config lines to the NX-OS device running config.

lines
    Configuration lines to add

save_config
    If False, don't save configuration commands to startup configuration.
    If True, save configuration to startup configuration.
    Default: True

    salt '*' nxos.add_config 'snmp-server community TESTSTRINGHERE group network-operator'

Note:
    For more than one config added per command, lines should be a list.

nxos.check_password:

Verify user password.

username
    Username on which to perform password check

password
    Password to check

encrypted
    Whether or not the password is encrypted
    Default: False

.. code-block: bash

    salt '*' nxos.check_password username=admin password=admin
    salt '*' nxos.check_password username=admin \
        password='$5$2fWwO2vK$s7.Hr3YltMNHuhywQQ3nfOd.gAPHgs3SOBYYdGT3E.A' \
        encrypted=True

nxos.check_role:

Verify role assignment for user.

    salt '*' nxos.check_role username=admin role=network-admin

nxos.check_upgrade_impact:

Display upgrade impact information without actually upgrading the device.

system_image (Mandatory Option)
    Path on bootflash: to system image upgrade file.

kickstart_image
    Path on bootflash: to kickstart image upgrade file.
    (Not required if using combined system/kickstart image file)
    Default: None

issu
    In Service Software Upgrade (non-disruptive). When True,
    the upgrade will abort if issu is not possible.
    When False: Force (disruptive) Upgrade/Downgrade.
    Default: True

timeout
    Timeout in seconds for long running 'install all' impact command.
    Default: 900

error_pattern
    Use the option to pass in a regular expression to search for in the
    output of the 'install all impact' command that indicates an error
    has occurred.  This option is only used when proxy minion connection
    type is ssh and otherwise ignored.

    salt 'n9k' nxos.check_upgrade_impact system_image=nxos.9.2.1.bin
    salt 'n7k' nxos.check_upgrade_impact system_image=n7000-s2-dk9.8.1.1.bin \
        kickstart_image=n7000-s2-kickstart.8.1.1.bin issu=False

nxos.cmd:

NOTE: This function is preserved for backwards compatibility.  This allows
commands to be executed using either of the following syntactic forms.

salt '*' nxos.cmd <function>

or

salt '*' nxos.<function>

command
    function from `salt.modules.nxos` to run

args
    positional args to pass to `command` function

kwargs
    key word arguments to pass to `command` function

    salt '*' nxos.cmd sendline 'show ver'
    salt '*' nxos.cmd show_run
    salt '*' nxos.cmd check_password username=admin password='$5$lkjsdfoi$blahblahblah' encrypted=True

nxos.config:

Configures the Nexus switch with the specified commands.

This method is used to send configuration commands to the switch.  It
will take either a string or a list and prepend the necessary commands
to put the session into config mode.

Warning:

    All the commands will be applied directly to the running-config.

config_file
    The source file with the configuration commands to be sent to the
    device.

    The file can also be a template that can be rendered using the template
    engine of choice.

    This can be specified using the absolute path to the file, or using one
    of the following URL schemes:

    - ``salt://``, to fetch the file from the Salt fileserver.
    - ``http://`` or ``https://``
    - ``ftp://``
    - ``s3://``
    - ``swift://``

commands
    The commands to send to the switch in config mode.  If the commands
    argument is a string it will be cast to a list.
    The list of commands will also be prepended with the necessary commands
    to put the session in config mode.

    Note:

        This argument is ignored when ``config_file`` is specified.

template_engine: ``jinja``
    The template engine to use when rendering the source file. Default:
    ``jinja``. To simply fetch the file without attempting to render, set
    this argument to ``None``.

context
    Variables to add to the template context.

defaults
    Default values of the context_dict.

save_config
    If False, don't save configuration commands to startup configuration.
    If True, save configuration to startup configuration.
    Default: True

CLI Example:

    salt '*' nxos.config commands="['spanning-tree mode mstp']"
    salt '*' nxos.config config_file=salt://config.txt
    salt '*' nxos.config config_file=https://bit.ly/2LGLcDy context="{'servers': ['1.2.3.4']}"

nxos.delete_config:

Delete one or more config lines to the switch running config.

lines
    Configuration lines to remove.

save_config
    If False, don't save configuration commands to startup configuration.
    If True, save configuration to startup configuration.
    Default: True

    salt '*' nxos.delete_config 'snmp-server community TESTSTRINGHERE group network-operator'

Note:
    For more than one config deleted per command, lines should be a list.

nxos.find:

Find all instances where the pattern is in the running configuration.

    salt '*' nxos.find '^snmp-server.*$'

Note:
    This uses the `re.MULTILINE` regex format for python, and runs the
    regex against the whole show_run output.

nxos.get_roles:

Get roles assigned to a username.

.. code-block: bash

    salt '*' nxos.get_roles username=admin

nxos.get_user:

Get username line from switch.

.. code-block: bash

    salt '*' nxos.get_user username=admin

nxos.grains:

Get grains for minion.

.. code-block: bash

    salt '*' nxos.grains

nxos.grains_refresh:

Refresh the grains for the NX-OS device.

.. code-block: bash

    salt '*' nxos.grains_refresh

nxos.ping:

Ping the device on the other end of the connection.

.. code-block: bash

    salt '*' nxos.ping

nxos.remove_user:

Remove user from switch.

username
    Username to remove

save_config
    If False, don't save configuration commands to startup configuration.
    If True, save configuration to startup configuration.
    Default: True

    salt '*' nxos.remove_user username=daniel

nxos.replace:

Replace string or full line matches in switch's running config.

If full_match is set to True, then the whole line will need to be matched
as part of the old value.

    salt '*' nxos.replace 'TESTSTRINGHERE' 'NEWTESTSTRINGHERE'

nxos.save_running_config:

Save the running configuration to startup configuration.

    salt '*' nxos.save_running_config

nxos.sendline:

Send arbitrary commands to the NX-OS device.

command
    The command or list of commands to be sent.
    ['cmd1', 'cmd2'] is converted to 'cmd1 ; cmd2'.

method:
    ``cli_show_ascii``: Return raw test or unstructured output.
    ``cli_show``: Return structured output.
    ``cli_conf``: Send configuration commands to the device.
    Defaults to ``cli_show_ascii``.
    NOTE: method is ignored for SSH proxy minion.  All data is returned
    unstructured.

error_pattern
    Use the option to pass in a regular expression to search for in the
    returned output of the command that indicates an error has occurred.
    This option is only used when proxy minion connection type is ssh and
    otherwise ignored.

.. code-block: bash

    salt '*' nxos.sendline 'show run | include "^username admin password"'
    salt '*' nxos.sendline "['show inventory', 'show version']"
    salt '*' nxos.sendline 'show inventory ; show version'

nxos.set_password:

Set users password on switch.

username
    Username to configure

password
    Password to configure for username

encrypted
    Whether or not to encrypt the password
    Default: False

role
    Configure role for the username
    Default: None

crypt_salt
    Configure crypt_salt setting
    Default: None

algorithm
    Encryption algorithm
    Default: sha256

save_config
    If False, don't save configuration commands to startup configuration.
    If True, save configuration to startup configuration.
    Default: True

    salt '*' nxos.set_password admin TestPass
    salt '*' nxos.set_password admin \
        password='$5$2fWwO2vK$s7.Hr3YltMNHuhywQQ3nfOd.gAPHgs3SOBYYdGT3E.A' \
        encrypted=True

nxos.set_role:

Assign role to username.

username
    Username for role configuration

role
    Configure role for username

save_config
    If False, don't save configuration commands to startup configuration.
    If True, save configuration to startup configuration.
    Default: True

    salt '*' nxos.set_role username=daniel role=vdc-admin.

nxos.show:

Execute one or more show (non-configuration) commands.

commands
    The commands to be executed.

raw_text: ``True``
    Whether to return raw text or structured data.
    NOTE: raw_text option is ignored for SSH proxy minion.  Data is
    returned unstructured.

CLI Example:

    salt-call --local nxos.show 'show version'
    salt '*' nxos.show 'show bgp sessions ; show processes' raw_text=False
    salt 'regular-minion' nxos.show 'show interfaces' host=sw01.example.com username=test password=test

nxos.show_run:

Shortcut to run `show running-config` on the NX-OS device.

    salt '*' nxos.show_run

nxos.show_ver:

Shortcut to run `show version` on the NX-OS device.

    salt '*' nxos.show_ver

nxos.system_info:

Return system information for grains of the minion.

    salt '*' nxos.system_info

nxos.unset_role:

Remove role from username.

username
    Username for role removal

role
    Role to remove

save_config
    If False, don't save configuration commands to startup configuration.
    If True, save configuration to startup configuration.
    Default: True

    salt '*' nxos.unset_role username=daniel role=vdc-admin

nxos.upgrade:

Upgrade NX-OS switch.

system_image (Mandatory Option)
    Path on bootflash: to system image upgrade file.

kickstart_image
    Path on bootflash: to kickstart image upgrade file.
    (Not required if using combined system/kickstart image file)
    Default: None

issu
    Set this option to True when an In Service Software Upgrade or
    non-disruptive upgrade is required. The upgrade will abort if issu is
    not possible.
    Default: True

timeout
    Timeout in seconds for long running 'install all' upgrade command.
    Default: 900

error_pattern
    Use the option to pass in a regular expression to search for in the
    output of the 'install all upgrade command that indicates an error
    has occurred.  This option is only used when proxy minion connection
    type is ssh and otherwise ignored.

    salt 'n9k' nxos.upgrade system_image=nxos.9.2.1.bin
    salt 'n7k' nxos.upgrade system_image=n7000-s2-dk9.8.1.1.bin \
        kickstart_image=n7000-s2-kickstart.8.1.1.bin issu=False

nxos_api.config:

Configures the Nexus switch with the specified commands.

This method is used to send configuration commands to the switch.  It
will take either a string or a list and prepend the necessary commands
to put the session into config mode.

Warning:

    All the commands will be applied directly into the running-config.

config_file
    The source file with the configuration commands to be sent to the
    device.

    The file can also be a template that can be rendered using the template
    engine of choice.

    This can be specified using the absolute path to the file, or using one
    of the following URL schemes:

    - ``salt://``, to fetch the file from the Salt fileserver.
    - ``http://`` or ``https://``
    - ``ftp://``
    - ``s3://``
    - ``swift://``

commands
    The commands to send to the switch in config mode.  If the commands
    argument is a string it will be cast to a list.
    The list of commands will also be prepended with the necessary commands
    to put the session in config mode.

    Note:

        This argument is ignored when ``config_file`` is specified.

template_engine: ``jinja``
    The template engine to use when rendering the source file. Default:
    ``jinja``. To simply fetch the file without attempting to render, set
    this argument to ``None``.

context
    Variables to add to the template context.

defaults
    Default values of the context_dict.

transport: ``https``
    Specifies the type of connection transport to use. Valid values for the
    connection are ``http``, and  ``https``.

host: ``localhost``
    The IP address or DNS host name of the connection device.

username: ``admin``
    The username to pass to the device to authenticate the NX-API connection.

password
    The password to pass to the device to authenticate the NX-API connection.

port
    The TCP port of the endpoint for the NX-API connection. If this keyword is
    not specified, the default value is automatically determined by the
    transport type (``80`` for ``http``, or ``443`` for ``https``).

timeout: ``60``
    Time in seconds to wait for the device to respond. Default: 60 seconds.

verify: ``True``
    Either a boolean, in which case it controls whether we verify the NX-API
    TLS certificate, or a string, in which case it must be a path to a CA bundle
    to use. Defaults to ``True``.

CLI Example:

    salt '*' nxos_api.config commands="['spanning-tree mode mstp']"
    salt '*' nxos_api.config config_file=salt://config.txt
    salt '*' nxos_api.config config_file=https://bit.ly/2LGLcDy context="{'servers': ['1.2.3.4']}"

nxos_api.rpc:

Execute an arbitrary RPC request via the Nexus API.

commands
    The commands to be executed.

method: ``cli``
    The type of the response, i.e., raw text (``cli_ascii``) or structured
    document (``cli``). Defaults to ``cli`` (structured data).

transport: ``https``
    Specifies the type of connection transport to use. Valid values for the
    connection are ``http``, and  ``https``.

host: ``localhost``
    The IP address or DNS host name of the connection device.

username: ``admin``
    The username to pass to the device to authenticate the NX-API connection.

password
    The password to pass to the device to authenticate the NX-API connection.

port
    The TCP port of the endpoint for the NX-API connection. If this keyword is
    not specified, the default value is automatically determined by the
    transport type (``80`` for ``http``, or ``443`` for ``https``).

timeout: ``60``
    Time in seconds to wait for the device to respond. Default: 60 seconds.

verify: ``True``
    Either a boolean, in which case it controls whether we verify the NX-API
    TLS certificate, or a string, in which case it must be a path to a CA bundle
    to use. Defaults to ``True``.

CLI Example:

    salt-call --local nxos_api.rpc 'show version'

nxos_api.show:

Execute one or more show (non-configuration) commands.

commands
    The commands to be executed.  Multiple commands should
    be specified as a list.

raw_text: ``True``
    Whether to return raw text or structured data.

transport: ``https``
    Specifies the type of connection transport to use. Valid values for the
    connection are ``http``, and  ``https``.

host: ``localhost``
    The IP address or DNS host name of the connection device.

username: ``admin``
    The username to pass to the device to authenticate the NX-API connection.

password
    The password to pass to the device to authenticate the NX-API connection.

port
    The TCP port of the endpoint for the NX-API connection. If this keyword is
    not specified, the default value is automatically determined by the
    transport type (``80`` for ``http``, or ``443`` for ``https``).

timeout: ``60``
    Time in seconds to wait for the device to respond. Default: 60 seconds.

verify: ``True``
    Either a boolean, in which case it controls whether we verify the NX-API
    TLS certificate, or a string, in which case it must be a path to a CA bundle
    to use. Defaults to ``True``.

CLI Example:

    salt-call --local nxos_api.show 'show version'
    salt '*' nxos_api.show "['show bgp sessions','show processes']" raw_text=False
    salt 'regular-minion' nxos_api.show 'show interfaces' host=sw01.example.com username=test password=test

nxos_upgrade.check_upgrade_impact:

Display upgrade impact information without actually upgrading the device.

system_image (Mandatory Option)
    Path on bootflash: to system image upgrade file.

kickstart_image
    Path on bootflash: to kickstart image upgrade file.
    (Not required if using combined system/kickstart image file)
    Default: None

issu
    In Service Software Upgrade (non-disruptive). When True,
    the upgrade will abort if issu is not possible.
    When False: Force (disruptive) Upgrade/Downgrade.
    Default: True

timeout
    Timeout in seconds for long running 'install all' impact command.
    Default: 900

error_pattern
    Use the option to pass in a regular expression to search for in the
    output of the 'install all impact' command that indicates an error
    has occurred.  This option is only used when proxy minion connection
    type is ssh and otherwise ignored.

    salt 'n9k' nxos.check_upgrade_impact system_image=nxos.9.2.1.bin
    salt 'n7k' nxos.check_upgrade_impact system_image=n7000-s2-dk9.8.1.1.bin \
        kickstart_image=n7000-s2-kickstart.8.1.1.bin issu=False

nxos_upgrade.upgrade:

Upgrade NX-OS switch.

system_image (Mandatory Option)
    Path on bootflash: to system image upgrade file.

kickstart_image
    Path on bootflash: to kickstart image upgrade file.
    (Not required if using combined system/kickstart image file)
    Default: None

issu
    Set this option to True when an In Service Software Upgrade or
    non-disruptive upgrade is required. The upgrade will abort if issu is
    not possible.
    Default: True

timeout
    Timeout in seconds for long running 'install all' upgrade command.
    Default: 900

error_pattern
    Use the option to pass in a regular expression to search for in the
    output of the 'install all upgrade command that indicates an error
    has occurred.  This option is only used when proxy minion connection
    type is ssh and otherwise ignored.

    salt 'n9k' nxos.upgrade system_image=nxos.9.2.1.bin
    salt 'n7k' nxos.upgrade system_image=n7000-s2-dk9.8.1.1.bin \
        kickstart_image=n7000-s2-kickstart.8.1.1.bin issu=False

openscap.xccdf:

Run ``oscap xccdf`` commands on minions.
It uses cp.push_dir to upload the generated files to the salt master
in the master's minion files cachedir
(defaults to ``/var/cache/salt/master/minions/minion-id/files``)

It needs ``file_recv`` set to ``True`` in the master configuration file.

CLI Example:

    salt '*'  openscap.xccdf "eval --profile Default /usr/share/openscap/scap-yast2sec-xccdf.xml"

openscap.xccdf_eval:

Run ``oscap xccdf eval`` commands on minions.

New in version 3007.0

It uses cp.push_dir to upload the generated files to the salt master
in the master's minion files cachedir
(defaults to ``/var/cache/salt/master/minions/minion-id/files``)

It needs ``file_recv`` set to ``True`` in the master configuration file.

xccdffile
    the path to the xccdf file to evaluate

ovalfiles
    additional oval definition files

profile
    the name of Profile to be evaluated

rule
    the name of a single rule to be evaluated

oval_results
    save OVAL results as well (True or False)

results
    write XCCDF Results into given file

report
    write HTML report into given file

fetch_remote_resources
    download remote content referenced by XCCDF (True or False)

tailoring_file
    use given XCCDF Tailoring file

tailoring_id
    use given DS component as XCCDF Tailoring file

remediate
    automatically execute XCCDF fix elements for failed rules.
    Use of this option is always at your own risk. (True or False)

CLI Example:

    salt '*'  openscap.xccdf_eval /usr/share/openscap/scap-yast2sec-xccdf.xml profile=Default

openstack_config.delete:

Delete a value from an OpenStack configuration file.

filename
    The full path to the configuration file

section
    The section from which to delete the parameter

parameter
    The parameter to delete

CLI Example:

    salt-call openstack_config.delete /etc/keystone/keystone.conf sql connection

openstack_config.get:

Get a value from an OpenStack configuration file.

filename
    The full path to the configuration file

section
    The section from which to search for the parameter

parameter
    The parameter to return

CLI Example:

    salt-call openstack_config.get /etc/keystone/keystone.conf sql connection

openstack_config.set:

Set a value in an OpenStack configuration file.

filename
    The full path to the configuration file

section
    The section in which the parameter will be set

parameter
    The parameter to change

value
    The value to set

CLI Example:

    salt-call openstack_config.set /etc/keystone/keystone.conf sql connection foo

opsgenie.post_data:

Post data to OpsGenie. It's designed for Salt's Event Reactor.

After configuring the sls reaction file as shown above, you can trigger the
module with your designated tag (og-tag in this case).

CLI Example:

    salt-call event.send 'og-tag' '{"reason" : "Overheating CPU!"}'

Required parameters:

api_key
    It's the API Key you've copied while adding integration in OpsGenie.

reason
    It will be used as alert's default message in OpsGenie.

action_type
    OpsGenie supports the default values Create/Close for action_type. You
    can customize this field with OpsGenie's custom actions for other
    purposes like adding notes or acknowledging alerts.

Optional parameters:

name
    It will be used as alert's alias. If you want to use the close
    functionality you must provide name field for both states like in
    this case.

out.html_format:

Return the formatted string as HTML.

data
    The JSON serializable object.

out: ``nested``
    The name of the output to use to transform the data. Default: ``nested``.

opts
    Dictionary of configuration options. Default: ``__opts__``.

kwargs
    Arguments to sent to the outputter module.

CLI Example:

    salt '*' out.html_format "{'key': 'value'}" out=yaml

out.out_format:

Return the formatted outputter string for the Python object.

data
    The JSON serializable object.

out: ``nested``
    The name of the output to use to transform the data. Default: ``nested``.

opts
    Dictionary of configuration options. Default: ``__opts__``.

kwargs
    Arguments to sent to the outputter module.

CLI Example:

    salt '*' out.out_format "{'key': 'value'}"

out.string_format:

Return the outputter formatted string, removing the ANSI escape sequences.

data
    The JSON serializable object.

out: ``nested``
    The name of the output to use to transform the data. Default: ``nested``.

opts
    Dictionary of configuration options. Default: ``__opts__``.

kwargs
    Arguments to sent to the outputter module.

CLI Example:

    salt '*' out.string_format "{'key': 'value'}" out=table

pagerduty.create_event:

Create an event in PagerDuty. Designed for use in states.

CLI Example:

    salt myminion pagerduty.create_event <service_key> <description> <details>         profile=my-pagerduty-account

The following parameters are required:

service_key
    This key can be found by using pagerduty.list_services.

description
    This is a short description of the event.

details
    This can be a more detailed description of the event.

profile
    This refers to the configuration profile to use to connect to the
    PagerDuty service.

pagerduty.list_escalation_policies:

This function is an alias of list_policies.

List escalation policies belonging to this account

CLI Example:

    salt myminion pagerduty.list_policies my-pagerduty-account
    salt myminion pagerduty.list_escalation_policies my-pagerduty-account

pagerduty.list_incidents:

List incidents belonging to this account

CLI Example:

    salt myminion pagerduty.list_incidents my-pagerduty-account

pagerduty.list_maintenance_windows:

This function is an alias of list_windows.

List maintenance windows belonging to this account

CLI Example:

    salt myminion pagerduty.list_windows my-pagerduty-account
    salt myminion pagerduty.list_maintenance_windows my-pagerduty-account

pagerduty.list_policies:

List escalation policies belonging to this account

CLI Example:

    salt myminion pagerduty.list_policies my-pagerduty-account
    salt myminion pagerduty.list_escalation_policies my-pagerduty-account

pagerduty.list_schedules:

List schedules belonging to this account

CLI Example:

    salt myminion pagerduty.list_schedules my-pagerduty-account

pagerduty.list_services:

List services belonging to this account

CLI Example:

    salt myminion pagerduty.list_services my-pagerduty-account

pagerduty.list_users:

List users belonging to this account

CLI Example:

    salt myminion pagerduty.list_users my-pagerduty-account

pagerduty.list_windows:

List maintenance windows belonging to this account

CLI Example:

    salt myminion pagerduty.list_windows my-pagerduty-account
    salt myminion pagerduty.list_maintenance_windows my-pagerduty-account

pagerduty_util.create_or_update_resource:

create or update any pagerduty resource
Helper method for present().

Determining if two resources are the same is different for different PD resource, so this method accepts a diff function.
The diff function will be invoked as diff(state_information, object_returned_from_pagerduty), and
should return a dict of data to pass to the PagerDuty update API method, or None if no update
is to be performed.  If no diff method is provided, the default behavor is to scan the keys in the state_information,
comparing the matching values in the object_returned_from_pagerduty, and update any values that differ.

examples:
    create_or_update_resource("user", ["id","name","email"])
    create_or_update_resource("escalation_policies", ["id","name"], diff=my_diff_function)

pagerduty_util.delete_resource:

delete any pagerduty resource

Helper method for absent()

example:
        delete_resource("users", key, ["id","name","email"]) # delete by id or name or email

pagerduty_util.get_escalation_policies:

List escalation_policies belonging to this account

CLI Example:

    salt myminion pagerduty.get_escalation_policies

pagerduty_util.get_resource:

Get any single pagerduty resource by key.

We allow flexible lookup by any of a list of identifier_fields.
So, for example, you can look up users by email address or name by calling:

        get_resource('users', key, ['name', 'email'], ...)

This method is mainly used to translate state sls into pagerduty id's for dependent objects.
For example, a pagerduty escalation policy contains one or more schedules, which must be passed
by their pagerduty id.  We look up the schedules by name (using this method), and then translate
the names into id's.

This method is implemented by getting all objects of the resource type (cached into __context__),
then brute force searching through the list and trying to match any of the identifier_fields.
The __context__ cache is purged after any create, update or delete to the resource.

pagerduty_util.get_schedules:

List schedules belonging to this account

CLI Example:

    salt myminion pagerduty.get_schedules

pagerduty_util.get_services:

List services belonging to this account

CLI Example:

    salt myminion pagerduty.get_services

pagerduty_util.get_users:

List users belonging to this account

CLI Example:

    salt myminion pagerduty.get_users

pagerduty_util.resource_absent:

Generic resource.absent state method.   Pagerduty state modules should be a thin wrapper over this method,
with a custom diff function.

This method calls delete_resource() and formats the result as a salt state return value.

example:
        resource_absent("users", ["id","name","email"])

pagerduty_util.resource_present:

Generic resource.present state method.   Pagerduty state modules should be a thin wrapper over this method,
with a custom diff function.

This method calls create_or_update_resource() and formats the result as a salt state return value.

example:
        resource_present("users", ["id","name","email"])

pam.read_file:

This is just a test function, to make sure parsing works

CLI Example:

    salt '*' pam.read_file /etc/pam.d/login

parallels.clone:

Clone a VM

New in version 2016.11.0

:param str name:
    Name/ID of VM to clone

:param str new_name:
    Name of the new VM

:param bool linked:
    Create a linked virtual machine.

:param bool template:
    Create a virtual machine template instead of a real virtual machine.

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.clone macvm macvm_new runas=macdev
    salt '*' parallels.clone macvm macvm_templ template=True runas=macdev

parallels.delete:

Delete a VM

New in version 2016.11.0

:param str name:
    Name/ID of VM to clone

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.exec macvm 'find /etc/paths.d' runas=macdev

parallels.delete_snapshot:

Delete a snapshot

Note:

    Deleting a snapshot from which other snapshots are dervied will not
    delete the derived snapshots

:param str name:
    Name/ID of VM whose snapshot will be deleted

:param str snap_name:
    Name/ID of snapshot to delete

:param str runas:
    The user that the prlctl command will be run as

:param bool all:
    Delete all snapshots having the name given

    New in version 2016.11.0

Example:

    salt '*' parallels.delete_snapshot macvm 'unneeded snapshot' runas=macdev
    salt '*' parallels.delete_snapshot macvm 'Snapshot for linked clone' all=True runas=macdev

parallels.exec:

Run a command on a VM

:param str name:
    Name/ID of VM whose exec will be returned

:param str command:
    Command to run on the VM

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.exec macvm 'find /etc/paths.d' runas=macdev

parallels.exists:

Query whether a VM exists

New in version 2016.11.0

:param str name:
    Name/ID of VM

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.exists macvm runas=macdev

parallels.list_snapshots:

List the snapshots

:param str name:
    Name/ID of VM whose snapshots will be listed

:param str snap_id:
    Name/ID of snapshot to display information about.  If ``tree=True`` is
    also specified, display the snapshot subtree having this snapshot as
    the root snapshot

:param bool tree:
    List snapshots in tree format rather than tabular format

:param bool names:
    List snapshots as ID, name pairs

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.list_snapshots macvm runas=macdev
    salt '*' parallels.list_snapshots macvm tree=True runas=macdev
    salt '*' parallels.list_snapshots macvm snap_name=original runas=macdev
    salt '*' parallels.list_snapshots macvm names=True runas=macdev

parallels.list_vms:

List information about the VMs

:param str name:
    Name/ID of VM to list

    Changed in version 2016.11.0

        No longer implies ``info=True``

:param str info:
    List extra information

:param bool all:
    List all non-template VMs

:param tuple args:
    Additional arguments given to ``prctl list``

:param str runas:
    The user that the prlctl command will be run as

:param bool template:
    List the available virtual machine templates.  The real virtual
    machines will not be included in the output

    New in version 2016.11.0

Example:

    salt '*' parallels.list_vms runas=macdev
    salt '*' parallels.list_vms name=macvm info=True runas=macdev
    salt '*' parallels.list_vms info=True runas=macdev
    salt '*' parallels.list_vms ' -o uuid,status' all=True runas=macdev

parallels.prlctl:

Execute a prlctl command

:param str sub_cmd:
    prlctl subcommand to execute

:param str args:
    The arguments supplied to ``prlctl <sub_cmd>``

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.prlctl user list runas=macdev
    salt '*' parallels.prlctl exec 'macvm uname' runas=macdev
    salt -- '*' parallels.prlctl capture 'macvm --file macvm.display.png' runas=macdev

parallels.prlsrvctl:

Execute a prlsrvctl command

New in version 2016.11.0

:param str sub_cmd:
    prlsrvctl subcommand to execute

:param str args:
    The arguments supplied to ``prlsrvctl <sub_cmd>``

:param str runas:
    The user that the prlsrvctl command will be run as

Example:

    salt '*' parallels.prlsrvctl info runas=macdev
    salt '*' parallels.prlsrvctl usb list runas=macdev
    salt -- '*' parallels.prlsrvctl set '--mem-limit auto' runas=macdev

parallels.reset:

Reset a VM by performing a hard shutdown and then a restart

:param str name:
    Name/ID of VM to reset

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.reset macvm runas=macdev

parallels.restart:

Restart a VM by gracefully shutting it down and then restarting
it

:param str name:
    Name/ID of VM to restart

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.restart macvm runas=macdev

parallels.revert_snapshot:

Revert a VM to a snapshot

:param str name:
    Name/ID of VM to revert to a snapshot

:param str snap_name:
    Name/ID of snapshot to revert to

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.revert_snapshot macvm base-with-updates runas=macdev

parallels.snapshot:

Create a snapshot

:param str name:
    Name/ID of VM to take a snapshot of

:param str snap_name:
    Name of snapshot

:param str desc:
    Description of snapshot

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.create_snapshot macvm snap_name=macvm-original runas=macdev
    salt '*' parallels.create_snapshot macvm snap_name=macvm-updates desc='clean install with updates' runas=macdev

parallels.snapshot_id_to_name:

Attempt to convert a snapshot ID to a snapshot name.  If the snapshot has
no name or if the ID is not found or invalid, an empty string will be returned

:param str name:
    Name/ID of VM whose snapshots are inspected

:param str snap_id:
    ID of the snapshot

:param bool strict:
    Raise an exception if a name cannot be found for the given ``snap_id``

:param str runas:
    The user that the prlctl command will be run as

Example data

    ID: {a5b8999f-5d95-4aff-82de-e515b0101b66}
    Name: original
    Date: 2016-03-04 10:50:34
    Current: yes
    State: poweroff
    Description: original state

CLI Example:

    salt '*' parallels.snapshot_id_to_name macvm a5b8999f-5d95-4aff-82de-e515b0101b66 runas=macdev

parallels.snapshot_name_to_id:

Attempt to convert a snapshot name to a snapshot ID.  If the name is not
found an empty string is returned.  If multiple snapshots share the same
name, a list will be returned

:param str name:
    Name/ID of VM whose snapshots are inspected

:param str snap_name:
    Name of the snapshot

:param bool strict:
    Raise an exception if multiple snapshot IDs are found

:param str runas:
    The user that the prlctl command will be run as

CLI Example:

    salt '*' parallels.snapshot_id_to_name macvm original runas=macdev

parallels.start:

Start a VM

:param str name:
    Name/ID of VM to start

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.start macvm runas=macdev

parallels.status:

Status of a VM

:param str name:
    Name/ID of VM whose status will be returned

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.status macvm runas=macdev

parallels.stop:

Stop a VM

:param str name:
    Name/ID of VM to stop

:param bool kill:
    Perform a hard shutdown

:param str runas:
    The user that the prlctl command will be run as

Example:

    salt '*' parallels.stop macvm runas=macdev
    salt '*' parallels.stop macvm kill=True runas=macdev

partition.align_check:

Check if partition satisfies the alignment constraint of part_type.
Type must be "minimal" or "optimal".

CLI Example:

    salt '*' partition.align_check /dev/sda minimal 1

partition.check:

Checks if the file system on partition <minor> has any errors.

CLI Example:

    salt '*' partition.check 1

partition.cp:

Copies the file system on the partition <from-minor> to partition
<to-minor>, deleting the original contents of the destination
partition.

CLI Example:

    salt '*' partition.cp /dev/sda 2 3

partition.disk_set:

Changes a flag on selected device.

A flag can be either "on" or "off" (make sure to use proper
quoting, see :ref:`YAML Idiosyncrasies
<yaml-idiosyncrasies>`). Some or all of these flags will be
available, depending on what disk label you are using.

Valid flags are:
  * cylinder_alignment
  * pmbr_boot
  * implicit_partition_table

CLI Example:

    salt '*' partition.disk_set /dev/sda pmbr_boot '"on"'

partition.disk_toggle:

Toggle the state of <flag> on <device>. Valid flags are the same
as the disk_set command.

CLI Example:

    salt '*' partition.disk_toggle /dev/sda pmbr_boot

partition.exists:

Check to see if the partition exists

CLI Example:

    salt '*' partition.exists /dev/sdb1

partition.get_block_device:

Retrieve a list of disk devices

New in version 2014.7.0

CLI Example:

    salt '*' partition.get_block_device

partition.get_id:

Prints the system ID for the partition. Some typical values are::

     b: FAT32 (vfat)
     7: HPFS/NTFS
    82: Linux Swap
    83: Linux
    8e: Linux LVM
    fd: Linux RAID Auto

CLI Example:

    salt '*' partition.get_id /dev/sda 1

partition.list:

Prints partition information of given <device>

CLI Examples:

    salt '*' partition.list /dev/sda
    salt '*' partition.list /dev/sda unit=s
    salt '*' partition.list /dev/sda unit=kB

partition.mkfs:

Makes a file system <fs_type> on partition <device>, destroying all data
that resides on that partition. <fs_type> must be one of "ext2", "fat32",
"fat16", "linux-swap" or "reiserfs" (if libreiserfs is installed)

CLI Example:

    salt '*' partition.mkfs /dev/sda2 fat32

partition.mklabel:

Create a new disklabel (partition table) of label_type.

Type should be one of "aix", "amiga", "bsd", "dvh", "gpt", "loop", "mac",
"msdos", "pc98", or "sun".

CLI Example:

    salt '*' partition.mklabel /dev/sda msdos

partition.mkpart:

Make a part_type partition for filesystem fs_type, beginning at start and
ending at end (by default in megabytes).  part_type should be one of
"primary", "logical", or "extended".

CLI Examples:

    salt '*' partition.mkpart /dev/sda primary fs_type=fat32 start=0 end=639
    salt '*' partition.mkpart /dev/sda primary start=0 end=639

partition.mkpartfs:

The mkpartfs actually is an alias to mkpart and is kept for compatibility.
To know the valid options and usage syntax read mkpart documentation.

CLI Examples:

    salt '*' partition.mkpartfs /dev/sda primary fs_type=fat32 start=0 end=639
    salt '*' partition.mkpartfs /dev/sda primary start=0 end=639

partition.name:

Set the name of partition to name. This option works only on Mac, PC98, and
GPT disklabels. The name can be placed in quotes, if necessary.

CLI Example:

    salt '*' partition.name /dev/sda 1 'My Documents'

partition.probe:

Ask the kernel to update its local partition data. When no args are
specified all block devices are tried.

Caution: Generally only works on devices with no mounted partitions and
may take a long time to return if specified devices are in use.

CLI Examples:

    salt '*' partition.probe
    salt '*' partition.probe /dev/sda
    salt '*' partition.probe /dev/sda /dev/sdb

partition.rescue:

Rescue a lost partition that was located somewhere between start and end.
If a partition is found, parted will ask if you want to create an
entry for it in the partition table.

CLI Example:

    salt '*' partition.rescue /dev/sda 0 8056

partition.resize:

Resizes the partition with number <minor>.

The partition will start <start> from the beginning of the disk, and end
<end> from the beginning of the disk. resize never changes the minor number.
Extended partitions can be resized, so long as the new extended partition
completely contains all logical partitions.

CLI Example:

    salt '*' partition.resize /dev/sda 3 200 850

partition.rm:

Removes the partition with number <minor>.

CLI Example:

    salt '*' partition.rm /dev/sda 5

partition.set:

Changes a flag on the partition with number <minor>.

A flag can be either "on" or "off" (make sure to use proper quoting, see
:ref:`YAML Idiosyncrasies <yaml-idiosyncrasies>`). Some or all of these
flags will be available, depending on what disk label you are using.

Valid flags are:
  * boot
  * root
  * swap
  * hidden
  * raid
  * lvm
  * lba
  * hp-service
  * palo
  * prep
  * msftres
  * bios_grub
  * atvrecv
  * diag
  * legacy_boot
  * msftdata
  * irst
  * esp
  * type

CLI Example:

    salt '*' partition.set /dev/sda 1 boot '"on"'

partition.set_id:

Sets the system ID for the partition. Some typical values are::

     b: FAT32 (vfat)
     7: HPFS/NTFS
    82: Linux Swap
    83: Linux
    8e: Linux LVM
    fd: Linux RAID Auto

CLI Example:

    salt '*' partition.set_id /dev/sda 1 83

partition.system_types:

List the system types that are supported by the installed version of sfdisk

CLI Example:

    salt '*' partition.system_types

partition.toggle:

Toggle the state of <flag> on <partition>. Valid flags are the same as
    the set command.

CLI Example:

    salt '*' partition.toggle /dev/sda 1 boot

peeringdb.get_fac:

Return the details of the facility identified using the search
filters specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible facilities registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/netfac/netfac_list

CLI Example:

    salt '*' peeringdb.get_fac id=1774
    salt '*' peeringdb.get_fac state=UT

peeringdb.get_ix:

Return the details of an IX (Internet Exchange) using the search filters
specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible IXs registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/ix/ix_list

CLI Example:

    salt '*' peeringdb.get_ix id=1
    salt '*' peeringdb.get_ix city='Milwaukee'

peeringdb.get_ixfac:

Return the details of an IX (Internet Exchange) facility using the search
filters specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible IX facilities registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/ixfac/ixfac_list

CLI Example:

    salt '*' peeringdb.get_ixfac id=1
    salt '*' peeringdb.get_ixfac city='Milwaukee'

peeringdb.get_ixlan:

Return the details of an IX (Internet Exchange) together with the networks
available in this location (and their details), using the search filters
specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible IX LAN facilities registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/ixlan/ixlan_list

CLI Example:

    salt '*' peeringdb.get_ixlan id=780
    salt '*' peeringdb.get_ixlan city='Milwaukee'

peeringdb.get_ixpfx:

Return the details of an IX (Internet Exchange) together with the PeeringDB
IDs of the networks available in this location, using the search filters
specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible IX LAN facilities registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/ixpfx/ixpfx_list

CLI Example:

    salt '*' peeringdb.get_ixpfx id=780
    salt '*' peeringdb.get_ixpfx city='Milwaukee'

peeringdb.get_net:

Return the details of a network identified using the search filters
specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible networks registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/net/net_list

CLI Example:

    salt '*' peeringdb.get_net id=4224
    salt '*' peeringdb.get_net asn=13335
    salt '*' peeringdb.get_net city='Salt Lake City'
    salt '*' peeringdb.get_net name__startswith=GTT

peeringdb.get_netfac:

Return the list of facilities used by a particular network, given the ``id``
or other filters specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible network facilities registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/netfac/netfac_list

CLI Example:

    salt '*' peeringdb.get_netfac id=780
    salt '*' peeringdb.get_netfac city='Milwaukee'

peeringdb.get_netixlan:

Return the IP addresses used by a particular network at all the IXs where it
is available. The network is selected either via the ``id`` argument or the
other filters specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible IP addresses, of all networks, at all IXs, registered in
    PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/netixlan/netixlan_list

CLI Example:

    salt '*' peeringdb.get_netixlan asn=13335
    salt '*' peeringdb.get_netixlan ipaddr4=185.1.114.25

peeringdb.get_org:

Return the details of an organisation together with the networks
available in this location, using the search filters specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible organisations registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/org/org_list

CLI Example:

    salt '*' peeringdb.get_org id=2
    salt '*' peeringdb.get_org city=Duesseldorf

peeringdb.get_poc:

Return the details of a person of contact together using the search filters
specified in the query.

Note:
    If no ``id`` or filter arguments are specified, it will return all the
    possible contacts registered in PeeringDB.

    The available filters are documented at:
    https://www.peeringdb.com/apidocs/#!/poc/poc_list

CLI Example:

    salt '*' peeringdb.get_poc id=6721
    salt '*' peeringdb.get_poc email__contains='@cloudflare.com'

pillar.data:

Calls the master for a fresh pillar, generates the pillar data on the
fly (same as :py:func:`items`)

pillar
    If specified, allows for a dictionary of pillar data to be made
    available to pillar and ext_pillar rendering. these pillar variables
    will also override any variables of the same name in pillar or
    ext_pillar.

pillar_enc
    If specified, the data passed in the ``pillar`` argument will be passed
    through this renderer to decrypt it.

    Note:
        This will decrypt on the minion side, so the specified renderer
        must be set up on the minion for this to work. Alternatively,
        pillar data can be decrypted master-side. For more information, see
        the :ref:`Pillar Encryption <pillar-encryption>` documentation.
        Pillar data that is decrypted master-side, is not decrypted until
        the end of pillar compilation though, so minion-side decryption
        will be necessary if the encrypted pillar data must be made
        available in an decrypted state pillar/ext_pillar rendering.

pillarenv
    Pass a specific pillar environment from which to compile pillar data.
    If not specified, then the minion's :conf_minion:`pillarenv` option is
    not used, and if that also is not specified then all configured pillar
    environments will be merged into a single pillar dictionary and
    returned.

saltenv
    Included only for compatibility with
    :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

CLI Examples:

    salt '*' pillar.data

pillar.ext:

Changed in version 2016.3.6,2016.11.3,2017.7.0
    The supported ext_pillar types are now tunable using the
    :conf_master:`on_demand_ext_pillar` config option. Earlier releases
    used a hard-coded default.

Generate the pillar and apply an explicit external pillar


external
    A single ext_pillar to add to the ext_pillar configuration. This must
    be passed as a single section from the ext_pillar configuration (see
    CLI examples below). For more complicated ``ext_pillar``
    configurations, it can be helpful to use the Python shell to load YAML
    configuration into a dictionary, and figure out

        >>> import salt.utils.yaml
        >>> ext_pillar = salt.utils.yaml.safe_load("""
        ... ext_pillar:
        ...   - git:
        ...     - issue38440 https://github.com/terminalmage/git_pillar:
        ...       - env: base
        ... """)
        >>> ext_pillar
        {'ext_pillar': [{'git': [{'mybranch https://github.com/myuser/myrepo': [{'env': 'base'}]}]}]}
        >>> ext_pillar['ext_pillar'][0]
        {'git': [{'mybranch https://github.com/myuser/myrepo': [{'env': 'base'}]}]}

    In the above example, the value to pass would be
    ``{'git': [{'mybranch https://github.com/myuser/myrepo': [{'env': 'base'}]}]}``.
    Note that this would need to be quoted when passing on the CLI (as in
    the CLI examples below).

pillar : None
    If specified, allows for a dictionary of pillar data to be made
    available to pillar and ext_pillar rendering. These pillar variables
    will also override any variables of the same name in pillar or
    ext_pillar.

    New in version 2015.5.0

CLI Examples:

    salt '*' pillar.ext '{libvirt: _}'
    salt '*' pillar.ext "{'git': ['master https://github.com/myuser/myrepo']}"
    salt '*' pillar.ext "{'git': [{'mybranch https://github.com/myuser/myrepo': [{'env': 'base'}]}]}"

pillar.fetch:

New in version 0.14.0

Attempt to retrieve the named value from :ref:`in-memory pillar data
<pillar-in-memory>`. If the pillar key is not present in the in-memory
pillar, then the value specified in the ``default`` option (described
below) will be returned.

If the merge parameter is set to ``True``, the default will be recursively
merged into the returned pillar data.

The value can also represent a value in a nested dict using a ":" delimiter
for the dict. This means that if a dict in pillar looks like this::

    {'pkg': {'apache': 'httpd'}}

To retrieve the value associated with the ``apache`` key in the ``pkg``
dict this key can be passed as::

    pkg:apache

key
    The pillar key to get value from

default
    The value specified by this option will be returned if the desired
    pillar key does not exist.

    If a default value is not specified, then it will be an empty string,
    unless :conf_minion:`pillar_raise_on_missing` is set to ``True``, in
    which case an error will be raised.

merge : ``False``
    If ``True``, the retrieved values will be merged into the passed
    default. When the default and the retrieved value are both
    dictionaries, the dictionaries will be recursively merged.

    New in version 2014.7.0
    Changed in version 2016.3.7,2016.11.4,2017.7.0
        If the default and the retrieved value are not of the same type,
        then merging will be skipped and the retrieved value will be
        returned. Earlier releases raised an error in these cases.

merge_nested_lists
    If set to ``False``, lists nested within the retrieved pillar
    dictionary will *overwrite* lists in ``default``. If set to ``True``,
    nested lists will be *merged* into lists in ``default``. If unspecified
    (the default), this option is inherited from the
    :conf_minion:`pillar_merge_lists` minion config option.

    Note:
        This option is ignored when ``merge`` is set to ``False``.

    New in version 2016.11.6

delimiter
    Specify an alternate delimiter to use when traversing a nested dict.
    This is useful for when the desired key contains a colon. See CLI
    example below for usage.

    New in version 2014.7.0

pillarenv
    If specified, this function will query the master to generate fresh
    pillar data on the fly, specifically from the requested pillar
    environment. Note that this can produce different pillar data than
    executing this function without an environment, as its normal behavior
    is just to return a value from minion's pillar data in memory (which
    can be sourced from more than one pillar environment).

    Using this argument will not affect the pillar data in memory. It will
    however be slightly slower and use more resources on the master due to
    the need for the master to generate and send the minion fresh pillar
    data. This tradeoff in performance however allows for the use case
    where pillar data is desired only from a single environment.

    New in version 2017.7.0

saltenv
    Included only for compatibility with
    :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

    New in version 2017.7.0

CLI Example:

    salt '*' pillar.get pkg:apache
    salt '*' pillar.get abc::def|ghi delimiter='|'

pillar.file_exists:

New in version 2016.3.0

This is a master-only function. Calling from the minion is not supported.

Use the given path and search relative to the pillar environments to see if
a file exists at that path.

If the ``saltenv`` argument is given, restrict search to that environment
only.

Will only work with ``pillar_roots``, not external pillars.

Returns True if the file is found, and False otherwise.

path
    The path to the file in question. Will be treated as a relative path

saltenv
    Optional argument to restrict the search to a specific saltenv

CLI Example:

    salt '*' pillar.file_exists foo/bar.sls

pillar.filter_by:

New in version 2017.7.0

Look up the given pillar in a given dictionary and return the result

:param lookup_dict: A dictionary, keyed by a pillar, containing a value or
    values relevant to systems matching that pillar. For example, a key
    could be a pillar for a role and the value could the name of a package
    on that particular OS.

    The dictionary key can be a globbing pattern. The function will return
    the corresponding ``lookup_dict`` value where the pillar value matches
    the  pattern. For example:

        # this will render 'got some salt' if ``role`` begins with 'salt'
        salt '*' pillar.filter_by '{salt*: got some salt, default: salt is not here}' role

:param pillar: The name of a pillar to match with the system's pillar. For
    example, the value of the "role" pillar could be used to pull values
    from the ``lookup_dict`` dictionary.

    The pillar value can be a list. The function will return the
    ``lookup_dict`` value for a first found item in the list matching
    one of the ``lookup_dict`` keys.

:param merge: A dictionary to merge with the results of the pillar
    selection from ``lookup_dict``. This allows another dictionary to
    override the values in the ``lookup_dict``.

:param default: default lookup_dict's key used if the pillar does not exist
    or if the pillar value has no match on lookup_dict.  If unspecified
    the value is "default".

:param base: A lookup_dict key to use for a base dictionary.  The
    pillar-selected ``lookup_dict`` is merged over this and then finally
    the ``merge`` dictionary is merged.  This allows common values for
    each case to be collected in the base and overridden by the pillar
    selection dictionary and the merge dictionary.  Default is unset.

CLI Example:

    salt '*' pillar.filter_by '{web: Serve it up, db: I query, default: x_x}' role

pillar.get:

New in version 0.14.0

Attempt to retrieve the named value from :ref:`in-memory pillar data
<pillar-in-memory>`. If the pillar key is not present in the in-memory
pillar, then the value specified in the ``default`` option (described
below) will be returned.

If the merge parameter is set to ``True``, the default will be recursively
merged into the returned pillar data.

The value can also represent a value in a nested dict using a ":" delimiter
for the dict. This means that if a dict in pillar looks like this::

    {'pkg': {'apache': 'httpd'}}

To retrieve the value associated with the ``apache`` key in the ``pkg``
dict this key can be passed as::

    pkg:apache

key
    The pillar key to get value from

default
    The value specified by this option will be returned if the desired
    pillar key does not exist.

    If a default value is not specified, then it will be an empty string,
    unless :conf_minion:`pillar_raise_on_missing` is set to ``True``, in
    which case an error will be raised.

merge : ``False``
    If ``True``, the retrieved values will be merged into the passed
    default. When the default and the retrieved value are both
    dictionaries, the dictionaries will be recursively merged.

    New in version 2014.7.0
    Changed in version 2016.3.7,2016.11.4,2017.7.0
        If the default and the retrieved value are not of the same type,
        then merging will be skipped and the retrieved value will be
        returned. Earlier releases raised an error in these cases.

merge_nested_lists
    If set to ``False``, lists nested within the retrieved pillar
    dictionary will *overwrite* lists in ``default``. If set to ``True``,
    nested lists will be *merged* into lists in ``default``. If unspecified
    (the default), this option is inherited from the
    :conf_minion:`pillar_merge_lists` minion config option.

    Note:
        This option is ignored when ``merge`` is set to ``False``.

    New in version 2016.11.6

delimiter
    Specify an alternate delimiter to use when traversing a nested dict.
    This is useful for when the desired key contains a colon. See CLI
    example below for usage.

    New in version 2014.7.0

pillarenv
    If specified, this function will query the master to generate fresh
    pillar data on the fly, specifically from the requested pillar
    environment. Note that this can produce different pillar data than
    executing this function without an environment, as its normal behavior
    is just to return a value from minion's pillar data in memory (which
    can be sourced from more than one pillar environment).

    Using this argument will not affect the pillar data in memory. It will
    however be slightly slower and use more resources on the master due to
    the need for the master to generate and send the minion fresh pillar
    data. This tradeoff in performance however allows for the use case
    where pillar data is desired only from a single environment.

    New in version 2017.7.0

saltenv
    Included only for compatibility with
    :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

    New in version 2017.7.0

CLI Example:

    salt '*' pillar.get pkg:apache
    salt '*' pillar.get abc::def|ghi delimiter='|'

pillar.item:

New in version 0.16.2

Return one or more pillar entries from the :ref:`in-memory pillar data
<pillar-in-memory>`.

delimiter
    Delimiter used to traverse nested dictionaries.

    Note:
        This is different from :py:func:`pillar.get
        <salt.modules.pillar.get>` in that no default value can be
        specified. :py:func:`pillar.get <salt.modules.pillar.get>` should
        probably still be used in most cases to retrieve nested pillar
        values, as it is a bit more flexible. One reason to use this
        function instead of :py:func:`pillar.get <salt.modules.pillar.get>`
        however is when it is desirable to retrieve the values of more than
        one key, since :py:func:`pillar.get <salt.modules.pillar.get>` can
        only retrieve one key at a time.

    New in version 2015.8.0

pillarenv
    If specified, this function will query the master to generate fresh
    pillar data on the fly, specifically from the requested pillar
    environment. Note that this can produce different pillar data than
    executing this function without an environment, as its normal behavior
    is just to return a value from minion's pillar data in memory (which
    can be sourced from more than one pillar environment).

    Using this argument will not affect the pillar data in memory. It will
    however be slightly slower and use more resources on the master due to
    the need for the master to generate and send the minion fresh pillar
    data. This tradeoff in performance however allows for the use case
    where pillar data is desired only from a single environment.

    New in version 2017.7.6,2018.3.1

saltenv
    Included only for compatibility with
    :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

    New in version 2017.7.6,2018.3.1

CLI Examples:

    salt '*' pillar.item foo
    salt '*' pillar.item foo:bar
    salt '*' pillar.item foo bar baz

pillar.items:

Calls the master for a fresh pillar and generates the pillar data on the
fly

Contrast with :py:func:`raw` which returns the pillar data that is
currently loaded into the minion.

pillar
    If specified, allows for a dictionary of pillar data to be made
    available to pillar and ext_pillar rendering. these pillar variables
    will also override any variables of the same name in pillar or
    ext_pillar.

    New in version 2015.5.0

pillar_enc
    If specified, the data passed in the ``pillar`` argument will be passed
    through this renderer to decrypt it.

    Note:
        This will decrypt on the minion side, so the specified renderer
        must be set up on the minion for this to work. Alternatively,
        pillar data can be decrypted master-side. For more information, see
        the :ref:`Pillar Encryption <pillar-encryption>` documentation.
        Pillar data that is decrypted master-side, is not decrypted until
        the end of pillar compilation though, so minion-side decryption
        will be necessary if the encrypted pillar data must be made
        available in an decrypted state pillar/ext_pillar rendering.

    New in version 2017.7.0

pillarenv
    Pass a specific pillar environment from which to compile pillar data.
    If not specified, then the minion's :conf_minion:`pillarenv` option is
    not used, and if that also is not specified then all configured pillar
    environments will be merged into a single pillar dictionary and
    returned.

    New in version 2016.11.2

saltenv
    Included only for compatibility with
    :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

CLI Example:

    salt '*' pillar.items

pillar.keys:

New in version 2015.8.0

Attempt to retrieve a list of keys from the named value from the pillar.

The value can also represent a value in a nested dict using a ":" delimiter
for the dict, similar to how pillar.get works.

delimiter
    Specify an alternate delimiter to use when traversing a nested dict

CLI Example:

    salt '*' pillar.keys web:sites

pillar.ls:

New in version 2015.8.0

Calls the master for a fresh pillar, generates the pillar data on the
fly (same as :py:func:`items`), but only shows the available main keys.

pillar
    If specified, allows for a dictionary of pillar data to be made
    available to pillar and ext_pillar rendering. these pillar variables
    will also override any variables of the same name in pillar or
    ext_pillar.

pillar_enc
    If specified, the data passed in the ``pillar`` argument will be passed
    through this renderer to decrypt it.

    Note:
        This will decrypt on the minion side, so the specified renderer
        must be set up on the minion for this to work. Alternatively,
        pillar data can be decrypted master-side. For more information, see
        the :ref:`Pillar Encryption <pillar-encryption>` documentation.
        Pillar data that is decrypted master-side, is not decrypted until
        the end of pillar compilation though, so minion-side decryption
        will be necessary if the encrypted pillar data must be made
        available in an decrypted state pillar/ext_pillar rendering.

pillarenv
    Pass a specific pillar environment from which to compile pillar data.
    If not specified, then the minion's :conf_minion:`pillarenv` option is
    not used, and if that also is not specified then all configured pillar
    environments will be merged into a single pillar dictionary and
    returned.

saltenv
    Included only for compatibility with
    :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

CLI Examples:

    salt '*' pillar.ls

pillar.obfuscate:

New in version 2015.8.0

Same as :py:func:`items`, but replace pillar values with a simple type indication.

This is useful to avoid displaying sensitive information on console or
flooding the console with long output, such as certificates.
For many debug or control purposes, the stakes lie more in dispatching than in
actual values.

In case the value is itself a collection type, obfuscation occurs within the value.
For mapping types, keys are not obfuscated.
Here are some examples:

* ``'secret password'`` becomes ``'<str>'``
* ``['secret', 1]`` becomes ``['<str>', '<int>']``
* ``{'login': 'somelogin', 'pwd': 'secret'}`` becomes
  ``{'login': '<str>', 'pwd': '<str>'}``

CLI Examples:

    salt '*' pillar.obfuscate

pillar.raw:

Return the raw pillar data that is currently loaded into the minion.

Contrast with :py:func:`items` which calls the master to fetch the most
up-to-date Pillar.

CLI Example:

    salt '*' pillar.raw

With the optional key argument, you can select a subtree of the
pillar raw data.::

    salt '*' pillar.raw key='roles'

pip.freeze:

Return a list of installed packages either globally or in the specified
virtualenv

bin_env
    Path to pip (or to a virtualenv). This can be used to specify the path
    to the pip to use when more than one Python release is installed (e.g.
    ``/usr/bin/pip-2.7`` or ``/usr/bin/pip-2.6``. If a directory path is
    specified, it is assumed to be a virtualenv.

user
    The user under which to run pip

cwd
    Directory from which to run pip

Note:
    If the version of pip available is older than 8.0.3, the list will not
    include the packages ``pip``, ``wheel``, ``setuptools``, or
    ``distribute`` even if they are installed.

CLI Example:

    salt '*' pip.freeze bin_env=/home/code/path/to/virtualenv

pip.install:

Install packages with pip

Install packages individually or from a pip requirements file. Install
packages globally or to a virtualenv.

pkgs
    Comma separated list of packages to install

requirements
    Path to requirements

bin_env
    Path to pip (or to a virtualenv). This can be used to specify the path
    to the pip to use when more than one Python release is installed (e.g.
    ``/usr/bin/pip-2.7`` or ``/usr/bin/pip-2.6``. If a directory path is
    specified, it is assumed to be a virtualenv.

    Note:

        For Windows, if the pip module is being used to upgrade the pip
        package, bin_env should be the path to the virtualenv or to the
        python binary that should be used.  The pip command is unable to
        upgrade itself in Windows.

use_wheel
    Prefer wheel archives (requires pip>=1.4)

no_use_wheel
    Force to not use wheel archives (requires pip>=1.4,<10.0.0)

no_binary
    Force to not use binary packages (requires pip >= 7.0.0)
    Accepts either :all: to disable all binary packages, :none: to empty the set,
    or one or more package names with commas between them

log
    Log file where a complete (maximum verbosity) record will be kept.
    If this file doesn't exist and the parent directory is writeable,
    it will be created.

proxy
    Specify a proxy in the form ``user:passwd@proxy.server:port``. Note
    that the ``user:password@`` is optional and required only if you are
    behind an authenticated proxy. If you provide
    ``user@proxy.server:port`` then you will be prompted for a password.

    Note:
        If the Minion has a globaly configured proxy - it will be used
        even if no proxy was set here. To explicitly disable proxy for pip
        you should pass ``False`` as a value.

timeout
    Set the socket timeout (default 15 seconds)

editable
    install something editable (e.g.
    ``git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed``)

find_links
    URL to search for packages

index_url
    Base URL of Python Package Index

extra_index_url
    Extra URLs of package indexes to use in addition to ``index_url``

no_index
    Ignore package index

mirrors
    Specific mirror URL(s) to query (automatically adds --use-mirrors)

    Warning:

        This option has been deprecated and removed in pip version 7.0.0.
        Please use ``index_url`` and/or ``extra_index_url`` instead.

build
    Unpack packages into ``build`` dir

target
    Install packages into ``target`` dir

download
    Download packages into ``download`` instead of installing them

download_cache | cache_dir
    Cache downloaded packages in ``download_cache`` or ``cache_dir`` dir

source
    Check out ``editable`` packages into ``source`` dir

upgrade
    Upgrade all packages to the newest available version

force_reinstall
    When upgrading, reinstall all packages even if they are already
    up-to-date.

ignore_installed
    Ignore the installed packages (reinstalling instead)

exists_action
    Default action when a path already exists: (s)witch, (i)gnore, (w)ipe,
    (b)ackup

no_deps
    Ignore package dependencies

no_install
    Download and unpack all packages, but don't actually install them

no_download
    Don't download any packages, just install the ones already downloaded
    (completes an install run with ``--no-install``)

install_options
    Extra arguments to be supplied to the setup.py install command (e.g.
    like ``--install-option='--install-scripts=/usr/local/bin'``).  Use
    multiple --install-option options to pass multiple options to setup.py
    install. If you are using an option with a directory path, be sure to
    use absolute path.

global_options
    Extra global options to be supplied to the setup.py call before the
    install command.

user
    The user under which to run pip

cwd
    Directory from which to run pip

pre_releases
    Include pre-releases in the available versions

cert
    Provide a path to an alternate CA bundle

allow_all_external
    Allow the installation of all externally hosted files

allow_external
    Allow the installation of externally hosted files (comma separated
    list)

allow_unverified
    Allow the installation of insecure and unverifiable files (comma
    separated list)

process_dependency_links
    Enable the processing of dependency links

env_vars
    Set environment variables that some builds will depend on. For example,
    a Python C-module may have a Makefile that needs INCLUDE_PATH set to
    pick up a header file while compiling.  This must be in the form of a
    dictionary or a mapping.

    Example:

        salt '*' pip.install django_app env_vars="{'CUSTOM_PATH': '/opt/django_app'}"

trusted_host
    Mark this host as trusted, even though it does not have valid or any
    HTTPS.

use_vt
    Use VT terminal emulation (see output while installing)

no_cache_dir
    Disable the cache.

extra_args
    pip keyword and positional arguments not yet implemented in salt

        salt '*' pip.install pandas extra_args="[{'--latest-pip-kwarg':'param'}, '--latest-pip-arg']"

    Warning:

        If unsupported options are passed here that are not supported in a
        minion's version of pip, a `No such option error` will be thrown.

Will be translated into the following pip command:

    pip install pandas --latest-pip-kwarg param --latest-pip-arg

disable_version_check
    Pip may periodically check PyPI to determine whether a new version of
    pip is available to download. Passing True for this option disables
    that check.

CLI Example:

    salt '*' pip.install <package name>,<package2 name>
    salt '*' pip.install requirements=/path/to/requirements.txt
    salt '*' pip.install <package name> bin_env=/path/to/virtualenv
    salt '*' pip.install <package name> bin_env=/path/to/pip_bin

Complicated CLI Example:

    salt '*' pip.install markdown,django                 editable=git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed upgrade=True no_deps=True

pip.is_installed:

New in version 2018.3.0
Changed in version 3006.0

Filter list of installed modules and return True if ``pkgname`` exists in
the list of packages installed.

CLI Example:

    salt '*' pip.is_installed salt

pip.list:

Changed in version 3006.0

Output list of installed apps from ``pip list`` in JSON format and check to
see if ``prefix`` exists in the list of packages installed.

Note:

    If the version of pip available is older than 9.0.0, parsing the
    ``freeze`` function output will be used to determine the name and
    version of installed modules.

CLI Example:

    salt '*' pip.list salt

pip.list_all_versions:

New in version 2017.7.3

List all available versions of a pip package

pkg
    The package to check

bin_env
    Path to pip (or to a virtualenv). This can be used to specify the path
    to the pip to use when more than one Python release is installed (e.g.
    ``/usr/bin/pip-2.7`` or ``/usr/bin/pip-2.6``. If a directory path is
    specified, it is assumed to be a virtualenv.

include_alpha
    Include alpha versions in the list

include_beta
    Include beta versions in the list

include_rc
    Include release candidates versions in the list

user
    The user under which to run pip

cwd
    Directory from which to run pip

index_url
    Base URL of Python Package Index
    New in version 2019.2.0

extra_index_url
    Additional URL of Python Package Index
    New in version 2019.2.0

CLI Example:

   salt '*' pip.list_all_versions <package name>

pip.list_freeze_parse:

New in version 3006.0

Filter list of installed apps from ``freeze`` and check to see if
``prefix`` exists in the list of packages installed.

Note:

    If the version of pip available is older than 8.0.3, the packages
    ``wheel``, ``setuptools``, and ``distribute`` will not be reported by
    this function even if they are installed. Unlike :py:func:`pip.freeze
    <salt.modules.pip.freeze>`, this function always reports the version of
    pip which is installed.

CLI Example:

    salt '*' pip.list_freeze_parse salt

pip.list_upgrades:

Check whether or not an upgrade is available for all packages

CLI Example:

    salt '*' pip.list_upgrades

pip.uninstall:

Uninstall packages individually or from a pip requirements file

pkgs
    comma separated list of packages to install

requirements
    Path to requirements file

bin_env
    Path to pip (or to a virtualenv). This can be used to specify the path
    to the pip to use when more than one Python release is installed (e.g.
    ``/usr/bin/pip-2.7`` or ``/usr/bin/pip-2.6``. If a directory path is
    specified, it is assumed to be a virtualenv.

log
    Log file where a complete (maximum verbosity) record will be kept

proxy
    Specify a proxy in the format ``user:passwd@proxy.server:port``. Note
    that the ``user:password@`` is optional and required only if you are
    behind an authenticated proxy.  If you provide
    ``user@proxy.server:port`` then you will be prompted for a password.

    Note:
        If the Minion has a globaly configured proxy - it will be used
        even if no proxy was set here. To explicitly disable proxy for pip
        you should pass ``False`` as a value.

timeout
    Set the socket timeout (default 15 seconds)

user
    The user under which to run pip

cwd
    Directory from which to run pip

use_vt
    Use VT terminal emulation (see output while installing)

CLI Example:

    salt '*' pip.uninstall <package name>,<package2 name>
    salt '*' pip.uninstall requirements=/path/to/requirements.txt
    salt '*' pip.uninstall <package name> bin_env=/path/to/virtualenv
    salt '*' pip.uninstall <package name> bin_env=/path/to/pip_bin

pip.upgrade:

New in version 2015.5.0

Upgrades outdated pip packages.

Note:
    On Windows you can't update salt from pip using salt, so salt will be
    skipped

Returns a dict containing the changes.

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

CLI Example:

    salt '*' pip.upgrade

pip.upgrade_available:

New in version 2015.5.0

Check whether or not an upgrade is available for a given package

CLI Example:

    salt '*' pip.upgrade_available <package name>

pip.version:

New in version 0.17.0

Returns the version of pip. Use ``bin_env`` to specify the path to a
virtualenv and get the version of pip in that virtualenv.

If unable to detect the pip version, returns ``None``.

Changed in version 3001.1
    The ``user`` parameter was added, to allow specifying the user who runs
    the version command.

CLI Example:

    salt '*' pip.version

pkg.add_repo_key:

New in version 2017.7.0

Add a repo key using ``apt-key add``.

:param str path: The path of the key file to import.
:param str text: The key data to import, in string form.
:param str keyserver: The server to download the repo key specified by the keyid.
:param str keyid: The key id of the repo key to add.
:param str saltenv: The environment the key file resides in.
:param bool aptkey: Use the binary apt-key.
:param str keydir: The directory path to save keys. The default directory
                   is /etc/apt/keyrings/ which is the recommended path
                   for adding third party keys. This argument is only used
                   when aptkey is False.

:param str keyfile: The name of the key to add. This is only required when
                    aptkey is False and you are using a keyserver. This
                    argument is only used when aptkey is False.

:return: A boolean representing whether the repo key was added.
:rtype: bool

Warning:
   The apt-key binary is deprecated and will last be available
   in Debian 11 and Ubuntu 22.04. It is recommended to use aptkey=False
   when using this module.

CLI Examples:

    salt '*' pkg.add_repo_key 'salt://apt/sources/test.key'

    salt '*' pkg.add_repo_key text="'$KEY1'"

    salt '*' pkg.add_repo_key keyserver='keyserver.example' keyid='0000AAAA'

pkg.autoremove:

New in version 2015.5.0

Remove packages not required by another package using ``apt-get
autoremove``.

list_only : False
    Only retrieve the list of packages to be auto-removed, do not actually
    perform the auto-removal.

purge : False
    Also remove package config data when autoremoving packages.

    New in version 2015.8.0

CLI Example:

    salt '*' pkg.autoremove
    salt '*' pkg.autoremove list_only=True
    salt '*' pkg.autoremove purge=True

pkg.available_version:

This function is an alias of latest_version.

Changed in version 3007.0

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.

A specific repo can be requested using the ``fromrepo`` keyword argument.

cache_valid_time

    New in version 2016.11.0

    Skip refreshing the package database if refresh has already occurred within
    <value> seconds

CLI Example:

    salt '*' pkg.latest_version <package name>
    salt '*' pkg.latest_version <package name> fromrepo=unstable
    salt '*' pkg.latest_version <package1> <package2> <package3> ...

pkg.del_repo:

Delete a repo from the sources.list / sources.list.d

If the .list file is in the sources.list.d directory
and the file that the repo exists in does not contain any other
repo configuration, the file itself will be deleted.

The repo passed in must be a fully formed repository definition
string.

CLI Examples:

    salt '*' pkg.del_repo "myrepo definition"

pkg.del_repo_key:

New in version 2015.8.0

Remove a repo key using ``apt-key del``

name
    Repo from which to remove the key. Unnecessary if ``keyid`` is passed.

keyid
    The KeyID of the GPG key to remove

keyid_ppa : False
    If set to ``True``, the repo's GPG key ID will be looked up from
    ppa.launchpad.net and removed.

    Note:

        Setting this option to ``True`` requires that the ``name`` param
        also be passed.

aptkey
    Use the binary apt-key.

keydir
    The directory path to save keys. The default directory
    is /etc/apt/keyrings/ which is the recommended path
    for adding third party keys.

Warning:
   The apt-key binary is deprecated and will last be available
   in Debian 11 and Ubuntu 22.04. It is recommended to use aptkey=False
   when using this module.

CLI Examples:

    salt '*' pkg.del_repo_key keyid=0123ABCD
    salt '*' pkg.del_repo_key name='ppa:foo/bar' keyid_ppa=True

pkg.file_dict:

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:

    salt '*' pkg.file_dict httpd
    salt '*' pkg.file_dict httpd postfix
    salt '*' pkg.file_dict

pkg.file_list:

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:

    salt '*' pkg.file_list httpd
    salt '*' pkg.file_list httpd postfix
    salt '*' pkg.file_list

pkg.get_repo:

Display a repo from the sources.list / sources.list.d

The repo passed in needs to be a complete repo entry.

CLI Examples:

    salt '*' pkg.get_repo "myrepo definition"

pkg.get_repo_keys:

New in version 2017.7.0

List known repo key details.
:param bool aptkey: Use the binary apt-key.
:param str keydir: The directory path to save keys. The default directory
is /etc/apt/keyrings/ which is the recommended path
for adding third party keys. This argument is only used
when aptkey is False.

:return: A dictionary containing the repo keys.
:rtype: dict

CLI Examples:

    salt '*' pkg.get_repo_keys

pkg.get_selections:

View package state from the dpkg database.

Returns a dict of dicts containing the state, and package names:

    {'<host>':
        {'<state>': ['pkg1',
                     ...
                    ]
        },
        ...
    }

CLI Example:

    salt '*' pkg.get_selections
    salt '*' pkg.get_selections 'python-*'
    salt '*' pkg.get_selections state=hold
    salt '*' pkg.get_selections 'openssh*' state=hold

pkg.hold:

New in version 2014.7.0

Set package in 'hold' state, meaning it will not be upgraded.

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

    CLI Example:

        salt '*' pkg.hold <package name>

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

    CLI Example:

        salt '*' pkg.hold pkgs='["foo", "bar"]'

pkg.info_installed:

Return the information of the named package(s) installed on the system.

New in version 2015.8.1

names
    The names of the packages for which to return information.

failhard
    Whether to throw an exception if none of the packages are installed.
    Defaults to True.

    New in version 2016.11.3

CLI Example:

    salt '*' pkg.info_installed <package1>
    salt '*' pkg.info_installed <package1> <package2> <package3> ...
    salt '*' pkg.info_installed <package1> failhard=false

pkg.install:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands which modify installed packages from the
    ``salt-minion`` daemon's control group. This is done to keep systemd
    from killing any apt-get/dpkg commands spawned by Salt when the
    ``salt-minion`` service is restarted. (see ``KillMode`` in the
    `systemd.kill(5)`_ manpage for more information). If desired, usage of
    `systemd-run(1)`_ can be suppressed by setting a :mod:`config option
    <salt.modules.config.get>` called ``systemd.scope``, with a value of
    ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html
.. _`systemd.kill(5)`: https://www.freedesktop.org/software/systemd/man/systemd.kill.html

Install the passed package, add refresh=True to update the dpkg 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.

    32-bit packages can be installed on 64-bit systems by appending the
    architecture designation (``:i386``, etc.) to the end of the package
    name.

    CLI Example:

        salt '*' pkg.install <package name>

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

cache_valid_time

    New in version 2016.11.0

    Skip refreshing the package database if refresh has already occurred within
    <value> seconds

fromrepo
    Specify a package repository to install from
    (e.g., ``apt-get -t unstable install somepackage``)

skip_verify
    Skip the GPG verification check (e.g., ``--allow-unauthenticated``, or
    ``--force-bad-verify`` for install from package file).

debconf
    Provide the path to a debconf answers file, processed before
    installation.

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

    Changed in version 2018.3.0
        version can now contain comparison operators (e.g. ``>1.2.3``,
        ``<=2.0``, etc.)

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

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

    New in version 2015.8.0

ignore_epoch : False
    Only used when the version of a package is specified using a comparison
    operator (e.g. ``>4.1``). If set to ``True``, then the epoch will be
    ignored when comparing the currently-installed version to the desired
    version.

    New in version 2018.3.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:

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

sources
    A list of DEB 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.

    32-bit packages can be installed on 64-bit systems by appending the
    architecture designation (``:i386``, etc.) to the end of the package
    name.

    Changed in version 2014.7.0

    CLI Example:

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

force_yes
    Passes ``--force-yes`` to the apt-get command.  Don't use this unless
    you know what you're doing.

    New in version 0.17.4

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

    New in version 2015.5.0

only_upgrade
    Only upgrade the packages, if they are already installed. Default is False.

    New in version 2015.5.0

force_conf_new
    Always install the new version of any configuration files.

    New in version 2015.8.0

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

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

pkg.latest_version:

Changed in version 3007.0

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.

A specific repo can be requested using the ``fromrepo`` keyword argument.

cache_valid_time

    New in version 2016.11.0

    Skip refreshing the package database if refresh has already occurred within
    <value> seconds

CLI Example:

    salt '*' pkg.latest_version <package name>
    salt '*' pkg.latest_version <package name> fromrepo=unstable
    salt '*' pkg.latest_version <package1> <package2> <package3> ...

pkg.list_downloaded:

New in version 3000

List prefetched packages downloaded by apt in the local disk.

root
    operate on a different root directory.

CLI Example:

    salt '*' pkg.list_downloaded

pkg.list_pkgs:

List the packages currently installed in a dict::

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

removed
    If ``True``, then only packages which have been removed (but not
    purged) will be returned.

purge_desired
    If ``True``, then only packages which have been marked to be purged,
    but can't be purged due to their status as dependencies for other
    installed packages, will be returned. Note that these packages will
    appear in installed

    Changed in version 2014.1.1

        Packages in this state now correctly show up in the output of this
        function.

CLI Example:

    salt '*' pkg.list_pkgs
    salt '*' pkg.list_pkgs versions_as_list=True

pkg.list_repo_pkgs:

New in version 2017.7.0

Returns all available packages. Optionally, package names (and name globs)
can be passed and the results will be filtered to packages matching those
names.

This function can be helpful in discovering the version or repo to specify
in a :mod:`pkg.installed <salt.states.pkg.installed>` state.

The return data will be a dictionary mapping package names to a list of
version numbers, ordered from newest to oldest. For example:

    {
        'bash': ['4.3-14ubuntu1.1',
                 '4.3-14ubuntu1'],
        'nginx': ['1.10.0-0ubuntu0.16.04.4',
                  '1.9.15-0ubuntu1']
    }

CLI Examples:

    salt '*' pkg.list_repo_pkgs
    salt '*' pkg.list_repo_pkgs foo bar baz

pkg.list_repos:

Lists all repos in the sources.list (and sources.lists.d) files

CLI Example:

   salt '*' pkg.list_repos
   salt '*' pkg.list_repos disabled=True

pkg.list_upgrades:

List all available package upgrades.

refresh
    Whether to refresh the package database before listing upgrades.
    Default: True.

cache_valid_time

    New in version 2016.11.0

    Skip refreshing the package database if refresh has already occurred within
    <value> seconds

dist_upgrade
    Whether to list the upgrades using dist-upgrade vs upgrade.  Default is
    to use dist-upgrade.

CLI Example:

    salt '*' pkg.list_upgrades

pkg.mod_repo:

Modify one or more values for a repo.  If the repo does not exist, it will
be created, so long as the definition is well formed.  For Ubuntu the
``ppa:<project>/repo`` format is acceptable. ``ppa:`` format can only be
used to create a new repository.

The following options are available to modify a repo definition:

architectures
    A comma-separated list of supported architectures, e.g. ``amd64`` If
    this option is not set, all architectures (configured in the system)
    will be used.

comps
    A comma separated list of components for the repo, e.g. ``main``

file
    A file name to be used

keyserver
    Keyserver to get gpg key from

keyid
    Key ID or a list of key IDs to load with the ``keyserver`` argument

key_url
    URL to a GPG key to add to the APT GPG keyring

key_text
    GPG key in string form to add to the APT GPG keyring

    New in version 2018.3.0

consolidate : False
    If ``True``, will attempt to de-duplicate and consolidate sources

comments
    Sometimes you want to supply additional information, but not as
    enabled configuration. All comments provided here will be joined
    into a single string and appended to the repo configuration with a
    comment marker (#) before it.

    New in version 2015.8.9

refresh : True
    Enable or disable (True or False) refreshing of the apt package
    database. The previous ``refresh_db`` argument was deprecated in
    favor of ``refresh```. The ``refresh_db`` argument will still
    continue to work to ensure backwards compatibility, but please
    change to using the preferred ``refresh``.

Note:
    Due to the way keys are stored for APT, there is a known issue where
    the key won't be updated unless another change is made at the same
    time. Keys should be properly added on initial configuration.

CLI Examples:

    salt '*' pkg.mod_repo 'myrepo definition' uri=http://new/uri
    salt '*' pkg.mod_repo 'myrepo definition' comps=main,universe

pkg.normalize_name:

Strips the architecture from the specified package name, if necessary.

CLI Example:

    salt '*' pkg.normalize_name zsh:amd64

pkg.owner:

New in version 2014.7.0

Return the name of the package that owns the file. Multiple file paths can
be passed. Like :mod:`pkg.version <salt.modules.aptpkg.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:

    salt '*' pkg.owner /usr/bin/apachectl
    salt '*' pkg.owner /usr/bin/apachectl /usr/bin/basename

pkg.parse_arch:

Parse name and architecture from the specified package name.

CLI Example:

    salt '*' pkg.parse_arch zsh:amd64

pkg.purge:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands which modify installed packages from the
    ``salt-minion`` daemon's control group. This is done to keep systemd
    from killing any apt-get/dpkg commands spawned by Salt when the
    ``salt-minion`` service is restarted. (see ``KillMode`` in the
    `systemd.kill(5)`_ manpage for more information). If desired, usage of
    `systemd-run(1)`_ can be suppressed by setting a :mod:`config option
    <salt.modules.config.get>` called ``systemd.scope``, with a value of
    ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html
.. _`systemd.kill(5)`: https://www.freedesktop.org/software/systemd/man/systemd.kill.html

Remove packages via ``apt-get purge`` along with all configuration files.

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.

New in version 0.16.0


Returns a dict containing the changes.

CLI Example:

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

pkg.refresh_db:

Updates the APT 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
- ``None``: Database already up-to-date

cache_valid_time

    New in version 2016.11.0

    Skip refreshing the package database if refresh has already occurred within
    <value> seconds

failhard

    If False, return results of Err 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.

CLI Example:

    salt '*' pkg.refresh_db

pkg.remove:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands which modify installed packages from the
    ``salt-minion`` daemon's control group. This is done to keep systemd
    from killing any apt-get/dpkg commands spawned by Salt when the
    ``salt-minion`` service is restarted. (see ``KillMode`` in the
    `systemd.kill(5)`_ manpage for more information). If desired, usage of
    `systemd-run(1)`_ can be suppressed by setting a :mod:`config option
    <salt.modules.config.get>` called ``systemd.scope``, with a value of
    ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html
.. _`systemd.kill(5)`: https://www.freedesktop.org/software/systemd/man/systemd.kill.html

Remove packages using ``apt-get 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.

New in version 0.16.0


Returns a dict containing the changes.

CLI Example:

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

pkg.services_need_restart:

New in version 3003

List services that use files which have been changed by the
package manager. It might be needed to restart them.

Requires checkrestart from the debian-goodies package.

CLI Examples:

    salt '*' pkg.services_need_restart

pkg.set_selections:

Change package state in the dpkg database.

The state can be any one of, documented in ``dpkg(1)``:

- install
- hold
- deinstall
- purge

This command is commonly used to mark specific packages to be held from
being upgraded, that is, to be kept at a certain version. When a state is
changed to anything but being held, then it is typically followed by
``apt-get -u dselect-upgrade``.

Note: Be careful with the ``clear`` argument, since it will start
with setting all packages to deinstall state.

Returns a dict of dicts containing the package names, and the new and old
versions:

    {'<host>':
        {'<package>': {'new': '<new-state>',
                       'old': '<old-state>'}
        },
        ...
    }

CLI Example:

    salt '*' pkg.set_selections selection='{"install": ["netcat"]}'
    salt '*' pkg.set_selections selection='{"hold": ["openssh-server", "openssh-client"]}'
    salt '*' pkg.set_selections salt://path/to/file
    salt '*' pkg.set_selections salt://path/to/file clear=True

pkg.show:

New in version 2019.2.0

Runs an ``apt-cache show`` on the passed package names, and returns the
results in a nested dictionary. The top level of the return data will be
the package name, with each package name mapping to a dictionary of version
numbers to any additional information returned by ``apt-cache show``.

filter
    An optional comma-separated list (or quoted Python list) of
    case-insensitive keys on which to filter. This allows one to restrict
    the information returned for each package to a smaller selection of
    pertinent items.

refresh : False
    If ``True``, the apt cache will be refreshed first. By default, no
    refresh is performed.

CLI Examples:

    salt myminion pkg.show gawk
    salt myminion pkg.show 'nginx-*'
    salt myminion pkg.show 'nginx-*' filter=description,provides

pkg.unhold:

New in version 2014.7.0

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:

        salt '*' pkg.unhold <package name>

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

    CLI Example:

        salt '*' pkg.unhold pkgs='["foo", "bar"]'

pkg.upgrade:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands which modify installed packages from the
    ``salt-minion`` daemon's control group. This is done to keep systemd
    from killing any apt-get/dpkg commands spawned by Salt when the
    ``salt-minion`` service is restarted. (see ``KillMode`` in the
    `systemd.kill(5)`_ manpage for more information). If desired, usage of
    `systemd-run(1)`_ can be suppressed by setting a :mod:`config option
    <salt.modules.config.get>` called ``systemd.scope``, with a value of
    ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html
.. _`systemd.kill(5)`: https://www.freedesktop.org/software/systemd/man/systemd.kill.html

Upgrades all packages via ``apt-get upgrade`` or ``apt-get dist-upgrade``
if  ``dist_upgrade`` is ``True``.

Returns a dictionary containing the changes:

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

dist_upgrade
    Whether to perform the upgrade using dist-upgrade vs upgrade.  Default
    is to use upgrade.

    New in version 2014.7.0

refresh : True
    If ``True``, the apt cache will be refreshed first. By default,
    this is ``True`` and a refresh is performed.

cache_valid_time

    New in version 2016.11.0

    Skip refreshing the package database if refresh has already occurred within
    <value> seconds

download_only (or downloadonly)
    Only download the packages, don't unpack or install them. Use
    downloadonly to be in line with yum and zypper module.

    New in version 2018.3.0

force_conf_new
    Always install the new version of any configuration files.

    New in version 2015.8.0

allow_downgrades
    Allow apt to downgrade packages without a prompt.

    New in version 3005

CLI Example:

    salt '*' pkg.upgrade

pkg.upgrade_available:

Check whether or not an upgrade is available for a given package

CLI Example:

    salt '*' pkg.upgrade_available <package name>

pkg.version:

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:

    salt '*' pkg.version <package name>
    salt '*' pkg.version <package1> <package2> <package3> ...

pkg.version_cmp:

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

    New in version 2015.8.10,2016.3.2

CLI Example:

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

pkg_resource.add_pkg:

Add a package to a dict of installed packages.

CLI Example:

    salt '*' pkg_resource.add_pkg '{}' bind 9

pkg_resource.check_extra_requirements:

Check if the installed package already has the given requirements.
This function will return the result of ``pkg.check_extra_requirements`` if
this function exists for the minion, otherwise it will return True.

CLI Example:

    salt '*' pkg_resource.check_extra_requirements <pkgname> <extra_requirements>

pkg_resource.format_pkg_list:

Formats packages according to parameters for list_pkgs.

pkg_resource.format_version:

Formats a version string for list_pkgs.

pkg_resource.pack_sources:

Accepts list of dicts (or a string representing a list of dicts) and packs
the key/value pairs into a single dict.

``'[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]'`` would become
``{"foo": "salt://foo.rpm", "bar": "salt://bar.rpm"}``

normalize : True
    Normalize the package name by removing the architecture, if the
    architecture of the package is different from the architecture of the
    operating system. The ability to disable this behavior is useful for
    poorly-created packages which include the architecture as an actual
    part of the name, such as kernel modules which match a specific kernel
    version.

    New in version 2015.8.0

CLI Example:

    salt '*' pkg_resource.pack_sources '[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]'

pkg_resource.parse_targets:

Parses the input to pkg.install and returns back the package(s) to be
installed. Returns a list of packages, as well as a string noting whether
the packages are to come from a repository or a binary package.

CLI Example:

    salt '*' pkg_resource.parse_targets

pkg_resource.sort_pkglist:

Accepts a dict obtained from pkg.list_pkgs() and sorts in place the list of
versions for any packages that have multiple versions installed, so that
two package lists can be compared to one another.

CLI Example:

    salt '*' pkg_resource.sort_pkglist '["3.45", "2.13"]'

pkg_resource.stringify:

Takes a dict of package name/version information and joins each list of
installed versions into a string.

CLI Example:

    salt '*' pkg_resource.stringify 'vim: 7.127'

pkg_resource.version:

Common interface for obtaining the version of installed packages.

CLI Example:

    salt '*' pkg_resource.version vim
    salt '*' pkg_resource.version foo bar baz
    salt '*' pkg_resource.version 'python*'

pkg_resource.version_clean:

Clean the version string removing extra data.
This function will simply try to call ``pkg.version_clean``.

CLI Example:

    salt '*' pkg_resource.version_clean <version_string>

pkg_resource.version_compare:

New in version 3001

Perform a version comparison, using (where available) platform-specific
version comparison tools to make the comparison.

ver1
    The first version to be compared

oper
    One of `==`, `!=`, `>=`, `<=`, `>`, `<`

ver2
    The second version to be compared

Note:
    To avoid shell interpretation, each of the above values should be
    quoted when this function is used on the CLI.

ignore_epoch : False
    If ``True``, both package versions will have their epoch prefix
    stripped before comparison.

This function is useful in Jinja templates, to perform specific actions
when a package's version meets certain criteria. For example:

    {%- set postfix_version = salt.pkg.version('postfix') %}
    {%- if postfix_version and salt.pkg_resource.version_compare(postfix_version, '>=', '3.3', ignore_epoch=True) %}
      {#- do stuff #}
    {%- endif %}

CLI Examples:

    salt myminion pkg_resource.version_compare '3.5' '<=' '2.4'
    salt myminion pkg_resource.version_compare '3.5' '<=' '2.4' ignore_epoch=True

postfix.delete:

Delete message(s) from the mail queue

CLI Example:

    salt '*' postfix.delete 5C33CA0DEA

    salt '*' postfix.delete ALL

postfix.hold:

Put message(s) on hold from the mail queue

CLI Example:

    salt '*' postfix.hold 5C33CA0DEA

    salt '*' postfix.hold ALL

postfix.requeue:

Requeue message(s) in the mail queue

CLI Example:

    salt '*' postfix.requeue 5C33CA0DEA

    salt '*' postfix.requeue ALL

postfix.set_main:

Set a single config value in the main.cf file. If the value does not already
exist, it will be appended to the end.

CLI Example:

    salt <minion> postfix.set_main mailq_path /usr/bin/mailq

postfix.set_master:

Set a single config value in the master.cf file. If the value does not
already exist, it will be appended to the end.

Because of shell parsing issues, '-' cannot be set as a value, as is normal
in the master.cf file; either 'y', 'n' or a number should be used when
calling this function from the command line. If the value used matches the
default, it will internally be converted to a '-'. Calling this function
from the Python API is not affected by this limitation

The settings and their default values, in order, are: service (required),
conn_type (required), private (y), unpriv (y), chroot (y), wakeup (n),
maxproc (100), command (required).

By default, this function will write out the changes to the master.cf file,
and then returns the full contents of the file. By setting the
``write_conf`` option to ``False``, it will skip writing the file.

CLI Example:

    salt <minion> postfix.set_master smtp inet n y n n 100 smtpd

postfix.show_main:

Return a dict of active config values. This does not include comments,
spacing or order. Bear in mind that order is functionally important in the
main.cf file, since keys can be referred to as variables. This means that
the data returned from this function should not be used for direct
modification of the main.cf file; other functions are available for that.

CLI Examples:

    salt <minion> postfix.show_main
    salt <minion> postfix.show_main path=/path/to/main.cf

postfix.show_master:

Return a dict of active config values. This does not include comments,
spacing or order.

The data returned from this function should not be used for direct
modification of the main.cf file; other functions are available for that.

CLI Examples:

    salt <minion> postfix.show_master
    salt <minion> postfix.show_master path=/path/to/master.cf

postfix.show_queue:

Show contents of the mail queue

CLI Example:

    salt '*' postfix.show_queue

postfix.unhold:

Set held message(s) in the mail queue to unheld

CLI Example:

    salt '*' postfix.unhold 5C33CA0DEA

    salt '*' postfix.unhold ALL

ps.boot_time:

Return the boot time in number of seconds since the epoch began.

CLI Example:

time_format
    Optionally specify a `strftime`_ format string. Use
    ``time_format='%c'`` to get a nicely-formatted locale specific date and
    time (i.e. ``Fri May  2 19:08:32 2014``).

    .. _strftime: https://docs.python.org/2/library/datetime.html#strftime-strptime-behavior

    New in version 2014.1.4

    salt '*' ps.boot_time

ps.cpu_percent:

Return the percent of time the CPU is busy.

interval
    the number of seconds to sample CPU usage over
per_cpu
    if True return an array of CPU percent busy for each CPU, otherwise
    aggregate all percents into one number

CLI Example:

    salt '*' ps.cpu_percent

ps.cpu_times:

Return the percent of time the CPU spends in each state,
e.g. user, system, idle, nice, iowait, irq, softirq.

per_cpu
    if True return an array of percents for each CPU, otherwise aggregate
    all percents into one number

CLI Example:

    salt '*' ps.cpu_times

ps.disk_io_counters:

Return disk I/O statistics.

CLI Example:

    salt '*' ps.disk_io_counters

    salt '*' ps.disk_io_counters device=sda1

ps.disk_partition_usage:

Return a list of disk partitions plus the mount point, filesystem and usage
statistics.

CLI Example:

    salt '*' ps.disk_partition_usage

ps.disk_partitions:

Return a list of disk partitions and their device, mount point, and
filesystem type.

all
    if set to False, only return local, physical partitions (hard disk,
    USB, CD/DVD partitions).  If True, return all filesystems.

CLI Example:

    salt '*' ps.disk_partitions

ps.disk_usage:

Given a path, return a dict listing the total available space as well as
the free space, and used space.

CLI Example:

    salt '*' ps.disk_usage /home

ps.get_pid_list:

Return a list of process ids (PIDs) for all running processes.

CLI Example:

    salt '*' ps.get_pid_list

ps.get_users:

Return logged-in users.

CLI Example:

    salt '*' ps.get_users

ps.kill_pid:

Kill a process by PID.

    salt 'minion' ps.kill_pid pid [signal=signal_number]

pid
    PID of process to kill.

signal
    Signal to send to the process. See manpage entry for kill
    for possible values. Default: 15 (SIGTERM).

**Example:**

Send SIGKILL to process with PID 2000:

    salt 'minion' ps.kill_pid 2000 signal=9

ps.lsof:

Retrieve the lsof information of the given process name.

CLI Example:

    salt '*' ps.lsof apache2

ps.netstat:

Retrieve the netstat information of the given process name.

CLI Example:

    salt '*' ps.netstat apache2

ps.network_io_counters:

Return network I/O statistics.

CLI Example:

    salt '*' ps.network_io_counters

    salt '*' ps.network_io_counters interface=eth0

ps.num_cpus:

Return the number of CPUs.

CLI Example:

    salt '*' ps.num_cpus

ps.pgrep:

Return the pids for processes matching a pattern.

If full is true, the full command line is searched for a match,
otherwise only the name of the command is searched.

    salt '*' ps.pgrep pattern [user=username] [full=(true|false)]

pattern
    Pattern to search for in the process list.

user
    Limit matches to the given username. Default: All users.

full
    A boolean value indicating whether only the name of the command or
    the full command line should be matched against the pattern.

pattern_is_regex
    This flag enables ps.pgrep to mirror the regex search functionality
    found in the pgrep command line utility.

    New in version 3001

**Examples:**

Find all httpd processes on all 'www' minions:

    salt 'www.*' ps.pgrep httpd

Find all bash processes owned by user 'tom':

    salt '*' ps.pgrep bash user=tom

ps.pkill:

Kill processes matching a pattern.

    salt '*' ps.pkill pattern [user=username] [signal=signal_number] \
            [full=(true|false)]

pattern
    Pattern to search for in the process list.

user
    Limit matches to the given username. Default: All users.

signal
    Signal to send to the process(es). See manpage entry for kill
    for possible values. Default: 15 (SIGTERM).

full
    A boolean value indicating whether only the name of the command or
    the full command line should be matched against the pattern.

**Examples:**

Send SIGHUP to all httpd processes on all 'www' minions:

    salt 'www.*' ps.pkill httpd signal=1

Send SIGKILL to all bash processes owned by user 'tom':

    salt '*' ps.pkill bash signal=9 user=tom

ps.proc_info:

Return a dictionary of information for a process id (PID).

CLI Example:

    salt '*' ps.proc_info 2322
    salt '*' ps.proc_info 2322 attrs='["pid", "name"]'

pid
    PID of process to query.

attrs
    Optional list of desired process attributes.  The list of possible
    attributes can be found here:
    https://psutil.readthedocs.io/en/latest/#processes

ps.psaux:

Retrieve information corresponding to a "ps aux" filtered
with the given pattern. It could be just a name or a regular
expression (using python search from "re" module).

CLI Example:

    salt '*' ps.psaux www-data.+apache2

ps.ss:

Retrieve the ss information of the given process name.

CLI Example:

    salt '*' ps.ss apache2

New in version 2016.11.6

ps.status:

New in version 3006.0

Returns a list of processes according to their state.

CLI Example:

    salt '*' ps.status STATUS

where ``STATUS`` is one of

* running
* sleeping
* disk_sleep
* stopped
* tracing_stop
* zombie
* dead
* wake_kill
* waking
* parked (Linux)
* idle (Linux, macOS, FreeBSD)
* locked (FreeBSD)
* waiting (FreeBSD)
* suspended (NetBSD)

See https://psutil.readthedocs.io/en/latest/index.html?highlight=status#process-status-constants

ps.swap_memory:

New in version 2014.7.0

Return a dict that describes swap memory statistics.

Note:

    This function is only available in psutil version 0.6.0 and above.

CLI Example:

    salt '*' ps.swap_memory

ps.top:

Return a list of top CPU consuming processes during the interval.
num_processes = return the top N CPU consuming processes
interval = the number of seconds to sample CPU usage over

CLI Examples:

    salt '*' ps.top

    salt '*' ps.top 5 10

ps.total_physical_memory:

Return the total number of bytes of physical memory.

CLI Example:

    salt '*' ps.total_physical_memory

ps.virtual_memory:

New in version 2014.7.0

Return a dict that describes statistics about system memory usage.

Note:

    This function is only available in psutil version 0.6.0 and above.

CLI Example:

    salt '*' ps.virtual_memory

publish.full_data:

Return the full data about the publication, this is invoked in the same
way as the publish function

CLI Example:

    salt system.example.com publish.full_data '*' cmd.run 'ls -la /tmp'

.. admonition:: Attention

    If you need to pass a value to a function argument and that value
    contains an equal sign, you **must** include the argument name.
    For example:

        salt '*' publish.full_data test.kwarg arg='cheese=spam'

publish.publish:

Publish a command from the minion out to other minions.

Publications need to be enabled on the Salt master and the minion
needs to have permission to publish the command. The Salt master
will also prevent a recursive publication loop, this means that a
minion cannot command another minion to command another minion as
that would create an infinite command loop.

The ``tgt_type`` argument is used to pass a target other than a glob into
the execution, the available options are:

- glob
- pcre
- grain
- grain_pcre
- pillar
- pillar_pcre
- ipcidr
- range
- compound

Changed in version 2017.7.0
    The ``expr_form`` argument has been renamed to ``tgt_type``, earlier
    releases must use ``expr_form``.

Note that for pillar matches must be exact, both in the pillar matcher
and the compound matcher. No globbing is supported.

The arguments sent to the minion publish function are separated with
commas. This means that for a minion executing a command with multiple
args it will look like this:

    salt system.example.com publish.publish '*' user.add 'foo,1020,1020'
    salt system.example.com publish.publish 'os:Fedora' network.interfaces '' grain

CLI Example:

    salt system.example.com publish.publish '*' cmd.run 'ls -la /tmp'


.. admonition:: Attention

    If you need to pass a value to a function argument and that value
    contains an equal sign, you **must** include the argument name.
    For example:

        salt '*' publish.publish test.kwarg arg='cheese=spam'

    Multiple keyword arguments should be passed as a list.

        salt '*' publish.publish test.kwarg arg="['cheese=spam','spam=cheese']"


When running via salt-call, the `via_master` flag may be set to specific which
master the publication should be sent to. Only one master may be specified. If
unset, the publication will be sent only to the first master in minion configuration.

publish.runner:

Execute a runner on the master and return the data from the runner
function

CLI Example:

    salt publish.runner manage.down

pushover.post_message:

Send a message to a Pushover user or group.

:param user:        The user or group to send to, must be key of user or group not email address.
:param message:     The message to send to the PushOver user or group.
:param title:       Specify who the message is from.
:param priority:    The priority of the message, defaults to 0.
:param expire:      The message should expire after N number of seconds.
:param retry:       The number of times the message should be retried.
:param sound:       The sound to associate with the message.
:param api_version: The PushOver API version, if not specified in the configuration.
:param token:       The PushOver token, if not specified in the configuration.
:return:            Boolean if message was sent successfully.

CLI Example:

    salt '*' pushover.post_message user='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' title='Message from Salt' message='Build is done'

    salt '*' pushover.post_message user='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' title='Message from Salt' message='Build is done' priority='2' expire='720' retry='5'

pyenv.default:

Returns or sets the currently defined default python.

python=None
    The version to set as the default. Should match one of the versions
    listed by :mod:`pyenv.versions <salt.modules.pyenv.versions>`. Leave
    blank to return the current default.

CLI Example:

    salt '*' pyenv.default
    salt '*' pyenv.default 2.0.0-p0

pyenv.do:

Execute a python command with pyenv's shims from the user or the system.

CLI Example:

    salt '*' pyenv.do 'gem list bundler'
    salt '*' pyenv.do 'gem list bundler' deploy

pyenv.do_with_python:

Execute a python command with pyenv's shims using a specific python version.

CLI Example:

    salt '*' pyenv.do_with_python 2.0.0-p0 'gem list bundler'
    salt '*' pyenv.do_with_python 2.0.0-p0 'gem list bundler' deploy

pyenv.install:

Install pyenv systemwide

CLI Example:

    salt '*' pyenv.install

pyenv.install_python:

Install a python implementation.

python
    The version of python to install, should match one of the
    versions listed by pyenv.list

CLI Example:

    salt '*' pyenv.install_python 2.0.0-p0

pyenv.is_installed:

Check if pyenv is installed.

CLI Example:

    salt '*' pyenv.is_installed

pyenv.list:

List the installable versions of python.

CLI Example:

    salt '*' pyenv.list

pyenv.rehash:

Run pyenv rehash to update the installed shims.

CLI Example:

    salt '*' pyenv.rehash

pyenv.uninstall_python:

Uninstall a python implementation.

python
    The version of python to uninstall. Should match one of the versions
    listed by :mod:`pyenv.versions <salt.modules.pyenv.versions>`

CLI Example:

    salt '*' pyenv.uninstall_python 2.0.0-p0

pyenv.update:

Updates the current versions of pyenv and python-Build

CLI Example:

    salt '*' pyenv.update

pyenv.versions:

List the installed versions of python.

CLI Example:

    salt '*' pyenv.versions

random.get_str:

New in version 2014.7.0
Changed in version 3004

     Changed the default character set used to include symbols and implemented arguments to control the used character set.

Returns a random string of the specified length.

length : 20
    Any valid number of bytes.

chars : None
    New in version 3004

    String with any character that should be used to generate random string.

    This argument supersedes all other character controlling arguments.

lowercase : True
    New in version 3004

    Use lowercase letters in generated random string.
    (see :py:data:`string.ascii_lowercase`)

    This argument is superseded by chars.

uppercase : True
    New in version 3004

    Use uppercase letters in generated random string.
    (see :py:data:`string.ascii_uppercase`)

    This argument is superseded by chars.

digits : True
    New in version 3004

    Use digits in generated random string.
    (see :py:data:`string.digits`)

    This argument is superseded by chars.

printable : False
    New in version 3004

    Use printable characters in generated random string and includes lowercase, uppercase,
    digits, punctuation and whitespace.
    (see :py:data:`string.printable`)

    It is disabled by default as includes whitespace characters which some systems do not
    handle well in passwords.
    This argument also supersedes all other classes because it includes them.

    This argument is superseded by chars.

punctuation : True
    New in version 3004

    Use punctuation characters in generated random string.
    (see :py:data:`string.punctuation`)

    This argument is superseded by chars.

whitespace : False
    New in version 3004

    Use whitespace characters in generated random string.
    (see :py:data:`string.whitespace`)

    It is disabled by default as some systems do not handle whitespace characters in passwords
    well.

    This argument is superseded by chars.

CLI Example:

    salt '*' random.get_str 128
    salt '*' random.get_str 128 chars='abc123.!()'
    salt '*' random.get_str 128 lowercase=False whitespace=True

random.hash:

New in version 2014.7.0

Encodes a value with the specified encoder.

value
    The value to be hashed.

algorithm : sha512
    The algorithm to use. May be any valid algorithm supported by
    hashlib.

CLI Example:

    salt '*' random.hash 'I am a string' md5

random.rand_int:

Returns a random integer number between the start and end number.

New in version 2015.5.3

start : 1
    Any valid integer number

end : 10
    Any valid integer number

seed :
    Optional hashable object

Changed in version 2019.2.0
    Added seed argument. Will return the same result when run with the same seed.

CLI Example:

    salt '*' random.rand_int 1 10

random.sample:

Return a given sample size from a list. By default, the random number
generator uses the current system time unless given a seed value.

New in version 3005

value
    A list to e used as input.

size
    The sample size to return.

seed
    Any value which will be hashed as a seed for random.

CLI Example:

    salt '*' random.sample '["one", "two"]' 1 seed="something"

random.seed:

Returns a random number within a range. Optional hash argument can
be any hashable object. If hash is omitted or None, the id of the minion is used.

New in version 2015.8.0

hash: None
    Any hashable object.

range: 10
    Any valid integer number

CLI Example:

    salt '*' random.seed 10 hash=None

random.shadow_hash:

Generates a salted hash suitable for /etc/shadow.

crypt_salt : None
    Salt to be used in the generation of the hash. If one is not
    provided, a random salt will be generated.

password : None
    Value to be salted and hashed. If one is not provided, a random
    password will be generated.

algorithm : sha512
    Hash algorithm to use.

CLI Example:

    salt '*' random.shadow_hash 'My5alT' 'MyP@asswd' md5

random.shuffle:

Return a shuffled copy of an input list. By default, the random number
generator uses the current system time unless given a seed value.

New in version 3005

value
    A list to be used as input.

seed
    Any value which will be hashed as a seed for random.

CLI Example:

    salt '*' random.shuffle '["one", "two"]' seed="something"

random.str_encode:

New in version 2014.7.0

value
    The value to be encoded.

encoder : base64
    The encoder to use on the subsequent string.

CLI Example:

    salt '*' random.str_encode 'I am a new string' base64

random_org.generateBlobs:

List all Slack users.

:param api_key: The Random.org api key.
:param api_version: The Random.org api version.
:param format: Specifies the format in which the
               blobs will be returned. Values
               allowed are base64 and hex.
:return: The user list.

CLI Example:

    salt '*' get_integers number=5 min=1 max=6

    salt '*' get_integers number=5 min=1 max=6

random_org.generateDecimalFractions:

Generates true random decimal fractions

:param api_key: The Random.org api key.
:param api_version: The Random.org api version.
:param number: How many random decimal fractions
               you need. Must be within the [1,1e4] range.
:param decimalPlaces: The number of decimal places
                      to use. Must be within the [1,20] range.
:param replacement: Specifies whether the random numbers should
                    be picked with replacement. The default (true)
                    will cause the numbers to be picked with replacement,
                    i.e., the resulting numbers may contain duplicate
                    values (like a series of dice rolls). If you want the
                    numbers picked to be unique (like raffle tickets drawn
                    from a container), set this value to false.
:return: A list of decimal fraction

CLI Example:

    salt '*' random_org.generateDecimalFractions number=10 decimalPlaces=4

    salt '*' random_org.generateDecimalFractions number=10 decimalPlaces=4 replacement=True

random_org.generateGaussians:

This method generates true random numbers from a
Gaussian distribution (also known as a normal distribution).

:param api_key: The Random.org api key.
:param api_version: The Random.org api version.
:param number: How many random numbers you need.
               Must be within the [1,1e4] range.
:param mean: The distribution's mean. Must be
             within the [-1e6,1e6] range.
:param standardDeviation: The distribution's standard
                          deviation. Must be within
                          the [-1e6,1e6] range.
:param significantDigits: The number of significant digits
                          to use. Must be within the [2,20] range.
:return: The user list.

CLI Example:

    salt '*' random_org.generateGaussians number=10 mean=0.0 standardDeviation=1.0 significantDigits=8

random_org.generateIntegers:

Generate random integers

:param api_key: The Random.org api key.
:param api_version: The Random.org api version.
:param number: The number of integers to generate
:param minimum: The lower boundary for the range from which the
                random numbers will be picked. Must be within
                the [-1e9,1e9] range.
:param maximum: The upper boundary for the range from which the
                random numbers will be picked. Must be within
                the [-1e9,1e9] range.
:param replacement: Specifies whether the random numbers should
                    be picked with replacement. The default (true)
                    will cause the numbers to be picked with replacement,
                    i.e., the resulting numbers may contain duplicate
                    values (like a series of dice rolls). If you want the
                    numbers picked to be unique (like raffle tickets drawn
                    from a container), set this value to false.
:param base: Specifies the base that will be used to display the numbers.
             Values allowed are 2, 8, 10 and 16. This affects the JSON
             types and formatting of the resulting data as discussed below.
:return: A list of integers.

CLI Example:

    salt '*' random_org.generateIntegers number=5 minimum=1 maximum=6

    salt '*' random_org.generateIntegers number=5 minimum=2 maximum=255 base=2

random_org.generateStrings:

Generate random strings.

:param api_key: The Random.org api key.
:param api_version: The Random.org api version.
:param number: The number of strings to generate.
:param length: The length of each string. Must be
               within the [1,20] range. All strings
               will be of the same length
:param characters: A string that contains the set of
                   characters that are allowed to occur
                   in the random strings. The maximum number
                   of characters is 80.
:param replacement: Specifies whether the random strings should be picked
                    with replacement. The default (true) will cause the
                    strings to be picked with replacement, i.e., the
                    resulting list of strings may contain duplicates (like
                    a series of dice rolls). If you want the strings to be
                    unique (like raffle tickets drawn from a container), set
                    this value to false.
:return: A list of strings.

CLI Example:

    salt '*' random_org.generateStrings number=5 length=8 characters='abcdefghijklmnopqrstuvwxyz'

    salt '*' random_org.generateStrings number=10 length=16 characters'abcdefghijklmnopqrstuvwxyz'

random_org.generateUUIDs:

Generate a list of random UUIDs

:param api_key: The Random.org api key.
:param api_version: The Random.org api version.
:param number: How many random UUIDs you need.
               Must be within the [1,1e3] range.
:return: A list of UUIDs

CLI Example:

    salt '*' random_org.generateUUIDs number=5

random_org.getUsage:

Show current usages statistics

:param api_key: The Random.org api key.
:param api_version: The Random.org api version.
:return: The current usage statistics.

CLI Example:

    salt '*' random_org.getUsage

    salt '*' random_org.getUsage api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_version=1

rbenv.default:

Returns or sets the currently defined default ruby

ruby
    The version to set as the default. Should match one of the versions
    listed by :py:func:`rbenv.versions <salt.modules.rbenv.versions>`.
    Leave blank to return the current default.

CLI Example:

    salt '*' rbenv.default
    salt '*' rbenv.default 2.0.0-p0

rbenv.do:

Execute a ruby command with rbenv's shims from the user or the system

CLI Example:

    salt '*' rbenv.do 'gem list bundler'
    salt '*' rbenv.do 'gem list bundler' deploy

rbenv.do_with_ruby:

Execute a ruby command with rbenv's shims using a specific ruby version

CLI Example:

    salt '*' rbenv.do_with_ruby 2.0.0-p0 'gem list bundler'
    salt '*' rbenv.do_with_ruby 2.0.0-p0 'gem list bundler' runas=deploy

rbenv.install:

Install rbenv systemwide

CLI Example:

    salt '*' rbenv.install

rbenv.install_ruby:

Install a ruby implementation.

ruby
    The version of Ruby to install, should match one of the
    versions listed by :py:func:`rbenv.list <salt.modules.rbenv.list>`

runas
    The user under which to run rbenv. If not specified, then rbenv will be
    run as the user under which Salt is running.

Additional environment variables can be configured in pillar /
grains / master:

    rbenv:
      build_env: 'CONFIGURE_OPTS="--no-tcmalloc" CFLAGS="-fno-tree-dce"'

CLI Example:

    salt '*' rbenv.install_ruby 2.0.0-p0

rbenv.is_installed:

Check if rbenv is installed

CLI Example:

    salt '*' rbenv.is_installed

rbenv.list:

List the installable versions of ruby

runas
    The user under which to run rbenv. If not specified, then rbenv will be
    run as the user under which Salt is running.

CLI Example:

    salt '*' rbenv.list

rbenv.rehash:

Run ``rbenv rehash`` to update the installed shims

runas
    The user under which to run rbenv. If not specified, then rbenv will be
    run as the user under which Salt is running.

CLI Example:

    salt '*' rbenv.rehash

rbenv.uninstall_ruby:

Uninstall a ruby implementation.

ruby
    The version of ruby to uninstall. Should match one of the versions
    listed by :py:func:`rbenv.versions <salt.modules.rbenv.versions>`.

runas
    The user under which to run rbenv. If not specified, then rbenv will be
    run as the user under which Salt is running.

CLI Example:

    salt '*' rbenv.uninstall_ruby 2.0.0-p0

rbenv.update:

Updates the current versions of rbenv and ruby-build

runas
    The user under which to run rbenv. If not specified, then rbenv will be
    run as the user under which Salt is running.

CLI Example:

    salt '*' rbenv.update

rbenv.versions:

List the installed versions of ruby

CLI Example:

    salt '*' rbenv.versions

rest_sample_utils.fix_outage:

"Fix" the outage

CLI Example:

    salt 'rest-sample-proxy' rest_sample.fix_outage

rest_sample_utils.get_test_string:

Helper function to test cross-calling to the __proxy__ dunder.

CLI Example:

    salt 'rest-sample-proxy' rest_sample.get_test_string

restartcheck.restartcheck:

Analyzes files openeded by running processes and seeks for packages which need to be restarted.

Args:
    ignorelist: string or list of packages to be ignored.
    blacklist: string or list of file paths to be ignored.
    excludepid: string or list of process IDs to be ignored.
    verbose: boolean, enables extensive output.
    timeout: int, timeout in minute.

Returns:
    Dict on error: ``{ 'result': False, 'comment': '<reason>' }``.
    String with checkrestart output if some package seems to need to be restarted or
    if no packages need restarting.

New in version 2015.8.3

CLI Example:

    salt '*' restartcheck.restartcheck

ret.get_fun:

Return info about last time fun was called on each minion

CLI Example:

    salt '*' ret.get_fun mysql network.interfaces

ret.get_jid:

Return the information for a specified job id

CLI Example:

    salt '*' ret.get_jid redis 20421104181954700505

ret.get_jids:

Return a list of all job ids

CLI Example:

    salt '*' ret.get_jids mysql

ret.get_minions:

Return a list of all minions

CLI Example:

    salt '*' ret.get_minions mysql

rsync.config:

Changed in version 2016.3.0
    Return data now contains just the contents of the rsyncd.conf as a
    string, instead of a dictionary as returned from :py:func:`cmd.run_all
    <salt.modules.cmdmod.run_all>`.

Returns the contents of the rsync config file

conf_path : /etc/rsyncd.conf
    Path to the config file

CLI Example:

    salt '*' rsync.config

rsync.rsync:

Changed in version 2016.3.0
    Return data now contains just the output of the rsync command, instead
    of a dictionary as returned from :py:func:`cmd.run_all
    <salt.modules.cmdmod.run_all>`.

Rsync files from src to dst

src
    The source location where files will be rsynced from.

dst
    The destination location where files will be rsynced to.

delete : False
    Whether to enable the rsync `--delete` flag, which
    will delete extraneous files from dest dirs

force : False
    Whether to enable the rsync `--force` flag, which
    will force deletion of dirs even if not empty.

update : False
    Whether to enable the rsync `--update` flag, which
    forces rsync to skip any files which exist on the
    destination and have a modified time that is newer
    than the source file.

passwordfile
    A file that contains a password for accessing an
    rsync daemon.  The file should contain just the
    password.

exclude
    Whether to enable the rsync `--exclude` flag, which
    will exclude files matching a PATTERN.

excludefrom
    Whether to enable the rsync `--excludefrom` flag, which
    will read exclude patterns from a file.

dryrun : False
    Whether to enable the rsync `--dry-run` flag, which
    will perform a trial run with no changes made.

rsh
    Whether to enable the rsync `--rsh` flag, to
    specify the remote shell to use.

additional_opts
    Any additional rsync options, should be specified as a list.

saltenv
    Specify a salt fileserver environment to be used.

CLI Example:

    salt '*' rsync.rsync /path/to/src /path/to/dest delete=True update=True passwordfile=/etc/pass.crt exclude=exclude/dir
    salt '*' rsync.rsync /path/to/src delete=True excludefrom=/xx.ini
    salt '*' rsync.rsync /path/to/src delete=True exclude='[exclude1/dir,exclude2/dir]' additional_opts='["--partial", "--bwlimit=5000"]'

rsync.version:

Changed in version 2016.3.0
    Return data now contains just the version number as a string, instead
    of a dictionary as returned from :py:func:`cmd.run_all
    <salt.modules.cmdmod.run_all>`.

Returns rsync version

CLI Example:

    salt '*' rsync.version

rvm.do:

Execute a command in an RVM controlled environment.

ruby
    Which ruby to use

command
    The rvm command to execute

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

cwd
    The directory from which to run the rvm command. Defaults to the user's
    home directory.

CLI Example:

    salt '*' rvm.do 2.0.0 <command>

rvm.gemset_copy:

Copy all gems from one gemset to another.

source
    The name of the gemset to copy, complete with ruby version

destination
    The destination gemset

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.gemset_copy foobar bazquo

rvm.gemset_create:

Creates a gemset.

ruby
    The ruby version for which to create the gemset

gemset
    The name of the gemset to create

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.gemset_create 2.0.0 foobar

rvm.gemset_delete:

Delete a gemset

ruby
    The ruby version to which the gemset belongs

gemset
    The gemset to delete

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.gemset_delete 2.0.0 foobar

rvm.gemset_empty:

Remove all gems from a gemset.

ruby
    The ruby version to which the gemset belongs

gemset
    The gemset to empty

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.gemset_empty 2.0.0 foobar

rvm.gemset_list:

List all gemsets for the given ruby.

ruby : default
    The ruby version for which to list the gemsets

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.gemset_list

rvm.gemset_list_all:

List all gemsets for all installed rubies.

Note that you must have set a default ruby before this can work.

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.gemset_list_all

rvm.get:

Update RVM

version : stable
    Which version of RVM to install, (e.g. stable or head)

CLI Example:

    salt '*' rvm.get

rvm.install:

Install RVM system-wide

runas
    The user under which to run the rvm installer script. If not specified,
    then it be run as the user under which Salt is running.

CLI Example:

    salt '*' rvm.install

rvm.install_ruby:

Install a ruby implementation.

ruby
    The version of ruby to install

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

env
    Environment to set for the install command. Useful for exporting compilation
    flags such as RUBY_CONFIGURE_OPTS

opts
    List of options to pass to the RVM installer (ie -C, --patch, etc)

CLI Example:

    salt '*' rvm.install_ruby 1.9.3-p385

rvm.is_installed:

Check if RVM is installed.

CLI Example:

    salt '*' rvm.is_installed

rvm.list:

List all rvm-installed rubies

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.list

rvm.reinstall_ruby:

Reinstall a ruby implementation

ruby
    The version of ruby to reinstall

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.reinstall_ruby 1.9.3-p385

rvm.rubygems:

Installs a specific rubygems version in the given ruby

ruby
    The ruby for which to install rubygems

version
    The version of rubygems to install, or 'remove' to use the version that
    ships with 1.9

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.rubygems 2.0.0 1.8.24

rvm.set_default:

Set the default ruby

ruby
    The version of ruby to make the default

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

CLI Example:

    salt '*' rvm.set_default 2.0.0

rvm.wrapper:

Install RVM wrapper scripts

ruby_string
    Ruby/gemset to install wrappers for

wrapper_prefix
    What to prepend to the name of the generated wrapper binaries

runas
    The user under which to run rvm. If not specified, then rvm will be run
    as the user under which Salt is running.

binaries : None
    The names of the binaries to create wrappers for. When nothing is
    given, wrappers for ruby, gem, rake, irb, rdoc, ri and testrb are
    generated.

CLI Example:

    salt '*' rvm.wrapper <ruby_string> <wrapper_prefix>

s3.delete:

Delete a bucket, or delete an object from a bucket.


CLI Example to delete a bucket::

    salt myminion s3.delete mybucket

CLI Example to delete an object from a bucket::

    salt myminion s3.delete mybucket remoteobject

s3.get:

List the contents of a bucket, or return an object from a bucket. Set
return_bin to True in order to retrieve an object wholesale. Otherwise,
Salt will attempt to parse an XML response.

CLI Example to list buckets:

    salt myminion s3.get

CLI Example to list the contents of a bucket:

    salt myminion s3.get mybucket

CLI Example to return the binary contents of an object:

    salt myminion s3.get mybucket myfile.png return_bin=True

CLI Example to save the binary contents of an object to a local file:

    salt myminion s3.get mybucket myfile.png local_file=/tmp/myfile.png

It is also possible to perform an action on a bucket. Currently, S3
supports the following actions::

    acl
    cors
    lifecycle
    policy
    location
    logging
    notification
    tagging
    versions
    requestPayment
    versioning
    website

To perform an action on a bucket:

    salt myminion s3.get mybucket myfile.png action=acl

s3.head:

Return the metadata for a bucket, or an object in a bucket.

CLI Examples:

    salt myminion s3.head mybucket
    salt myminion s3.head mybucket myfile.png

s3.put:

Create a new bucket, or upload an object to a bucket.

CLI Example to create a bucket:

    salt myminion s3.put mybucket

CLI Example to upload an object to a bucket:

    salt myminion s3.put mybucket remotepath local_file=/path/to/file

s6.available:

Returns ``True`` if the specified service is available, otherwise returns
``False``.

CLI Example:

    salt '*' s6.available foo

s6.full_restart:

Calls s6.restart() function

CLI Example:

    salt '*' s6.full_restart <service name>

s6.get_all:

Return a list of all available services

CLI Example:

    salt '*' s6.get_all

s6.missing:

The inverse of s6.available.
Returns ``True`` if the specified service is not available, otherwise returns
``False``.

CLI Example:

    salt '*' s6.missing foo

s6.reload:

Send a HUP to service via s6

CLI Example:

    salt '*' s6.reload <service name>

s6.restart:

Restart service via s6. This will stop/start service

CLI Example:

    salt '*' s6.restart <service name>

s6.start:

Starts service via s6

CLI Example:

    salt '*' s6.start <service name>

s6.status:

Return the status for a service via s6, return pid if running

CLI Example:

    salt '*' s6.status <service name>

s6.stop:

Stops service via s6

CLI Example:

    salt '*' s6.stop <service name>

s6.term:

Send a TERM to service via s6

CLI Example:

    salt '*' s6.term <service name>

salt_proxy.configure_proxy:

Create the salt proxy file and start the proxy process
if required

Parameters:
    proxyname:
        Name to be used for this proxy (should match entries in pillar)
    start:
        Boolean indicating if the process should be started
        default = True

CLI Example:

    salt deviceminion salt_proxy.configure_proxy p8000

salt_proxy.is_running:

Check if the salt-proxy process associated
with this proxy (name) is running.

Returns True if the process is running
False otherwise

Parameters:
    proxyname:
        String name of the proxy (p8000 for example)

CLI Example:

    salt deviceminion salt_proxy.is_running p8000

salt_version.equal:

Returns a boolean (True) if the minion's current version
code name matches the named version.

name
    The release code name to check the version against.

CLI Example:

    salt '*' salt_version.equal 'Oxygen'

salt_version.get_release_number:

Returns the release number of a given release code name in a
``MAJOR.PATCH`` format (for Salt versions < 3000) or ``MAJOR`` for newer Salt versions.

If the release name has not been given an assigned release number, the
function returns a string. If the release cannot be found, it returns
``None``.

name
    The release code name for which to find a release number.

CLI Example:

    salt '*' salt_version.get_release_number 'Oxygen'

salt_version.greater_than:

Returns a boolean (True) if the minion's current
version code name is greater than the named version.

name
    The release code name to check the version against.

CLI Example:

    salt '*' salt_version.greater_than 'Oxygen'

salt_version.less_than:

Returns a boolean (True) if the minion's current
version code name is less than the named version.

name
    The release code name to check the version against.

CLI Example:

    salt '*' salt_version.less_than 'Oxygen'

saltcheck.parallel_scheck: triggers salt-call in parallel

saltcheck.report_highstate_tests:

Report on tests for states assigned to the minion through highstate.
Quits with the exit code for the number of missing tests.

CLI Example:

    salt '*' saltcheck.report_highstate_tests

New in version 3000

saltcheck.run_highstate_tests:

Execute all tests for states assigned to the minion through highstate and return results

:param str saltenv: optional saltenv. Defaults to base
:param bool only_fails: boolean to only print failure results
:param bool junit: boolean to print results in junit format
    New in version 3007.0

CLI Example:

    salt '*' saltcheck.run_highstate_tests

saltcheck.run_state_tests:

Execute tests for a salt state and return results
Nested states will also be tested

:param str state: state name for which to run associated .tst test files
:param str saltenv: optional saltenv. Defaults to base
:param bool check_all: boolean to run all tests in state/saltcheck-tests directory
:param bool only_fails: boolean to only print failure results
:param bool junit: boolean to print results in junit format
    New in version 3007.0

CLI Example:

    salt '*' saltcheck.run_state_tests postfix,common

Tests will be run in parallel by adding "saltcheck_parallel: True" in minion config.
When enabled, saltcheck will use up to the number of cores detected. This can be limited
by setting the "saltcheck_processes" value to an integer to set the maximum number
of parallel processes.

saltcheck.run_state_tests_ssh:

This function is an alias of run_state_tests.

Execute tests for a salt state and return results
Nested states will also be tested

:param str state: state name for which to run associated .tst test files
:param str saltenv: optional saltenv. Defaults to base
:param bool check_all: boolean to run all tests in state/saltcheck-tests directory
:param bool only_fails: boolean to only print failure results
:param bool junit: boolean to print results in junit format
    New in version 3007.0

CLI Example:

    salt '*' saltcheck.run_state_tests postfix,common

Tests will be run in parallel by adding "saltcheck_parallel: True" in minion config.
When enabled, saltcheck will use up to the number of cores detected. This can be limited
by setting the "saltcheck_processes" value to an integer to set the maximum number
of parallel processes.

saltcheck.run_test:

Execute one saltcheck test and return result

:param keyword arg test:

CLI Example:

    salt '*' saltcheck.run_test
        test='{"module_and_function": "test.echo",
               "assertion": "assertEqual",
               "expected_return": "This works!",
               "args":["This works!"] }'

saltcheck.state_apply:

Runs :py:func:`state.apply <salt.modules.state.apply>` with given options to set up test data.
Intended to be used for optional test setup or teardown

Reference the :py:func:`state.apply <salt.modules.state.apply>` module documentation for arguments and usage options

CLI Example:

    salt '*' saltcheck.state_apply postfix

saltutil.clear_cache:

Forcibly removes all caches on a minion.

New in version 2014.7.0

WARNING: The safest way to clear a minion cache is by first stopping
the minion and then deleting the cache files before restarting it.

CLI Example:

    salt '*' saltutil.clear_cache

saltutil.clear_job_cache:

Forcibly removes job cache folders and files on a minion.

New in version 2018.3.0

WARNING: The safest way to clear a minion cache is by first stopping
the minion and then deleting the cache files before restarting it.

CLI Example:

    salt '*' saltutil.clear_job_cache hours=12

saltutil.cmd:

Changed in version 2017.7.0
    The ``expr_form`` argument has been renamed to ``tgt_type``, earlier
    releases must use ``expr_form``.

Assuming this minion is a master, execute a salt command

CLI Example:

    salt '*' saltutil.cmd

saltutil.cmd_iter:

Changed in version 2017.7.0
    The ``expr_form`` argument has been renamed to ``tgt_type``, earlier
    releases must use ``expr_form``.

Assuming this minion is a master, execute a salt command

CLI Example:

    salt '*' saltutil.cmd_iter

saltutil.find_cached_job:

Return the data for a specific cached job id. Note this only works if
cache_jobs has previously been set to True on the minion.

CLI Example:

    salt '*' saltutil.find_cached_job <job id>

saltutil.find_job:

Return the data for a specific job id that is currently running.

jid
    The job id to search for and return data.

CLI Example:

    salt '*' saltutil.find_job <job id>

Note that the find_job function only returns job information when the job is still running. If
the job is currently running, the output looks something like this:

    # salt my-minion saltutil.find_job 20160503150049487736
    my-minion:
        ----------
        arg:
            - 30
        fun:
            test.sleep
        jid:
            20160503150049487736
        pid:
            9601
        ret:
        tgt:
            my-minion
        tgt_type:
            glob
        user:
            root

If the job has already completed, the job cannot be found and therefore the function returns
an empty dictionary, which looks like this on the CLI:

    # salt my-minion saltutil.find_job 20160503150049487736
    my-minion:
        ----------

saltutil.is_running:

If the named function is running return the data associated with it/them.
The argument can be a glob

CLI Example:

    salt '*' saltutil.is_running state.highstate

saltutil.kill_all_jobs:

Sends a kill signal (SIGKILL 9) to all currently running jobs

CLI Example:

    salt '*' saltutil.kill_all_jobs

saltutil.kill_job:

Sends a kill signal (SIGKILL 9) to the named salt job's process

CLI Example:

    salt '*' saltutil.kill_job <job id>

saltutil.list_extmods:

New in version 2017.7.0

List Salt modules which have been synced externally

CLI Examples:

    salt '*' saltutil.list_extmods

saltutil.mmodule:

Loads minion modules from an environment so that they can be used in pillars
for that environment

CLI Example:

    salt '*' saltutil.mmodule base test.ping

saltutil.pillar_refresh:

This function is an alias of refresh_pillar.

Signal the minion to refresh the in-memory pillar data. See :ref:`pillar-in-memory`.

:param wait:            Wait for pillar refresh to complete, defaults to False.
:type wait:             bool, optional
:param timeout:         How long to wait in seconds, only used when wait is True, defaults to 30.
:type timeout:          int, optional
:param clean_cache:     Clean the pillar cache, only used when `pillar_cache` is True. Defaults to True
:type clean_cache:      bool, optional
    New in version 3005
:return:                Boolean status, True when the pillar_refresh event was fired successfully.

CLI Example:

    salt '*' saltutil.refresh_pillar
    salt '*' saltutil.refresh_pillar wait=True timeout=60

saltutil.refresh_beacons:

Signal the minion to refresh the beacons.

CLI Example:

    salt '*' saltutil.refresh_beacons

saltutil.refresh_grains:

New in version 2016.3.6,2016.11.4,2017.7.0

Refresh the minion's grains without syncing custom grains modules from
``salt://_grains``.

Note:
    The available execution modules will be reloaded as part of this
    proceess, as grains can affect which modules are available.

refresh_pillar : True
    Set to ``False`` to keep pillar data from being refreshed.

clean_pillar_cache : False
    Set to ``True`` to refresh pillar cache.

CLI Examples:

    salt '*' saltutil.refresh_grains

saltutil.refresh_matchers:

Signal the minion to refresh its matchers.

CLI Example:

    salt '*' saltutil.refresh_matchers

saltutil.refresh_modules:

Signal the minion to refresh the module and grain data

The default is to refresh module asynchronously. To block
until the module refresh is complete, set the 'async' flag
to False.

CLI Example:

    salt '*' saltutil.refresh_modules

saltutil.refresh_pillar:

Signal the minion to refresh the in-memory pillar data. See :ref:`pillar-in-memory`.

:param wait:            Wait for pillar refresh to complete, defaults to False.
:type wait:             bool, optional
:param timeout:         How long to wait in seconds, only used when wait is True, defaults to 30.
:type timeout:          int, optional
:param clean_cache:     Clean the pillar cache, only used when `pillar_cache` is True. Defaults to True
:type clean_cache:      bool, optional
    New in version 3005
:return:                Boolean status, True when the pillar_refresh event was fired successfully.

CLI Example:

    salt '*' saltutil.refresh_pillar
    salt '*' saltutil.refresh_pillar wait=True timeout=60

saltutil.regen_keys:

Used to regenerate the minion keys.

CLI Example:

    salt '*' saltutil.regen_keys

saltutil.revoke_auth:

The minion sends a request to the master to revoke its own key.
Note that the minion session will be revoked and the minion may
not be able to return the result of this command back to the master.

If the 'preserve_minion_cache' flag is set to True, the master
cache for this minion will not be removed.

CLI Example:

    salt '*' saltutil.revoke_auth

saltutil.runner:

Execute a runner function. This function must be run on the master,
either by targeting a minion running on a master or by using
salt-call on a master.

New in version 2014.7.0

name
    The name of the function to run

kwargs
    Any keyword arguments to pass to the runner function

CLI Example:

In this example, assume that `master_minion` is a minion running
on a master.

    salt master_minion saltutil.runner jobs.list_jobs
    salt master_minion saltutil.runner test.arg arg="['baz']" kwarg="{'foo': 'bar'}"

saltutil.running:

Return the data on all running salt processes on the minion

CLI Example:

    salt '*' saltutil.running

saltutil.signal_job:

Sends a signal to the named salt job's process

CLI Example:

    salt '*' saltutil.signal_job <job id> 15

saltutil.sync_all:

Changed in version 3007.0

    On masterless minions, master top modules are now synced as well.
    When ``refresh`` is set to ``True``, this module's cache containing
    the environments from which extension modules are synced when
    ``saltenv`` is not specified will be refreshed.

Changed in version 2015.8.11,2016.3.2
    On masterless minions, pillar modules are now synced, and refreshed
    when ``refresh`` is set to ``True``.

Sync down all of the dynamic modules from the file server for a specific
environment. This function synchronizes custom modules, states, beacons,
grains, returners, output modules, renderers, and utils.

refresh : True
    Also refresh the execution modules and recompile pillar data available
    to the minion. If this is a masterless minion, also refresh the environments
    from which extension modules are synced after syncing master tops.
    This refresh will be performed even if no new dynamic
    modules are synced. Set to ``False`` to prevent this refresh.

.. important::

    If this function is executed using a :py:func:`module.run
    <salt.states.module.run>` state, the SLS file will not have access to
    newly synced execution modules unless a ``refresh`` argument is
    added to the state, like so:

        load_my_custom_module:
          module.run:
            - name: saltutil.sync_all
            - refresh: True

    See :ref:`here <reloading-modules>` for a more detailed explanation of
    why this is necessary.

extmod_whitelist : None
    dictionary of modules to sync based on type

extmod_blacklist : None
    dictionary of modules to blacklist based on type

clean_pillar_cache : False
    Set to ``True`` to refresh pillar cache.

CLI Examples:

    salt '*' saltutil.sync_all
    salt '*' saltutil.sync_all saltenv=dev
    salt '*' saltutil.sync_all saltenv=base,dev
    salt '*' saltutil.sync_all extmod_whitelist={'modules': ['custom_module']}

saltutil.sync_beacons:

New in version 2015.5.1

Sync beacons from ``salt://_beacons`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for beacons to sync. If no top files are
    found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available beacons on the minion. This refresh
    will be performed even if no new beacons are synced. Set to ``False``
    to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Example:

    salt '*' saltutil.sync_beacons
    salt '*' saltutil.sync_beacons saltenv=dev
    salt '*' saltutil.sync_beacons saltenv=base,dev

saltutil.sync_clouds:

New in version 2017.7.0

Sync cloud modules from ``salt://_cloud`` to the minion

saltenv : base
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new utility modules are
    synced. Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_clouds
    salt '*' saltutil.sync_clouds saltenv=dev
    salt '*' saltutil.sync_clouds saltenv=base,dev

saltutil.sync_engines:

New in version 2016.3.0

Sync engine modules from ``salt://_engines`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for engines to sync. If no top files are
    found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new engine modules are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_engines
    salt '*' saltutil.sync_engines saltenv=base,dev

saltutil.sync_executors:

New in version 3000

Sync executors from ``salt://_executors`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for log handlers to sync. If no top files
    are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new log handlers are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-seperated list of modules to sync

extmod_blacklist : None
    comma-seperated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_executors
    salt '*' saltutil.sync_executors saltenv=dev
    salt '*' saltutil.sync_executors saltenv=base,dev

saltutil.sync_grains:

New in version 0.10.0

Sync grains modules from ``salt://_grains`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for grains modules to sync. If no top
    files are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules and recompile
    pillar data for the minion. This refresh will be performed even if no
    new grains modules are synced. Set to ``False`` to prevent this
    refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

clean_pillar_cache : False
    Set to ``True`` to refresh pillar cache.

CLI Examples:

    salt '*' saltutil.sync_grains
    salt '*' saltutil.sync_grains saltenv=dev
    salt '*' saltutil.sync_grains saltenv=base,dev

saltutil.sync_log_handlers:

New in version 2015.8.0

Sync log handlers from ``salt://_log_handlers`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for log handlers to sync. If no top files
    are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new log handlers are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_log_handlers
    salt '*' saltutil.sync_log_handlers saltenv=dev
    salt '*' saltutil.sync_log_handlers saltenv=base,dev

saltutil.sync_matchers:

New in version 2019.2.0

Sync engine modules from ``salt://_matchers`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for engines to sync. If no top files are
    found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new matcher modules are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_matchers
    salt '*' saltutil.sync_matchers saltenv=base,dev

saltutil.sync_modules:

New in version 0.10.0

Sync execution modules from ``salt://_modules`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for execution modules to sync. If no top
    files are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new execution modules are
    synced. Set to ``False`` to prevent this refresh.

.. important::

    If this function is executed using a :py:func:`module.run
    <salt.states.module.run>` state, the SLS file will not have access to
    newly synced execution modules unless a ``refresh`` argument is
    added to the state, like so:

        load_my_custom_module:
          module.run:
            - name: saltutil.sync_modules
            - refresh: True

    See :ref:`here <reloading-modules>` for a more detailed explanation of
    why this is necessary.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Example:

    salt '*' saltutil.sync_modules
    salt '*' saltutil.sync_modules saltenv=dev
    salt '*' saltutil.sync_modules saltenv=base,dev

saltutil.sync_output:

Sync outputters from ``salt://_output`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for outputters to sync. If no top files
    are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new outputters are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_output
    salt '*' saltutil.sync_output saltenv=dev
    salt '*' saltutil.sync_output saltenv=base,dev

saltutil.sync_outputters:

This function is an alias of sync_output.

Sync outputters from ``salt://_output`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for outputters to sync. If no top files
    are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new outputters are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_output
    salt '*' saltutil.sync_output saltenv=dev
    salt '*' saltutil.sync_output saltenv=base,dev

saltutil.sync_pillar:

New in version 2015.8.11,2016.3.2

Sync pillar modules from the ``salt://_pillar`` directory on the Salt
fileserver. This function is environment-aware, pass the desired
environment to grab the contents of the ``_pillar`` directory from that
environment. The default environment, if none is specified,  is ``base``.

refresh : True
    Also refresh the execution modules available to the minion, and refresh
    pillar data.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

clean_pillar_cache : False
    Set to ``True`` to refresh pillar cache.

Note:
    This function will raise an error if executed on a traditional (i.e.
    not masterless) minion

CLI Examples:

    salt '*' saltutil.sync_pillar
    salt '*' saltutil.sync_pillar saltenv=dev

saltutil.sync_proxymodules:

New in version 2015.8.2

Sync proxy modules from ``salt://_proxy`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for proxy modules to sync. If no top
    files are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new proxy modules are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_proxymodules
    salt '*' saltutil.sync_proxymodules saltenv=dev
    salt '*' saltutil.sync_proxymodules saltenv=base,dev

saltutil.sync_renderers:

New in version 0.10.0

Sync renderers from ``salt://_renderers`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for renderers to sync. If no top files
    are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new renderers are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_renderers
    salt '*' saltutil.sync_renderers saltenv=dev
    salt '*' saltutil.sync_renderers saltenv=base,dev

saltutil.sync_returners:

New in version 0.10.0

Sync returners from ``salt://_returners`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for returners to sync. If no top files
    are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new returners are synced. Set
    to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_returners
    salt '*' saltutil.sync_returners saltenv=dev

saltutil.sync_sdb:

New in version 2015.5.8,2015.8.3

Sync sdb modules from ``salt://_sdb`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for sdb modules to sync. If no top files
    are found, then the ``base`` environment will be synced.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Example:

    salt '*' saltutil.sync_sdb
    salt '*' saltutil.sync_sdb saltenv=dev
    salt '*' saltutil.sync_sdb saltenv=base,dev

saltutil.sync_serializers:

New in version 2019.2.0

Sync serializers from ``salt://_serializers`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for serializer modules to sync. If no top
    files are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new serializer modules are
    synced. Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-seperated list of modules to sync

extmod_blacklist : None
    comma-seperated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_serializers
    salt '*' saltutil.sync_serializers saltenv=dev
    salt '*' saltutil.sync_serializers saltenv=base,dev

saltutil.sync_states:

New in version 0.10.0

Sync state modules from ``salt://_states`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for state modules to sync. If no top
    files are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available states on the minion. This refresh
    will be performed even if no new state modules are synced. Set to
    ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_states
    salt '*' saltutil.sync_states saltenv=dev
    salt '*' saltutil.sync_states saltenv=base,dev

saltutil.sync_thorium:

New in version 2018.3.0

Sync Thorium modules from ``salt://_thorium`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for engines to sync. If no top files are
    found, then the ``base`` environment will be synced.

refresh: ``True``
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new Thorium modules are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist
    comma-separated list of modules to sync

extmod_blacklist
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_thorium
    salt '*' saltutil.sync_thorium saltenv=base,dev

saltutil.sync_tops:

New in version 3007.0

Sync master tops from ``salt://_tops`` to the minion.

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for master tops to sync. If no top files
    are found, then the ``base`` environment will be synced.

refresh : True
    Refresh this module's cache containing the environments from which
    extension modules are synced when ``saltenv`` is not specified.
    This refresh will be performed even if no new master tops are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

Note:
    This function will raise an error if executed on a traditional (i.e.
    not masterless) minion

CLI Examples:

    salt '*' saltutil.sync_tops
    salt '*' saltutil.sync_tops saltenv=dev

saltutil.sync_utils:

New in version 2014.7.0

Sync utility modules from ``salt://_utils`` to the minion

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for utility modules to sync. If no top
    files are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available execution modules on the minion.
    This refresh will be performed even if no new utility modules are
    synced. Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-separated list of modules to sync

extmod_blacklist : None
    comma-separated list of modules to blacklist based on type

CLI Examples:

    salt '*' saltutil.sync_utils
    salt '*' saltutil.sync_utils saltenv=dev
    salt '*' saltutil.sync_utils saltenv=base,dev

saltutil.sync_wrapper:

New in version 3007.0

Sync salt-ssh wrapper modules from ``salt://_wrapper`` to the minion.

saltenv
    The fileserver environment from which to sync. To sync from more than
    one environment, pass a comma-separated list.

    If not passed, then all environments configured in the :ref:`top files
    <states-top>` will be checked for wrappers to sync. If no top files
    are found, then the ``base`` environment will be synced.

refresh : True
    If ``True``, refresh the available wrapper modules on the minion.
    This refresh will be performed even if no wrappers are synced.
    Set to ``False`` to prevent this refresh.

extmod_whitelist : None
    comma-seperated list of modules to sync

extmod_blacklist : None
    comma-seperated list of modules to blacklist based on type

Note:
    This function will raise an error if executed on a traditional (i.e.
    not masterless) minion.

CLI Examples:

    salt '*' saltutil.sync_wrapper
    salt '*' saltutil.sync_wrapper saltenv=dev
    salt '*' saltutil.sync_wrapper saltenv=base,dev

saltutil.term_all_jobs:

Sends a termination signal (SIGTERM 15) to all currently running jobs

CLI Example:

    salt '*' saltutil.term_all_jobs

saltutil.term_job:

Sends a termination signal (SIGTERM 15) to the named salt job's process

CLI Example:

    salt '*' saltutil.term_job <job id>

saltutil.update:

Update the salt minion from the URL defined in opts['update_url']
VMware, Inc provides the latest builds here:
update_url: https://repo.saltproject.io/windows/

Be aware that as of 2014-8-11 there's a bug in esky such that only the
latest version available in the update_url can be downloaded and installed.

This feature requires the minion to be running a bdist_esky build.

The version number is optional and will default to the most recent version
available at opts['update_url'].

Returns details about the transaction upon completion.

CLI Examples:

    salt '*' saltutil.update
    salt '*' saltutil.update 0.10.3

saltutil.wheel:

Execute a wheel module and function. This function must be run against a
minion that is local to the master.

New in version 2014.7.0

name
    The name of the function to run

args
    Any positional arguments to pass to the wheel function. A common example
    of this would be the ``match`` arg needed for key functions.

    New in version 2015.8.11

kwargs
    Any keyword arguments to pass to the wheel function

CLI Example:

    salt my-local-minion saltutil.wheel key.accept jerry
    salt my-local-minion saltutil.wheel minions.connected

Note:

    Since this function must be run against a minion that is running locally
    on the master in order to get accurate returns, if this function is run
    against minions that are not local to the master, "empty" returns are
    expected. The remote minion does not have access to wheel functions and
    their return data.

schedule.add:

Add a job to the schedule

CLI Example:

    salt '*' schedule.add job1 function='test.ping' seconds=3600
    # If function have some arguments, use job_args
    salt '*' schedule.add job2 function='cmd.run' job_args="['date >> /tmp/date.log']" seconds=60

    # Add job to Salt minion when the Salt minion is not running
    salt '*' schedule.add job1 function='test.ping' seconds=3600 offline=True

schedule.build_schedule_item:

Build a schedule job

CLI Example:

    salt '*' schedule.build_schedule_item job1 function='test.ping' seconds=3600

schedule.copy:

Copy scheduled job to another minion or minions.

CLI Example:

    salt '*' schedule.copy jobname target

schedule.delete:

Delete a job from the minion's schedule

CLI Example:

    salt '*' schedule.delete job1

    # Delete job on Salt minion when the Salt minion is not running
    salt '*' schedule.delete job1

schedule.disable:

Disable all scheduled jobs on the minion

CLI Example:

    salt '*' schedule.disable

schedule.disable_job:

Disable a job in the minion's schedule

CLI Example:

    salt '*' schedule.disable_job job1

schedule.enable:

Enable all scheduled jobs on the minion

CLI Example:

    salt '*' schedule.enable

schedule.enable_job:

Enable a job in the minion's schedule

CLI Example:

    salt '*' schedule.enable_job job1

schedule.is_enabled:

List a Job only if its enabled

If job is not specified, indicate
if the scheduler is enabled or disabled.

New in version 2015.5.3

CLI Example:

    salt '*' schedule.is_enabled name=job_name
    salt '*' schedule.is_enabled

schedule.job_status:

Show the information for a particular job.

CLI Example:

    salt '*' schedule.job_status job_name

schedule.list:

List the jobs currently scheduled on the minion

CLI Example:

    salt '*' schedule.list

    # Show all jobs including hidden internal jobs
    salt '*' schedule.list show_all=True

    # Hide disabled jobs from list of jobs
    salt '*' schedule.list show_disabled=False

schedule.modify:

Modify an existing job in the schedule

CLI Example:

    salt '*' schedule.modify job1 function='test.ping' seconds=3600

    # Modify job on Salt minion when the Salt minion is not running
    salt '*' schedule.modify job1 function='test.ping' seconds=3600 offline=True

schedule.move:

Move scheduled job to another minion or minions.

CLI Example:

    salt '*' schedule.move jobname target

schedule.postpone_job:

Postpone a job in the minion's schedule

Current time and new time should be in date string format,
default value is %Y-%m-%dT%H:%M:%S.

New in version 2018.3.0

CLI Example:

    salt '*' schedule.postpone_job job current_time new_time

    salt '*' schedule.postpone_job job current_time new_time time_fmt='%Y-%m-%dT%H:%M:%S'

schedule.purge:

Purge all the jobs currently scheduled on the minion

CLI Example:

    salt '*' schedule.purge

    # Purge jobs on Salt minion
    salt '*' schedule.purge

schedule.reload:

Reload saved scheduled jobs on the minion

CLI Example:

    salt '*' schedule.reload

schedule.run_job:

Run a scheduled job on the minion immediately

CLI Example:

    salt '*' schedule.run_job job1

    salt '*' schedule.run_job job1 force=True
    Force the job to run even if it is disabled.

schedule.save:

Save all scheduled jobs on the minion

CLI Example:

    salt '*' schedule.save

schedule.show_next_fire_time:

Show the next fire time for scheduled job

New in version 2018.3.0

CLI Example:

    salt '*' schedule.show_next_fire_time job_name

schedule.skip_job:

Skip a job in the minion's schedule at specified time.

Time to skip should be specified as date string format,
default value is %Y-%m-%dT%H:%M:%S.

New in version 2018.3.0

CLI Example:

    salt '*' schedule.skip_job job time

scsi.ls:

List SCSI devices, with details

CLI Examples:

    salt '*' scsi.ls
    salt '*' scsi.ls get_size=False

get_size : True
    Get the size information for scsi devices.  This option
    should be set to False for older OS distributions (RHEL6 and older)
    due to lack of support for the '-s' option in lsscsi.

    New in version 2015.5.10

scsi.rescan_all:

List scsi devices

CLI Example:

    salt '*' scsi.rescan_all 0

sdb.delete:

Delete a value from a db, using a uri in the form of ``sdb://<profile>/<key>``.
If the uri provided does not start with ``sdb://`` or the value is not
successfully deleted, return ``False``.

CLI Example:

    salt '*' sdb.delete sdb://mymemcached/foo

sdb.get:

Get a value from a db, using a uri in the form of ``sdb://<profile>/<key>``. If
the uri provided is not valid, then it will be returned as-is, unless ``strict=True`` was passed.

CLI Example:

    salt '*' sdb.get sdb://mymemcached/foo strict=True

sdb.get_or_set_hash:

Perform a one-time generation of a hash and write it to sdb.
If that value has already been set return the value instead.

This is useful for generating passwords or keys that are specific to
multiple minions that need to be stored somewhere centrally.

State Example:

    some_mysql_user:
      mysql_user:
        - present
        - host: localhost
        - password: '{{ salt["sdb.get_or_set_hash"]("sdb://mymemcached/some_user_pass") }}'

CLI Example:

    salt '*' sdb.get_or_set_hash 'sdb://mymemcached/SECRET_KEY' 50

Warning:

    This function could return strings which may contain characters which are reserved
    as directives by the YAML parser, such as strings beginning with ``%``. To avoid
    issues when using the output of this function in an SLS file containing YAML+Jinja,
    surround the call with single quotes.

sdb.set:

Set a value in a db, using a uri in the form of ``sdb://<profile>/<key>``.
If the uri provided does not start with ``sdb://`` or the value is not
successfully set, return ``False``.

CLI Example:

    salt '*' sdb.set sdb://mymemcached/foo bar

seed.apply:

Seed a location (disk image, directory, or block device) with the
minion config, approve the minion's key, and/or install salt-minion.

CLI Example:

    salt 'minion' seed.apply path id [config=config_data] \
            [gen_key=(true|false)] [approve_key=(true|false)] \
            [install=(true|false)]

path
    Full path to the directory, device, or disk image  on the target
    minion's file system.

id
    Minion id with which to seed the path.

config
    Minion configuration options. By default, the 'master' option is set to
    the target host's 'master'.

approve_key
    Request a pre-approval of the generated minion key. Requires
    that the salt-master be configured to either auto-accept all keys or
    expect a signing request from the target host. Default: true.

install
    Install salt-minion, if absent. Default: true.

prep_install
    Prepare the bootstrap script, but don't run it. Default: false

seed.mkconfig:

Generate keys and config and put them in a tmp directory.

pub_key
    absolute path or file content of an optional preseeded salt key

priv_key
    absolute path or file content of an optional preseeded salt key

CLI Example:

    salt 'minion' seed.mkconfig [config=config_data] [tmp=tmp_dir] \
            [id_=minion_id] [approve_key=(true|false)]

seed.prep_bootstrap:

Update and get the random script to a random place

CLI Example:

    salt '*' seed.prep_bootstrap /tmp

serverdensity_device.create:

Function to create device in Server Density. For more info, see the `API
docs`__.

.. __: https://apidocs.serverdensity.com/Inventory/Devices/Creating

CLI Example:

    salt '*' serverdensity_device.create lama
    salt '*' serverdensity_device.create rich_lama group=lama_band installedRAM=32768

serverdensity_device.delete:

Delete a device from Server Density. For more information, see the `API
docs`__.

.. __: https://apidocs.serverdensity.com/Inventory/Devices/Deleting

CLI Example:

    salt '*' serverdensity_device.delete 51f7eafcdba4bb235e000ae4

serverdensity_device.get_sd_auth:

Returns requested Server Density authentication value from pillar.

CLI Example:

    salt '*' serverdensity_device.get_sd_auth <val>

serverdensity_device.install_agent:

Function downloads Server Density installation agent, and installs sd-agent
with agent_key. Optionally the agent_version would select the series to
use (defaults on the v1 one).

CLI Example:

    salt '*' serverdensity_device.install_agent c2bbdd6689ff46282bdaa07555641498
    salt '*' serverdensity_device.install_agent c2bbdd6689ff46282bdaa07555641498 2

serverdensity_device.ls:

List devices in Server Density

Results will be filtered by any params passed to this function. For more
information, see the API docs on listing_ and searching_.

.. _listing: https://apidocs.serverdensity.com/Inventory/Devices/Listing
.. _searching: https://apidocs.serverdensity.com/Inventory/Devices/Searching

CLI Example:

    salt '*' serverdensity_device.ls
    salt '*' serverdensity_device.ls name=lama
    salt '*' serverdensity_device.ls name=lama group=lama_band installedRAM=32768

serverdensity_device.update:

Updates device information in Server Density. For more information see the
`API docs`__.

.. __: https://apidocs.serverdensity.com/Inventory/Devices/Updating

CLI Example:

    salt '*' serverdensity_device.update 51f7eafcdba4bb235e000ae4 name=lama group=lama_band
    salt '*' serverdensity_device.update 51f7eafcdba4bb235e000ae4 name=better_lama group=rock_lamas swapSpace=512

service.available:

New in version 0.10.4

Check that the given service is available taking into account template
units.

CLI Example:

    salt '*' service.available sshd

service.disable:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Disable the named service to not start when the system boots

no_block : False
    Set to ``True`` to start the service using ``--no-block``.

    New in version 2017.7.0

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.disable <service name>

service.disabled:

Return if the named service is disabled from starting on boot

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.disabled <service name>

service.enable:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Enable the named service to start when the system boots

no_block : False
    Set to ``True`` to start the service using ``--no-block``.

    New in version 2017.7.0

unmask : False
    Set to ``True`` to remove an indefinite mask before attempting to
    enable the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        enabling. This behavior is no longer the default.

unmask_runtime : False
    Set to ``True`` to remove a runtime mask before attempting to enable
    the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        enabling. This behavior is no longer the default.

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.enable <service name>

service.enabled:

Return if the named service is enabled to start on boot

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.enabled <service name>

service.execs:

New in version 2014.7.0

Return a list of all files specified as ``ExecStart`` for all services.

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.execs

service.firstboot:

New in version 3001

Call systemd-firstboot to configure basic settings of the system

locale
    Set primary locale (LANG=)

locale_message
    Set message locale (LC_MESSAGES=)

keymap
    Set keymap

timezone
    Set timezone

hostname
    Set host name

machine_id
    Set machine ID

root
    Operate on an alternative filesystem root

CLI Example:

    salt '*' service.firstboot keymap=jp locale=en_US.UTF-8

service.force_reload:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

New in version 0.12.0

Force-reload the specified service with systemd

no_block : False
    Set to ``True`` to start the service using ``--no-block``.

    New in version 2017.7.0

unmask : False
    Set to ``True`` to remove an indefinite mask before attempting to
    force-reload the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        force-reloading. This behavior is no longer the default.

unmask_runtime : False
    Set to ``True`` to remove a runtime mask before attempting to
    force-reload the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        force-reloading. This behavior is no longer the default.

CLI Example:

    salt '*' service.force_reload <service name>

service.get_all:

Return a list of all available services

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.get_all

service.get_disabled:

Return a list of all disabled services

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.get_disabled

service.get_enabled:

Return a list of all enabled services

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.get_enabled

service.get_running:

Return a list of all running services, so far as systemd is concerned

CLI Example:

    salt '*' service.get_running

service.get_static:

New in version 2015.8.5

Return a list of all static services

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.get_static

service.mask:

New in version 2015.5.0
Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Mask the specified service with systemd

runtime : False
    Set to ``True`` to mask this service only until the next reboot

    New in version 2015.8.5

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.mask foo
    salt '*' service.mask foo runtime=True

service.masked:

New in version 2015.8.0
Changed in version 2015.8.5
    The return data for this function has changed. If the service is
    masked, the return value will now be the output of the ``systemctl
    is-enabled`` command (so that a persistent mask can be distinguished
    from a runtime mask). If the service is not masked, then ``False`` will
    be returned.
Changed in version 2017.7.0
    This function now returns a boolean telling the user whether a mask
    specified by the new ``runtime`` argument is set. If ``runtime`` is
    ``False``, this function will return ``True`` if an indefinite mask is
    set for the named service (otherwise ``False`` will be returned). If
    ``runtime`` is ``False``, this function will return ``True`` if a
    runtime mask is set, otherwise ``False``.

Check whether or not a service is masked

runtime : False
    Set to ``True`` to check for a runtime mask

    New in version 2017.7.0
        In previous versions, this function would simply return the output
        of ``systemctl is-enabled`` when the service was found to be
        masked. However, since it is possible to both have both indefinite
        and runtime masks on a service simultaneously, this function now
        only checks for runtime masks if this argument is set to ``True``.
        Otherwise, it will check for an indefinite mask.

root
    Enable/disable/mask unit files in the specified root directory

CLI Examples:

    salt '*' service.masked foo
    salt '*' service.masked foo runtime=True

service.missing:

New in version 2014.1.0

The inverse of :py:func:`service.available
<salt.modules.systemd.available>`. Returns ``True`` if the specified
service is not available, otherwise returns ``False``.

CLI Example:

    salt '*' service.missing sshd

service.offline:

New in version 3004

Check if systemd is working in offline mode, where is not possible
to talk with PID 1.

CLI Example:

    salt '*' service.offline

service.reload:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Reload the specified service with systemd

no_block : False
    Set to ``True`` to reload the service using ``--no-block``.

    New in version 2017.7.0

unmask : False
    Set to ``True`` to remove an indefinite mask before attempting to
    reload the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        reloading. This behavior is no longer the default.

unmask_runtime : False
    Set to ``True`` to remove a runtime mask before attempting to reload
    the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        reloading. This behavior is no longer the default.

CLI Example:

    salt '*' service.reload <service name>

service.restart:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Restart the specified service with systemd

no_block : False
    Set to ``True`` to start the service using ``--no-block``.

    New in version 2017.7.0

unmask : False
    Set to ``True`` to remove an indefinite mask before attempting to
    restart the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        restarting. This behavior is no longer the default.

unmask_runtime : False
    Set to ``True`` to remove a runtime mask before attempting to restart
    the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        restarting. This behavior is no longer the default.

CLI Example:

    salt '*' service.restart <service name>

service.show:

New in version 2014.7.0

Show properties of one or more units/jobs or the manager

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.show <service name>

service.start:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Start the specified service with systemd

no_block : False
    Set to ``True`` to start the service using ``--no-block``.

    New in version 2017.7.0

unmask : False
    Set to ``True`` to remove an indefinite mask before attempting to start
    the service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        starting. This behavior is no longer the default.

unmask_runtime : False
    Set to ``True`` to remove a runtime mask before attempting to start the
    service.

    New in version 2017.7.0
        In previous releases, Salt would simply unmask a service before
        starting. This behavior is no longer the default.

CLI Example:

    salt '*' service.start <service name>

service.status:

Return the status for a service via systemd.
If the name contains globbing, a dict mapping service name to True/False
values is returned.

Changed in version 2018.3.0
    The service name can now be a glob (e.g. ``salt*``)

Args:
    name (str): The name of the service to check
    sig (str): Not implemented

Returns:
    bool: True if running, False otherwise
    dict: Maps service name to True if running, False otherwise

CLI Example:

    salt '*' service.status <service name> [service signature]

service.stop:

Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Stop the specified service with systemd

no_block : False
    Set to ``True`` to start the service using ``--no-block``.

    New in version 2017.7.0

CLI Example:

    salt '*' service.stop <service name>

service.systemctl_reload:

New in version 0.15.0

Reloads systemctl, an action needed whenever unit files are updated.

CLI Example:

    salt '*' service.systemctl_reload

service.unmask:

New in version 2015.5.0
Changed in version 2015.8.12,2016.3.3,2016.11.0
    On minions running systemd>=205, `systemd-run(1)`_ is now used to
    isolate commands run by this function from the ``salt-minion`` daemon's
    control group. This is done to avoid a race condition in cases where
    the ``salt-minion`` service is restarted while a service is being
    modified. If desired, usage of `systemd-run(1)`_ can be suppressed by
    setting a :mod:`config option <salt.modules.config.get>` called
    ``systemd.scope``, with a value of ``False`` (no quotes).

.. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html

Unmask the specified service with systemd

runtime : False
    Set to ``True`` to unmask this service only until the next reboot

    New in version 2017.7.0
        In previous versions, this function would remove whichever mask was
        identified by running ``systemctl is-enabled`` on the service.
        However, since it is possible to both have both indefinite and
        runtime masks on a service simultaneously, this function now
        removes a runtime mask only when this argument is set to ``True``,
        and otherwise removes an indefinite mask.

root
    Enable/disable/mask unit files in the specified root directory

CLI Example:

    salt '*' service.unmask foo
    salt '*' service.unmask foo runtime=True

shadow.default_hash:

Returns the default hash used for unset passwords

CLI Example:

    salt '*' shadow.default_hash

shadow.del_password:

New in version 2014.7.0

Delete the password from name user

name
    User to delete

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.del_password username

shadow.gen_password:

New in version 2014.7.0

Generate hashed password

Note:

    When called this function is called directly via remote-execution,
    the password argument may be displayed in the system's process list.
    This may be a security risk on certain systems.

password
    Plaintext password to be hashed.

crypt_salt
    Crpytographic salt. If not given, a random 8-character salt will be
    generated.

algorithm
    The following hash algorithms are supported:

    * md5
    * blowfish (not in mainline glibc, only available in distros that add it)
    * sha256
    * sha512 (default)

CLI Example:

    salt '*' shadow.gen_password 'I_am_password'
    salt '*' shadow.gen_password 'I_am_password' crypt_salt='I_am_salt' algorithm=sha256

shadow.info:

Return information for the specified user

name
    User to get the information for

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.info root

shadow.list_users:

New in version 2018.3.0

Return a list of all shadow users

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.list_users

shadow.lock_password:

New in version 2016.11.0

Lock the password from specified user

name
    User to lock

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.lock_password username

shadow.set_date:

Sets the value for the date the password was last changed to days since the
epoch (January 1, 1970). See man chage.

name
    User to modify

date
    Date the password was last changed

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.set_date username 0

shadow.set_expire:

Changed in version 2014.7.0

Sets the value for the date the account expires as days since the epoch
(January 1, 1970). Using a value of -1 will clear expiration. See man
chage.

name
    User to modify

date
    Date the account expires

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.set_expire username -1

shadow.set_inactdays:

Set the number of days of inactivity after a password has expired before
the account is locked. See man chage.

name
    User to modify

inactdays
    Set password inactive after this number of days

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.set_inactdays username 7

shadow.set_maxdays:

Set the maximum number of days during which a password is valid.
See man chage.

name
    User to modify

maxdays
    Maximum number of days during which a password is valid

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.set_maxdays username 90

shadow.set_mindays:

Set the minimum number of days between password changes. See man chage.

name
    User to modify

mindays
    Minimum number of days between password changes

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.set_mindays username 7

shadow.set_password:

Set the password for a named user. The password must be a properly defined
hash. A password hash can be generated with :py:func:`gen_password`.

name
    User to set the password

password
    Password already hashed

use_usermod
    Use usermod command to better compatibility

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.set_password root '$1$UYCIxa628.9qXjpQCjM4a..'

shadow.set_warndays:

Set the number of days of warning before a password change is required.
See man chage.

name
    User to modify

warndays
    Number of days of warning before a password change is required

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.set_warndays username 7

shadow.unlock_password:

New in version 2016.11.0

Unlock the password from name user

name
    User to unlock

root
    Directory to chroot into

CLI Example:

    salt '*' shadow.unlock_password username

slack.call_hook:

Send message to Slack incoming webhook.

:param message:     The topic of message.
:param attachment:  The message to send to the Slack WebHook.
:param color:       The color of border of left side
:param short:       An optional flag indicating whether the value is short
                    enough to be displayed side-by-side with other values.
:param identifier:  The identifier of WebHook.
:param channel:     The channel to use instead of the WebHook default.
:param username:    Username to use instead of WebHook default.
:param icon_emoji:  Icon to use instead of WebHook default.
:return:            Boolean if message was sent successfully.

CLI Example:

    salt '*' slack.call_hook message='Hello, from SaltStack'

slack.find_room:

Find a room by name and return it.

:param name:    The room name.
:param api_key: The Slack admin api key.
:return:        The room object.

CLI Example:

    salt '*' slack.find_room name="random"

    salt '*' slack.find_room name="random" api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15

slack.find_user:

Find a user by name and return it.

:param name:        The user name.
:param api_key:     The Slack admin api key.
:return:            The user object.

CLI Example:

    salt '*' slack.find_user name="ThomasHatch"

    salt '*' slack.find_user name="ThomasHatch" api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15

slack.list_rooms:

List all Slack rooms.

:param api_key: The Slack admin api key.
:return: The room list.

CLI Example:

    salt '*' slack.list_rooms

    salt '*' slack.list_rooms api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15

slack.list_users:

List all Slack users.

:param api_key: The Slack admin api key.
:return: The user list.

CLI Example:

    salt '*' slack.list_users

    salt '*' slack.list_users api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15

slack.post_message:

Send a message to a Slack channel.

Changed in version 3003
    Added `attachments` and `blocks` kwargs

:param channel:     The channel name, either will work.
:param message:     The message to send to the Slack channel.
:param from_name:   Specify who the message is from.
:param api_key:     The Slack api key, if not specified in the configuration.
:param icon:        URL to an image to use as the icon for this message
:param attachments: Any attachments to be sent with the message.
:param blocks:      Any blocks to be sent with the message.
:return:            Boolean if message was sent successfully.

CLI Example:

    salt '*' slack.post_message channel="Development Room" message="Build is done" from_name="Build Server"

slsutil.banner:

Create a standardized comment block to include in a templated file.

A common technique in configuration management is to include a comment
block in managed files, warning users not to modify the file. This
function simplifies and standardizes those comment blocks.

:param width: The width, in characters, of the banner. Default is 72.
:param commentchar: The character to be used in the starting position of
    each line. This value should be set to a valid line comment character
    for the syntax of the file in which the banner is being inserted.
    Multiple character sequences, like '//' are supported.
    If the file's syntax does not support line comments (such as XML),
    use the ``blockstart`` and ``blockend`` options.
:param borderchar: The character to use in the top and bottom border of
    the comment box. Must be a single character.
:param blockstart: The character sequence to use at the beginning of a
    block comment. Should be used in conjunction with ``blockend``
:param blockend: The character sequence to use at the end of a
    block comment. Should be used in conjunction with ``blockstart``
:param title: The first field of the comment block. This field appears
    centered at the top of the box.
:param text: The second filed of the comment block. This field appears
    left-justified at the bottom of the box.
:param newline: Boolean value to indicate whether the comment block should
    end with a newline. Default is ``False``.

**Example 1 - the default banner:**

    {{ salt['slsutil.banner']() }}

    ########################################################################
    #                                                                      #
    #              THIS FILE IS MANAGED BY SALT - DO NOT EDIT              #
    #                                                                      #
    # The contents of this file are managed by Salt. Any changes to this   #
    # file may be overwritten automatically and without warning.           #
    ########################################################################

**Example 2 - a Javadoc-style banner:**

    {{ salt['slsutil.banner'](commentchar=' *', borderchar='*', blockstart='/**', blockend=' */') }}

    /**
     ***********************************************************************
     *                                                                     *
     *              THIS FILE IS MANAGED BY SALT - DO NOT EDIT             *
     *                                                                     *
     * The contents of this file are managed by Salt. Any changes to this  *
     * file may be overwritten automatically and without warning.          *
     ***********************************************************************
     */

**Example 3 - custom text:**

    {{ set copyright='This file may not be copied or distributed without permission of VMware, Inc.' }}
    {{ salt['slsutil.banner'](title='Copyright 2019 VMware, Inc.', text=copyright, width=60) }}

    ############################################################
    #                                                          #
    #              Copyright 2019 VMware, Inc.                 #
    #                                                          #
    # This file may not be copied or distributed without       #
    # permission of VMware, Inc.                               #
    ############################################################

slsutil.boolstr:

Convert a boolean value into a string. This function is
intended to be used from within file templates to provide
an easy way to take boolean values stored in Pillars or
Grains, and write them out in the appropriate syntax for
a particular file template.

:param value: The boolean value to be converted
:param true: The value to return if ``value`` is ``True``
:param false: The value to return if ``value`` is ``False``

In this example, a pillar named ``smtp:encrypted`` stores a boolean
value, but the template that uses that value needs ``yes`` or ``no``
to be written, based on the boolean value.

*Note: this is written on two lines for clarity. The same result
could be achieved in one line.*

    {% set encrypted = salt[pillar.get]('smtp:encrypted', false) %}
    use_tls: {{ salt['slsutil.boolstr'](encrypted, 'yes', 'no') }}

Result (assuming the value is ``True``):

    use_tls: yes

slsutil.deserialize:

Deserialize a Python object using one of the available
:ref:`all-salt.serializers`.

CLI Example:

    salt '*' slsutil.deserialize 'json' '{"foo": "Foo!"}'
    salt '*' --no-parse=stream_or_string slsutil.deserialize 'json' \
        stream_or_string='{"foo": "Foo!"}'

Jinja Example:

    {% set python_object = salt.slsutil.deserialize('json',
        '{"foo": "Foo!"}') %}

slsutil.dir_exists:

Return ``True`` if a directory exists in the state tree, ``False`` otherwise.

:param str path: The fully qualified path to a directory in the state tree.
:param str saltenv: The fileserver environment to search. Default: ``base``

New in version 3004

CLI Example:

    salt '*' slsutil.dir_exists nginx/files

slsutil.file_exists:

Return ``True`` if a file exists in the state tree, ``False`` otherwise.

New in version 3004

:param str path: The fully qualified path to a file in the state tree.
:param str saltenv: The fileserver environment to search. Default: ``base``

CLI Example:

    salt '*' slsutil.file_exists nginx/defaults.yaml

slsutil.findup:

Find the first path matching a filename or list of filenames in a specified
directory or the nearest ancestor directory. Returns the full path to the
first file found.

New in version 3004

:param str startpath: The fileserver path from which to begin the search.
    An empty string refers to the state tree root.
:param filenames: A filename or list of filenames to search for. Searching for
    directory names is also supported.
:param str saltenv: The fileserver environment to search. Default: ``base``

Example: return the path to ``defaults.yaml``, walking up the tree from the
state file currently being processed.

    {{ salt["slsutil.findup"](tplfile, "defaults.yaml") }}

CLI Example:

    salt '*' slsutil.findup formulas/shared/nginx map.jinja

slsutil.merge:

Merge a data structure into another by choosing a merge strategy

Strategies:

* aggregate
* list
* overwrite
* recurse
* smart

CLI Example:

    salt '*' slsutil.merge '{foo: Foo}' '{bar: Bar}'

slsutil.merge_all:

New in version 2019.2.0

Merge a list of objects into each other in order

:type lst: Iterable
:param lst: List of objects to be merged.

:type strategy: String
:param strategy: Merge strategy. See utils.dictupdate.

:type renderer: String
:param renderer:
    Renderer type. Used to determine strategy when strategy is 'smart'.

:type merge_lists: Bool
:param merge_lists: Defines whether to merge embedded object lists.

CLI Example:

    $ salt-call --output=txt slsutil.merge_all '[{foo: Foo}, {foo: Bar}]'
    local: {u'foo': u'Bar'}

slsutil.path_exists:

Return ``True`` if a path exists in the state tree, ``False`` otherwise. The path
could refer to a file or directory.

New in version 3004

:param str path: The fully qualified path to a file or directory in the state tree.
:param str saltenv: The fileserver environment to search. Default: ``base``

CLI Example:

    salt '*' slsutil.path_exists nginx/defaults.yaml

slsutil.renderer:

Parse a string or file through Salt's renderer system

Changed in version 2018.3.0
   Add support for Salt fileserver URIs.

This is an open-ended function and can be used for a variety of tasks. It
makes use of Salt's "renderer pipes" system to run a string or file through
a pipe of any of the loaded renderer modules.

:param path: The path to a file on Salt's fileserver (any URIs supported by
    :py:func:`cp.get_url <salt.modules.cp.get_url>`) or on the local file
    system.
:param string: An inline string to be used as the file to send through the
    renderer system. Note, not all renderer modules can work with strings;
    the 'py' renderer requires a file, for example.
:param default_renderer: The renderer pipe to send the file through; this
    is overridden by a "she-bang" at the top of the file.
:param kwargs: Keyword args to pass to Salt's compile_template() function.

Keep in mind the goal of each renderer when choosing a render-pipe; for
example, the Jinja renderer processes a text file and produces a string,
however the YAML renderer processes a text file and produces a data
structure.

One possible use is to allow writing "map files", as are commonly seen in
Salt formulas, but without tying the renderer of the map file to the
renderer used in the other sls files. In other words, a map file could use
the Python renderer and still be included and used by an sls file that uses
the default 'jinja|yaml' renderer.

For example, the two following map files produce identical results but one
is written using the normal 'jinja|yaml' and the other is using 'py':

    #!jinja|yaml
    {% set apache = salt.grains.filter_by({
        ...normal jinja map file here...
    }, merge=salt.pillar.get('apache:lookup')) %}
    {{ apache | yaml() }}

    #!py
    def run():
        apache = __salt__.grains.filter_by({
            ...normal map here but as a python dict...
        }, merge=__salt__.pillar.get('apache:lookup'))
        return apache

Regardless of which of the above map files is used, it can be accessed from
any other sls file by calling this function. The following is a usage
example in Jinja:

    {% set apache = salt.slsutil.renderer('map.sls') %}

CLI Example:

    salt '*' slsutil.renderer salt://path/to/file
    salt '*' slsutil.renderer /path/to/file
    salt '*' slsutil.renderer /path/to/file.jinja default_renderer='jinja'
    salt '*' slsutil.renderer /path/to/file.sls default_renderer='jinja|yaml'
    salt '*' slsutil.renderer string='Inline template! {{ saltenv }}'
    salt '*' slsutil.renderer string='Hello, {{ name }}.' name='world'

slsutil.serialize:

Serialize a Python object using one of the available
:ref:`all-salt.serializers`.

CLI Example:

    salt '*' --no-parse=obj slsutil.serialize 'json' obj="{'foo': 'Foo!'}

Jinja Example:

    {% set json_string = salt.slsutil.serialize('json',
        {'foo': 'Foo!'}) %}

slsutil.update:

Merge ``upd`` recursively into ``dest``

If ``merge_lists=True``, will aggregate list object types instead of
replacing. This behavior is only activated when ``recursive_update=True``.

CLI Example:

    salt '*' slsutil.update '{foo: Foo}' '{bar: Bar}'

smbios.get:

Get an individual DMI string from SMBIOS info

string
    The string to fetch. DMIdecode supports:
      - ``bios-vendor``
      - ``bios-version``
      - ``bios-release-date``
      - ``system-manufacturer``
      - ``system-product-name``
      - ``system-version``
      - ``system-serial-number``
      - ``system-uuid``
      - ``baseboard-manufacturer``
      - ``baseboard-product-name``
      - ``baseboard-version``
      - ``baseboard-serial-number``
      - ``baseboard-asset-tag``
      - ``chassis-manufacturer``
      - ``chassis-type``
      - ``chassis-version``
      - ``chassis-serial-number``
      - ``chassis-asset-tag``
      - ``processor-family``
      - ``processor-manufacturer``
      - ``processor-version``
      - ``processor-frequency``

clean
  | Don't return well-known false information
  | (invalid UUID's, serial 000000000's, etcetera)
  | Defaults to ``True``

CLI Example:

    salt '*' smbios.get system-uuid clean=False

smbios.records:

Return DMI records from SMBIOS

type
    Return only records of type(s)
    The SMBIOS specification defines the following DMI types:

    ====  ======================================
    Type  Information
    ====  ======================================
     0    BIOS
     1    System
     2    Baseboard
     3    Chassis
     4    Processor
     5    Memory Controller
     6    Memory Module
     7    Cache
     8    Port Connector
     9    System Slots
    10    On Board Devices
    11    OEM Strings
    12    System Configuration Options
    13    BIOS Language
    14    Group Associations
    15    System Event Log
    16    Physical Memory Array
    17    Memory Device
    18    32-bit Memory Error
    19    Memory Array Mapped Address
    20    Memory Device Mapped Address
    21    Built-in Pointing Device
    22    Portable Battery
    23    System Reset
    24    Hardware Security
    25    System Power Controls
    26    Voltage Probe
    27    Cooling Device
    28    Temperature Probe
    29    Electrical Current Probe
    30    Out-of-band Remote Access
    31    Boot Integrity Services
    32    System Boot
    33    64-bit Memory Error
    34    Management Device
    35    Management Device Component
    36    Management Device Threshold Data
    37    Memory Channel
    38    IPMI Device
    39    Power Supply
    40    Additional Information
    41    Onboard Devices Extended Information
    42    Management Controller Host Interface
    ====  ======================================

clean
  | Don't return well-known false information
  | (invalid UUID's, serial 000000000's, etcetera)
  | Defaults to ``True``

CLI Example:

    salt '*' smbios.records clean=False
    salt '*' smbios.records 14
    salt '*' smbios.records 4 core_count,thread_count,current_speed

smtp.send_msg:

Send a message to an SMTP recipient. To send a message to multiple     recipients, the recipients should be in a comma-seperated Python string.     Designed for use in states.

CLI Examples:

    salt '*' smtp.send_msg 'admin@example.com' 'This is a salt module test' profile='my-smtp-account'
    salt '*' smtp.send_msg 'admin@example.com,admin2@example.com' 'This is a salt module test for multiple recipients' profile='my-smtp-account'
    salt '*' smtp.send_msg 'admin@example.com' 'This is a salt module test' username='myuser' password='verybadpass' sender='admin@example.com' server='smtp.domain.com'
    salt '*' smtp.send_msg 'admin@example.com' 'This is a salt module test' username='myuser' password='verybadpass' sender='admin@example.com' server='smtp.domain.com' attachments="['/var/log/messages']"

solrcloud.alias_exists:

Check alias existence

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.alias_exists my_alias

solrcloud.alias_get_collections:

Get collection list for an alias

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.alias_get my_alias

solrcloud.alias_set_collections:

Define an alias

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.alias_set my_alias collections=[collection1, colletion2]

solrcloud.cluster_status:

Get cluster status

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.cluster_status

solrcloud.collection_backup:

Create a backup for a collection.

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.core_backup collection_name /mnt/nfs_backup

solrcloud.collection_backup_all:

Create a backup for all collection present on the server.

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.core_backup /mnt/nfs_backup

solrcloud.collection_check_options:

Check collections options

CLI Example:

    salt '*' solrcloud.collection_check_options '{"replicationFactor":4}'

solrcloud.collection_create:

Create a collection,

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.collection_create collection_name

Collection creation options may be passed using the "options" parameter.
Do not include option "name" since it already specified by the mandatory parameter "collection_name"

    salt '*' solrcloud.collection_create collection_name options={"replicationFactor":2, "numShards":3}

Cores options may be passed using the "properties" key in options.
Do not include property "name"

    salt '*' solrcloud.collection_create collection_name options={"replicationFactor":2, "numShards":3,             "properties":{"dataDir":"/srv/solr/hugePartitionSollection"}}

solrcloud.collection_creation_options:

Get collection option list that can only be defined at creation

CLI Example:

    salt '*' solrcloud.collection_creation_options

solrcloud.collection_exists:

Check if a collection exists

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.collection_exists collection_name

solrcloud.collection_get_options:

Get collection options

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.collection_get_options collection_name

solrcloud.collection_list:

List all collections

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.collection_list

solrcloud.collection_reload:

Check if a collection exists

Additional parameters (kwargs) may be passed, they will be proxied to http.query

CLI Example:

    salt '*' solrcloud.collection_reload collection_name

solrcloud.collection_set_options:

Change collection options

Additional parameters (kwargs) may be passed, they will be proxied to http.query

Note that not every parameter can be changed after collection creation

CLI Example:

    salt '*' solrcloud.collection_set_options collection_name options={"replicationFactor":4}

sqlite3.fetch:

Retrieve data from an sqlite3 db (returns all rows, be careful!)

CLI Example:

    salt '*' sqlite3.fetch /root/test.db 'SELECT * FROM test;'

sqlite3.indexes:

Show all indices in the database, for people with poor spelling skills

CLI Example:

    salt '*' sqlite3.indexes /root/test.db

sqlite3.indices:

Show all indices in the database

CLI Example:

    salt '*' sqlite3.indices /root/test.db

sqlite3.modify:

Issue an SQL query to sqlite3 (with no return data), usually used
to modify the database in some way (insert, delete, create, etc)

CLI Example:

    salt '*' sqlite3.modify /root/test.db 'CREATE TABLE test(id INT, testdata TEXT);'

sqlite3.sqlite_version:

Return version of sqlite

CLI Example:

    salt '*' sqlite3.sqlite_version

sqlite3.tables:

Show all tables in the database

CLI Example:

    salt '*' sqlite3.tables /root/test.db

sqlite3.version:

Return version of pysqlite

CLI Example:

    salt '*' sqlite3.version

ssh.auth_keys:

Return the authorized keys for users

CLI Example:

    salt '*' ssh.auth_keys
    salt '*' ssh.auth_keys root
    salt '*' ssh.auth_keys user=root
    salt '*' ssh.auth_keys user="[user1, user2]"

ssh.check_key:

Check to see if a key needs updating, returns "update", "add" or "exists"

CLI Example:

    salt '*' ssh.check_key <user> <key> <enc> <comment> <options>

ssh.check_key_file:

Check a keyfile from a source destination against the local keys and
return the keys to change

CLI Example:

    salt '*' ssh.check_key_file root salt://ssh/keyfile

ssh.check_known_host:

Check the record in known_hosts file, either by its value or by fingerprint
(it's enough to set up either key or fingerprint, you don't need to set up
both).

If provided key or fingerprint doesn't match with stored value, return
"update", if no value is found for a given host, return "add", otherwise
return "exists".

If neither key, nor fingerprint is defined, then additional validation is
not performed.

CLI Example:

    salt '*' ssh.check_known_host <user> <hostname> key='AAAA...FAaQ=='

ssh.get_known_host_entries:

New in version 2018.3.0

Return information about known host entries from the configfile, if any.
If there are no entries for a matching hostname, return None.

CLI Example:

    salt '*' ssh.get_known_host_entries <user> <hostname>

ssh.hash_known_hosts:

Hash all the hostnames in the known hosts file.

New in version 2014.7.0

user
    hash known hosts of this user

config
    path to known hosts file: can be absolute or relative to user's home
    directory

CLI Example:

    salt '*' ssh.hash_known_hosts

ssh.host_keys:

Return the minion's host keys

CLI Example:

    salt '*' ssh.host_keys
    salt '*' ssh.host_keys keydir=/etc/ssh
    salt '*' ssh.host_keys keydir=/etc/ssh private=False
    salt '*' ssh.host_keys keydir=/etc/ssh certs=False

ssh.key_is_encrypted:

New in version 2015.8.7

Function to determine whether or not a private key is encrypted with a
passphrase.

Checks key for a ``Proc-Type`` header with ``ENCRYPTED`` in the value. If
found, returns ``True``, otherwise returns ``False``.

CLI Example:

    salt '*' ssh.key_is_encrypted /root/id_rsa

ssh.recv_known_host_entries:

New in version 2018.3.0

Retrieve information about host public keys from remote server

hostname
    The name of the remote host (e.g. "github.com")

enc
    Defines what type of key is being used, can be ed25519, ecdsa,
    ssh-rsa, ssh-dss or any other type as of openssh server version 8.7.

port
    Optional parameter, denoting the port of the remote host on which an
    SSH daemon is running. By default the port 22 is used.

hash_known_hosts : True
    Hash all hostnames and addresses in the known hosts file.

timeout : int
    Set the timeout for connection attempts.  If ``timeout`` seconds have
    elapsed since a connection was initiated to a host or since the last
    time anything was read from that host, then the connection is closed
    and the host in question considered unavailable.  Default is 5 seconds.

fingerprint_hash_type
    The fingerprint hash type that the public key fingerprints were
    originally hashed with. This defaults to ``sha256`` if not specified.

    New in version 2016.11.4
    Changed in version 2017.7.0

        default changed from ``md5`` to ``sha256``

CLI Example:

    salt '*' ssh.recv_known_host_entries <hostname> enc=<enc> port=<port>

ssh.rm_auth_key:

Remove an authorized key from the specified user's authorized key file

CLI Example:

    salt '*' ssh.rm_auth_key <user> <key>

ssh.rm_auth_key_from_file:

Remove an authorized key from the specified user's authorized key file,
using a file as source

CLI Example:

    salt '*' ssh.rm_auth_key_from_file <user> salt://ssh_keys/<user>.id_rsa.pub

ssh.rm_known_host:

Remove all keys belonging to hostname from a known_hosts file.

CLI Example:

    salt '*' ssh.rm_known_host <user> <hostname>

ssh.set_auth_key:

Add a key to the authorized_keys file. The "key" parameter must only be the
string of text that is the encoded key. If the key begins with "ssh-rsa"
or ends with user@host, remove those from the key before passing it to this
function.

CLI Example:

    salt '*' ssh.set_auth_key <user> '<key>' enc='dsa'

ssh.set_auth_key_from_file:

Add a key to the authorized_keys file, using a file as the source.

CLI Example:

    salt '*' ssh.set_auth_key_from_file <user> salt://ssh_keys/<user>.id_rsa.pub

ssh.set_known_host:

Download SSH public key from remote host "hostname", optionally validate
its fingerprint against "fingerprint" variable and save the record in the
known_hosts file.

If such a record does already exists in there, do nothing.

user
    The user who owns the ssh authorized keys file to modify

hostname
    The name of the remote host (e.g. "github.com")

fingerprint
    The fingerprint of the key which must be present in the known_hosts
    file (optional if key specified)

key
    The public key which must be presented in the known_hosts file
    (optional if fingerprint specified)

port
    optional parameter, denoting the port of the remote host, which will be
    used in case, if the public key will be requested from it. By default
    the port 22 is used.

enc
    Defines what type of key is being used, can be ed25519, ecdsa,
    ssh-rsa, ssh-dss or any other type as of openssh server version 8.7.

config
    The location of the authorized keys file relative to the user's home
    directory, defaults to ".ssh/known_hosts". If no user is specified,
    defaults to "/etc/ssh/ssh_known_hosts". If present, must be an
    absolute path when a user is not specified.

hash_known_hosts : True
    Hash all hostnames and addresses in the known hosts file.

timeout : int
    Set the timeout for connection attempts.  If ``timeout`` seconds have
    elapsed since a connection was initiated to a host or since the last
    time anything was read from that host, then the connection is closed
    and the host in question considered unavailable.  Default is 5 seconds.

    New in version 2016.3.0

fingerprint_hash_type
    The public key fingerprint hash type that the public key fingerprint
    was originally hashed with. This defaults to ``sha256`` if not specified.

    New in version 2016.11.4
    Changed in version 2017.7.0

        default changed from ``md5`` to ``sha256``

CLI Example:

    salt '*' ssh.set_known_host <user> fingerprint='xx:xx:..:xx' enc='ssh-rsa' config='.ssh/known_hosts'

ssh.user_keys:

Return the user's ssh keys on the minion

New in version 2014.7.0

CLI Example:

    salt '*' ssh.user_keys
    salt '*' ssh.user_keys user=user1
    salt '*' ssh.user_keys user=user1 pubfile=/home/user1/.ssh/id_rsa.pub prvfile=/home/user1/.ssh/id_rsa
    salt '*' ssh.user_keys user=user1 prvfile=False
    salt '*' ssh.user_keys user="['user1','user2'] pubfile=id_rsa.pub prvfile=id_rsa

As you can see you can tell Salt not to read from the user's private (or
public) key file by setting the file path to ``False``. This can be useful
to prevent Salt from publishing private data via Salt Mine or others.

state.apply:

New in version 2015.5.0

This function will call :mod:`state.highstate
<salt.modules.state.highstate>` or :mod:`state.sls
<salt.modules.state.sls>` based on the arguments passed to this function.
It exists as a more intuitive way of applying states.

.. rubric:: APPLYING ALL STATES CONFIGURED IN TOP.SLS (A.K.A. :ref:`HIGHSTATE <running-highstate>`)

To apply all configured states, simply run ``state.apply`` with no SLS
targets, like so:

    salt '*' state.apply

The following additional arguments are also accepted when applying all
states configured in top.sls:

test
    Run states in test-only (dry-run) mode

mock
    The mock option allows for the state run to execute without actually
    calling any states. This then returns a mocked return which will show
    the requisite ordering as well as fully validate the state run.

    New in version 2015.8.4

pillar
    Custom Pillar values, passed as a dictionary of key-value pairs

        salt '*' state.apply stuff pillar='{"foo": "bar"}'

    Note:
        Values passed this way will override Pillar values set via
        ``pillar_roots`` or an external Pillar source.

exclude
    Exclude specific states from execution. Accepts a list of sls names, a
    comma-separated string of sls names, or a list of dictionaries
    containing ``sls`` or ``id`` keys. Glob-patterns may be used to match
    multiple states.

        salt '*' state.apply exclude=bar,baz
        salt '*' state.apply exclude=foo*
        salt '*' state.apply exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"

queue : False
    Instead of failing immediately when another state run is in progress,
    a value of ``True`` will queue the new state run to begin running once
    the other has finished.

    This option starts a new thread for each queued state run, so use this
    option sparingly.

    Changed in version 3006.0
        This parameter can also be set via the ``state_queue`` configuration
        option. Additionally, it can now be set to an integer representing
        the maximum queue size which can be attained before the state runs
        will fail to be queued. This can prevent runaway conditions where
        new threads are started until system performance is hampered.

localconfig
    Optionally, instead of using the minion config, load minion opts from
    the file specified by this argument, and then merge them with the
    options from the minion config. This functionality allows for specific
    states to be run with their own custom minion configuration, including
    different pillars, file_roots, etc.

        salt '*' state.apply localconfig=/path/to/minion.yml

state_events
    The state_events option sends progress events as each function in
    a state run completes execution.

    New in version 3006.0


.. rubric:: APPLYING INDIVIDUAL SLS FILES (A.K.A. :py:func:`STATE.SLS <salt.modules.state.sls>`)

To apply individual SLS files, pass them as a comma-separated list:

    # Run the states configured in salt://stuff.sls (or salt://stuff/init.sls)
    salt '*' state.apply stuff

    # Run the states configured in salt://stuff.sls (or salt://stuff/init.sls)
    # and salt://pkgs.sls (or salt://pkgs/init.sls).
    salt '*' state.apply stuff,pkgs

    # Run the states configured in a more deeply nested directory such as salt://my/organized/stuff.sls (or salt://my/organized/stuff/init.sls)
    salt '*' state.apply my.organized.stuff

The following additional arguments are also accepted when applying
individual SLS files:

test
    Run states in test-only (dry-run) mode

mock
    The mock option allows for the state run to execute without actually
    calling any states. This then returns a mocked return which will show
    the requisite ordering as well as fully validate the state run.

    New in version 2015.8.4

pillar
    Custom Pillar values, passed as a dictionary of key-value pairs

        salt '*' state.apply stuff pillar='{"foo": "bar"}'

    Note:
        Values passed this way will override Pillar values set via
        ``pillar_roots`` or an external Pillar source.

queue : False
    Instead of failing immediately when another state run is in progress,
    a value of ``True`` will queue the new state run to begin running once
    the other has finished.

    This option starts a new thread for each queued state run, so use this
    option sparingly.

    Changed in version 3006.0
        This parameter can also be set via the ``state_queue`` configuration
        option. Additionally, it can now be set to an integer representing
        the maximum queue size which can be attained before the state runs
        will fail to be queued. This can prevent runaway conditions where
        new threads are started until system performance is hampered.

concurrent : False
    Execute state runs concurrently instead of serially

    Warning:

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

saltenv
    Specify a salt fileserver environment to be used when applying states

    Changed in version 0.17.0
        Argument name changed from ``env`` to ``saltenv``

    Changed in version 2014.7.0
        If no saltenv is specified, the minion config will be checked for an
        ``environment`` parameter and if found, it will be used. If none is
        found, ``base`` will be used. In prior releases, the minion config
        was not checked and ``base`` would always be assumed when the
        saltenv was not explicitly set.

pillarenv
    Specify a Pillar environment to be used when applying states. This
    can also be set in the minion config file using the
    :conf_minion:`pillarenv` option. When neither the
    :conf_minion:`pillarenv` minion config option nor this CLI argument is
    used, all Pillar environments will be merged together.

localconfig
    Optionally, instead of using the minion config, load minion opts from
    the file specified by this argument, and then merge them with the
    options from the minion config. This functionality allows for specific
    states to be run with their own custom minion configuration, including
    different pillars, file_roots, etc.

        salt '*' state.apply stuff localconfig=/path/to/minion.yml

sync_mods
    If specified, the desired custom module types will be synced prior to
    running the SLS files:

        salt '*' state.apply stuff sync_mods=states,modules
        salt '*' state.apply stuff sync_mods=all

    Note:
        This option is ignored when no SLS files are specified, as a
        :ref:`highstate <running-highstate>` automatically syncs all custom
        module types.

    New in version 2017.7.8,2018.3.3,2019.2.0

state_events
    The state_events option sends progress events as each function in
    a state run completes execution.

    New in version 3006.0

state.check_request:

New in version 2015.5.0

Return the state request information, if any

CLI Example:

    salt '*' state.check_request

state.clear_cache:

Clear out cached state files, forcing even cache runs to refresh the cache
on the next state execution.

Remember that the state cache is completely disabled by default, this
execution only applies if cache=True is used in states

CLI Example:

    salt '*' state.clear_cache

state.clear_request:

New in version 2015.5.0

Clear out the state execution request without executing it

CLI Example:

    salt '*' state.clear_request

state.disable:

Disable state runs.

CLI Example:

    salt '*' state.disable highstate

    salt '*' state.disable highstate,test.succeed_without_changes

Note:
    To disable a state file from running provide the same name that would
    be passed in a state.sls call.

    salt '*' state.disable bind.config

state.enable:

Enable state function or sls run

CLI Example:

    salt '*' state.enable highstate

    salt '*' state.enable test.succeed_without_changes

Note:
    To enable a state file from running provide the same name that would
    be passed in a state.sls call.

    salt '*' state.disable bind.config

state.event:

Watch Salt's event bus and block until the given tag is matched

New in version 2016.3.0
Changed in version 2019.2.0
    ``tagmatch`` can now be either a glob or regular expression.

This is useful for utilizing Salt's event bus from shell scripts or for
taking simple actions directly from the CLI.

Enable debug logging to see ignored events.

:param tagmatch: the event is written to stdout for each tag that matches
    this glob or regular expression.
:param count: this number is decremented for each event that matches the
    ``tagmatch`` parameter; pass ``-1`` to listen forever.
:param quiet: do not print to stdout; just block
:param sock_dir: path to the Salt master's event socket file.
:param pretty: Output the JSON all on a single line if ``False`` (useful
    for shell tools); pretty-print the JSON output if ``True``.
:param node: Watch the minion-side or master-side event bus.

CLI Example:

    salt-call --local state.event pretty=True

state.get_pauses:

Get a report on all of the currently paused state runs and pause
run settings.
Optionally send in a jid if you only desire to see a single pause
data set.

state.high:

Execute the compound calls stored in a single set of high data

This function is mostly intended for testing the state system and is not
likely to be needed in everyday usage.

CLI Example:

    salt '*' state.high '{"vim": {"pkg": ["installed"]}}'

state.highstate:

Retrieve the state data from the salt master for this minion and execute it

test
    Run states in test-only (dry-run) mode

pillar
    Custom Pillar values, passed as a dictionary of key-value pairs

        salt '*' state.highstate stuff pillar='{"foo": "bar"}'

    Note:
        Values passed this way will override Pillar values set via
        ``pillar_roots`` or an external Pillar source.

    Changed in version 2016.3.0
        GPG-encrypted CLI Pillar data is now supported via the GPG
        renderer. See :ref:`here <encrypted-cli-pillar-data>` for details.

pillar_enc
    Specify which renderer to use to decrypt encrypted data located within
    the ``pillar`` value. Currently, only ``gpg`` is supported.

    New in version 2016.3.0

exclude
    Exclude specific states from execution. Accepts a list of sls names, a
    comma-separated string of sls names, or a list of dictionaries
    containing ``sls`` or ``id`` keys. Glob-patterns may be used to match
    multiple states.

        salt '*' state.highstate exclude=bar,baz
        salt '*' state.highstate exclude=foo*
        salt '*' state.highstate exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"

saltenv
    Specify a salt fileserver environment to be used when applying states

    Changed in version 0.17.0
        Argument name changed from ``env`` to ``saltenv``.

    Changed in version 2014.7.0
        If no saltenv is specified, the minion config will be checked for a
        ``saltenv`` parameter and if found, it will be used. If none is
        found, ``base`` will be used. In prior releases, the minion config
        was not checked and ``base`` would always be assumed when the
        saltenv was not explicitly set.

pillarenv
    Specify a Pillar environment to be used when applying states. This
    can also be set in the minion config file using the
    :conf_minion:`pillarenv` option. When neither the
    :conf_minion:`pillarenv` minion config option nor this CLI argument is
    used, all Pillar environments will be merged together.

queue : False
    Instead of failing immediately when another state run is in progress,
    a value of ``True`` will queue the new state run to begin running once
    the other has finished.

    This option starts a new thread for each queued state run, so use this
    option sparingly.

    Changed in version 3006.0
        This parameter can also be set via the ``state_queue`` configuration
        option. Additionally, it can now be set to an integer representing
        the maximum queue size which can be attained before the state runs
        will fail to be queued. This can prevent runaway conditions where
        new threads are started until system performance is hampered.

concurrent : False
    Execute state runs concurrently instead of serially

    Warning:

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

localconfig
    Optionally, instead of using the minion config, load minion opts from
    the file specified by this argument, and then merge them with the
    options from the minion config. This functionality allows for specific
    states to be run with their own custom minion configuration, including
    different pillars, file_roots, etc.

mock
    The mock option allows for the state run to execute without actually
    calling any states. This then returns a mocked return which will show
    the requisite ordering as well as fully validate the state run.

    New in version 2015.8.4

state_events
    The state_events option sends progress events as each function in
    a state run completes execution.

    New in version 3006.0

CLI Examples:

    salt '*' state.highstate

    salt '*' state.highstate whitelist=sls1_to_run,sls2_to_run
    salt '*' state.highstate exclude=sls_to_exclude
    salt '*' state.highstate exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"

    salt '*' state.highstate pillar="{foo: 'Foo!', bar: 'Bar!'}"

state.id_exists:

Tests for the existence of a specific ID or list of IDs within the
specified SLS file(s). Similar to :py:func:`state.sls_exists
<salt.modules.state.sls_exists>`, returns True or False. The default
environment is base``, use ``saltenv`` to specify a different environment.

New in version 2019.2.0

saltenv
    Specify a salt fileserver environment from which to look for the SLS files
    specified in the ``mods`` argument

CLI Example:

    salt '*' state.id_exists create_myfile,update_template filestate saltenv=dev

state.list_disabled:

List the states which are currently disabled

CLI Example:

    salt '*' state.list_disabled

state.low:

Execute a single low data call

This function is mostly intended for testing the state system and is not
likely to be needed in everyday usage.

CLI Example:

    salt '*' state.low '{"state": "pkg", "fun": "installed", "name": "vi"}'

state.orchestrate:

New in version 2016.11.0

Execute the orchestrate runner from a masterless minion.

.. seealso:: More Orchestrate documentation

    * :ref:`Full Orchestrate Tutorial <orchestrate-runner>`
    * Docs for the salt state module :py:mod:`salt.states.saltmod`

CLI Examples:

    salt-call --local state.orchestrate webserver
    salt-call --local state.orchestrate webserver saltenv=dev test=True
    salt-call --local state.orchestrate webserver saltenv=dev pillarenv=aws

state.pause:

Set up a state id pause, this instructs a running state to pause at a given
state id. This needs to pass in the jid of the running state and can
optionally pass in a duration in seconds. If a state_id is not passed then
the jid referenced will be paused at the beginning of the next state run.

The given state id is the id got a given state execution, so given a state
that looks like this:

    vim:
      pkg.installed: []

The state_id to pass to `pause` is `vim`

CLI Examples:

    salt '*' state.pause 20171130110407769519
    salt '*' state.pause 20171130110407769519 vim
    salt '*' state.pause 20171130110407769519 vim 20

state.pkg:

Execute a packaged state run, the packaged state run will exist in a
tarball available locally. This packaged state
can be generated using salt-ssh.

CLI Example:

    salt '*' state.pkg /tmp/salt_state.tgz 760a9353810e36f6d81416366fc426dc md5

state.request:

New in version 2015.5.0

Request that the local admin execute a state run via
`salt-call state.run_request`.
All arguments match those of state.apply.

CLI Example:

    salt '*' state.request
    salt '*' state.request stuff
    salt '*' state.request stuff,pkgs

state.resume:

Remove a pause from a jid, allowing it to continue. If the state_id is
not specified then the a general pause will be resumed.

The given state_id is the id got a given state execution, so given a state
that looks like this:

    vim:
      pkg.installed: []

The state_id to pass to `rm_pause` is `vim`

CLI Examples:

    salt '*' state.resume 20171130110407769519
    salt '*' state.resume 20171130110407769519 vim

state.run_request:

New in version 2015.5.0

Execute the pending state request

CLI Example:

    salt '*' state.run_request

state.running:

Return a list of strings that contain state return data if a state function
is already running. This function is used to prevent multiple state calls
from being run at the same time.

CLI Example:

    salt '*' state.running

state.show_highstate:

Retrieve the highstate data from the salt master and display it

Custom Pillar data can be passed with the ``pillar`` kwarg.

CLI Example:

    salt '*' state.show_highstate

state.show_low_sls:

Display the low data from a specific sls. The default environment is
``base``, use ``saltenv`` to specify a different environment.

saltenv
    Specify a salt fileserver environment to be used when applying states

pillar
    Custom Pillar values, passed as a dictionary of key-value pairs

        salt '*' state.show_low_sls stuff pillar='{"foo": "bar"}'

    Note:
        Values passed this way will override Pillar values set via
        ``pillar_roots`` or an external Pillar source.

pillarenv
    Specify a Pillar environment to be used when applying states. This
    can also be set in the minion config file using the
    :conf_minion:`pillarenv` option. When neither the
    :conf_minion:`pillarenv` minion config option nor this CLI argument is
    used, all Pillar environments will be merged together.

CLI Example:

    salt '*' state.show_low_sls foo
    salt '*' state.show_low_sls foo saltenv=dev

state.show_lowstate:

List out the low data that will be applied to this minion

CLI Example:

    salt '*' state.show_lowstate

state.show_sls:

Display the state data from a specific sls or list of sls files on the
master. The default environment is ``base``, use ``saltenv`` to specify a
different environment.

This function does not support topfiles.  For ``top.sls`` please use
``show_top`` instead.

Custom Pillar data can be passed with the ``pillar`` kwarg.

saltenv
    Specify a salt fileserver environment to be used when applying states

pillarenv
    Specify a Pillar environment to be used when applying states. This
    can also be set in the minion config file using the
    :conf_minion:`pillarenv` option. When neither the
    :conf_minion:`pillarenv` minion config option nor this CLI argument is
    used, all Pillar environments will be merged together.

CLI Example:

    salt '*' state.show_sls core,edit.vim saltenv=dev

state.show_state_usage:

Retrieve the highstate data from the salt master to analyse used and unused states

Custom Pillar data can be passed with the ``pillar`` kwarg.

CLI Example:

    salt '*' state.show_state_usage

state.show_states:

Returns the list of states that will be applied on highstate.

CLI Example:

    salt '*' state.show_states

New in version 2019.2.0

state.show_top:

Return the top data that the minion will use for a highstate

CLI Example:

    salt '*' state.show_top

state.single:

Execute a single state function with the named kwargs, returns False if
insufficient data is sent to the command

By default, the values of the kwargs will be parsed as YAML. So, you can
specify lists values, or lists of single entry key-value maps, as you
would in a YAML salt file. Alternatively, JSON format of keyword values
is also supported.

CLI Example:

    salt '*' state.single pkg.installed name=vim

state.sls:

Execute the states in one or more SLS files

test
    Run states in test-only (dry-run) mode

pillar
    Custom Pillar values, passed as a dictionary of key-value pairs

        salt '*' state.sls stuff pillar='{"foo": "bar"}'

    Note:
        Values passed this way will override existing Pillar values set via
        ``pillar_roots`` or an external Pillar source.  Pillar values that
        are not included in the kwarg will not be overwritten.

    Changed in version 2016.3.0
        GPG-encrypted CLI Pillar data is now supported via the GPG
        renderer. See :ref:`here <encrypted-cli-pillar-data>` for details.

pillar_enc
    Specify which renderer to use to decrypt encrypted data located within
    the ``pillar`` value. Currently, only ``gpg`` is supported.

    New in version 2016.3.0

exclude
    Exclude specific states from execution. Accepts a list of sls names, a
    comma-separated string of sls names, or a list of dictionaries
    containing ``sls`` or ``id`` keys. Glob-patterns may be used to match
    multiple states.

        salt '*' state.sls foo,bar,baz exclude=bar,baz
        salt '*' state.sls foo,bar,baz exclude=ba*
        salt '*' state.sls foo,bar,baz exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"

queue : False
    Instead of failing immediately when another state run is in progress,
    a value of ``True`` will queue the new state run to begin running once
    the other has finished.

    This option starts a new thread for each queued state run, so use this
    option sparingly.

    Changed in version 3006.0
        This parameter can also be set via the ``state_queue`` configuration
        option. Additionally, it can now be set to an integer representing
        the maximum queue size which can be attained before the state runs
        will fail to be queued. This can prevent runaway conditions where
        new threads are started until system performance is hampered.

concurrent : False
    Execute state runs concurrently instead of serially

    Warning:

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

saltenv
    Specify a salt fileserver environment to be used when applying states

    Changed in version 0.17.0
        Argument name changed from ``env`` to ``saltenv``.

    Changed in version 2014.7.0
        If no saltenv is specified, the minion config will be checked for an
        ``environment`` parameter and if found, it will be used. If none is
        found, ``base`` will be used. In prior releases, the minion config
        was not checked and ``base`` would always be assumed when the
        saltenv was not explicitly set.

pillarenv
    Specify a Pillar environment to be used when applying states. This
    can also be set in the minion config file using the
    :conf_minion:`pillarenv` option. When neither the
    :conf_minion:`pillarenv` minion config option nor this CLI argument is
    used, all Pillar environments will be merged together.

localconfig
    Optionally, instead of using the minion config, load minion opts from
    the file specified by this argument, and then merge them with the
    options from the minion config. This functionality allows for specific
    states to be run with their own custom minion configuration, including
    different pillars, file_roots, etc.

mock
    The mock option allows for the state run to execute without actually
    calling any states. This then returns a mocked return which will show
    the requisite ordering as well as fully validate the state run.

    New in version 2015.8.4

sync_mods
    If specified, the desired custom module types will be synced prior to
    running the SLS files:

        salt '*' state.sls stuff sync_mods=states,modules
        salt '*' state.sls stuff sync_mods=all

    New in version 2017.7.8,2018.3.3,2019.2.0

state_events
    The state_events option sends progress events as each function in
    a state run completes execution.

    New in version 3006.0

CLI Example:

    # Run the states configured in salt://example.sls (or salt://example/init.sls)
    salt '*' state.apply example

    # Run the states configured in salt://core.sls (or salt://core/init.sls)
    # and salt://edit/vim.sls (or salt://edit/vim/init.sls)
    salt '*' state.sls core,edit.vim

    # Run the states configured in a more deeply nested directory such as salt://my/nested/state.sls (or salt://my/nested/state/init.sls)
    salt '*' state.sls my.nested.state

    salt '*' state.sls core exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"
    salt '*' state.sls myslsfile pillar="{foo: 'Foo!', bar: 'Bar!'}"

state.sls_exists:

Tests for the existence the of a specific SLS or list of SLS files on the
master. Similar to :py:func:`state.show_sls <salt.modules.state.show_sls>`,
rather than returning state details, returns True or False. The default
environment is ``base``, use ``saltenv`` to specify a different environment.

New in version 2019.2.0

saltenv
    Specify a salt fileserver environment from which to look for the SLS files
    specified in the ``mods`` argument

CLI Example:

    salt '*' state.sls_exists core,edit.vim saltenv=dev

state.sls_id:

Call a single ID from the named module(s) and handle all requisites

The state ID comes *before* the module ID(s) on the command line.

id
    ID to call

mods
    Comma-delimited list of modules to search for given id and its requisites

New in version 2014.7.0

saltenv : base
    Specify a salt fileserver environment to be used when applying states

pillarenv
    Specify a Pillar environment to be used when applying states. This
    can also be set in the minion config file using the
    :conf_minion:`pillarenv` option. When neither the
    :conf_minion:`pillarenv` minion config option nor this CLI argument is
    used, all Pillar environments will be merged together.

pillar
    Custom Pillar values, passed as a dictionary of key-value pairs

        salt '*' state.sls_id my_state my_module pillar='{"foo": "bar"}'

    Note:
        Values passed this way will override existing Pillar values set via
        ``pillar_roots`` or an external Pillar source.  Pillar values that
        are not included in the kwarg will not be overwritten.

    New in version 2018.3.0

CLI Example:

    salt '*' state.sls_id my_state my_module

    salt '*' state.sls_id my_state my_module,a_common_module

state.soft_kill:

Set up a state run to die before executing the given state id,
this instructs a running state to safely exit at a given
state id. This needs to pass in the jid of the running state.
If a state_id is not passed then the jid referenced will be safely exited
at the beginning of the next state run.

The given state id is the id got a given state execution, so given a state
that looks like this:

    vim:
      pkg.installed: []

The state_id to pass to `soft_kill` is `vim`

CLI Examples:

    salt '*' state.soft_kill 20171130110407769519
    salt '*' state.soft_kill 20171130110407769519 vim

state.template:

Execute the information stored in a template file on the minion.

This function does not ask a master for a SLS file to render but
instead directly processes the file at the provided path on the minion.

CLI Example:

    salt '*' state.template '<Path to template on the minion>'

state.template_str:

Execute the information stored in a string from an sls template

CLI Example:

    salt '*' state.template_str '<Template String>'

state.test:

New in version 3001

Alias for `state.apply` with the kwarg `test` forced to `True`.

This is a nicety to avoid the need to type out `test=True` and the possibility of
a typo causing changes you do not intend.

state.top:

Execute a specific top file instead of the default. This is useful to apply
configurations from a different environment (for example, dev or prod), without
modifying the default top file.

queue : False
    Instead of failing immediately when another state run is in progress,
    a value of ``True`` will queue the new state run to begin running once
    the other has finished.

    This option starts a new thread for each queued state run, so use this
    option sparingly.

    Changed in version 3006.0
        This parameter can also be set via the ``state_queue`` configuration
        option. Additionally, it can now be set to an integer representing
        the maximum queue size which can be attained before the state runs
        will fail to be queued. This can prevent runaway conditions where
        new threads are started until system performance is hampered.

saltenv
    Specify a salt fileserver environment to be used when applying states

pillarenv
    Specify a Pillar environment to be used when applying states. This
    can also be set in the minion config file using the
    :conf_minion:`pillarenv` option. When neither the
    :conf_minion:`pillarenv` minion config option nor this CLI argument is
    used, all Pillar environments will be merged together.

    New in version 2017.7.0

CLI Example:

    salt '*' state.top reverse_top.sls
    salt '*' state.top prod_top.sls exclude=sls_to_exclude
    salt '*' state.top dev_top.sls exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"

status.all_status:

Return a composite of all status data and info for this minion.
Warning: There is a LOT here!

CLI Example:

    salt '*' status.all_status

status.cpuinfo:

Changed in version 2016.3.2
    Return the CPU info for this minion

Changed in version 2016.11.4
    Added support for AIX

Changed in version 2018.3.0
    Added support for NetBSD and OpenBSD

CLI Example:

    salt '*' status.cpuinfo

status.cpustats:

Return the CPU stats for this minion

Changed in version 2016.11.4
    Added support for AIX

Changed in version 2018.3.0
    Added support for OpenBSD

CLI Example:

    salt '*' status.cpustats

status.custom:

Return a custom composite of status data and info for this minion,
based on the minion config file. An example config like might be::

    status.cpustats.custom: [ 'cpu', 'ctxt', 'btime', 'processes' ]

Where status refers to status.py, cpustats is the function
where we get our data, and custom is this function It is followed
by a list of keys that we want returned.

This function is meant to replace all_status(), which returns
anything and everything, which we probably don't want.

By default, nothing is returned. Warning: Depending on what you
include, there can be a LOT here!

CLI Example:

    salt '*' status.custom

status.diskstats:

Changed in version 2016.3.2
    Return the disk stats for this minion

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' status.diskstats

status.diskusage:

Return the disk usage for this minion

Usage::

    salt '*' status.diskusage [paths and/or filesystem types]

CLI Example:

    salt '*' status.diskusage         # usage for all filesystems
    salt '*' status.diskusage / /tmp  # usage for / and /tmp
    salt '*' status.diskusage ext?    # usage for ext[234] filesystems
    salt '*' status.diskusage / ext?  # usage for / and all ext filesystems

status.loadavg:

Return the load averages for this minion

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' status.loadavg

    :raises CommandExecutionError: If the system cannot report loadaverages to Python

status.master:

New in version 2014.7.0

Return the connection status with master. Fire an event if the
connection to master is not as expected. This function is meant to be
run via a scheduled job from the minion. If master_ip is an FQDN/Hostname,
it must be resolvable to a valid IPv4 address.

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' status.master

status.meminfo:

Return the memory info for this minion

Changed in version 2016.11.4
    Added support for AIX

Changed in version 2018.3.0
    Added support for OpenBSD

CLI Example:

    salt '*' status.meminfo

status.netdev:

Changed in version 2016.3.2
    Return the network device stats for this minion

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' status.netdev

status.netstats:

Return the network stats for this minion

Changed in version 2016.11.4
    Added support for AIX

Changed in version 2018.3.0
    Added support for OpenBSD

CLI Example:

    salt '*' status.netstats

status.nproc:

Return the number of processing units available on this system

Changed in version 2016.11.4
    Added support for AIX

Changed in version 2018.3.0
    Added support for Darwin, FreeBSD and OpenBSD

CLI Example:

    salt '*' status.nproc

status.pid:

Return the PID or an empty string if the process is running or not.
Pass a signature to use to find the process via ps.  Note you can pass
a Python-compatible regular expression to return all pids of
processes matching the regexp.

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' status.pid <sig>

status.ping_master:

New in version 2016.3.0

Sends ping request to the given master. Fires '__master_failback' event on success.
Returns bool result.

CLI Example:

    salt '*' status.ping_master localhost

status.procs:

Return the process data

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' status.procs

status.proxy_reconnect:

Forces proxy minion reconnection when not alive.

proxy_name
    The virtual name of the proxy module.

opts: None
    Opts dictionary. Not intended for CLI usage.

CLI Example:

    salt '*' status.proxy_reconnect rest_sample

status.time:

New in version 2016.3.0

Return the current time on the minion,
formatted based on the format parameter.

Default date format: Monday, 27. July 2015 07:55AM

CLI Example:

    salt '*' status.time

    salt '*' status.time '%s'

status.uptime:

Return the uptime for this system.

Changed in version 2015.8.9
    The uptime function was changed to return a dictionary of easy-to-read
    key/value pairs containing uptime information, instead of the output
    from a ``cmd.run`` call.

Changed in version 2016.11.0
    Support for OpenBSD, FreeBSD, NetBSD, MacOS, and Solaris

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' status.uptime

status.version:

Return the system version for this minion

Changed in version 2016.11.4
    Added support for AIX

Changed in version 2018.3.0
    Added support for OpenBSD

CLI Example:

    salt '*' status.version

status.vmstats:

Changed in version 2016.3.2
    Return the virtual memory stats for this minion

Changed in version 2016.11.4
    Added support for AIX

CLI Example:

    salt '*' status.vmstats

status.w:

Return a list of logged in users for this minion, using the w command

CLI Example:

    salt '*' status.w

statuspage.create:

Insert a new entry under a specific endpoint.

endpoint: incidents
    Insert under this specific endpoint.

page_id
    Page ID. Can also be specified in the config file.

api_key
    API key. Can also be specified in the config file.

api_version: 1
    API version. Can also be specified in the config file.

api_url
    Custom API URL in case the user has a StatusPage service running in a custom environment.

CLI Example:

    salt 'minion' statuspage.create endpoint='components' name='my component' group_id='993vgplshj12'

Example output:

    minion:
        ----------
        comment:
        out:
            ----------
            created_at:
                2017-01-05T19:35:27.135Z
            description:
                None
            group_id:
                993vgplshj12
            id:
                mjkmtt5lhdgc
            name:
                my component
            page_id:
                ksdhgfyiuhaa
            position:
                7
            status:
                operational
            updated_at:
                2017-01-05T19:35:27.135Z
        result:
            True

statuspage.delete:

Remove an entry from an endpoint.

endpoint: incidents
    Request a specific endpoint.

page_id
    Page ID. Can also be specified in the config file.

api_key
    API key. Can also be specified in the config file.

api_version: 1
    API version. Can also be specified in the config file.

api_url
    Custom API URL in case the user has a StatusPage service running in a custom environment.

CLI Example:

    salt 'minion' statuspage.delete endpoint='components' id='ftgks51sfs2d'

Example output:

    minion:
        ----------
        comment:
        out:
            None
        result:
            True

statuspage.retrieve:

Retrieve a specific endpoint from the Statuspage API.

endpoint: incidents
    Request a specific endpoint.

page_id
    Page ID. Can also be specified in the config file.

api_key
    API key. Can also be specified in the config file.

api_version: 1
    API version. Can also be specified in the config file.

api_url
    Custom API URL in case the user has a StatusPage service running in a custom environment.

CLI Example:

    salt 'minion' statuspage.retrieve components

Example output:

    minion:
        ----------
        comment:
        out:
            |_
              ----------
              backfilled:
                  False
              created_at:
                  2015-01-26T20:25:02.702Z
              id:
                  kh2qwjbheqdc36
              impact:
                  major
              impact_override:
                  None
              incident_updates:
                  |_
                    ----------
                    affected_components:
                        None
                    body:
                        We are currently investigating this issue.
                    created_at:
                        2015-01-26T20:25:02.849Z
                    display_at:
                        2015-01-26T20:25:02.849Z
                    id:
                        zvx7xz2z5skr
                    incident_id:
                        kh2qwjbheqdc36
                    status:
                        investigating
                    twitter_updated_at:
                        None
                    updated_at:
                        2015-01-26T20:25:02.849Z
                    wants_twitter_update:
                        False
              monitoring_at:
                  None
              name:
                  just testing some stuff
              page_id:
                  ksdhgfyiuhaa
              postmortem_body:
                  None
              postmortem_body_last_updated_at:
                  None
              postmortem_ignored:
                  False
              postmortem_notified_subscribers:
                  False
              postmortem_notified_twitter:
                  False
              postmortem_published_at:
                  None
              resolved_at:
                  None
              scheduled_auto_completed:
                  False
              scheduled_auto_in_progress:
                  False
              scheduled_for:
                  None
              scheduled_remind_prior:
                  False
              scheduled_reminded_at:
                  None
              scheduled_until:
                  None
              shortlink:
                  http://stspg.io/voY
              status:
                  investigating
              updated_at:
                  2015-01-26T20:25:13.379Z
        result:
            True

statuspage.update:

Update attribute(s) of a specific endpoint.

id
    The unique ID of the endpoint entry.

endpoint: incidents
    Endpoint name.

page_id
    Page ID. Can also be specified in the config file.

api_key
    API key. Can also be specified in the config file.

api_version: 1
    API version. Can also be specified in the config file.

api_url
    Custom API URL in case the user has a StatusPage service running in a custom environment.

CLI Example:

    salt 'minion' statuspage.update id=dz959yz2nd4l status=resolved

Example output:

    minion:
        ----------
        comment:
        out:
            ----------
            created_at:
                2017-01-03T15:25:30.718Z
            description:
                None
            group_id:
                993vgplshj12
            id:
                dz959yz2nd4l
            name:
                Management Portal
            page_id:
                xzwjjdw87vpf
            position:
                11
            status:
                resolved
            updated_at:
                2017-01-05T15:34:27.676Z
        result:
            True

supervisord.add:

Activates any updates in config for process/group.

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.add <name>

supervisord.custom:

Run any custom supervisord command

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.custom "mstop '*gunicorn*'"

supervisord.options:

New in version 2014.1.0

Read the config file and return the config options for a given process

name
    Name of the configured process
conf_file
    path to supervisord config file

CLI Example:

    salt '*' supervisord.options foo

supervisord.remove:

Removes process/group from active config

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.remove <name>

supervisord.reread:

Reload the daemon's configuration files

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.reread

supervisord.restart:

Restart the named service.
Process group names should not include a trailing asterisk.

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.restart <service>
    salt '*' supervisord.restart <group>:

supervisord.start:

Start the named service.
Process group names should not include a trailing asterisk.

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.start <service>
    salt '*' supervisord.start <group>:

supervisord.status:

List programs and its state

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.status

supervisord.status_bool:

Check for status of a specific supervisord process and return boolean result.

name
    name of the process to check

expected_state
    search for a specific process state. If set to ``None`` - any process state will match.

user
    user to run supervisorctl as

conf_file
    path to supervisord config file

bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.status_bool nginx expected_state='RUNNING'

supervisord.status_raw:

Display the raw output of status

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.status_raw

supervisord.stop:

Stop the named service.
Process group names should not include a trailing asterisk.

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed

CLI Example:

    salt '*' supervisord.stop <service>
    salt '*' supervisord.stop <group>:

supervisord.update:

Reload config and add/remove/update as necessary

user
    user to run supervisorctl as
conf_file
    path to supervisord config file
bin_env
    path to supervisorctl bin or path to virtualenv with supervisor
    installed
name
    name of the process group to update. if none then update any
    process group that has changes

CLI Example:

    salt '*' supervisord.update

sys.argspec:

Return the argument specification of functions in Salt execution
modules.

CLI Example:

    salt '*' sys.argspec pkg.install
    salt '*' sys.argspec sys
    salt '*' sys.argspec

Module names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.argspec 'pkg.*'

sys.doc:

Return the docstrings for all modules. Optionally, specify a module or a
function to narrow the selection.

The strings are aggregated into a single document on the master for easy
reading.

Multiple modules/functions can be specified.

CLI Example:

    salt '*' sys.doc
    salt '*' sys.doc sys
    salt '*' sys.doc sys.doc
    salt '*' sys.doc network.traceroute user.info

Modules can be specified as globs.

New in version 2015.5.0

    salt '*' sys.doc 'sys.*'
    salt '*' sys.doc 'sys.list_*'

sys.list_functions:

List the functions for all modules. Optionally, specify a module or modules
from which to list.

CLI Example:

    salt '*' sys.list_functions
    salt '*' sys.list_functions sys
    salt '*' sys.list_functions sys user

New in version 0.12.0

    salt '*' sys.list_functions 'module.specific_function'

Function names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.list_functions 'sys.list_*'

sys.list_modules:

List the modules loaded on the minion

New in version 2015.5.0

CLI Example:

    salt '*' sys.list_modules

Module names can be specified as globs.

    salt '*' sys.list_modules 's*'

sys.list_renderers:

List the renderers loaded on the minion

New in version 2015.5.0

CLI Example:

    salt '*' sys.list_renderers

Render names can be specified as globs.

    salt '*' sys.list_renderers 'yaml*'

sys.list_returner_functions:

List the functions for all returner modules. Optionally, specify a returner
module or modules from which to list.

New in version 2014.7.0

CLI Example:

    salt '*' sys.list_returner_functions
    salt '*' sys.list_returner_functions mysql
    salt '*' sys.list_returner_functions mysql etcd

Returner names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.list_returner_functions 'sqlite3.get_*'

sys.list_returners:

List the returners loaded on the minion

New in version 2014.7.0

CLI Example:

    salt '*' sys.list_returners

Returner names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.list_returners 's*'

sys.list_runner_functions:

List the functions for all runner modules. Optionally, specify a runner
module or modules from which to list.

New in version 2014.7.0

CLI Example:

    salt '*' sys.list_runner_functions
    salt '*' sys.list_runner_functions state
    salt '*' sys.list_runner_functions state virt

Runner function names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.list_runner_functions 'state.*' 'virt.*'

sys.list_runners:

List the runners loaded on the minion

New in version 2014.7.0

CLI Example:

    salt '*' sys.list_runners

Runner names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.list_runners 'm*'

sys.list_state_functions:

List the functions for all state modules. Optionally, specify a state
module or modules from which to list.

New in version 2014.7.0

CLI Example:

    salt '*' sys.list_state_functions
    salt '*' sys.list_state_functions file
    salt '*' sys.list_state_functions pkg user

State function names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.list_state_functions 'file.*'
    salt '*' sys.list_state_functions 'file.s*'

New in version 2016.9.0

    salt '*' sys.list_state_functions 'module.specific_function'

sys.list_state_modules:

List the modules loaded on the minion

New in version 2014.7.0

CLI Example:

    salt '*' sys.list_state_modules

State module names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.list_state_modules 'mysql_*'

sys.reload_modules:

    Tell the minion to reload the execution modules

    CLI Example:

        salt '*' sys.reload_modules

sys.renderer_doc:

Return the docstrings for all renderers. Optionally, specify a renderer or a
function to narrow the selection.

The strings are aggregated into a single document on the master for easy
reading.

Multiple renderers can be specified.

New in version 2015.5.0

CLI Example:

    salt '*' sys.renderer_doc
    salt '*' sys.renderer_doc cheetah
    salt '*' sys.renderer_doc jinja json

Renderer names can be specified as globs.

    salt '*' sys.renderer_doc 'c*' 'j*'

sys.returner_argspec:

Return the argument specification of functions in Salt returner
modules.

New in version 2015.5.0

CLI Example:

    salt '*' sys.returner_argspec xmpp
    salt '*' sys.returner_argspec xmpp smtp
    salt '*' sys.returner_argspec

Returner names can be specified as globs.

    salt '*' sys.returner_argspec 'sqlite3.*'

sys.returner_doc:

Return the docstrings for all returners. Optionally, specify a returner or a
function to narrow the selection.

The strings are aggregated into a single document on the master for easy
reading.

Multiple returners/functions can be specified.

New in version 2014.7.0

CLI Example:

    salt '*' sys.returner_doc
    salt '*' sys.returner_doc sqlite3
    salt '*' sys.returner_doc sqlite3.get_fun
    salt '*' sys.returner_doc sqlite3.get_fun etcd.get_fun

Returner names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.returner_doc 'sqlite3.get_*'

sys.runner_argspec:

Return the argument specification of functions in Salt runner
modules.

New in version 2015.5.0

CLI Example:

    salt '*' sys.runner_argspec state
    salt '*' sys.runner_argspec http
    salt '*' sys.runner_argspec

Runner names can be specified as globs.

    salt '*' sys.runner_argspec 'winrepo.*'

sys.runner_doc:

Return the docstrings for all runners. Optionally, specify a runner or a
function to narrow the selection.

The strings are aggregated into a single document on the master for easy
reading.

Multiple runners/functions can be specified.

New in version 2014.7.0

CLI Example:

    salt '*' sys.runner_doc
    salt '*' sys.runner_doc cache
    salt '*' sys.runner_doc cache.grains
    salt '*' sys.runner_doc cache.grains mine.get

Runner names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.runner_doc 'cache.clear_*'

sys.state_argspec:

Return the argument specification of functions in Salt state
modules.

New in version 2015.5.0

CLI Example:

    salt '*' sys.state_argspec pkg.installed
    salt '*' sys.state_argspec file
    salt '*' sys.state_argspec

State names can be specified as globs.

    salt '*' sys.state_argspec 'pkg.*'

sys.state_doc:

Return the docstrings for all states. Optionally, specify a state or a
function to narrow the selection.

The strings are aggregated into a single document on the master for easy
reading.

Multiple states/functions can be specified.

New in version 2014.7.0

CLI Example:

    salt '*' sys.state_doc
    salt '*' sys.state_doc service
    salt '*' sys.state_doc service.running
    salt '*' sys.state_doc service.running ipables.append

State names can be specified as globs.

New in version 2015.5.0

    salt '*' sys.state_doc 'service.*' 'iptables.*'

sys.state_schema:

Return a JSON Schema for the given state function(s)

New in version 2016.3.0

CLI Example:

    salt '*' sys.state_schema
    salt '*' sys.state_schema pkg.installed

sysctl.assign:

Assign a single sysctl parameter for this minion

CLI Example:

    salt '*' sysctl.assign net.ipv4.ip_forward 1

sysctl.default_config:

Linux hosts using systemd 207 or later ignore ``/etc/sysctl.conf`` and only
load from ``/etc/sysctl.d/*.conf``. This function will do the proper checks
and return a default config file which will be valid for the Minion. Hosts
running systemd >= 207 will use ``/etc/sysctl.d/99-salt.conf``.

CLI Example:

    salt -G 'kernel:Linux' sysctl.default_config

sysctl.get:

Return a single sysctl parameter for this minion

CLI Example:

    salt '*' sysctl.get net.ipv4.ip_forward

sysctl.persist:

Assign and persist a simple sysctl parameter for this minion. If ``config``
is not specified, a sensible default will be chosen using
:mod:`sysctl.default_config <salt.modules.linux_sysctl.default_config>`.

CLI Example:

    salt '*' sysctl.persist net.ipv4.ip_forward 1

sysctl.show:

Return a list of sysctl parameters for this minion

config: Pull the data from the system configuration file
    instead of the live data.

CLI Example:

    salt '*' sysctl.show

sysfs.attr:

Access/write a SysFS attribute.
If the attribute is a symlink, its destination is returned

:return: value or bool

CLI Example:

    salt '*' sysfs.attr block/sda/queue/logical_block_size

sysfs.interfaces:

Generate a dictionary with all available interfaces relative to root.
Symlinks are not followed.

CLI Example:

    salt '*' sysfs.interfaces block/bcache0/bcache

Output example:
   {
      "r": [
        "state",
        "partial_stripes_expensive",
        "writeback_rate_debug",
        "stripe_size",
        "dirty_data",
        "stats_total/cache_hits",
        "stats_total/cache_bypass_misses",
        "stats_total/bypassed",
        "stats_total/cache_readaheads",
        "stats_total/cache_hit_ratio",
        "stats_total/cache_miss_collisions",
        "stats_total/cache_misses",
        "stats_total/cache_bypass_hits",
      ],
      "rw": [
        "writeback_rate",
        "writeback_rate_update_seconds",
        "cache_mode",
        "writeback_delay",
        "label",
        "writeback_running",
        "writeback_metadata",
        "running",
        "writeback_rate_p_term_inverse",
        "sequential_cutoff",
        "writeback_percent",
        "writeback_rate_d_term",
        "readahead"
      ],
      "w": [
        "stop",
        "clear_stats",
        "attach",
        "detach"
      ]
   }

Note:
  * 'r' interfaces are read-only
  * 'w' interfaces are write-only (e.g. actions)
  * 'rw' are interfaces that can both be read or written

sysfs.read:

Read from SysFS

:param key: file or path in SysFS; if key is a list then root will be prefixed on each key

:return: the full (tree of) SysFS attributes under key

CLI Example:

    salt '*' sysfs.read class/net/em1/statistics

sysfs.target:

Return the basename of a SysFS key path

:param key: the location to resolve within SysFS
:param full: full path instead of basename

:return: fullpath or basename of path

CLI Example:

    salt '*' sysfs.read class/ttyS0

sysfs.write:

Write a SysFS attribute/action

CLI Example:

    salt '*' sysfs.write devices/system/cpu/cpu0/cpufreq/scaling_governor 'performance'

syslog_ng.config:

Builds syslog-ng configuration. This function is intended to be used from
the state module, users should not use it directly!

name : the id of the Salt document or it is the format of <statement name>.id
config : the parsed YAML code
write : if True, it writes  the config into the configuration file,
otherwise just returns it

CLI Example:

    salt '*' syslog_ng.config name='s_local' config="[{'tcp':[{'ip':'127.0.0.1'},{'port':1233}]}]"

syslog_ng.config_test:

Runs syntax check against cfgfile. If syslog_ng_sbin_dir is specified, it
is added to the PATH during the test.

CLI Example:

    salt '*' syslog_ng.config_test
    salt '*' syslog_ng.config_test /home/user/install/syslog-ng/sbin
    salt '*' syslog_ng.config_test /home/user/install/syslog-ng/sbin /etc/syslog-ng/syslog-ng.conf

syslog_ng.get_config_file:

Returns the configuration directory, which contains syslog-ng.conf.

CLI Example:

    salt '*' syslog_ng.get_config_file

syslog_ng.modules:

Returns the available modules. If syslog_ng_sbin_dir is specified, it
is added to the PATH during the execution of the command syslog-ng.

CLI Example:

    salt '*' syslog_ng.modules
    salt '*' syslog_ng.modules /home/user/install/syslog-ng/sbin

syslog_ng.reload:

Reloads syslog-ng. This function is intended to be used from states.

If :mod:`syslog_ng.set_config_file
<salt.modules.syslog_ng.set_binary_path>`, is called before, this function
will use the set binary path.

CLI Example:

    salt '*' syslog_ng.reload

syslog_ng.set_binary_path:

Sets the path, where the syslog-ng binary can be found. This function is
intended to be used from states.

If syslog-ng is installed via a package manager, users don't need to use
this function.

CLI Example:

    salt '*' syslog_ng.set_binary_path name=/usr/sbin

syslog_ng.set_config_file:

Sets the configuration's name. This function is intended to be used from
states.

CLI Example:

    salt '*' syslog_ng.set_config_file name=/etc/syslog-ng

syslog_ng.set_parameters:

Sets variables.

CLI Example:

    salt '*' syslog_ng.set_parameters version='3.6'
    salt '*' syslog_ng.set_parameters  binary_path=/home/user/install/syslog-ng/sbin config_file=/home/user/install/syslog-ng/etc/syslog-ng.conf

syslog_ng.start:

Ensures, that syslog-ng is started via the given parameters. This function
is intended to be used from the state module.

Users shouldn't use this function, if the service module is available on
their system. If :mod:`syslog_ng.set_config_file
<salt.modules.syslog_ng.set_binary_path>`, is called before, this function
will use the set binary path.

CLI Example:

    salt '*' syslog_ng.start

syslog_ng.stats:

Returns statistics from the running syslog-ng instance. If
syslog_ng_sbin_dir is specified, it is added to the PATH during the
execution of the command syslog-ng-ctl.

CLI Example:

    salt '*' syslog_ng.stats
    salt '*' syslog_ng.stats /home/user/install/syslog-ng/sbin

syslog_ng.stop:

Kills syslog-ng. This function is intended to be used from the state module.

Users shouldn't use this function, if the service module is available on
their system.  If :mod:`syslog_ng.set_config_file
<salt.modules.syslog_ng.set_binary_path>` is called before, this function
will use the set binary path.

CLI Example:

    salt '*' syslog_ng.stop

syslog_ng.version:

Returns the version of the installed syslog-ng. If syslog_ng_sbin_dir is
specified, it is added to the PATH during the execution of the command
syslog-ng.

CLI Example:

    salt '*' syslog_ng.version
    salt '*' syslog_ng.version /home/user/install/syslog-ng/sbin

syslog_ng.write_config:

Writes the given parameter config into the config file. This function is
intended to be used from states.

If :mod:`syslog_ng.set_config_file
<salt.modules.syslog_ng.set_config_file>`, is called before, this function
will use the set config file.

CLI Example:

    salt '*' syslog_ng.write_config config='# comment'

syslog_ng.write_version:

Removes the previous configuration file, then creates a new one and writes
the name line. This function is intended to be used from states.

If :mod:`syslog_ng.set_config_file
<salt.modules.syslog_ng.set_config_file>`, is called before, this function
will use the set config file.

CLI Example:

    salt '*' syslog_ng.write_version name="3.6"

system.get_computer_desc:

Get ``PRETTY_HOSTNAME`` value stored in ``/etc/machine-info``
If this file doesn't exist or the variable doesn't exist
return ``False``.

:return: Value of ``PRETTY_HOSTNAME`` in ``/etc/machine-info``.
    If file/variable does not exist ``False``.
:rtype: str

CLI Example:

    salt '*' system.get_computer_desc

system.get_computer_name:

Get hostname.

CLI Example:

    salt '*' network.get_hostname

system.get_reboot_required_witnessed:

Note:

    This only applies to Minions running on NI Linux RT

Determine if at any time during the current boot session the salt minion
witnessed an event indicating that a reboot is required.

Returns:
    bool: ``True`` if the a reboot request was witnessed, ``False`` otherwise

CLI Example:

    salt '*' system.get_reboot_required_witnessed

system.get_system_date:

Get the system date

:param str utc_offset: The UTC offset in 4 digit (``+0600``) format with an
    optional sign (``+``/``-``).  Will default to ``None`` which will use the local
    timezone. To set the time based off of UTC use ``+0000``. Note: If
    being passed through the command line will need to be quoted twice to
    allow negative offsets (e.g. ``"'+0000'"``).
:return: Returns the system date.
:rtype: str

CLI Example:

    salt '*' system.get_system_date

system.get_system_date_time:

Get the system date/time.

:param str utc_offset: The UTC offset in 4 digit (``+0600``) format with an
    optional sign (``+``/``-``).  Will default to ``None`` which will use the local
    timezone. To set the time based off of UTC use ``+0000``. Note: If
    being passed through the command line will need to be quoted twice to
    allow negative offsets (e.g. ``"'+0000'"``).
:return: Returns the system time in ``YYYY-MM-DD hh:mm:ss`` format.
:rtype: str

CLI Example:

    salt '*' system.get_system_date_time "'-0500'"

system.get_system_time:

Get the system time.

:param str utc_offset: The UTC offset in 4 digit (e.g. ``+0600``) format with an
    optional sign (``+``/``-``).  Will default to ``None`` which will use the local
    timezone. To set the time based off of UTC use ``+0000``. Note: If
    being passed through the command line will need to be quoted twice to
    allow negative offsets (e.g. ``"'+0000'"``).
:return: Returns the system time in ``HH:MM:SS AM/PM`` format.
:rtype: str

CLI Example:

    salt '*' system.get_system_time

system.halt:

Halt a running system

CLI Example:

    salt '*' system.halt

system.has_settable_hwclock:

Returns ``True`` if the system has a hardware clock capable of being
set from software.

CLI Example:

    salt '*' system.has_settable_hwclock

system.init:

Change the system runlevel on sysV compatible systems

CLI Example:

    salt '*' system.init 3

system.poweroff:

Poweroff a running system

CLI Example:

    salt '*' system.poweroff

system.reboot:

Reboot the system

at_time
    The wait time in minutes before the system will be rebooted.

CLI Example:

    salt '*' system.reboot

system.set_computer_desc:

Set ``PRETTY_HOSTNAME`` value stored in ``/etc/machine-info``
This will create the file if it does not exist. If
it is unable to create or modify this file, ``False`` is returned.

:param str desc: The computer description
:return: ``False`` on failure. ``True`` if successful.

CLI Example:

    salt '*' system.set_computer_desc "Michael's laptop"

system.set_computer_name:

Modify hostname.

CLI Example:

    salt '*' system.set_computer_name master.saltstack.com

system.set_reboot_required_witnessed:

Note:

    This only applies to Minions running on NI Linux RT

This function is used to remember that an event indicating that a reboot is
required was witnessed. This function writes to a temporary filesystem so
the event gets cleared upon reboot.

Returns:
    bool: ``True`` if successful, otherwise ``False``

CLI Example:

    salt '*' system.set_reboot_required_witnessed

system.set_system_date:

Set the system date. Use ``<mm-dd-yy>`` format for the date.

:param str newdate:
    The date to set. Can be any of the following formats:

    - ``YYYY-MM-DD``
    - ``MM-DD-YYYY``
    - ``MM-DD-YY``
    - ``MM/DD/YYYY``
    - ``MM/DD/YY``
    - ``YYYY/MM/DD``

CLI Example:

    salt '*' system.set_system_date '03-28-13'

system.set_system_date_time:

Set the system date and time. Each argument is an element of the date, but
not required. If an element is not passed, the current system value for
that element will be used. For example, if the year is not passed, the
current system year will be used. (Used by
:mod:`system.set_system_date <salt.modules.system.set_system_date>` and
:mod:`system.set_system_time <salt.modules.system.set_system_time>`)

Updates hardware clock, if present, in addition to software
(kernel) clock.

:param int years: Years digit, e.g.: ``2015``
:param int months: Months digit: ``1``-``12``
:param int days: Days digit: ``1``-``31``
:param int hours: Hours digit: ``0``-``23``
:param int minutes: Minutes digit: ``0``-``59``
:param int seconds: Seconds digit: ``0``-``59``
:param str utc_offset: The UTC offset in 4 digit (``+0600``) format with an
    optional sign (``+``/``-``).  Will default to ``None`` which will use the local
    timezone. To set the time based off of UTC use ``+0000``. Note: If
    being passed through the command line will need to be quoted twice to
    allow negative offsets (e.g. ``"'+0000'"``).
:return: ``True`` if successful. Otherwise ``False``.
:rtype: bool

CLI Example:

    salt '*' system.set_system_date_time 2015 5 12 11 37 53 "'-0500'"

system.set_system_time:

Set the system time.

:param str newtime:
    The time to set. Can be any of the following formats.

    - ``HH:MM:SS AM/PM``
    - ``HH:MM AM/PM``
    - ``HH:MM:SS`` (24 hour)
    - ``HH:MM`` (24 hour)

    Note that the Salt command line parser parses the date/time
    before we obtain the argument (preventing us from doing UTC)
    Therefore the argument must be passed in as a string.
    Meaning the text might have to be quoted twice on the command line.

:param str utc_offset: The UTC offset in 4 digit (``+0600``) format with an
    optional sign (``+``/``-``).  Will default to ``None`` which will use the local
    timezone. To set the time based off of UTC use ``+0000``. Note: If
    being passed through the command line will need to be quoted twice to
    allow negative offsets (e.g. ``"'+0000'"``)
:return: Returns ``True`` if successful. Otherwise ``False``.
:rtype: bool

CLI Example:

    salt '*' system.set_system_time "'11:20'"

system.shutdown:

Shutdown a running system

at_time
    The wait time in minutes before the system will be shutdown.

CLI Example:

    salt '*' system.shutdown 5

telegram.post_message:

Send a message to a Telegram chat.

:param message: The message to send to the Telegram chat.
:param chat_id: (optional) The Telegram chat id.
:param token:   (optional) The Telegram API token.
:return:        Boolean if message was sent successfully.

CLI Example:

    salt '*' telegram.post_message message="Hello Telegram!"

telemetry.create_alarm:

create an telemetry alarms.

data is a dict of alert configuration data.

Returns (bool success, str message) tuple.

CLI Example:

    salt myminion telemetry.create_alarm rs-ds033197 {} profile=telemetry

telemetry.delete_alarms: delete an alert specified by alert_id or if not specified blows away all the alerts in the current deployment.

Returns (bool success, str message) tuple.

CLI Example:

    salt myminion telemetry.delete_alarms rs-ds033197 profile=telemetry

telemetry.get_alarms:

get all the alarms set up against the current deployment

Returns dictionary of alarm information

CLI Example:

    salt myminion telemetry.get_alarms rs-ds033197 profile=telemetry

telemetry.get_alert_config:

Get all alert definitions associated with a given deployment or if metric_name
is specified, obtain the specific alert config

Returns dictionary or list of dictionaries.

CLI Example:

    salt myminion telemetry.get_alert_config rs-ds033197 currentConnections profile=telemetry
    salt myminion telemetry.get_alert_config rs-ds033197 profile=telemetry

telemetry.get_notification_channel_id:

Given an email address, creates a notification-channels
if one is not found and also returns the corresponding
notification channel id.

notify_channel
    Email escalation policy
profile
    A dict of telemetry config information.

CLI Example:

    salt myminion telemetry.get_notification_channel_id userx@company.com profile=telemetry

telemetry.update_alarm:

update an telemetry alarms. data is a dict of alert configuration data.

Returns (bool success, str message) tuple.

CLI Example:

    salt myminion telemetry.update_alarm rs-ds033197 {} profile=telemetry

temp.dir:

Create a temporary directory

CLI Example:

    salt '*' temp.dir
    salt '*' temp.dir prefix='mytemp-' parent='/var/run/'

temp.file:

Create a temporary file

CLI Example:

    salt '*' temp.file
    salt '*' temp.file prefix='mytemp-' parent='/var/run/'

test.arg:

Print out the data passed into the function ``*args`` and ``kwargs``, this
is used to both test the publication data and CLI argument passing, but
also to display the information available within the publication data.

:return: ``{"args": args, "kwargs": kwargs}``
:rtype: dict

CLI Example:

    salt '*' test.arg 1 "two" 3.1 txt="hello" wow='{a: 1, b: "hello"}'

test.arg_clean:

Like :mod:`test.arg <salt.modules.test.arg>` but cleans ``kwargs`` of the ``__pub*`` items

CLI Example:

    salt '*' test.arg_clean 1 "two" 3.1 txt="hello" wow='{a: 1, b: "hello"}'

test.arg_repr:

Print out the data passed into the function ``*args`` and ``kwargs``, this
is used to both test the publication data and CLI argument passing, but
also to display the information available within the publication data.

:return: ``{"args": repr(args), "kwargs": repr(kwargs)}``

CLI Example:

    salt '*' test.arg_repr 1 "two" 3.1 txt="hello" wow='{a: 1, b: "hello"}'

test.arg_type:

Print out the types of the ``args`` and ``kwargs``. This is used to test the types
of the ``args`` and ``kwargs`` passed down to the Minion

:rtype: dict

CLI Example:

       salt '*' test.arg_type 1 'int'

test.assertion:

Assert the given argument

CLI Example:

    salt '*' test.assertion False

test.attr_call:

Call grains.items via the attribute

CLI Example:

    salt '*' test.attr_call

test.collatz:

Execute the collatz conjecture from the passed starting number,
returns the sequence and the time it took to compute. Used for
performance tests.

CLI Example:

    salt '*' test.collatz 3

test.conf_test:

Return the value for test.foo in the minion configuration file, or return
the default value

CLI Example:

    salt '*' test.conf_test

test.cross_test:

Execute a minion function via the ``__salt__`` object in the test
module, used to verify that the Minion functions can be called
via the ``__salt__`` module.

CLI Example:

    salt '*' test.cross_test file.gid_to_group 0

test.deprecation_warning:

Return True, but also produce two DeprecationWarnings. One by date, the
other by the codename - release Oganesson, which should correspond to Salt
3108.

CLI Example:

    salt \* test.deprecation_warning

test.echo:

Return a string - used for testing the connection

CLI Example:

    salt '*' test.echo 'foo bar baz quo qux'

test.exception:

Raise an exception

Optionally provide an error message or output the full stack.

CLI Example:

    salt '*' test.exception 'Oh noes!'

test.false:

Always return ``False``

CLI Example:

    salt '*' test.false

test.fib:

Return the ``num``-th Fibonacci number, and the time it took to compute in
seconds. Used for performance tests.

This function is designed to have terrible performance.

CLI Example:

    salt '*' test.fib 3

test.get_opts:

Return the configuration options passed to this minion

CLI Example:

    salt '*' test.get_opts

test.kwarg:

Print out the data passed into the function ``**kwargs``, this is used to
both test the publication data and CLI ``kwarg`` passing, but also to display
the information available within the publication data.

CLI Example:

    salt '*' test.kwarg num=1 txt="two" env='{a: 1, b: "hello"}'

test.module_report:

Return a dict containing all of the execution modules with a report on
the overall availability via different references

CLI Example:

    salt '*' test.module_report

test.not_loaded:

List the modules that were not loaded by the salt loader system

CLI Example:

    salt '*' test.not_loaded

test.opts_pkg:

Return an ``opts`` package with the ``grains`` and ``opts`` for this Minion.
This is primarily used to create the options used for Master side
state compiling routines

CLI Example:

    salt '*' test.opts_pkg

test.outputter:

Test the outputter, pass in data to return

CLI Example:

    salt '*' test.outputter foobar

test.ping:

Used to make sure the minion is up and responding. Not an ICMP ping.

Returns ``True``.

CLI Example:

    salt '*' test.ping

test.provider:

Pass in a function name to discover what provider is being used

CLI Example:

    salt '*' test.provider service

test.providers:

Return a dict of the provider names and the files that provided them

CLI Example:

    salt '*' test.providers

test.raise_exception:

Raise an exception. Built-in exceptions and those in
:mod:`salt.exceptions <salt.internals.salt.exceptions>`
can be raised by this test function. If no matching exception is found,
then no exception will be raised and this function will return ``False``.

This function is designed to test Salt's exception and return code
handling.

CLI Example:

    salt '*' test.raise_exception TypeError "An integer is required"
    salt '*' test.raise_exception salt.exceptions.CommandExecutionError "Something went wrong"

test.rand_sleep:

Sleep for a random number of seconds, used to test long-running commands
and minions returning at differing intervals

CLI Example:

    salt '*' test.rand_sleep 60

test.rand_str:

This function has been renamed to
:mod:`test.random_hash <salt.modules.test.random_hash>`. This function will stay to
ensure backwards compatibility, but please switch to using the preferred name
:mod:`test.random_hash <salt.modules.test.random_hash>`.

test.random_hash:

New in version 2015.5.2
Changed in version 2018.3.0
    Function has been renamed from ``test.rand_str`` to
    ``test.random_hash``

Generates a random number between 1 and ``size``, then returns a hash of
that number. If no ``hash_type`` is passed, the ``hash_type`` specified by the
Minion's :conf_minion:`hash_type` config option is used.

CLI Example:

    salt '*' test.random_hash
    salt '*' test.random_hash hash_type=sha512

test.retcode:

Test tha