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 that the returncode system is functioning correctly
CLI Example:
salt '*' test.retcode 42
test.sleep:
Instruct the minion to initiate a process that will sleep for a given
period of time.
CLI Example:
salt '*' test.sleep 20
test.stack:
Return the current stack trace
CLI Example:
salt '*' test.stack
test.true:
Always return ``True``
CLI Example:
salt '*' test.true
test.try:
Try to run a module command. On an exception return ``None``.
If ``return_try_exception`` is set to ``True``, return the exception.
This can be helpful in templates where running a module might fail as expected.
Jinja Example:
{% for i in range(0,230) %}
{{ salt['test.try'](module='ipmi.get_users', bmc_host='172.2.2.'+i)|yaml(False) }}
{% endfor %}
test.tty:
Deprecated! Moved to :mod:`cmd.tty <salt.modules.cmdmod.tty>`
CLI Example:
salt '*' test.tty tty0 'This is a test'
salt '*' test.tty pts3 'This is a test'
test.version:
Return the version of salt on the minion
CLI Example:
salt '*' test.version
test.versions:
This function is an alias of versions_report.
Returns versions of components used by salt
CLI Example:
salt '*' test.versions_report
test.versions_information:
Report the versions of dependent and system software
CLI Example:
salt '*' test.versions_information
test.versions_report:
Returns versions of components used by salt
CLI Example:
salt '*' test.versions_report
timezone.get_hwclock:
Get current hardware clock setting (UTC or localtime)
CLI Example:
salt '*' timezone.get_hwclock
timezone.get_offset:
Get current numeric timezone offset from UTC (i.e. -0700)
CLI Example:
salt '*' timezone.get_offset
timezone.get_zone:
Get current timezone (i.e. America/Denver)
Changed in version 2016.11.4
Note:
On AIX operating systems, Posix values can also be returned
'CST6CDT,M3.2.0/2:00:00,M11.1.0/2:00:00'
CLI Example:
salt '*' timezone.get_zone
timezone.get_zonecode:
Get current timezone (i.e. PST, MDT, etc)
CLI Example:
salt '*' timezone.get_zonecode
timezone.set_hwclock:
Sets the hardware clock to be either UTC or localtime
CLI Example:
salt '*' timezone.set_hwclock UTC
timezone.set_zone:
Unlinks, then symlinks /etc/localtime to the set timezone.
The timezone is crucial to several system processes, each of which SHOULD
be restarted (for instance, whatever you system uses as its cron and
syslog daemons). This will not be automagically done and must be done
manually!
CLI Example:
salt '*' timezone.set_zone 'America/Denver'
Changed in version 2016.11.4
Note:
On AIX operating systems, Posix values are also allowed, see below
salt '*' timezone.set_zone 'CST6CDT,M3.2.0/2:00:00,M11.1.0/2:00:00'
timezone.zone_compare:
Compares the given timezone name with the system timezone name.
Checks the hash sum between the given timezone, and the one set in
/etc/localtime. Returns True if names and hash sums match, and False if not.
Mostly useful for running state checks.
Changed in version 2016.3.0
Note:
On Solaris-like operating systems only a string comparison is done.
Changed in version 2016.11.4
Note:
On AIX operating systems only a string comparison is done.
CLI Example:
salt '*' timezone.zone_compare 'America/Denver'
tls.ca_exists:
Verify whether a Certificate Authority (CA) already exists
ca_name
name of the CA
cacert_path
absolute path to ca certificates root directory
ca_filename
alternative filename for the CA
New in version 2015.5.3
CLI Example:
salt '*' tls.ca_exists test_ca /etc/certs
tls.cert_base_path:
Return the base path for certs from CLI or from options
cacert_path
absolute path to ca certificates root directory
CLI Example:
salt '*' tls.cert_base_path
tls.cert_info:
Return information for a particular certificate
cert
path to the certifiate PEM file or string
Changed in version 2018.3.4
digest
what digest to use for fingerprinting
CLI Example:
salt '*' tls.cert_info /dir/for/certs/cert.pem
tls.create_ca:
Create a Certificate Authority (CA)
ca_name
name of the CA
bits
number of RSA key bits, default is 2048
days
number of days the CA will be valid, default is 365
CN
common name in the request, default is "localhost"
C
country, default is "US"
ST
state, default is "Utah"
L
locality, default is "Centerville", the city where SaltStack originated
O
organization, default is "SaltStack"
OU
organizational unit, default is None
emailAddress
email address for the CA owner, default is None
cacert_path
absolute path to ca certificates root directory
ca_filename
alternative filename for the CA
New in version 2015.5.3
digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: 'sha256'
replace
Replace this certificate even if it exists
New in version 2015.5.1
Writes out a CA certificate based upon defined config values. If the file
already exists, the function just returns assuming the CA certificate
already exists.
If the following values were set::
ca.cert_base_path='/etc/pki'
ca_name='koji'
the resulting CA, and corresponding key, would be written in the following
location with appropriate permissions::
/etc/pki/koji/koji_ca_cert.crt
/etc/pki/koji/koji_ca_cert.key
CLI Example:
salt '*' tls.create_ca test_ca
tls.create_ca_signed_cert:
Create a Certificate (CERT) signed by a named Certificate Authority (CA)
If the certificate file already exists, the function just returns assuming
the CERT already exists.
The CN *must* match an existing CSR generated by create_csr. If it
does not, this method does nothing.
ca_name
name of the CA
CN
common name matching the certificate signing request
days
number of days certificate is valid, default is 365 (1 year)
cacert_path
absolute path to ca certificates root directory
ca_filename
alternative filename for the CA
New in version 2015.5.3
cert_path
full path to the certificates directory
cert_filename
alternative filename for the certificate, useful when using special
characters in the CN. If this option is set it will override
the certificate filename output effects of ``cert_type``.
``type_ext`` will be completely overridden.
New in version 2015.5.3
digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: 'sha256'
replace
Replace this certificate even if it exists
New in version 2015.5.1
cert_type
string. Either 'server' or 'client' (see create_csr() for details).
If create_csr(type_ext=True) this function **must** be called with the
same cert_type so it can find the CSR file.
Note:
create_csr() defaults to cert_type='server'; therefore, if it was also
called with type_ext, cert_type becomes a required argument for
create_ca_signed_cert()
type_ext
bool. If set True, use ``cert_type`` as an extension to the CN when
formatting the filename.
e.g.: some_subject_CN_server.crt or some_subject_CN_client.crt
This facilitates the context where both types are required for the same
subject
If ``cert_filename`` is `not None`, setting ``type_ext`` has no
effect
If the following values were set:
ca.cert_base_path='/etc/pki'
ca_name='koji'
CN='test.egavas.org'
the resulting signed certificate would be written in the following
location:
/etc/pki/koji/certs/test.egavas.org.crt
CLI Example:
salt '*' tls.create_ca_signed_cert test localhost
tls.create_csr:
Create a Certificate Signing Request (CSR) for a
particular Certificate Authority (CA)
ca_name
name of the CA
bits
number of RSA key bits, default is 2048
CN
common name in the request, default is "localhost"
C
country, default is "US"
ST
state, default is "Utah"
L
locality, default is "Centerville", the city where SaltStack originated
O
organization, default is "SaltStack"
NOTE: Must the same as CA certificate or an error will be raised
OU
organizational unit, default is None
emailAddress
email address for the request, default is None
subjectAltName
valid subjectAltNames in full form, e.g. to add DNS entry you would call
this function with this value:
examples: ['DNS:somednsname.com',
'DNS:1.2.3.4',
'IP:1.2.3.4',
'IP:2001:4801:7821:77:be76:4eff:fe11:e51',
'email:me@i.like.pie.com']
Note:
some libraries do not properly query IP: prefixes, instead looking
for the given req. source with a DNS: prefix. To be thorough, you
may want to include both DNS: and IP: entries if you are using
subjectAltNames for destinations for your TLS connections.
e.g.:
requests to https://1.2.3.4 will fail from python's
requests library w/out the second entry in the above list
New in version 2015.8.0
cert_type
Specify the general certificate type. Can be either `server` or
`client`. Indicates the set of common extensions added to the CSR.
server: {
'basicConstraints': 'CA:FALSE',
'extendedKeyUsage': 'serverAuth',
'keyUsage': 'digitalSignature, keyEncipherment'
}
client: {
'basicConstraints': 'CA:FALSE',
'extendedKeyUsage': 'clientAuth',
'keyUsage': 'nonRepudiation, digitalSignature, keyEncipherment'
}
type_ext
boolean. Whether or not to extend the filename with CN_[cert_type]
This can be useful if a server and client certificate are needed for
the same CN. Defaults to False to avoid introducing an unexpected file
naming pattern
The files normally named some_subject_CN.csr and some_subject_CN.key
will then be saved
replace
Replace this signing request even if it exists
New in version 2015.5.1
Writes out a Certificate Signing Request (CSR) If the file already
exists, the function just returns assuming the CSR already exists.
If the following values were set::
ca.cert_base_path='/etc/pki'
ca_name='koji'
CN='test.egavas.org'
the resulting CSR, and corresponding key, would be written in the
following location with appropriate permissions::
/etc/pki/koji/certs/test.egavas.org.csr
/etc/pki/koji/certs/test.egavas.org.key
CLI Example:
salt '*' tls.create_csr test
tls.create_empty_crl:
Create an empty Certificate Revocation List.
New in version 2015.8.0
ca_name
name of the CA
cacert_path
absolute path to ca certificates root directory
ca_filename
alternative filename for the CA
New in version 2015.5.3
crl_file
full path to the CRL file
digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: 'sha256'
CLI Example:
salt '*' tls.create_empty_crl ca_name='koji' ca_filename='ca' crl_file='/etc/openvpn/team1/crl.pem'
tls.create_pkcs12:
Create a PKCS#12 browser certificate for a particular Certificate (CN)
ca_name
name of the CA
CN
common name matching the certificate signing request
passphrase
used to unlock the PKCS#12 certificate when loaded into the browser
cacert_path
absolute path to ca certificates root directory
replace
Replace this certificate even if it exists
New in version 2015.5.1
If the following values were set::
ca.cert_base_path='/etc/pki'
ca_name='koji'
CN='test.egavas.org'
the resulting signed certificate would be written in the
following location::
/etc/pki/koji/certs/test.egavas.org.p12
CLI Example:
salt '*' tls.create_pkcs12 test localhost
tls.create_self_signed_cert:
Create a Self-Signed Certificate (CERT)
tls_dir
location appended to the ca.cert_base_path, default is 'tls'
bits
number of RSA key bits, default is 2048
CN
common name in the request, default is "localhost"
C
country, default is "US"
ST
state, default is "Utah"
L
locality, default is "Centerville", the city where SaltStack originated
O
organization, default is "SaltStack"
NOTE: Must the same as CA certificate or an error will be raised
OU
organizational unit, default is None
emailAddress
email address for the request, default is None
cacert_path
absolute path to ca certificates root directory
digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: 'sha256'
replace
Replace this certificate even if it exists
New in version 2015.5.1
Writes out a Self-Signed Certificate (CERT). If the file already
exists, the function just returns.
If the following values were set::
ca.cert_base_path='/etc/pki'
tls_dir='koji'
CN='test.egavas.org'
the resulting CERT, and corresponding key, would be written in the
following location with appropriate permissions::
/etc/pki/koji/certs/test.egavas.org.crt
/etc/pki/koji/certs/test.egavas.org.key
CLI Example:
salt '*' tls.create_self_signed_cert
Passing options from the command line:
salt 'minion' tls.create_self_signed_cert CN='test.mysite.org'
tls.get_ca:
Get the certificate path or content
ca_name
name of the CA
as_text
if true, return the certificate content instead of the path
cacert_path
absolute path to ca certificates root directory
CLI Example:
salt '*' tls.get_ca test_ca as_text=False cacert_path=/etc/certs
tls.get_ca_signed_cert:
Get the certificate path or content
ca_name
name of the CA
CN
common name of the certificate
as_text
if true, return the certificate content instead of the path
cacert_path
absolute path to certificates root directory
cert_filename
alternative filename for the certificate, useful when using special characters in the CN
New in version 2015.5.3
CLI Example:
salt '*' tls.get_ca_signed_cert test_ca CN=localhost as_text=False cacert_path=/etc/certs
tls.get_ca_signed_key:
Get the certificate path or content
ca_name
name of the CA
CN
common name of the certificate
as_text
if true, return the certificate content instead of the path
cacert_path
absolute path to certificates root directory
key_filename
alternative filename for the key, useful when using special characters
New in version 2015.5.3
in the CN
CLI Example:
salt '*' tls.get_ca_signed_key test_ca CN=localhost as_text=False cacert_path=/etc/certs
tls.get_expiration_date:
New in version 2019.2.0
Get a certificate's expiration date
cert
Full path to the certificate
date_format
By default this will return the expiration date in YYYY-MM-DD format,
use this to specify a different strftime format string. Note that the
expiration time will be in UTC.
CLI Examples:
salt '*' tls.get_expiration_date /path/to/foo.crt
salt '*' tls.get_expiration_date /path/to/foo.crt date_format='%d/%m/%Y'
tls.get_extensions:
Fetch X509 and CSR extension definitions from tls:extensions:
(common|server|client) or set them to standard defaults.
New in version 2015.8.0
cert_type:
The type of certificate such as ``server`` or ``client``.
CLI Example:
salt '*' tls.get_extensions client
tls.maybe_fix_ssl_version:
Check that the X509 version is correct
(was incorrectly set in previous salt versions).
This will fix the version if needed.
ca_name
ca authority name
cacert_path
absolute path to ca certificates root directory
ca_filename
alternative filename for the CA
New in version 2015.5.3
CLI Example:
salt '*' tls.maybe_fix_ssl_version test_ca /etc/certs
tls.revoke_cert:
Revoke a certificate.
New in version 2015.8.0
ca_name
Name of the CA.
CN
Common name matching the certificate signing request.
cacert_path
Absolute path to ca certificates root directory.
ca_filename
Alternative filename for the CA.
cert_path
Path to the cert file.
cert_filename
Alternative filename for the certificate, useful when using special
characters in the CN.
crl_file
Full path to the CRL file.
digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: 'sha256'
CLI Example:
salt '*' tls.revoke_cert ca_name='koji' ca_filename='ca' crl_file='/etc/openvpn/team1/crl.pem'
tls.set_ca_path:
If wanted, store the aforementioned cacert_path in context
to be used as the basepath for further operations
CLI Example:
salt '*' tls.set_ca_path /etc/certs
tls.validate:
New in version 3000
Validate a certificate against a given CA/CRL.
cert
path to the certifiate PEM file or string
ca_name
name of the CA
crl_file
full path to the CRL file
travisci.verify_webhook:
Verify the webhook signature from travisci
signature
The signature header from the webhook header
body
The full payload body from the webhook post
Note: The body needs to be the urlencoded version of the body.
CLI Example:
salt '*' travisci.verify_webhook 'M6NucCX5722bxisQs7e...' 'payload=%7B%22id%22%3A183791261%2C%22repository...'
udev.env:
Return all environment variables udev has for dev
CLI Example:
salt '*' udev.env /dev/sda
salt '*' udev.env /sys/class/net/eth0
udev.exportdb:
Return all the udev database
CLI Example:
salt '*' udev.exportdb
udev.info:
Extract all info delivered by udevadm
CLI Example:
salt '*' udev.info /dev/sda
salt '*' udev.info /sys/class/net/eth0
udev.links:
Return all udev-created device symlinks
CLI Example:
salt '*' udev.links /dev/sda
salt '*' udev.links /sys/class/net/eth0
udev.name:
Return the actual dev name(s?) according to udev for dev
CLI Example:
salt '*' udev.dev /dev/sda
salt '*' udev.dev /sys/class/net/eth0
udev.path:
Return the physical device path(s?) according to udev for dev
CLI Example:
salt '*' udev.path /dev/sda
salt '*' udev.path /sys/class/net/eth0
uptime.check_exists:
Check if a given URL is in being monitored by uptime
CLI Example:
salt '*' uptime.check_exists http://example.org
uptime.checks_list:
List URL checked by uptime
CLI Example:
salt '*' uptime.checks_list
uptime.create: Create a check on a given URL.
Additional parameters can be used and are passed to API (for
example interval, maxTime, etc). See the documentation
https://github.com/fzaninotto/uptime for a full list of the
parameters.
CLI Example:
salt '*' uptime.create http://example.org
uptime.delete:
Delete a check on a given URL
CLI Example:
salt '*' uptime.delete http://example.org
user.add:
Add a user to the minion
name
Username LOGIN to add
uid
User ID of the new account
gid
Name or ID of the primary group of the new account
groups
List of supplementary groups of the new account
home
Home directory of the new account
shell
Login shell of the new account
unique
If not True, the user account can have a non-unique UID
system
Create a system account
fullname
GECOS field for the full name
roomnumber
GECOS field for the room number
workphone
GECOS field for the work phone
homephone
GECOS field for the home phone
other
GECOS field for other information
createhome
Create the user's home directory
loginclass
Login class for the new account (OpenBSD)
nologinit
Do not add the user to the lastlog and faillog databases
root
Directory to chroot into
usergroup
Create and add the user to a new primary group of the same name
local (Only on systems with luseradd available)
Specifically add the user locally rather than possibly through remote providers (e.g. LDAP)
New in version 3007.0
CLI Example:
salt '*' user.add name <uid> <gid> <groups> <home> <shell>
user.chfullname:
Change the user's Full Name
name
User to modify
fullname
GECOS field for the full name
root
Directory to chroot into
CLI Example:
salt '*' user.chfullname foo "Foo Bar"
user.chgid:
Change the default group of the user
name
User to modify
gid
Force use GID as new primary group
root
Directory to chroot into
CLI Example:
salt '*' user.chgid foo 4376
user.chgroups:
Change the groups to which this user belongs
name
User to modify
groups
Groups to set for the user
append : False
If ``True``, append the specified group(s). Otherwise, this function
will replace the user's groups with the specified group(s).
root
Directory to chroot into
CLI Examples:
salt '*' user.chgroups foo wheel,root
salt '*' user.chgroups foo wheel,root append=True
user.chhome:
Change the home directory of the user, pass True for persist to move files
to the new home directory if the old home directory exist.
name
User to modify
home
New home directory for the user account
persist
Move contents of the home directory to the new location
root
Directory to chroot into
CLI Example:
salt '*' user.chhome foo /home/users/foo True
user.chhomephone:
Change the user's Home Phone
name
User to modify
homephone
GECOS field for the home phone
root
Directory to chroot into
CLI Example:
salt '*' user.chhomephone foo 7735551234
user.chloginclass:
Change the default login class of the user
name
User to modify
loginclass
Login class for the new account
root
Directory to chroot into
Note:
This function only applies to OpenBSD systems.
CLI Example:
salt '*' user.chloginclass foo staff
user.chother:
Change the user's other GECOS attribute
name
User to modify
other
GECOS field for other information
root
Directory to chroot into
CLI Example:
salt '*' user.chother foobar
user.chroomnumber:
Change the user's Room Number
CLI Example:
salt '*' user.chroomnumber foo 123
user.chshell:
Change the default shell of the user
name
User to modify
shell
New login shell for the user account
root
Directory to chroot into
CLI Example:
salt '*' user.chshell foo /bin/zsh
user.chuid:
Change the uid for a named user
name
User to modify
uid
New UID for the user account
root
Directory to chroot into
CLI Example:
salt '*' user.chuid foo 4376
user.chworkphone:
Change the user's Work Phone
name
User to modify
workphone
GECOS field for the work phone
root
Directory to chroot into
CLI Example:
salt '*' user.chworkphone foo 7735550123
user.delete:
Remove a user from the minion
name
Username to delete
remove
Remove home directory and mail spool
force
Force some actions that would fail otherwise
root
Directory to chroot into
local (Only on systems with luserdel available):
Ensure the user account is removed locally ignoring global
account management (default is False).
New in version 3007.0
CLI Example:
salt '*' user.delete name remove=True force=True
user.get_loginclass:
Get the login class of the user
name
User to get the information
Note:
This function only applies to OpenBSD systems.
CLI Example:
salt '*' user.get_loginclass foo
user.getent:
Return the list of all info for all users
refresh
Force a refresh of user information
root
Directory to chroot into
CLI Example:
salt '*' user.getent
user.info:
Return user information
name
User to get the information
root
Directory to chroot into
CLI Example:
salt '*' user.info root
user.list_groups:
Return a list of groups the named user belongs to
name
User to get the information
CLI Example:
salt '*' user.list_groups foo
user.list_users:
Return a list of all users
root
Directory to chroot into
CLI Example:
salt '*' user.list_users
user.primary_group:
Return the primary group of the named user
New in version 2016.3.0
name
User to get the information
CLI Example:
salt '*' user.primary_group saltadmin
user.rename:
Change the username for a named user
name
User to modify
new_name
New value of the login name
root
Directory to chroot into
CLI Example:
salt '*' user.rename name new_name
vault.clear_cache:
New in version 3007.0
Delete Vault caches. Will ensure the current token and associated leases
are revoked by default.
The cache is organized in a hierarchy: ``/vault/connection/session/leases``.
(*italics* mark data that is only cached when receiving configuration from a master)
``connection`` contains KV metadata (by default), *configuration* and *(AppRole) auth credentials*.
``session`` contains the currently active token.
``leases`` contains leases issued to the currently active token like database credentials.
CLI Example:
salt '*' vault.clear_cache
salt '*' vault.clear_cache session=True
connection
Only clear the cached data scoped to a connection. This includes
configuration, auth credentials, the currently active auth token
as well as leases and KV metadata (by default). Defaults to true.
Set this to false to clear all Vault caches.
session
Only clear the cached data scoped to a session. This only includes
leases and the currently active auth token, but not configuration
or (AppRole) auth credentials. Defaults to false.
Setting this to true will keep the connection cache, regardless
of ``connection``.
vault.clear_token_cache:
Changed in version 3001
Changed in version 3007.0
This is now an alias for ``vault.clear_cache`` with ``connection=True``.
Delete minion Vault token cache.
CLI Example:
salt '*' vault.clear_token_cache
vault.delete_secret:
Delete secret at <path>. The vault policy used must allow this.
If <path> is on KV v2, the secret will be soft-deleted.
CLI Example:
salt '*' vault.delete_secret "secret/my/secret"
salt '*' vault.delete_secret "secret/my/secret" 1 2 3
Required policy:
path "<mount>/<secret>" {
capabilities = ["delete"]
}
# or KV v2
path "<mount>/data/<secret>" {
capabilities = ["delete"]
}
# KV v2 versions
path "<mount>/delete/<secret>" {
capabilities = ["update"]
}
path
The path to the secret, including mount.
New in version 3007.0
For KV v2, you can specify versions to soft-delete as supplemental
positional arguments.
vault.destroy_secret:
New in version 3001
Destroy specified secret versions <path>. The vault policy
used must allow this. Only supported on Vault KV version 2.
CLI Example:
salt '*' vault.destroy_secret "secret/my/secret" 1 2
Required policy:
path "<mount>/destroy/<secret>" {
capabilities = ["update"]
}
path
The path to the secret, including mount.
You can specify versions to destroy as supplemental positional arguments.
At least one is required.
vault.get_server_config:
New in version 3007.0
Return the server connection configuration that's currently in use by Salt.
Contains ``url``, ``verify`` and ``namespace``.
CLI Example:
salt '*' vault.get_server_config
vault.list_secrets:
List secret keys at <path>. The vault policy used must allow this.
The path should end with a trailing slash.
Changed in version 3001
The ``default`` argument has been added. When the path or path/key
combination is not found, an exception will be raised, unless a default
is provided.
CLI Example:
salt '*' vault.list_secrets "secret/my/"
Required policy:
path "<mount>/<path>" {
capabilities = ["list"]
}
# or KV v2
path "<mount>/metadata/<path>" {
capabilities = ["list"]
}
path
The path to the secret, including mount.
default
New in version 3001
When the path is not found, an exception will be raised, unless a default
is provided here.
keys_only
New in version 3007.0
This function used to return a dictionary like ``{"keys": ["some/", "some/key"]}``.
Setting this to True will only return the list of keys.
For backwards-compatibility reasons, this defaults to False.
vault.patch_secret:
Patch secret dataset at <path>. Fields are specified as arbitrary keyword arguments.
Note:
This works even for older Vault versions, KV v1 and with missing
``patch`` capability, but will use more than one request to simulate
the functionality by issuing a read and update request.
For proper, single-request patching, requires versions of KV v2 that
support the ``patch`` capability and the ``patch`` capability to be available
for the path.
Note:
This uses JSON Merge Patch format internally.
Keys set to ``null`` (JSON/YAML)/``None`` (Python) will be deleted.
CLI Example:
salt '*' vault.patch_secret "secret/my/secret" password="baz"
Required policy:
# Proper patching
path "<mount>/data/<secret>" {
capabilities = ["patch"]
}
# OR (!), for older KV v2 setups:
path "<mount>/data/<secret>" {
capabilities = ["read", "update"]
}
# OR (!), for KV v1 setups:
path "<mount>/<secret>" {
capabilities = ["read", "update"]
}
path
The path to the secret, including mount.
vault.policies_list:
New in version 3007.0
List all ACL policies.
CLI Example:
salt '*' vault.policies_list
Required policy:
path "sys/policy" {
capabilities = ["read"]
}
vault.policy_delete:
New in version 3007.0
Delete an ACL policy. Returns False if the policy did not exist.
CLI Example:
salt '*' vault.policy_delete salt_minion
Required policy:
path "sys/policy/<policy>" {
capabilities = ["delete"]
}
policy
The name of the policy to delete.
vault.policy_fetch:
New in version 3007.0
Fetch the rules associated with an ACL policy. Returns None if the policy
does not exist.
CLI Example:
salt '*' vault.policy_fetch salt_minion
Required policy:
path "sys/policy/<policy>" {
capabilities = ["read"]
}
policy
The name of the policy to fetch.
vault.policy_write:
New in version 3007.0
Create or update an ACL policy.
CLI Example:
salt '*' vault.policy_write salt_minion 'path "secret/foo" {...}'
Required policy:
path "sys/policy/<policy>" {
capabilities = ["create", "update"]
}
policy
The name of the policy to create/update.
rules
Rules to write, formatted as in-line HCL.
vault.query:
New in version 3007.0
Issue arbitrary queries against the Vault API.
CLI Example:
salt '*' vault.query GET auth/token/lookup-self
Required policy: Depends on the query.
You can ask the vault CLI to output the necessary policy:
vault read -output-policy auth/token/lookup-self
method
HTTP method to use.
endpoint
Vault API endpoint to issue the request against. Do not include ``/v1/``.
payload
Optional dictionary to use as JSON payload.
vault.read_secret:
Return the value of <key> at <path> in vault, or entire secret.
Changed in version 3001
The ``default`` argument has been added. When the path or path/key
combination is not found, an exception will be raised, unless a default
is provided.
CLI Example:
salt '*' vault.read_secret salt/kv/secret
Required policy:
path "<mount>/<secret>" {
capabilities = ["read"]
}
# or KV v2
path "<mount>/data/<secret>" {
capabilities = ["read"]
}
path
The path to the secret, including mount.
key
The data field at <path> to read. If unspecified, returns the
whole dataset.
metadata
New in version 3001
If using KV v2 backend, display full results, including metadata.
Defaults to False.
default
New in version 3001
When the path or path/key combination is not found, an exception will
be raised, unless a default is provided here.
vault.update_config:
New in version 3007.0
Attempt to update the cached configuration without clearing the
currently active Vault session.
CLI Example:
salt '*' vault.update_config
keep_session
Only update configuration that can be updated without
creating a new login session.
If this is false, still tries to keep the active session,
but might clear it if the server configuration has changed
significantly.
Defaults to False.
vault.write_raw:
Set raw data at <path>. The vault policy used must allow this.
CLI Example:
salt '*' vault.write_raw "secret/my/secret" '{"user":"foo","password": "bar"}'
Required policy: see write_secret
path
The path to the secret, including mount.
raw
Secret data to write to <path>. Has to be a mapping.
vault.write_secret:
Set secret dataset at <path>. The vault policy used must allow this.
Fields are specified as arbitrary keyword arguments.
CLI Example:
salt '*' vault.write_secret "secret/my/secret" user="foo" password="bar"
Required policy:
path "<mount>/<secret>" {
capabilities = ["create", "update"]
}
# or KV v2
path "<mount>/data/<secret>" {
capabilities = ["create", "update"]
}
path
The path to the secret, including mount.
vbox_guest.additions_install:
Install VirtualBox Guest Additions. Uses the CD, connected by VirtualBox.
To connect VirtualBox Guest Additions via VirtualBox graphical interface
press 'Host+D' ('Host' is usually 'Right Ctrl').
See https://www.virtualbox.org/manual/ch04.html#idp52733088 for more details.
CLI Example:
salt '*' vbox_guest.additions_install
salt '*' vbox_guest.additions_install reboot=True
salt '*' vbox_guest.additions_install upgrade_os=True
:param reboot: reboot computer to complete installation
:type reboot: bool
:param upgrade_os: upgrade OS (to ensure the latests version of kernel and developer tools are installed)
:type upgrade_os: bool
:return: version of VirtualBox Guest Additions or string with error
vbox_guest.additions_mount:
Mount VirtualBox Guest Additions CD to the temp directory.
To connect VirtualBox Guest Additions via VirtualBox graphical interface
press 'Host+D' ('Host' is usually 'Right Ctrl').
CLI Example:
salt '*' vbox_guest.additions_mount
:return: True or OSError exception
vbox_guest.additions_remove:
Remove VirtualBox Guest Additions.
Firstly it tries to uninstall itself by executing
'/opt/VBoxGuestAdditions-VERSION/uninstall.run uninstall'.
It uses the CD, connected by VirtualBox if it failes.
CLI Example:
salt '*' vbox_guest.additions_remove
salt '*' vbox_guest.additions_remove force=True
:param force: force VirtualBox Guest Additions removing
:type force: bool
:return: True if VirtualBox Guest Additions were removed successfully else False
vbox_guest.additions_umount:
Unmount VirtualBox Guest Additions CD from the temp directory.
CLI Example:
salt '*' vbox_guest.additions_umount
:param mount_point: directory VirtualBox Guest Additions is mounted to
:return: True or an string with error
vbox_guest.additions_version:
Check VirtualBox Guest Additions version.
CLI Example:
salt '*' vbox_guest.additions_version
:return: version of VirtualBox Guest Additions or False if they are not installed
vbox_guest.grant_access_to_shared_folders_to:
Grant access to auto-mounted shared folders to the users.
User is specified by its name. To grant access for several users use argument `users`.
Access will be denied to the users not listed in `users` argument.
See https://www.virtualbox.org/manual/ch04.html#sf_mount_auto for more details.
CLI Example:
salt '*' vbox_guest.grant_access_to_shared_folders_to fred
salt '*' vbox_guest.grant_access_to_shared_folders_to users ['fred', 'roman']
:param name: name of the user to grant access to auto-mounted shared folders to
:type name: str
:param users: list of names of users to grant access to auto-mounted shared folders to (if specified, `name` will not be taken into account)
:type users: list of str
:return: list of users who have access to auto-mounted shared folders
vbox_guest.list_shared_folders_users:
List users who have access to auto-mounted shared folders.
See https://www.virtualbox.org/manual/ch04.html#sf_mount_auto for more details.
CLI Example:
salt '*' vbox_guest.list_shared_folders_users
:return: list of users who have access to auto-mounted shared folders
virtualenv.create:
Create a virtualenv
path
The path to the virtualenv to be created
venv_bin
The name (and optionally path) of the virtualenv command. This can also
be set globally in the minion config file as ``virtualenv.venv_bin``.
Defaults to ``virtualenv``.
system_site_packages : False
Passthrough argument given to virtualenv or pyvenv
distribute : False
Passthrough argument given to virtualenv
pip : False
Install pip after creating a virtual environment. Implies
``distribute=True``
clear : False
Passthrough argument given to virtualenv or pyvenv
python : None (default)
Passthrough argument given to virtualenv
extra_search_dir : None (default)
Passthrough argument given to virtualenv
never_download : None (default)
Passthrough argument given to virtualenv if True
prompt : None (default)
Passthrough argument given to virtualenv if not None
symlinks : None
Passthrough argument given to pyvenv if True
upgrade : None
Passthrough argument given to pyvenv if True
user : None
Set ownership for the virtualenv
Note:
On Windows you must also pass a ``password`` parameter. Additionally,
the user must have permissions to the location where the virtual
environment is being created
runas : None
Set ownership for the virtualenv
.. deprecated:: 2014.1.0
``user`` should be used instead
use_vt : False
Use VT terminal emulation (see output while installing)
New in version 2015.5.0
saltenv : 'base'
Specify a different environment. The default environment is ``base``.
New in version 2014.1.0
Note:
The ``runas`` argument is deprecated as of 2014.1.0. ``user`` should be
used instead.
CLI Example:
salt '*' virtualenv.create /path/to/new/virtualenv
Example of using --always-copy environment variable (in case your fs doesn't support symlinks).
This will copy files into the virtualenv instead of symlinking them.
- env:
- VIRTUALENV_ALWAYS_COPY: 1
virtualenv.get_distribution_path:
Return the path to a distribution installed inside a virtualenv
New in version 2016.3.0
venv
Path to the virtualenv.
distribution
Name of the distribution. Note, all non-alphanumeric characters
will be converted to dashes.
CLI Example:
salt '*' virtualenv.get_distribution_path /path/to/my/venv my_distribution
virtualenv.get_resource_content:
Return the content of a package resource installed inside a virtualenv
New in version 2015.5.0
venv
Path to the virtualenv
package
Name of the package in which the resource resides
New in version 2016.3.0
resource
Name of the resource of which the content is to be returned
New in version 2016.3.0
CLI Example:
salt '*' virtualenv.get_resource_content /path/to/my/venv my_package my/resource.xml
virtualenv.get_resource_path:
Return the path to a package resource installed inside a virtualenv
New in version 2015.5.0
venv
Path to the virtualenv
package
Name of the package in which the resource resides
New in version 2016.3.0
resource
Name of the resource of which the path is to be returned
New in version 2016.3.0
CLI Example:
salt '*' virtualenv.get_resource_path /path/to/my/venv my_package my/resource.xml
virtualenv.get_site_packages:
Return the path to the site-packages directory of a virtualenv
venv
Path to the virtualenv.
CLI Example:
salt '*' virtualenv.get_site_packages /path/to/my/venv
virtualenv.virtualenv_ver:
return virtualenv version if exists
vsphere.compare_vm_configs:
Compares virtual machine current and new configuration, the current is the
one which is deployed now, and the new is the target config. Returns the
differences between the objects in a dictionary, the keys are the
configuration parameter keys and the values are differences objects: either
list or recursive difference
new_config:
New config dictionary with every available parameter
current_config
Currently deployed configuration
vsphere.get_proxy_type:
Returns the proxy type retrieved either from the pillar of from the proxy
minion's config. Returns ``<undefined>`` otherwise.
CLI Example:
salt '*' vsphere.get_proxy_type
vsphere.get_ssh_key:
Retrieve the authorized_keys entry for root.
This function only works for ESXi, not vCenter.
:param host: The location of the ESXi Host
:param username: Username to connect as
:param password: Password for the ESXi web endpoint
:param protocol: defaults to https, can be http if ssl is disabled on ESXi
:param port: defaults to 443 for https
:param certificate_verify: If true require that the SSL connection present
a valid certificate. Default: True
:return: True if upload is successful
CLI Example:
salt '*' vsphere.get_ssh_key my.esxi.host root bad-password certificate_verify=True
vsphere.get_vm_config:
Queries and converts the virtual machine properties to the available format
from the schema. If the objects attribute is True the config objects will
have extra properties, like 'object' which will include the
vim.vm.device.VirtualDevice, this is necessary for deletion and update
actions.
name
Name of the virtual machine
datacenter
Datacenter's name where the virtual machine is available
objects
Indicates whether to return the vmware object properties
(eg. object, key) or just the properties which can be set
service_instance
vCenter service instance for connection and configuration
vsphere.upload_ssh_key:
Upload an ssh key for root to an ESXi host via http PUT.
This function only works for ESXi, not vCenter.
Only one ssh key can be uploaded for root. Uploading a second key will
replace any existing key.
:param host: The location of the ESXi Host
:param username: Username to connect as
:param password: Password for the ESXi web endpoint
:param ssh_key: Public SSH key, will be added to authorized_keys on ESXi
:param ssh_key_file: File containing the SSH key. Use 'ssh_key' or
ssh_key_file, but not both.
:param protocol: defaults to https, can be http if ssl is disabled on ESXi
:param port: defaults to 443 for https
:param certificate_verify: If true require that the SSL connection present
a valid certificate. Default: True
:return: Dictionary with a 'status' key, True if upload is successful.
If upload is unsuccessful, 'status' key will be False and
an 'Error' key will have an informative message.
CLI Example:
salt '*' vsphere.upload_ssh_key my.esxi.host root bad-password ssh_key_file='/etc/salt/my_keys/my_key.pub'
xfs.defragment:
Defragment mounted XFS filesystem.
In order to mount a filesystem, device should be properly mounted and writable.
CLI Example:
salt '*' xfs.defragment /dev/sda1
xfs.devices:
Get known XFS formatted devices on the system.
CLI Example:
salt '*' xfs.devices
xfs.dump:
Dump filesystem device to the media (file, tape etc).
Required parameters:
* **device**: XFS device, content of which to be dumped.
* **destination**: Specifies a dump destination.
Valid options are:
* **label**: Label of the dump. Otherwise automatically generated label is used.
* **level**: Specifies a dump level of 0 to 9.
* **noerase**: Pre-erase media.
Other options are not used in order to let ``xfsdump`` use its default
values, as they are most optimal. See the ``xfsdump(8)`` manpage for
a more complete description of these options.
CLI Example:
salt '*' xfs.dump /dev/sda1 /detination/on/the/client
salt '*' xfs.dump /dev/sda1 /detination/on/the/client label='Company accountancy'
salt '*' xfs.dump /dev/sda1 /detination/on/the/client noerase=True
xfs.estimate:
Estimate the space that an XFS filesystem will take.
For each directory estimate the space that directory would take
if it were copied to an XFS filesystem.
Estimation does not cross mount points.
CLI Example:
salt '*' xfs.estimate /path/to/file
salt '*' xfs.estimate /path/to/dir/*
xfs.info:
Get filesystem geometry information.
CLI Example:
salt '*' xfs.info /dev/sda1
xfs.inventory:
Display XFS dump inventory without restoration.
CLI Example:
salt '*' xfs.inventory
xfs.mkfs:
Create a file system on the specified device. By default wipes out with force.
General options:
* **label**: Specify volume label.
* **ssize**: Specify the fundamental sector size of the filesystem.
* **noforce**: Do not force create filesystem, if disk is already formatted.
Filesystem geometry options:
* **bso**: Block size options.
* **gmo**: Global metadata options.
* **dso**: Data section options. These options specify the location, size,
and other parameters of the data section of the filesystem.
* **ino**: Inode options to specify the inode size of the filesystem, and other inode allocation parameters.
* **lso**: Log section options.
* **nmo**: Naming options.
* **rso**: Realtime section options.
See the ``mkfs.xfs(8)`` manpage for a more complete description of corresponding options description.
CLI Example:
salt '*' xfs.mkfs /dev/sda1
salt '*' xfs.mkfs /dev/sda1 dso='su=32k,sw=6' noforce=True
salt '*' xfs.mkfs /dev/sda1 dso='su=32k,sw=6' lso='logdev=/dev/sda2,size=10000b'
xfs.modify:
Modify parameters of an XFS filesystem.
CLI Example:
salt '*' xfs.modify /dev/sda1 label='My backup' lazy_counting=False
salt '*' xfs.modify /dev/sda1 uuid=False
salt '*' xfs.modify /dev/sda1 uuid=True
xfs.prune_dump:
Prunes the dump session identified by the given session id.
CLI Example:
salt '*' xfs.prune_dump b74a3586-e52e-4a4a-8775-c3334fa8ea2c
xml.get_attribute:
Return the attributes of the matched xpath element.
CLI Example:
salt '*' xml.get_attribute /tmp/test.xml ".//element[@id='3']"
xml.get_value:
Returns the value of the matched xpath element
CLI Example:
salt '*' xml.get_value /tmp/test.xml ".//element"
xml.set_attribute:
Set the requested attribute key and value for matched xpath element.
CLI Example:
salt '*' xml.set_attribute /tmp/test.xml ".//element[@id='3']" editedby "gal"
xml.set_value:
Sets the value of the matched xpath element
CLI Example:
salt '*' xml.set_value /tmp/test.xml ".//element" "new value"
zabbix.apiinfo_version:
Retrieve the version of the Zabbix API.
New in version 2016.3.0
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: On success string with Zabbix API version, False on failure.
CLI Example:
salt '*' zabbix.apiinfo_version
zabbix.compare_params:
New in version 2017.7.0
Compares Zabbix object definition against existing Zabbix object.
:param defined: Zabbix object definition taken from sls file.
:param existing: Existing Zabbix object taken from result of an API call.
:param return_old_value: Default False. If True, returns dict("old"=old_val, "new"=new_val) for rollback purpose.
:return: Params that are different from existing object. Result extended by
object ID can be passed directly to Zabbix API update method.
CLI Example:
salt '*' zabbix.compare_params new_zabbix_object_dict existing_zabbix_onject_dict
zabbix.configuration_import:
New in version 2017.7.0
Imports Zabbix configuration specified in file to Zabbix server.
:param config_file: File with Zabbix config (local or remote)
:param rules: Optional - Rules that have to be different from default (defaults are the same as in Zabbix web UI.)
:param file_format: Config file format (default: xml)
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
CLI Example:
salt '*' zabbix.configuration_import salt://zabbix/config/zabbix_templates.xml "{'screens': {'createMissing': True, 'updateExisting': True}}"
zabbix.get_object_id_by_params:
New in version 2017.7.0
Get ID of single Zabbix object specified by its name.
:param obj: Zabbix object type
:param params: Parameters by which object is uniquely identified
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: object ID
CLI Example:
salt '*' zabbix.get_object_id_by_params object_type params=zabbix_api_query_parameters_dict
zabbix.get_zabbix_id_mapper:
New in version 2017.7.0
Make ZABBIX_ID_MAPPER constant available to state modules.
:return: ZABBIX_ID_MAPPER
CLI Example:
salt '*' zabbix.get_zabbix_id_mapper
zabbix.host_create:
New in version 2016.3.0
Create new host
Note:
This function accepts all standard host properties: keyword argument
names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.4/manual/api/reference/host/object#host
:param host: technical name of the host
:param groups: groupids of host groups to add the host to
:param interfaces: interfaces to be created for the host
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:param visible_name: string with visible name of the host, use
'visible_name' instead of 'name' parameter to not mess with value
supplied from Salt sls file.
return: ID of the created host.
CLI Example:
salt '*' zabbix.host_create technicalname 4
interfaces='{type: 1, main: 1, useip: 1, ip: "192.168.3.1", dns: "", port: 10050}'
visible_name='Host Visible Name' inventory_mode=0 inventory='{"alias": "something"}'
zabbix.host_delete:
Delete hosts.
New in version 2016.3.0
:param hostids: Hosts (hostids) to delete.
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of the deleted hosts.
CLI Example:
salt '*' zabbix.host_delete 10106
zabbix.host_exists:
Checks if at least one host that matches the given filter criteria exists.
New in version 2016.3.0
:param host: technical name of the host
:param hostids: Hosts (hostids) to delete.
:param name: visible name of the host
:param node: name of the node the hosts must belong to (zabbix API < 2.4)
:param nodeids: IDs of the node the hosts must belong to (zabbix API < 2.4)
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of the deleted hosts, False on failure.
CLI Example:
salt '*' zabbix.host_exists 'Zabbix server'
zabbix.host_get:
New in version 2016.3.0
Retrieve hosts according to the given parameters
Note:
This function accepts all optional host.get parameters: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.4/manual/api/reference/host/get
:param host: technical name of the host
:param name: visible name of the host
:param hostids: ids of the hosts
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with convenient hosts details, False if no host found or on failure.
CLI Example:
salt '*' zabbix.host_get 'Zabbix server'
zabbix.host_inventory_get:
Retrieve host inventory according to the given parameters.
See: https://www.zabbix.com/documentation/2.4/manual/api/reference/host/object#host_inventory
New in version 2019.2.0
:param hostids: ID of the host to query
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with host inventory fields, populated or not, False if host inventory is disabled or on failure.
CLI Example:
salt '*' zabbix.host_inventory_get 101054
zabbix.host_inventory_set:
Update host inventory items
NOTE: This function accepts all standard host: keyword argument names for inventory
see: https://www.zabbix.com/documentation/2.4/manual/api/reference/host/object#host_inventory
New in version 2019.2.0
:param hostid: ID of the host to update
:param clear_old: Set to True in order to remove all existing inventory items before setting the specified items
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: ID of the updated host, False on failure.
CLI Example:
salt '*' zabbix.host_inventory_set 101054 asset_tag=jml3322 type=vm clear_old=True
zabbix.host_list:
Retrieve all hosts.
New in version 2016.3.0
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with details about hosts, False on failure.
CLI Example:
salt '*' zabbix.host_list
zabbix.host_update:
New in version 2016.3.0
Update existing hosts
Note:
This function accepts all standard host and host.update properties:
keyword argument names differ depending on your zabbix version, see the
documentation for `host objects`_ and the documentation for `updating
hosts`_.
.. _`host objects`: https://www.zabbix.com/documentation/2.4/manual/api/reference/host/object#host
.. _`updating hosts`: https://www.zabbix.com/documentation/2.4/manual/api/reference/host/update
:param hostid: ID of the host to update
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:param visible_name: string with visible name of the host, use
'visible_name' instead of 'name' parameter to not mess with value
supplied from Salt sls file.
:return: ID of the updated host.
CLI Example:
salt '*' zabbix.host_update 10084 name='Zabbix server2'
zabbix.hostgroup_create:
New in version 2016.3.0
Create a host group
Note:
This function accepts all standard host group properties: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.4/manual/api/reference/hostgroup/object#host_group
:param name: name of the host group
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: ID of the created host group.
CLI Example:
salt '*' zabbix.hostgroup_create MyNewGroup
zabbix.hostgroup_delete:
Delete the host group.
New in version 2016.3.0
:param hostgroupids: IDs of the host groups to delete
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: ID of the deleted host groups, False on failure.
CLI Example:
salt '*' zabbix.hostgroup_delete 23
zabbix.hostgroup_exists:
Checks if at least one host group that matches the given filter criteria exists.
New in version 2016.3.0
:param name: names of the host groups
:param groupid: host group IDs
:param node: name of the node the host groups must belong to (zabbix API < 2.4)
:param nodeids: IDs of the nodes the host groups must belong to (zabbix API < 2.4)
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: True if at least one host group exists, False if not or on failure.
CLI Example:
salt '*' zabbix.hostgroup_exists MyNewGroup
zabbix.hostgroup_get:
New in version 2016.3.0
Retrieve host groups according to the given parameters
Note:
This function accepts all standard hostgroup.get properities: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.2/manual/api/reference/hostgroup/get
:param name: names of the host groups
:param groupid: host group IDs
:param node: name of the node the host groups must belong to
:param nodeids: IDs of the nodes the host groups must belong to
:param hostids: return only host groups that contain the given hosts
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with host groups details, False if no convenient host group found or on failure.
CLI Example:
salt '*' zabbix.hostgroup_get MyNewGroup
zabbix.hostgroup_list:
Retrieve all host groups.
New in version 2016.3.0
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with details about host groups, False on failure.
CLI Example:
salt '*' zabbix.hostgroup_list
zabbix.hostgroup_update:
New in version 2016.3.0
Update existing hosts group
Note:
This function accepts all standard host group properties: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.4/manual/api/reference/hostgroup/object#host_group
:param groupid: ID of the host group to update
:param name: name of the host group
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of updated host groups.
CLI Example:
salt '*' zabbix.hostgroup_update 24 name='Renamed Name'
zabbix.hostinterface_create:
New in version 2016.3.0
Create new host interface
Note:
This function accepts all standard host group interface: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/3.0/manual/api/reference/hostinterface/object
:param hostid: ID of the host the interface belongs to
:param ip_: IP address used by the interface
:param dns: DNS name used by the interface
:param main: whether the interface is used as default on the host (0 - not default, 1 - default)
:param port: port number used by the interface
:param type: Interface type (1 - agent; 2 - SNMP; 3 - IPMI; 4 - JMX)
:param useip: Whether the connection should be made via IP (0 - connect
using host DNS name; 1 - connect using host IP address for this host
interface)
:param _connection_user: Optional - zabbix user (can also be set in opts or
pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in
opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set
in opts, pillar, see module's docstring)
:return: ID of the created host interface, False on failure.
CLI Example:
salt '*' zabbix.hostinterface_create 10105 192.193.194.197
zabbix.hostinterface_delete:
Delete host interface
New in version 2016.3.0
:param interfaceids: IDs of the host interfaces to delete
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: ID of deleted host interfaces, False on failure.
CLI Example:
salt '*' zabbix.hostinterface_delete 50
zabbix.hostinterface_get:
New in version 2016.3.0
Retrieve host groups according to the given parameters
Note:
This function accepts all standard hostinterface.get properities:
keyword argument names differ depending on your zabbix version, see
here__.
.. __: https://www.zabbix.com/documentation/2.4/manual/api/reference/hostinterface/get
:param hostids: Return only host interfaces used by the given hosts.
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with host interfaces details, False if no convenient host interfaces found or on failure.
CLI Example:
salt '*' zabbix.hostinterface_get 101054
zabbix.hostinterface_update:
New in version 2016.3.0
Update host interface
Note:
This function accepts all standard hostinterface: keyword argument
names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.4/manual/api/reference/hostinterface/object#host_interface
:param interfaceid: ID of the hostinterface to update
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: ID of the updated host interface, False on failure.
CLI Example:
salt '*' zabbix.hostinterface_update 6 ip_=0.0.0.2
zabbix.mediatype_create:
Create new mediatype
Note:
This function accepts all standard mediatype properties: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/3.0/manual/api/reference/mediatype/object
:param mediatype: media type - 0: email, 1: script, 2: sms, 3: Jabber, 100: Ez Texting
:param exec_path: exec path - Required for script and Ez Texting types, see Zabbix API docs
:param gsm_modem: exec path - Required for sms type, see Zabbix API docs
:param smtp_email: email address from which notifications will be sent, required for email type
:param smtp_helo: SMTP HELO, required for email type
:param smtp_server: SMTP server, required for email type
:param status: whether the media type is enabled - 0: enabled, 1: disabled
:param username: authentication user, required for Jabber and Ez Texting types
:param passwd: authentication password, required for Jabber and Ez Texting types
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
return: ID of the created mediatype.
CLI Example:
salt '*' zabbix.mediatype_create 'Email' 0 smtp_email='noreply@example.com'
smtp_server='mailserver.example.com' smtp_helo='zabbix.example.com'
zabbix.mediatype_delete:
Delete mediatype
:param interfaceids: IDs of the mediatypes to delete
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: ID of deleted mediatype, False on failure.
CLI Example:
salt '*' zabbix.mediatype_delete 3
zabbix.mediatype_get:
Retrieve mediatypes according to the given parameters.
Args:
name: Name or description of the mediatype
mediatypeids: ids of the mediatypes
optional connection_args:
_connection_user: zabbix user (can also be set in opts or pillar, see module's docstring)
_connection_password: zabbix password (can also be set in opts or pillar, see module's docstring)
_connection_url: url of zabbix frontend (can also be set in opts or pillar, see module's docstring)
all optional mediatype.get parameters: keyword argument names depends on your zabbix version, see:
https://www.zabbix.com/documentation/2.2/manual/api/reference/mediatype/get
Returns:
Array with mediatype details, False if no mediatype found or on failure.
CLI Example:
salt '*' zabbix.mediatype_get name='Email'
salt '*' zabbix.mediatype_get mediatypeids="['1', '2', '3']"
zabbix.mediatype_update:
Update existing mediatype
Note:
This function accepts all standard mediatype properties: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/3.0/manual/api/reference/mediatype/object
:param mediatypeid: ID of the mediatype to update
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of the updated mediatypes, False on failure.
CLI Example:
salt '*' zabbix.usergroup_update 8 name="Email update"
zabbix.run_query:
Send Zabbix API call
Args:
method: actual operation to perform via the API
params: parameters required for specific method
optional connection_args:
_connection_user: zabbix user (can also be set in opts or pillar, see module's docstring)
_connection_password: zabbix password (can also be set in opts or pillar, see module's docstring)
_connection_url: url of zabbix frontend (can also be set in opts or pillar, see module's docstring)
all optional template.get parameters: keyword argument names depends on your zabbix version, see:
https://www.zabbix.com/documentation/2.4/manual/api/reference/
Returns:
Response from Zabbix API
CLI Example:
salt '*' zabbix.run_query proxy.create '{"host": "zabbixproxy.domain.com", "status": "5"}'
zabbix.substitute_params:
New in version 2017.7.0
Go through Zabbix object params specification and if needed get given object ID from Zabbix API and put it back
as a value. Definition of the object is done via dict with keys "query_object" and "query_name".
:param input_object: Zabbix object type specified in state file
:param extend_params: Specify query with params
:param filter_key: Custom filtering key (default: name)
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Params structure with values converted to string for further comparison purposes
CLI Example:
salt '*' zabbix.substitute_params '{"query_object": "object_name", "query_name": "specific_object_name"}'
zabbix.template_get:
Retrieve templates according to the given parameters.
Args:
host: technical name of the template
name: visible name of the template
hostids: ids of the templates
optional connection_args:
_connection_user: zabbix user (can also be set in opts or pillar, see module's docstring)
_connection_password: zabbix password (can also be set in opts or pillar, see module's docstring)
_connection_url: url of zabbix frontend (can also be set in opts or pillar, see module's docstring)
all optional template.get parameters: keyword argument names depends on your zabbix version, see:
https://www.zabbix.com/documentation/2.4/manual/api/reference/template/get
Returns:
Array with convenient template details, False if no template found or on failure.
CLI Example:
salt '*' zabbix.template_get name='Template OS Linux'
salt '*' zabbix.template_get templateids="['10050', '10001']"
zabbix.user_addmedia:
Add new media to multiple users. Available only for Zabbix version 3.4 or older.
New in version 2016.3.0
:param userids: ID of the user that uses the media
:param active: Whether the media is enabled (0 enabled, 1 disabled)
:param mediatypeid: ID of the media type used by the media
:param period: Time when the notifications can be sent as a time period
:param sendto: Address, user name or other identifier of the recipient
:param severity: Trigger severities to send notifications about
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of the created media.
CLI Example:
salt '*' zabbix.user_addmedia 4 active=0 mediatypeid=1 period='1-7,00:00-24:00' sendto='support2@example.com'
severity=63
zabbix.user_create:
New in version 2016.3.0
Create new zabbix user
Note:
This function accepts all standard user properties: keyword argument
names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.0/manual/appendix/api/user/definitions#user
:param alias: user alias
:param passwd: user's password
:param usrgrps: user groups to add the user to
:param _connection_user: zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: url of zabbix frontend (can also be set in opts or pillar, see module's docstring)
:param firstname: string with firstname of the user, use 'firstname' instead of 'name' parameter to not mess
with value supplied from Salt sls file.
:return: On success string with id of the created user.
CLI Example:
salt '*' zabbix.user_create james password007 '[7, 12]' firstname='James Bond'
zabbix.user_delete:
Delete zabbix users.
New in version 2016.3.0
:param users: array of users (userids) to delete
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: On success array with userids of deleted users.
CLI Example:
salt '*' zabbix.user_delete 15
zabbix.user_deletemedia:
Delete media by id. Available only for Zabbix version 3.4 or older.
New in version 2016.3.0
:param mediaids: IDs of the media to delete
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of the deleted media, False on failure.
CLI Example:
salt '*' zabbix.user_deletemedia 27
zabbix.user_exists:
Checks if user with given alias exists.
New in version 2016.3.0
:param alias: user alias
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: True if user exists, else False.
CLI Example:
salt '*' zabbix.user_exists james
zabbix.user_get:
Retrieve users according to the given parameters.
New in version 2016.3.0
:param alias: user alias
:param userids: return only users with the given IDs
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with details of convenient users, False on failure of if no user found.
CLI Example:
salt '*' zabbix.user_get james
zabbix.user_getmedia:
New in version 2016.3.0
Retrieve media according to the given parameters
Note:
This function accepts all standard usermedia.get properties: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/3.2/manual/api/reference/usermedia/get
:param userids: return only media that are used by the given users
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: List of retrieved media, False on failure.
CLI Example:
salt '*' zabbix.user_getmedia
zabbix.user_list:
Retrieve all of the configured users.
New in version 2016.3.0
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with user details.
CLI Example:
salt '*' zabbix.user_list
zabbix.user_update:
New in version 2016.3.0
Update existing users
Note:
This function accepts all standard user properties: keyword argument
names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.0/manual/appendix/api/user/definitions#user
:param userid: id of the user to update
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Id of the updated user on success.
CLI Example:
salt '*' zabbix.user_update 16 visible_name='James Brown'
zabbix.usergroup_create:
New in version 2016.3.0
Create new user group
Note:
This function accepts all standard user group properties: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.0/manual/appendix/api/usergroup/definitions#user_group
:param name: name of the user group
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of the created user groups.
CLI Example:
salt '*' zabbix.usergroup_create GroupName
zabbix.usergroup_delete:
New in version 2016.3.0
:param usergroupids: IDs of the user groups to delete
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of the deleted user groups.
CLI Example:
salt '*' zabbix.usergroup_delete 28
zabbix.usergroup_exists:
Checks if at least one user group that matches the given filter criteria exists
New in version 2016.3.0
:param name: names of the user groups
:param node: name of the node the user groups must belong to (This will override the nodeids parameter.)
:param nodeids: IDs of the nodes the user groups must belong to
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: True if at least one user group that matches the given filter criteria exists, else False.
CLI Example:
salt '*' zabbix.usergroup_exists Guests
zabbix.usergroup_get:
New in version 2016.3.0
Retrieve user groups according to the given parameters
Note:
This function accepts all usergroup_get properties: keyword argument
names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.4/manual/api/reference/usergroup/get
:param name: names of the user groups
:param usrgrpids: return only user groups with the given IDs
:param userids: return only user groups that contain the given users
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with convenient user groups details, False if no user group found or on failure.
CLI Example:
salt '*' zabbix.usergroup_get Guests
zabbix.usergroup_list:
Retrieve all enabled user groups.
New in version 2016.3.0
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: Array with enabled user groups details, False on failure.
CLI Example:
salt '*' zabbix.usergroup_list
zabbix.usergroup_update:
New in version 2016.3.0
Update existing user group
Note:
This function accepts all standard user group properties: keyword
argument names differ depending on your zabbix version, see here__.
.. __: https://www.zabbix.com/documentation/2.4/manual/api/reference/usergroup/object#user_group
:param usrgrpid: ID of the user group to update.
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
:return: IDs of the updated user group, False on failure.
CLI Example:
salt '*' zabbix.usergroup_update 8 name=guestsRenamed
zabbix.usermacro_create:
Create new host usermacro.
:param macro: name of the host usermacro
:param value: value of the host usermacro
:param hostid: hostid or templateid
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
return: ID of the created host usermacro.
CLI Example:
salt '*' zabbix.usermacro_create '{$SNMP_COMMUNITY}' 'public' 1
zabbix.usermacro_createglobal:
Create new global usermacro.
:param macro: name of the global usermacro
:param value: value of the global usermacro
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
return: ID of the created global usermacro.
CLI Example:
salt '*' zabbix.usermacro_createglobal '{$SNMP_COMMUNITY}' 'public'
zabbix.usermacro_delete:
Delete host usermacros.
:param macroids: macroids of the host usermacros
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
return: IDs of the deleted host usermacro.
CLI Example:
salt '*' zabbix.usermacro_delete 21
zabbix.usermacro_deleteglobal:
Delete global usermacros.
:param macroids: macroids of the global usermacros
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
return: IDs of the deleted global usermacro.
CLI Example:
salt '*' zabbix.usermacro_deleteglobal 21
zabbix.usermacro_get:
Retrieve user macros according to the given parameters.
Args:
macro: name of the usermacro
hostids: Return macros for the given hostids
templateids: Return macros for the given templateids
hostmacroids: Return macros with the given hostmacroids
globalmacroids: Return macros with the given globalmacroids (implies globalmacro=True)
globalmacro: if True, returns only global macros
optional connection_args:
_connection_user: zabbix user (can also be set in opts or pillar, see module's docstring)
_connection_password: zabbix password (can also be set in opts or pillar, see module's docstring)
_connection_url: url of zabbix frontend (can also be set in opts or pillar, see module's docstring)
Returns:
Array with usermacro details, False if no usermacro found or on failure.
CLI Example:
salt '*' zabbix.usermacro_get macro='{$SNMP_COMMUNITY}'
zabbix.usermacro_update:
Update existing host usermacro.
:param hostmacroid: id of the host usermacro
:param value: new value of the host usermacro
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
return: ID of the update host usermacro.
CLI Example:
salt '*' zabbix.usermacro_update 1 'public'
zabbix.usermacro_updateglobal:
Update existing global usermacro.
:param globalmacroid: id of the host usermacro
:param value: new value of the host usermacro
:param _connection_user: Optional - zabbix user (can also be set in opts or pillar, see module's docstring)
:param _connection_password: Optional - zabbix password (can also be set in opts or pillar, see module's docstring)
:param _connection_url: Optional - url of zabbix frontend (can also be set in opts, pillar, see module's docstring)
return: ID of the update global usermacro.
CLI Example:
salt '*' zabbix.usermacro_updateglobal 1 'public'
zenoss.add_device:
A function to connect to a zenoss server and add a new device entry.
Parameters:
device: (Optional) Will use the grain 'fqdn' by default.
device_class: (Optional) The device class to use. If none, will determine based on kernel grain.
collector: (Optional) The collector to use for this device. Defaults to 'localhost'.
prod_state: (Optional) The prodState to set on the device. If none, defaults to 1000 ( production )
CLI Example:
salt '*' zenoss.add_device
zenoss.device_exists:
Check to see if a device already exists in Zenoss.
Parameters:
device: (Optional) Will use the grain 'fqdn' by default
CLI Example:
salt '*' zenoss.device_exists
zenoss.find_device:
Find a device in Zenoss. If device not found, returns None.
Parameters:
device: (Optional) Will use the grain 'fqdn' by default
CLI Example:
salt '*' zenoss.find_device
zenoss.set_prod_state:
A function to set the prod_state in zenoss.
Parameters:
prod_state: (Required) Integer value of the state
device: (Optional) Will use the grain 'fqdn' by default.
CLI Example:
salt zenoss.set_prod_state 1000 hostname