Saltstack各模块文档
如果网页打开较慢 可以下载后查看https://files.cnblogs.com/files/randomlee/salt_modules_doc.md.zip
acl.delfacl:
Remove specific FACL from the specified file(s)
CLI Examples:
salt '*' acl.delfacl user myuser /tmp/house/kitchen
salt '*' acl.delfacl default:group mygroup /tmp/house/kitchen
salt '*' acl.delfacl d:u myuser /tmp/house/kitchen
salt '*' acl.delfacl g myuser /tmp/house/kitchen /tmp/house/livingroom
salt '*' acl.delfacl user myuser /tmp/house/kitchen recursive=True
acl.getfacl:
Return (extremely verbose) map of FACLs on specified file(s)
CLI Examples:
salt '*' acl.getfacl /tmp/house/kitchen
salt '*' acl.getfacl /tmp/house/kitchen /tmp/house/livingroom
salt '*' acl.getfacl /tmp/house/kitchen /tmp/house/livingroom recursive=True
acl.modfacl:
Add or modify a FACL for the specified file(s)
CLI Examples:
salt '*' acl.modfacl user myuser rwx /tmp/house/kitchen
salt '*' acl.modfacl default:group mygroup rx /tmp/house/kitchen
salt '*' acl.modfacl d:u myuser 7 /tmp/house/kitchen
salt '*' acl.modfacl g mygroup 0 /tmp/house/kitchen /tmp/house/livingroom
salt '*' acl.modfacl user myuser rwx /tmp/house/kitchen recursive=True
salt '*' acl.modfacl user myuser rwx /tmp/house/kitchen raise_err=True
acl.version:
Return facl version from getfacl --version
CLI Example:
salt '*' acl.version
acl.wipefacls:
Remove all FACLs from the specified file(s)
CLI Examples:
salt '*' acl.wipefacls /tmp/house/kitchen
salt '*' acl.wipefacls /tmp/house/kitchen /tmp/house/livingroom
salt '*' acl.wipefacls /tmp/house/kitchen /tmp/house/livingroom recursive=True
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
ansible.help:
Display help on Ansible standard module.
:param module:
:return:
ansible.list:
Lists available modules.
:return:
ansible.playbooks:
Run Ansible Playbooks
:param playbook: Which playbook to run.
:param rundir: Directory to run `ansible-playbook` in. (Default: None)
:param check: don't make any changes; instead, try to predict some
of the changes that may occur (Default: False)
:param diff: when changing (small) files and templates, show the
differences in those files; works great with --check
(default: False)
:param extra_vars: set additional variables as key=value or YAML/JSON, if
filename prepend with @, (default: None)
:param flush_cache: clear the fact cache for every host in inventory
(default: False)
:param forks: specify number of parallel processes to use
(Default: 5)
:param inventory: specify inventory host path or comma separated host
list. (Default: None) (Ansible's default is /etc/ansible/hosts)
:param limit: further limit selected hosts to an additional pattern (Default: None)
:param list_hosts: outputs a list of matching hosts; does not execute anything else
(Default: False)
:param list_tags: list all available tags (Default: False)
:param list_tasks: list all tasks that would be executed (Default: False)
:param module_path: prepend colon-separated path(s) to module library. (Default: None)
:param skip_tags: only run plays and tasks whose tags do not match these
values (Default: False)
:param start_at_task: start the playbook at the task matching this name (Default: None)
:param: syntax_check: perform a syntax check on the playbook, but do not execute it
(Default: False)
:param tags: only run plays and tasks tagged with these values (Default: None)
:return: Playbook return
CLI Example:
salt 'ansiblehost' ansible.playbook playbook=/srv/playbooks/play.yml
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
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
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
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
.. _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.
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 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:
Resest beacon configuration on the minion
CLI Example:
salt '*' beacons.reset
beacons.save:
Save all beacons on the minion
: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 Examples::
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 Examples::
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 Examples::
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
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.
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.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 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.powershell 'some command' env='{"FOO": "bar"}'
: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 be 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 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 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.powershell_all 'some command' env='{"FOO": "bar"}'
: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 be 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 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"}'
: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 be 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 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 it's 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"}'
: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'.
: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 be 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 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 "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"}'
: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'.
New in version 2018.3.0
: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 be 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 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:
.. versionadded: 2016.3.0
Execute the passed command in the background and return it's 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"}'
: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 be 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 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"}'
: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.
success_retcodes: This parameter will be 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
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"}'
: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 be 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 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"}'
: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 be 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 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 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.
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 it's 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"}'
: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 be 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 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"}'
: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 be 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 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"}'
: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 be 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 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:
.. versionadded: 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_dir:
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:
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
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:
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:
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:
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 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:
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:
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 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 : base
Salt fileserver envrionment 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:
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:
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:
List all of the files stored on the master
CLI Example:
salt '*' cp.list_master
cp.list_master_dirs:
List all of the directories stored on the master
CLI Example:
salt '*' cp.list_master_dirs
cp.list_master_symlinks:
List all of the symlinks stored on the master
CLI Example:
salt '*' cp.list_master_symlinks
cp.list_minion:
List all of the files cached on the minion
CLI Example:
salt '*' cp.list_minion
cp.list_states:
List all of the available state modules 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.
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.
cp.stat_file:
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
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
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.
CLI Example:
salt '*' default.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 to set 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.
It is more typical to use this in a templating language in formulas,
instead of directly on the command-line.
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.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.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.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.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
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.inodeusage:
Return inode usage information for volumes mounted on this minion
CLI Example:
salt '*' disk.inodeusage
disk.percent:
Return partition information for volumes mounted on this minion
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
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.
CLI Example:
salt '*' drbd.overview
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
etcd.get:
New in version 2014.7.0
Get a value from etcd, by direct path. Returns None on failure.
CLI Examples:
salt myminion etcd.get /path/to/key
salt myminion etcd.get /path/to/key profile=my_etcd_config
salt myminion etcd.get /path/to/key recurse=True profile=my_etcd_config
salt myminion etcd.get /path/to/key host=127.0.0.1 port=2379
etcd.ls:
New in version 2014.7.0
Return all keys and dirs inside a specific path. Returns an empty dict on
failure.
CLI Example:
salt myminion etcd.ls /path/to/dir/
salt myminion etcd.ls /path/to/dir/ profile=my_etcd_config
salt myminion etcd.ls /path/to/dir/ host=127.0.0.1 port=2379
etcd.rm:
New in version 2014.7.0
Delete a key from etcd. Returns True if the key was deleted, False if it was
not and None if there was a failure.
CLI Example:
salt myminion etcd.rm /path/to/key
salt myminion etcd.rm /path/to/key profile=my_etcd_config
salt myminion etcd.rm /path/to/key host=127.0.0.1 port=2379
salt myminion etcd.rm /path/to/dir recurse=True profile=my_etcd_config
etcd.set:
New in version 2014.7.0
Set a key in etcd by direct path. Optionally, create a directory
or set a TTL on the key. Returns None on failure.
CLI Example:
salt myminion etcd.set /path/to/key value
salt myminion etcd.set /path/to/key value profile=my_etcd_config
salt myminion etcd.set /path/to/key value host=127.0.0.1 port=2379
salt myminion etcd.set /path/to/dir '' directory=True
salt myminion etcd.set /path/to/key value ttl=5
etcd.tree:
New in version 2014.7.0
Recurse through etcd and return all values. Returns None on failure.
CLI Example:
salt myminion etcd.tree
salt myminion etcd.tree profile=my_etcd_config
salt myminion etcd.tree host=127.0.0.1 port=2379
salt myminion etcd.tree /path/to/keys profile=my_etcd_config
etcd.update:
New in version 2016.3.0
Sets a dictionary of values in one call. Useful for large updates
in syndic environments. The dictionary can contain a mix of formats
such as:
{
'/some/example/key': 'bar',
'/another/example/key': 'baz'
}
Or it may be a straight dictionary, which will be flattened to look
like the above format:
{
'some': {
'example': {
'key': 'bar'
}
},
'another': {
'example': {
'key': 'baz'
}
}
}
You can even mix the two formats and it will be flattened to the first
format. Leading and trailing '/' will be removed.
Empty directories can be created by setting the value of the key to an
empty dictionary.
The 'path' parameter will optionally set the root of the path to use.
CLI Example:
salt myminion etcd.update "{'/path/to/key': 'baz', '/another/key': 'bar'}"
salt myminion etcd.update "{'/path/to/key': 'baz', '/another/key': 'bar'}" profile=my_etcd_config
salt myminion etcd.update "{'/path/to/key': 'baz', '/another/key': 'bar'}" host=127.0.0.1 port=2379
salt myminion etcd.update "{'/path/to/key': 'baz', '/another/key': 'bar'}" path='/some/root'
etcd.watch:
New in version 2016.3.0
Makes a best effort to watch for a key or tree change in etcd.
Returns a dict containing the new key value ( or None if the key was
deleted ), the modifiedIndex of the key, whether the key changed or
not, the path to the key that changed and whether it is a directory or not.
If something catastrophic happens, returns {}
CLI Example:
salt myminion etcd.watch /path/to/key
salt myminion etcd.watch /path/to/key timeout=10
salt myminion etcd.watch /patch/to/key profile=my_etcd_config index=10
salt myminion etcd.watch /patch/to/key host=127.0.0.1 port=2379
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_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_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_offload:
Queries the specified network device for the state of protocol offload and other features
CLI Example:
salt '*' ethtool.show_offload <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}'
A convenient way to allow Jenkins to execute ``salt-call`` is via sudo. The
following rule in sudoers will allow the ``jenkins`` user to run only the
following command.
``/etc/sudoers`` (allow preserving the environment):
jenkins ALL=(ALL) NOPASSWD:SETENV: /usr/bin/salt-call event.send*
Call Jenkins via sudo (preserve the environment):
sudo -E salt-call event.send myco/jenkins/build/success with_env=[BUILD_ID, BUILD_URL, GIT_BRANCH, GIT_COMMIT]
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
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
See the ``mke2fs(8)`` manpage for a more complete description of these
options.
extfs.tune:
Set attributes for the specified device (using tune2fs)
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 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:
.. code-block::text
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.
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 salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' 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
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
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
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:
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
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://``).
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
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
Edit a line in the configuration file. The ``path`` and ``content``
arguments are required, as well as passing in one of the ``mode``
options.
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 becomes 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. This is based on the
``content`` argument.
- replace
If line already exists, it will be replaced.
- delete
Delete the line, once found.
- insert
Insert a line.
Note:
If ``mode=insert`` is used, at least one of the following
options must also be defined: ``location``, ``before``, or
``after``. If ``location`` is used, it takes precedence
over the other two options.
location
Defines where to place content in the line. Note this option is only
used when ``mode=insert`` is specified. If a location is passed in, it
takes precedence over both the ``before`` and ``after`` kwargs. Valid
locations are:
- 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.
This option is only used when either the ``ensure`` or ``insert`` mode
is defined.
after
Regular expression or an exact case-sensitive fragment of the string.
This option is only used when either the ``ensure`` or ``insert`` mode
is defined.
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.
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"
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
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
CLI Example:
salt '*' file.move /path/to/src /path/to/dst
file.namedtuple:
Returns a new subclass of tuple with named fields.
>>> Point = namedtuple('Point', ['x', 'y'])
>>> Point.__doc__ # docstring for the new class
'Point(x, y)'
>>> p = Point(11, y=22) # instantiate with positional args or keywords
>>> p[0] + p[1] # indexable like a plain tuple
33
>>> x, y = p # unpack like a regular tuple
>>> x, y
(11, 22)
>>> p.x + p.y # fields also accessable by name
33
>>> d = p._asdict() # convert to a dictionary
>>> d['x']
11
>>> Point(**d) # convert from a dictionary
Point(x=11, y=22)
>>> p._replace(x=100) # _replace() is like str.replace() but targets named fields
Point(x=100, y=22)
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.
CLI Example:
salt '*' file.patch /opt/file.txt /tmp/file.txt.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.
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
If canonicalize is set to True, then it return the final target
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
Remove the specified directory. Fails if a directory is not empty.
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:
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
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
mtime:
Last modification in Unix epoch 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']"
firewalld.add_interface:
Bind an interface to a zone
New in version 2016.3.0
CLI Example:
salt '*' firewalld.add_interface zone eth0
firewalld.add_masquerade:
Enable masquerade on a zone.
If zone is omitted, default zone will be used.
New in version 2015.8.0
CLI Example:
salt '*' firewalld.add_masquerade
To enable masquerade on a specific zone
salt '*' firewalld.add_masquerade dmz
firewalld.add_port:
Allow specific ports in a zone.
New in version 2015.8.0
CLI Example:
salt '*' firewalld.add_port internal 443/tcp
force_masquerade
when a zone is created ensure masquerade is also enabled
on that zone.
firewalld.add_port_fwd:
Add port forwarding.
New in version 2015.8.0
CLI Example:
salt '*' firewalld.add_port_fwd public 80 443 tcp
force_masquerade
when a zone is created ensure masquerade is also enabled
on that zone.
firewalld.add_rich_rule:
Add a rich rule to a zone
New in version 2016.11.0
CLI Example:
salt '*' firewalld.add_rich_rule zone 'rule'
firewalld.add_service:
Add a service for zone. If zone is omitted, default zone will be used.
CLI Example:
salt '*' firewalld.add_service ssh
To assign a service to a specific zone:
salt '*' firewalld.add_service ssh my_zone
firewalld.add_service_port:
Add a new port to the specified service.
New in version 2016.11.0
CLI Example:
salt '*' firewalld.add_service_port zone 80
firewalld.add_service_protocol:
Add a new protocol to the specified service.
New in version 2016.11.0
CLI Example:
salt '*' firewalld.add_service_protocol zone ssh
firewalld.add_source:
Bind a source to a zone
New in version 2016.3.0
CLI Example:
salt '*' firewalld.add_source zone 192.168.1.0/24
firewalld.allow_icmp:
Allow a specific ICMP type on a zone
New in version 2015.8.0
CLI Example:
salt '*' firewalld.allow_icmp zone echo-reply
firewalld.block_icmp:
Block a specific ICMP type on a zone
New in version 2015.8.0
CLI Example:
salt '*' firewalld.block_icmp zone echo-reply
firewalld.default_zone:
Print default zone for connections and interfaces
CLI Example:
salt '*' firewalld.default_zone
firewalld.delete_service:
Delete an existing service
CLI Example:
salt '*' firewalld.delete_service my_service
By default firewalld will be reloaded. However, to avoid reloading
you need to specify the restart as False
salt '*' firewalld.delete_service my_service False
firewalld.delete_zone:
Delete an existing zone
CLI Example:
salt '*' firewalld.delete_zone my_zone
By default firewalld will be reloaded. However, to avoid reloading
you need to specify the restart as False
salt '*' firewalld.delete_zone my_zone False
firewalld.get_icmp_types:
Print predefined icmptypes
CLI Example:
salt '*' firewalld.get_icmp_types
firewalld.get_interfaces:
List interfaces bound to a zone
New in version 2016.3.0
CLI Example:
salt '*' firewalld.get_interfaces zone
firewalld.get_masquerade:
Show if masquerading is enabled on a zone.
If zone is omitted, default zone will be used.
CLI Example:
salt '*' firewalld.get_masquerade zone
firewalld.get_rich_rules:
List rich rules bound to a zone
New in version 2016.11.0
CLI Example:
salt '*' firewalld.get_rich_rules zone
firewalld.get_service_ports:
List ports of a service.
New in version 2016.11.0
CLI Example:
salt '*' firewalld.get_service_ports zone
firewalld.get_service_protocols:
List protocols of a service.
New in version 2016.11.0
CLI Example:
salt '*' firewalld.get_service_protocols zone
firewalld.get_services:
Print predefined services
CLI Example:
salt '*' firewalld.get_services
firewalld.get_sources:
List sources bound to a zone
New in version 2016.3.0
CLI Example:
salt '*' firewalld.get_sources zone
firewalld.get_zones:
Print predefined zones
CLI Example:
salt '*' firewalld.get_zones
firewalld.list_all:
List everything added for or enabled in a zone
CLI Example:
salt '*' firewalld.list_all
List a specific zone
salt '*' firewalld.list_all my_zone
firewalld.list_icmp_block:
List ICMP blocks on a zone
New in version 2015.8.0
CLI Example:
salt '*' firewlld.list_icmp_block zone
firewalld.list_port_fwd:
List port forwarding
New in version 2015.8.0
CLI Example:
salt '*' firewalld.list_port_fwd public
firewalld.list_ports:
List all ports in a zone.
New in version 2015.8.0
CLI Example:
salt '*' firewalld.list_ports
firewalld.list_services:
List services added for zone as a space separated list.
If zone is omitted, default zone will be used.
CLI Example:
salt '*' firewalld.list_services
List a specific zone
salt '*' firewalld.list_services my_zone
firewalld.list_zones:
List everything added for or enabled in all zones
CLI Example:
salt '*' firewalld.list_zones
firewalld.make_permanent:
Make current runtime configuration permanent.
New in version 2016.3.0
CLI Example:
salt '*' firewalld.make_permanent
firewalld.new_service:
Add a new service
CLI Example:
salt '*' firewalld.new_service my_service
By default firewalld will be reloaded. However, to avoid reloading
you need to specify the restart as False
salt '*' firewalld.new_service my_service False
firewalld.new_zone:
Add a new zone
CLI Example:
salt '*' firewalld.new_zone my_zone
By default firewalld will be reloaded. However, to avoid reloading
you need to specify the restart as False
salt '*' firewalld.new_zone my_zone False
firewalld.reload_rules:
Reload the firewall rules, which makes the permanent configuration the new
runtime configuration without losing state information.
New in version 2016.11.0
CLI Example:
salt '*' firewalld.reload
firewalld.remove_interface:
Remove an interface bound to a zone
New in version 2016.3.0
CLI Example:
salt '*' firewalld.remove_interface zone eth0
firewalld.remove_masquerade:
Remove masquerade on a zone.
If zone is omitted, default zone will be used.
New in version 2015.8.0
CLI Example:
salt '*' firewalld.remove_masquerade
To remove masquerade on a specific zone
salt '*' firewalld.remove_masquerade dmz
firewalld.remove_port:
Remove a specific port from a zone.
New in version 2015.8.0
CLI Example:
salt '*' firewalld.remove_port internal 443/tcp
firewalld.remove_port_fwd:
Remove Port Forwarding.
New in version 2015.8.0
CLI Example:
salt '*' firewalld.remove_port_fwd public 80 443 tcp
firewalld.remove_rich_rule:
Add a rich rule to a zone
New in version 2016.11.0
CLI Example:
salt '*' firewalld.remove_rich_rule zone 'rule'
firewalld.remove_service:
Remove a service from zone. This option can be specified multiple times.
If zone is omitted, default zone will be used.
CLI Example:
salt '*' firewalld.remove_service ssh
To remove a service from a specific zone
salt '*' firewalld.remove_service ssh dmz
firewalld.remove_service_port:
Remove a port from the specified service.
New in version 2016.11.0
CLI Example:
salt '*' firewalld.remove_service_port zone 80
firewalld.remove_service_protocol:
Remove a protocol from the specified service.
New in version 2016.11.0
CLI Example:
salt '*' firewalld.remove_service_protocol zone ssh
firewalld.remove_source:
Remove a source bound to a zone
New in version 2016.3.0
CLI Example:
salt '*' firewalld.remove_source zone 192.168.1.0/24
firewalld.set_default_zone:
Set default zone
CLI Example:
salt '*' firewalld.set_default_zone damian
firewalld.version:
Return version from firewall-cmd
CLI Example:
salt '*' firewalld.version
freezer.clean_kwargs:
Return a dict without any of the __pub* keys (or any other keys starting
with a dunder) from the kwargs dict passed into the execution module
functions. These keys are useful for tracking what was used to invoke
the function call, but they may not be desirable to have if passing the
kwargs forward wholesale.
Usage example:
kwargs = __utils__['args.clean_kwargs'](**kwargs)
freezer.fopen:
Wrapper around open() built-in to set CLOEXEC on the fd.
This flag specifies that the file descriptor should be closed when an exec
function is invoked;
When a file descriptor is allocated (as with open or dup), this bit is
initially cleared on the new file descriptor, meaning that descriptor will
survive into the new program after exec.
NB! We still have small race condition between open and fcntl.
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 Beryllium
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
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.quote:
quote('abc def') -> 'abc%20def'
Each part of a URL, e.g. the path info, the query, etc., has a
different set of reserved characters that must be quoted.
RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax lists
the following reserved characters.
reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
"$" | ","
Each of these characters is reserved in some component of a URL,
but not necessarily in all of them.
By default, the quote function is intended for quoting the path
section of a URL. Thus, it will not encode '/'. This character
is reserved, but in typical usage the quote function is being
called on a path where the existing slash characters are used as
reserved characters.
glassfish.unquote:
unquote('abc%20def') -> 'abc def'.
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
gnome.get:
Get key in a particular GNOME schema
CLI Example:
salt '*' gnome.get user=<username> schema=org.gnome.desktop.screensaver key=idle-activation-enabled
gnome.getClockFormat:
Return the current clock format, either 12h or 24h format.
CLI Example:
salt '*' gnome.getClockFormat user=<username>
gnome.getClockShowDate:
Return the current setting, if the date is shown in the clock
CLI Example:
salt '*' gnome.getClockShowDate user=<username>
gnome.getIdleActivation:
Get whether the idle activation is enabled
CLI Example:
salt '*' gnome.getIdleActivation user=<username>
gnome.getIdleDelay:
Return the current idle delay setting in seconds
CLI Example:
salt '*' gnome.getIdleDelay user=<username>
gnome.ping:
A test to ensure the GNOME module is loaded
CLI Example:
salt '*' gnome.ping user=<username>
gnome.set:
Set key in a particular GNOME schema
CLI Example:
salt '*' gnome.set user=<username> schema=org.gnome.desktop.screensaver key=idle-activation-enabled value=False
gnome.setClockFormat:
Set the clock format, either 12h or 24h format.
CLI Example:
salt '*' gnome.setClockFormat <12h|24h> user=<username>
gnome.setClockShowDate:
Set whether the date is visible in the clock
CLI Example:
salt '*' gnome.setClockShowDate <True|False> user=<username>
gnome.setIdleActivation:
Set whether the idle activation is enabled
CLI Example:
salt '*' gnome.setIdleActivation <True|False> user=<username>
gnome.setIdleDelay:
Set the current idle delay setting in seconds
CLI Example:
salt '*' gnome.setIdleDelay <seconds> user=<username>
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"
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.
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.
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.get_or_set_hash:
Perform a one-time generation of a hash and write it to the local grains.
If that grain has already been set return the value instead.
This is useful for generating passwords or keys that are specific to a
single minion that don't need to be stored somewhere centrally.
State Example:
some_mysql_user:
mysql_user:
- present
- host: localhost
- password: {{ salt['grains.get_or_set_hash']('mysql:some_mysql_user') }}
CLI Example:
salt '*' grains.get_or_set_hash 'django: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.
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.
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.
CLI Example:
salt '*' grains.setvals "{'key1': 'val1', 'key2': 'val2'}"
group.add:
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
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:
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
CLI Example:
salt '*' group.chgid foo 4376
group.delete:
Remove the named group
name
Name group to delete
root
Directory to chroot into
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'
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.proccess_lowstates:
return proccessed lowstate data that was not blacklisted
render_module_function is used to provide your own.
defaults to from_lowstate
highstate_doc.proccesser_markdown:
Takes low state data and returns a dict of proccessed 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 proccessed
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_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 whole structure from an ini file and return it as dictionary.
API Example:
import salt
sc = salt.client.get_local_client()
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.
API Example:
import salt
sc = salt.client.get_local_client()
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 dictionary. If
the section is not found, an empty dictionary is returned.
API Example:
import salt
sc = salt.client.get_local_client()
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.
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 dictionary,
or ``None`` if nothing was removed.
API Example:
import salt
sc = salt.client.get_local_client()
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.
file_name
path of ini_file
sections : None
A dictionary representing the sections to be edited ini file
The keys are the section names and the values are the dictionary
containing the options
If the ini file does not contain sections the keys and values represent
the options
separator : =
A character used to separate keys and values. Standard ini files use
the "=" character.
New in version 2016.11.0
API Example:
import salt
sc = salt.client.get_local_client()
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 runing 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 runing 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:
Build a route script for a network interface.
CLI Example:
salt '*' ip.build_routes eth0 <settings>
ip.down:
Shutdown a network interface
CLI Example:
salt '*' ip.down eth0
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 contents of the interface routes script.
CLI Example:
salt '*' ip.get_routes eth0
ip.up:
Start up a network interface
CLI Example:
salt '*' ip.up eth0
ipset.add:
Append an entry to the specified set.
CLI Example:
salt '*' ipset.add setname 192.168.1.26
salt '*' ipset.add setname 192.168.0.3,AA:BB:CC:DD:EE:FF
ipset.check:
Check that an entry exists in the specified set.
set
The ipset name
entry
An entry in the ipset. This parameter can be a single IP address, a
range of IP addresses, or a subnet block. Example:
192.168.0.1
192.168.0.2-192.168.0.19
192.168.0.0/25
family
IP protocol version: ipv4 or ipv6
CLI Example:
salt '*' ipset.check setname '192.168.0.1 comment "Hello"'
ipset.check_set:
Check that given ipset set exists.
New in version 2014.7.0
CLI Example:
salt '*' ipset.check_set setname
ipset.delete:
Delete an entry from the specified set.
CLI Example:
salt '*' ipset.delete setname 192.168.0.3,AA:BB:CC:DD:EE:FF
ipset.delete_set:
New in version 2014.7.0
Delete ipset set.
CLI Example:
salt '*' ipset.delete_set custom_set
IPv6:
salt '*' ipset.delete_set custom_set family=ipv6
ipset.flush:
Flush entries in the specified set,
Flush all sets if set is not specified.
CLI Example:
salt '*' ipset.flush
salt '*' ipset.flush set
IPv6:
salt '*' ipset.flush
salt '*' ipset.flush set
ipset.list_sets:
New in version 2014.7.0
List all ipset sets.
CLI Example:
salt '*' ipset.list_sets
ipset.new_set:
New in version 2014.7.0
Create new custom set
CLI Example:
salt '*' ipset.new_set custom_set list:set
salt '*' ipset.new_set custom_set list:set comment=True
IPv6:
salt '*' ipset.new_set custom_set list:set family=ipv6
ipset.rename_set:
New in version 2014.7.0
Delete ipset set.
CLI Example:
salt '*' ipset.rename_set custom_set new_set=new_set_name
IPv6:
salt '*' ipset.rename_set custom_set new_set=new_set_name family=ipv6
ipset.test:
Test if an entry is in the specified set.
CLI Example:
salt '*' ipset.test setname 192.168.0.2
IPv6:
salt '*' ipset.test setname fd81:fc56:9ac7::/48
ipset.version:
Return version from ipset --version
CLI Example:
salt '*' ipset.version
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_yum.active` if a new kernel
has been installed and the system has not yet been rebooted.
The :py:func:`~salt.modules.kernelpkg_linux_yum.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_yum.list_installed`,
not the package name.
CLI Example:
salt '*' kernelpkg.remove 3.10.0-327.el7
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
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 RPM 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.rpm``).
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 envrionment 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/salt-2015.5.1-2.el7.noarch.rpm
salt '*' lowpkg.bin_pkg_info salt://salt-2015.5.1-2.el7.noarch.rpm
lowpkg.checksum:
Return if the signature of a RPM file is valid.
CLI Example:
salt '*' lowpkg.checksum /path/to/package1.rpm
salt '*' lowpkg.checksum /path/to/package1.rpm /path/to/package2.rpm
lowpkg.diff:
Return a formatted diff between current file and original in a package.
NOTE: this function includes all files (configuration and not), but does
not work on binary content.
:param package: Full pack of the RPM file
:param path: Full path to the installed file
:return: Difference or empty string. For binary files only a notification.
CLI example:
salt '*' lowpkg.diff /path/to/apache2.rpm /etc/apache2/httpd.conf
lowpkg.file_dict:
List the files that belong to a package, sorted by group. Not specifying
any packages will return a list of _every_ file on the system's rpm
database (not generally recommended).
CLI Examples:
salt '*' lowpkg.file_dict httpd
salt '*' lowpkg.file_dict httpd postfix
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 rpm database (not generally
recommended).
CLI Examples:
salt '*' lowpkg.file_list httpd
salt '*' lowpkg.file_list httpd postfix
salt '*' lowpkg.file_list
lowpkg.info:
Return a detailed package(s) summary information.
If no packages specified, all packages will be returned.
:param packages:
:param attr:
Comma-separated package attributes. If no 'attr' is specified, all available attributes returned.
Valid attributes are:
version, vendor, release, build_date, build_date_time_t, install_date, install_date_time_t,
build_host, group, source_rpm, arch, epoch, size, license, signature, packager, url, summary, description.
:param all_versions:
Return information for all installed versions of the packages
:return:
CLI example:
salt '*' lowpkg.info apache2 bash
salt '*' lowpkg.info apache2 bash attr=version
salt '*' lowpkg.info apache2 bash attr=version,build_date_iso,size
salt '*' lowpkg.info apache2 bash attr=version,build_date_iso,size all_versions=True
lowpkg.list_pkgs:
List the packages currently installed in a dict::
{'<package_name>': '<version>'}
CLI Example:
salt '*' lowpkg.list_pkgs
lowpkg.modified:
List the modified files that belong to a package. Not specifying any packages
will return a list of _all_ modified files on the system's RPM database.
New in version 2015.5.0
CLI examples:
salt '*' lowpkg.modified httpd
salt '*' lowpkg.modified httpd postfix
salt '*' lowpkg.modified
lowpkg.owner:
Return the name of the package that owns the file. Multiple file paths can
be passed. 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 Examples:
salt '*' lowpkg.owner /usr/bin/apachectl
salt '*' lowpkg.owner /usr/bin/apachectl /etc/httpd/conf/httpd.conf
lowpkg.verify:
Runs an rpm -Va on a system, and returns the results in a dict
Files with an attribute of config, doc, ghost, license or readme in the
package header can be ignored using the ``ignore_types`` keyword argument
CLI Example:
salt '*' lowpkg.verify
salt '*' lowpkg.verify httpd
salt '*' lowpkg.verify httpd postfix
salt '*' lowpkg.verify httpd postfix ignore_types=['config','doc']
lowpkg.version_cmp:
New in version 2015.8.9
Do a cmp-style comparison on two packages. Return -1 if ver1 < ver2, 0 if
ver1 == ver2, and 1 if ver1 > ver2. 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-001' '0.2.0.1-002'
lvm.fullversion:
Return all version info from lvm version
CLI Example:
salt '*' lvm.fullversion
lvm.lvcreate:
Create a new logical volume, with option for which physical volume to be used
CLI Examples:
salt '*' lvm.lvcreate new_volume_name vg_name size=10G
salt '*' lvm.lvcreate new_volume_name vg_name extents=100 pv=/dev/sdb
salt '*' lvm.lvcreate new_snapshot vg_name snapshot=volume_name size=3G
New in version to_complete
Support for thin pools and thin volumes
CLI Examples:
salt '*' lvm.lvcreate new_thinpool_name vg_name size=20G thinpool=True
salt '*' lvm.lvcreate new_thinvolume_name vg_name/thinpool_name size=10G thinvolume=True
lvm.lvdisplay:
Return information about the logical volume(s)
lvname
logical device name
quiet
if the logical volume is not present, do not show any error
CLI Examples:
salt '*' lvm.lvdisplay
salt '*' lvm.lvdisplay /dev/vg_myserver/root
lvm.lvremove:
Remove a given existing logical volume from a named existing volume group
CLI Example:
salt '*' lvm.lvremove lvname vgname force=True
lvm.lvresize:
Return information about the logical volume(s)
CLI Examples:
salt '*' lvm.lvresize +12M /dev/mapper/vg1-test
salt '*' lvm.lvresize lvpath=/dev/mapper/vg1-test extents=+100%FREE
lvm.pvcreate:
Set a physical device to be used as an LVM physical volume
override
Skip devices, if they are already LVM physical volumes
CLI Examples:
salt mymachine lvm.pvcreate /dev/sdb1,/dev/sdb2
salt mymachine lvm.pvcreate /dev/sdb1 dataalignmentoffset=7s
lvm.pvdisplay:
Return information about the physical volume(s)
pvname
physical device name
real
dereference any symlinks and report the real device
New in version 2015.8.7
quiet
if the physical volume is not present, do not show any error
CLI Examples:
salt '*' lvm.pvdisplay
salt '*' lvm.pvdisplay /dev/md0
lvm.pvremove:
Remove a physical device being used as an LVM physical volume
override
Skip devices, if they are already not used as LVM physical volumes
CLI Examples:
salt mymachine lvm.pvremove /dev/sdb1,/dev/sdb2
lvm.version:
Return LVM version from lvm version
CLI Example:
salt '*' lvm.version
lvm.vgcreate:
Create an LVM volume group
CLI Examples:
salt mymachine lvm.vgcreate my_vg /dev/sdb1,/dev/sdb2
salt mymachine lvm.vgcreate my_vg /dev/sdb1 clustered=y
lvm.vgdisplay:
Return information about the volume group(s)
vgname
volume group name
quiet
if the volume group is not present, do not show any error
CLI Examples:
salt '*' lvm.vgdisplay
salt '*' lvm.vgdisplay nova-volumes
lvm.vgextend:
Add physical volumes to an LVM volume group
CLI Examples:
salt mymachine lvm.vgextend my_vg /dev/sdb1,/dev/sdb2
salt mymachine lvm.vgextend my_vg /dev/sdb1
lvm.vgremove:
Remove an LVM volume group
CLI Examples:
salt mymachine lvm.vgremove vgname
salt mymachine lvm.vgremove vgname force=True
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'],
}, 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.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.
:param str allow_tgt_type: Type of the targeting specification. This value will
be ignored if ``allow_tgt`` is not specified.
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 succesful.
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 eth0
salt '*' mine.send eth0_ip_addrs mine_function=network.ip_addrs eth0
salt '*' mine.send eth0_ip_addrs mine_function=network.ip_addrs 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.saltstack.com/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.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:
..verionadded:: 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``)
Additonally, 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 and subnet mask of a cidr addr
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.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'.
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.
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.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'.
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.
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.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.
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
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 'ifconfig -a'
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 'ifconfig -a'
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_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 nxps_api.rpc 'show version'
nxos_api.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.
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
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"
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:
Make a <part_type> partition with a new filesystem of <fs_type>, beginning
at <start> and ending at <end> (by default in megabytes).
<part_type> should be one of "primary", "logical", or "extended". <fs_type>
must be one of "ext2", "fat32", "fat16", "linux-swap" or "reiserfs" (if
libreiserfs is installed)
CLI Example:
salt '*' partition.mkpartfs /dev/sda logical ext2 440 670
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.clean_kwargs:
Return a dict without any of the __pub* keys (or any other keys starting
with a dunder) from the kwargs dict passed into the execution module
functions. These keys are useful for tracking what was used to invoke
the function call, but they may not be desirable to have if passing the
kwargs forward wholesale.
Usage example:
kwargs = __utils__['args.clean_kwargs'](**kwargs)
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:
This function is an alias of 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.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
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 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
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 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.
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
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 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
Filter list of installed apps from ``freeze`` and return True or False if
``pkgname`` 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.is_installed salt
pip.list:
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 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_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 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``.
CLI Example:
salt '*' pip.version
pkg.available_version:
This function is an alias of latest_version.
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,
and the ``disableexcludes`` option is also supported.
New in version 2014.7.0
Support for the ``disableexcludes`` option
CLI Example:
salt '*' pkg.latest_version <package name>
salt '*' pkg.latest_version <package name> fromrepo=epel-testing
salt '*' pkg.latest_version <package name> disableexcludes=main
salt '*' pkg.latest_version <package1> <package2> <package3> ...
pkg.clean_metadata:
New in version 2014.1.0
Cleans local yum metadata. Functionally identical to :mod:`refresh_db()
<salt.modules.yumpkg.refresh_db>`.
CLI Example:
salt '*' pkg.clean_metadata
pkg.del_repo:
Delete a repo from <basedir> (default basedir: all dirs in `reposdir` yum
option).
If the .repo file in which the repo exists does not contain any other repo
configuration, the file itself will be deleted.
CLI Examples:
salt '*' pkg.del_repo myrepo
salt '*' pkg.del_repo myrepo basedir=/path/to/dir
salt '*' pkg.del_repo myrepo basedir=/path/to/dir,/path/to/another/dir
pkg.diff:
Return a formatted diff between current files and original in a package.
NOTE: this function includes all files (configuration and not), but does
not work on binary content.
:param path: Full path to the installed file
:return: Difference string or raises and exception if examined file is binary.
CLI example:
salt '*' pkg.diff /etc/apache2/httpd.conf /etc/sudoers
pkg.download:
New in version 2015.5.0
Download packages to the local disk. Requires ``yumdownloader`` from
``yum-utils`` package.
Note:
``yum-utils`` will already be installed on the minion if the package
was installed from the Fedora / EPEL repositories.
CLI example:
salt '*' pkg.download httpd
salt '*' pkg.download httpd postfix
pkg.file_dict:
New in version 2014.1.0
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
rpm database (not generally recommended).
CLI Examples:
salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list
pkg.file_list:
New in version 2014.1.0
List the files that belong to a package. Not specifying any packages will
return a list of *every* file on the system's rpm database (not generally
recommended).
CLI Examples:
salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list
pkg.get_locked_packages:
This function is an alias of list_holds.
Changed in version 2016.3.0,2015.8.4,2015.5.10
Function renamed from ``pkg.get_locked_pkgs`` to ``pkg.list_holds``.
List information on locked packages
Note:
Requires the appropriate ``versionlock`` plugin package to be installed:
- On RHEL 5: ``yum-versionlock``
- On RHEL 6 & 7: ``yum-plugin-versionlock``
- On Fedora: ``python-dnf-plugins-extras-versionlock``
pattern : \w+(?:[.-][^-]+)*
Regular expression used to match the package name
full : True
Show the full hold definition including version and epoch. Set to
``False`` to return just the name of the package(s) being held.
CLI Example:
salt '*' pkg.list_holds
salt '*' pkg.list_holds full=False
pkg.get_repo:
Display a repo from <basedir> (default basedir: all dirs in ``reposdir``
yum option).
CLI Examples:
salt '*' pkg.get_repo myrepo
salt '*' pkg.get_repo myrepo basedir=/path/to/dir
salt '*' pkg.get_repo myrepo basedir=/path/to/dir,/path/to/another/dir
pkg.group_diff:
New in version 2014.1.0
Changed in version 2016.3.0,2015.8.4,2015.5.10
Environment groups are now supported. The key names have been renamed,
similar to the changes made in :py:func:`pkg.group_info
<salt.modules.yumpkg.group_info>`.
Lists which of a group's packages are installed and which are not
installed
CLI Example:
salt '*' pkg.group_diff 'Perl Support'
pkg.group_info:
New in version 2014.1.0
Changed in version 2016.3.0,2015.8.4,2015.5.10
The return data has changed. A new key ``type`` has been added to
distinguish environment groups from package groups. Also, keys for the
group name and group ID have been added. The ``mandatory packages``,
``optional packages``, and ``default packages`` keys have been renamed
to ``mandatory``, ``optional``, and ``default`` for accuracy, as
environment groups include other groups, and not packages. Finally,
this function now properly identifies conditional packages.
Lists packages belonging to a certain group
name
Name of the group to query
expand : False
If the specified group is an environment group, then the group will be
expanded and the return data will include package names instead of
group names.
New in version 2016.3.0
CLI Example:
salt '*' pkg.group_info 'Perl Support'
pkg.group_install:
New in version 2014.1.0
Install the passed package group(s). This is basically a wrapper around
:py:func:`pkg.install <salt.modules.yumpkg.install>`, which performs
package group resolution for the user. This function is currently
considered experimental, and should be expected to undergo changes.
name
Package group to install. To install more than one group, either use a
comma-separated list or pass the value as a python list.
CLI Examples:
salt '*' pkg.group_install 'Group 1'
salt '*' pkg.group_install 'Group 1,Group 2'
salt '*' pkg.group_install '["Group 1", "Group 2"]'
skip
Packages that would normally be installed by the package group
("default" packages), which should not be installed. Can be passed
either as a comma-separated list or a python list.
CLI Examples:
salt '*' pkg.group_install 'My Group' skip='foo,bar'
salt '*' pkg.group_install 'My Group' skip='["foo", "bar"]'
include
Packages which are included in a group, which would not normally be
installed by a ``yum groupinstall`` ("optional" packages). Note that
this will not enforce group membership; if you include packages which
are not members of the specified groups, they will still be installed.
Can be passed either as a comma-separated list or a python list.
CLI Examples:
salt '*' pkg.group_install 'My Group' include='foo,bar'
salt '*' pkg.group_install 'My Group' include='["foo", "bar"]'
Note:
Because this is essentially a wrapper around pkg.install, any argument
which can be passed to pkg.install may also be included here, and it
will be passed along wholesale.
pkg.group_list:
New in version 2014.1.0
Lists all groups known by yum on this system
CLI Example:
salt '*' pkg.group_list
pkg.groupinstall:
This function is an alias of group_install.
New in version 2014.1.0
Install the passed package group(s). This is basically a wrapper around
:py:func:`pkg.install <salt.modules.yumpkg.install>`, which performs
package group resolution for the user. This function is currently
considered experimental, and should be expected to undergo changes.
name
Package group to install. To install more than one group, either use a
comma-separated list or pass the value as a python list.
CLI Examples:
salt '*' pkg.group_install 'Group 1'
salt '*' pkg.group_install 'Group 1,Group 2'
salt '*' pkg.group_install '["Group 1", "Group 2"]'
skip
Packages that would normally be installed by the package group
("default" packages), which should not be installed. Can be passed
either as a comma-separated list or a python list.
CLI Examples:
salt '*' pkg.group_install 'My Group' skip='foo,bar'
salt '*' pkg.group_install 'My Group' skip='["foo", "bar"]'
include
Packages which are included in a group, which would not normally be
installed by a ``yum groupinstall`` ("optional" packages). Note that
this will not enforce group membership; if you include packages which
are not members of the specified groups, they will still be installed.
Can be passed either as a comma-separated list or a python list.
CLI Examples:
salt '*' pkg.group_install 'My Group' include='foo,bar'
salt '*' pkg.group_install 'My Group' include='["foo", "bar"]'
Note:
Because this is essentially a wrapper around pkg.install, any argument
which can be passed to pkg.install may also be included here, and it
will be passed along wholesale.
pkg.hold:
New in version 2014.7.0
Version-lock packages
Note:
Requires the appropriate ``versionlock`` plugin package to be installed:
- On RHEL 5: ``yum-versionlock``
- On RHEL 6 & 7: ``yum-plugin-versionlock``
- On Fedora: ``python-dnf-plugins-extras-versionlock``
name
The name of the package to be held.
Multiple Package Options:
pkgs
A list of packages to hold. Must be passed as a python list. The
``name`` parameter will be ignored if this option is passed.
Returns a dict containing the changes.
CLI Example:
salt '*' pkg.hold <package name>
salt '*' pkg.hold pkgs='["foo", "bar"]'
pkg.info_installed:
New in version 2015.8.1
Return the information of the named package(s), installed on the system.
:param all_versions:
Include information for all versions of the packages installed on the minion.
CLI example:
salt '*' pkg.info_installed <package1>
salt '*' pkg.info_installed <package1> <package2> <package3> ...
salt '*' pkg.info_installed <package1> <package2> <package3> all_versions=True
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 yum/dnf 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(s), add refresh=True to clean the yum database
before package is installed.
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 (``.i686``, ``.i586``, etc.) to the end of the
package name.
CLI Example:
salt '*' pkg.install <package name>
refresh
Whether or not to update the yum database before executing.
reinstall
Specifying reinstall=True will use ``yum reinstall`` rather than
``yum install`` for requested packages that are already installed.
If a version is specified with the requested package, then
``yum reinstall`` will only be used if the installed version
matches the requested version.
Works with ``sources`` when the package header of the source can be
matched to the name and version of an installed package.
New in version 2014.7.0
skip_verify
Skip the GPG verification check (e.g., ``--nogpgcheck``)
downloadonly
Only download the packages, do not install.
version
Install a specific version of the package, e.g. 1.2.3-4.el5. 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.)
update_holds : False
If ``True``, and this function would update the package version, any
packages held using the yum/dnf "versionlock" plugin will be unheld so
that they can be updated. Otherwise, if this function attempts to
update a held package, the held package(s) will be skipped and an
error will be raised.
New in version 2016.11.0
setopt
A comma-separated or Python list of key=value options. This list will
be expanded and ``--setopt`` prepended to each in the yum/dnf command
that is run.
CLI Example:
salt '*' pkg.install foo setopt='obsoletes=0,plugins=0'
New in version 2019.2.0
Repository Options:
fromrepo
Specify a package repository (or repositories) from which to install.
(e.g., ``yum --disablerepo='*' --enablerepo='somerepo'``)
enablerepo (ignored if ``fromrepo`` is specified)
Specify a disabled package repository (or repositories) to enable.
(e.g., ``yum --enablerepo='somerepo'``)
disablerepo (ignored if ``fromrepo`` is specified)
Specify an enabled package repository (or repositories) to disable.
(e.g., ``yum --disablerepo='somerepo'``)
disableexcludes
Disable exclude from main, for a repo or for everything.
(e.g., ``yum --disableexcludes='main'``)
New in version 2014.7.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. A specific version number can be specified
by using a single-element dict representing the package and its
version.
CLI Examples:
salt '*' pkg.install pkgs='["foo", "bar"]'
salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-4.el5"}]'
sources
A list of RPM 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.
CLI Example:
salt '*' pkg.install sources='[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]'
normalize : True
Normalize the package name by removing the architecture. This is useful
for poorly created packages which might include the architecture as an
actual part of the name such as kernel modules which match a specific
kernel version.
salt -G role:nsd pkg.install gpfs.gplbin-2.6.32-279.31.1.el6.x86_64 normalize=False
New in version 2014.7.0
diff_attr:
If a list of package attributes is specified, returned value will
contain them, eg.::
{'<package>': {
'old': {
'version': '<old-version>',
'arch': '<old-arch>'},
'new': {
'version': '<new-version>',
'arch': '<new-arch>'}}}
Valid attributes are: ``epoch``, ``version``, ``release``, ``arch``,
``install_date``, ``install_date_time_t``.
If ``all`` is specified, all valid attributes will be returned.
New in version 2018.3.0
Returns a dict containing the new package names and versions::
{'<package>': {'old': '<old-version>',
'new': '<new-version>'}}
If an attribute list in diff_attr is specified, the dict will also contain
any specified attribute, eg.::
{'<package>': {
'old': {
'version': '<old-version>',
'arch': '<old-arch>'},
'new': {
'version': '<new-version>',
'arch': '<new-arch>'}}}
pkg.latest_version:
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,
and the ``disableexcludes`` option is also supported.
New in version 2014.7.0
Support for the ``disableexcludes`` option
CLI Example:
salt '*' pkg.latest_version <package name>
salt '*' pkg.latest_version <package name> fromrepo=epel-testing
salt '*' pkg.latest_version <package name> disableexcludes=main
salt '*' pkg.latest_version <package1> <package2> <package3> ...
pkg.list_downloaded:
New in version 2017.7.0
List prefetched packages downloaded by Yum in the local disk.
CLI example:
salt '*' pkg.list_downloaded
pkg.list_holds:
Changed in version 2016.3.0,2015.8.4,2015.5.10
Function renamed from ``pkg.get_locked_pkgs`` to ``pkg.list_holds``.
List information on locked packages
Note:
Requires the appropriate ``versionlock`` plugin package to be installed:
- On RHEL 5: ``yum-versionlock``
- On RHEL 6 & 7: ``yum-plugin-versionlock``
- On Fedora: ``python-dnf-plugins-extras-versionlock``
pattern : \w+(?:[.-][^-]+)*
Regular expression used to match the package name
full : True
Show the full hold definition including version and epoch. Set to
``False`` to return just the name of the package(s) being held.
CLI Example:
salt '*' pkg.list_holds
salt '*' pkg.list_holds full=False
pkg.list_installed_patches:
New in version 2017.7.0
List installed advisory patches on the system.
CLI Examples:
salt '*' pkg.list_installed_patches
pkg.list_patches:
New in version 2017.7.0
List all known advisory patches from available repos.
refresh
force a refresh if set to True.
If set to False (default) it depends on yum if a refresh is
executed.
CLI Examples:
salt '*' pkg.list_patches
pkg.list_pkgs:
List the packages currently installed as a dict. By default, the dict
contains versions as a comma separated string::
{'<package_name>': '<version>[,<version>...]'}
versions_as_list:
If set to true, the versions are provided as a list
{'<package_name>': ['<version>', '<version>']}
attr:
If a list of package attributes is specified, returned value will
contain them in addition to version, eg.::
{'<package_name>': [{'version' : 'version', 'arch' : 'arch'}]}
Valid attributes are: ``epoch``, ``version``, ``release``, ``arch``,
``install_date``, ``install_date_time_t``.
If ``all`` is specified, all valid attributes will be returned.
New in version 2018.3.0
CLI Example:
salt '*' pkg.list_pkgs
salt '*' pkg.list_pkgs attr=version,arch
salt '*' pkg.list_pkgs attr='["version", "arch"]'
pkg.list_repo_pkgs:
New in version 2014.1.0
Changed in version 2014.7.0
All available versions of each package are now returned. This required
a slight modification to the structure of the return dict. The return
data shown below reflects the updated return dict structure. Note that
packages which are version-locked using :py:mod:`pkg.hold
<salt.modules.yumpkg.hold>` will only show the currently-installed
version, as locking a package will make other versions appear
unavailable to yum/dnf.
Changed in version 2017.7.0
By default, the versions for each package are no longer organized by
repository. To get results organized by repository, use
``byrepo=True``.
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 is recommended as it speeds up the function considerably.
Warning:
Running this function on RHEL/CentOS 6 and earlier will be more
resource-intensive, as the version of yum that ships with older
RHEL/CentOS has no yum subcommand for listing packages from a
repository. Thus, a ``yum list installed`` and ``yum list available``
are run, which generates a lot of output, which must then be analyzed
to determine which package information to include in the return data.
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. If ``byrepo`` is set to
``True``, then the return dictionary will contain repository names at the
top level, and each repository will map packages to lists of version
numbers. For example:
# With byrepo=False (default)
{
'bash': ['4.1.2-15.el6_5.2',
'4.1.2-15.el6_5.1',
'4.1.2-15.el6_4'],
'kernel': ['2.6.32-431.29.2.el6',
'2.6.32-431.23.3.el6',
'2.6.32-431.20.5.el6',
'2.6.32-431.20.3.el6',
'2.6.32-431.17.1.el6',
'2.6.32-431.11.2.el6',
'2.6.32-431.5.1.el6',
'2.6.32-431.3.1.el6',
'2.6.32-431.1.2.0.1.el6',
'2.6.32-431.el6']
}
# With byrepo=True
{
'base': {
'bash': ['4.1.2-15.el6_4'],
'kernel': ['2.6.32-431.el6']
},
'updates': {
'bash': ['4.1.2-15.el6_5.2', '4.1.2-15.el6_5.1'],
'kernel': ['2.6.32-431.29.2.el6',
'2.6.32-431.23.3.el6',
'2.6.32-431.20.5.el6',
'2.6.32-431.20.3.el6',
'2.6.32-431.17.1.el6',
'2.6.32-431.11.2.el6',
'2.6.32-431.5.1.el6',
'2.6.32-431.3.1.el6',
'2.6.32-431.1.2.0.1.el6']
}
}
fromrepo : None
Only include results from the specified repo(s). Multiple repos can be
specified, comma-separated.
enablerepo (ignored if ``fromrepo`` is specified)
Specify a disabled package repository (or repositories) to enable.
(e.g., ``yum --enablerepo='somerepo'``)
New in version 2017.7.0
disablerepo (ignored if ``fromrepo`` is specified)
Specify an enabled package repository (or repositories) to disable.
(e.g., ``yum --disablerepo='somerepo'``)
New in version 2017.7.0
byrepo : False
When ``True``, the return data for each package will be organized by
repository.
New in version 2017.7.0
cacheonly : False
When ``True``, the repo information will be retrieved from the cached
repo metadata. This is equivalent to passing the ``-C`` option to
yum/dnf.
New in version 2017.7.0
setopt
A comma-separated or Python list of key=value options. This list will
be expanded and ``--setopt`` prepended to each in the yum/dnf command
that is run.
New in version 2019.2.0
CLI Examples:
salt '*' pkg.list_repo_pkgs
salt '*' pkg.list_repo_pkgs foo bar baz
salt '*' pkg.list_repo_pkgs 'samba4*' fromrepo=base,updates
salt '*' pkg.list_repo_pkgs 'python2-*' byrepo=True
pkg.list_repos:
Lists all repos in <basedir> (default: all dirs in `reposdir` yum option).
CLI Example:
salt '*' pkg.list_repos
salt '*' pkg.list_repos basedir=/path/to/dir
salt '*' pkg.list_repos basedir=/path/to/dir,/path/to/another/dir
pkg.list_updates:
This function is an alias of list_upgrades.
Check whether or not an upgrade is available for all packages
The ``fromrepo``, ``enablerepo``, and ``disablerepo`` arguments are
supported, as used in pkg states, and the ``disableexcludes`` option is
also supported.
New in version 2014.7.0
Support for the ``disableexcludes`` option
CLI Example:
salt '*' pkg.list_upgrades
pkg.list_upgrades:
Check whether or not an upgrade is available for all packages
The ``fromrepo``, ``enablerepo``, and ``disablerepo`` arguments are
supported, as used in pkg states, and the ``disableexcludes`` option is
also supported.
New in version 2014.7.0
Support for the ``disableexcludes`` option
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 following values are specified:
repo
name by which the yum refers to the repo
name
a human-readable name for the repo
baseurl
the URL for yum to reference
mirrorlist
the URL for yum to reference
Key/Value pairs may also be removed from a repo's configuration by setting
a key to a blank value. Bear in mind that a name cannot be deleted, and a
baseurl can only be deleted if a mirrorlist is specified (or vice versa).
CLI Examples:
salt '*' pkg.mod_repo reponame enabled=1 gpgcheck=1
salt '*' pkg.mod_repo reponame basedir=/path/to/dir enabled=1
salt '*' pkg.mod_repo reponame baseurl= mirrorlist=http://host.com/
pkg.modified:
List the modified files that belong to a package. Not specifying any packages
will return a list of _all_ modified files on the system's RPM database.
New in version 2015.5.0
Filtering by flags (True or False):
size
Include only files where size changed.
mode
Include only files which file's mode has been changed.
checksum
Include only files which MD5 checksum has been changed.
device
Include only files which major and minor numbers has been changed.
symlink
Include only files which are symbolic link contents.
owner
Include only files where owner has been changed.
group
Include only files where group has been changed.
time
Include only files where modification time of the file has been
changed.
capabilities
Include only files where capabilities differ or not. Note: supported
only on newer RPM versions.
CLI Examples:
salt '*' pkg.modified
salt '*' pkg.modified httpd
salt '*' pkg.modified httpd postfix
salt '*' pkg.modified httpd owner=True group=False
pkg.normalize_name:
Strips the architecture from the specified package name, if necessary.
Circumstances where this would be done include:
* If the arch is 32 bit and the package name ends in a 32-bit arch.
* If the arch matches the OS arch, or is ``noarch``.
CLI Example:
salt '*' pkg.normalize_name zsh.x86_64
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.yumpkg.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 Examples:
salt '*' pkg.owner /usr/bin/apachectl
salt '*' pkg.owner /usr/bin/apachectl /etc/httpd/conf/httpd.conf
pkg.parse_arch:
Parse name and architecture from the specified package name.
CLI Example:
salt '*' pkg.parse_arch zsh.x86_64
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 yum/dnf 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
Package purges are not supported by yum, this function is identical to
:mod:`pkg.remove <salt.modules.yumpkg.remove>`.
name
The name of the package to be purged
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:
Check the yum repos for updated packages
Returns:
- ``True``: Updates are available
- ``False``: An error occurred
- ``None``: No updates are available
repo
Refresh just the specified repo
disablerepo
Do not refresh the specified repo
enablerepo
Refresh a disabled repo using this option
branch
Add the specified branch when refreshing
disableexcludes
Disable the excludes defined in your config files. Takes one of three
options:
- ``all`` - disable all excludes
- ``main`` - disable excludes defined in [main] in yum.conf
- ``repoid`` - disable excludes defined for that repo
setopt
A comma-separated or Python list of key=value options. This list will
be expanded and ``--setopt`` prepended to each in the yum/dnf command
that is run.
New in version 2019.2.0
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 yum/dnf 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
name
The name of the package to be removed
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.unhold:
New in version 2014.7.0
Remove version locks
Note:
Requires the appropriate ``versionlock`` plugin package to be installed:
- On RHEL 5: ``yum-versionlock``
- On RHEL 6 & 7: ``yum-plugin-versionlock``
- On Fedora: ``python-dnf-plugins-extras-versionlock``
name
The name of the package to be unheld
Multiple Package Options:
pkgs
A list of packages to unhold. Must be passed as a python list. The
``name`` parameter will be ignored if this option is passed.
Returns a dict containing the changes.
CLI Example:
salt '*' pkg.unhold <package name>
salt '*' pkg.unhold pkgs='["foo", "bar"]'
pkg.update:
New in version 2019.2.0
Calls :py:func:`pkg.upgrade <salt.modules.yumpkg.upgrade>` with
``obsoletes=False``. Mirrors the CLI behavior of ``yum update``.
See :py:func:`pkg.upgrade <salt.modules.yumpkg.upgrade>` for
further documentation.
salt '*' pkg.update
pkg.upgrade:
Run a full system upgrade (a ``yum upgrade`` or ``dnf upgrade``), or
upgrade specified packages. If the packages aren't installed, they will
not be installed.
Changed in version 2014.7.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 which modify installed packages from the
``salt-minion`` daemon's control group. This is done to keep systemd
from killing any yum/dnf 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
Changed in version 2019.2.0
Added ``obsoletes`` and ``minimal`` arguments
Returns a dictionary containing the changes:
{'<package>': {'old': '<old-version>',
'new': '<new-version>'}}
CLI Example:
salt '*' pkg.upgrade
salt '*' pkg.upgrade name=openssl
Repository Options:
fromrepo
Specify a package repository (or repositories) from which to install.
(e.g., ``yum --disablerepo='*' --enablerepo='somerepo'``)
enablerepo (ignored if ``fromrepo`` is specified)
Specify a disabled package repository (or repositories) to enable.
(e.g., ``yum --enablerepo='somerepo'``)
disablerepo (ignored if ``fromrepo`` is specified)
Specify an enabled package repository (or repositories) to disable.
(e.g., ``yum --disablerepo='somerepo'``)
disableexcludes
Disable exclude from main, for a repo or for everything.
(e.g., ``yum --disableexcludes='main'``)
New in version 2014.7
name
The name of the package to be upgraded. Note that this parameter is
ignored if "pkgs" is passed.
32-bit packages can be upgraded on 64-bit systems by appending the
architecture designation (``.i686``, ``.i586``, etc.) to the end of the
package name.
Warning: if you forget 'name=' and run pkg.upgrade openssl, ALL packages
are upgraded. This will be addressed in next releases.
CLI Example:
salt '*' pkg.upgrade name=openssl
New in version 2016.3.0
pkgs
A list of packages to upgrade from a software repository. Must be
passed as a python list. A specific version number can be specified
by using a single-element dict representing the package and its
version. If the package was not already installed on the system,
it will not be installed.
CLI Examples:
salt '*' pkg.upgrade pkgs='["foo", "bar"]'
salt '*' pkg.upgrade pkgs='["foo", {"bar": "1.2.3-4.el5"}]'
New in version 2016.3.0
normalize : True
Normalize the package name by removing the architecture. This is useful
for poorly created packages which might include the architecture as an
actual part of the name such as kernel modules which match a specific
kernel version.
salt -G role:nsd pkg.upgrade gpfs.gplbin-2.6.32-279.31.1.el6.x86_64 normalize=False
New in version 2016.3.0
minimal : False
Use upgrade-minimal instead of upgrade (e.g., ``yum upgrade-minimal``)
Goes to the 'newest' package match which fixes a problem that affects your system.
salt '*' pkg.upgrade minimal=True
New in version 2019.2.0
obsoletes : True
Controls wether yum/dnf should take obsoletes into account and remove them.
If set to ``False`` yum will use ``update`` instead of ``upgrade``
and dnf will be run with ``--obsoletes=False``
salt '*' pkg.upgrade obsoletes=False
New in version 2019.2.0
setopt
A comma-separated or Python list of key=value options. This list will
be expanded and ``--setopt`` prepended to each in the yum/dnf command
that is run.
New in version 2019.2.0
Note:
To add extra arguments to the ``yum upgrade`` command, pass them as key
word arguments. For arguments without assignments, pass ``True``
salt '*' pkg.upgrade security=True exclude='kernel*'
pkg.upgrade_available:
Check whether or not an upgrade is available for a given package
CLI Example:
salt '*' pkg.upgrade_available <package name>
pkg.verify:
New in version 2014.1.0
Runs an rpm -Va on a system, and returns the results in a dict
Pass options to modify rpm verify behavior using the ``verify_options``
keyword argument
Files with an attribute of config, doc, ghost, license or readme in the
package header can be ignored using the ``ignore_types`` keyword argument
CLI Example:
salt '*' pkg.verify
salt '*' pkg.verify httpd
salt '*' pkg.verify 'httpd postfix'
salt '*' pkg.verify 'httpd postfix' ignore_types=['config','doc']
salt '*' pkg.verify 'httpd postfix' verify_options=['nodeps','nosize']
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:
New in version 2015.5.4
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-001' '0.2.0.1-002'
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>
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.
**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:
http://pythonhosted.org/psutil/#psutil.Process
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.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
Returns a random string of the specified length.
length : 20
Any valid number of bytes.
CLI Example:
salt '*' random.get_str 128
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.
.. versionadded: 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.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.
.. versionadded: 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.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
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.
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 'Sodium'
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 'Sodium'
saltcheck.dumps:
New in version 2018.3.0
Wraps json.dumps, and assumes that ensure_ascii is False (unless explicitly
passed as True) for unicode compatibility. Note that setting it to True
will mess up any unicode characters, as they will be dumped as the string
literal version of the unicode code point.
On Python 2, encodes the result to a str since json.dumps does not want
unicode types.
You can pass an alternate json module (loaded via import_json() above)
using the _json_module argument)
saltcheck.loads:
New in version 2018.3.0
Wraps json.loads and prevents a traceback in the event that a bytestring is
passed to the function. (Python < 3.6 cannot load bytestrings)
You can pass an alternate json module (loaded via import_json() above)
using the _json_module argument)
saltcheck.memoize:
Memoize aka cache the return output of a function
given a specific set of arguments
.. versionedited:: 2016.3.4
Added **kwargs support.
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
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
CLI Example:
salt '*' saltcheck.run_state_tests postfix,common
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
CLI Example:
salt '*' saltcheck.run_state_tests postfix,common
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 pillar data.
: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
:return: Boolean status, True when the pillar_refresh event was fired successfully.
CLI Example:
salt '*' saltutil.refresh_pillar
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.
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 pillar data.
: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
:return: Boolean status, True when the pillar_refresh event was fired successfully.
CLI Example:
salt '*' saltutil.refresh_pillar
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 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. 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
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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated list of modules to blacklist based on type
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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-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_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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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. 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_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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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.
refresh : False
This argument has no affect and is included for consistency with the
other sync functions.
extmod_whitelist : None
comma-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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-seperated list of modules to sync
extmod_blacklist
comma-seperated list of modules to blacklist based on type
CLI Examples:
salt '*' saltutil.sync_thorium
salt '*' saltutil.sync_thorium saltenv=base,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-seperated list of modules to sync
extmod_blacklist : None
comma-seperated 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.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']
SaltStack, Inc provides the latest builds here:
update_url: https://repo.saltstack.com/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 v2015.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
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
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
New in version 2015.5.3
CLI Example:
salt '*' schedule.is_enabled name=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
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
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 does not start with sdb://, then it will be returned as-is.
CLI Example:
salt '*' sdb.get sdb://mymemcached/foo
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']('some_mysql_user_pass') }}'
CLI Example:
salt '*' sdb.get_or_set_hash '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.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.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:
Check whether or not a service is active.
If the name contains globbing, a dict mapping service names to True/False
values is returned.
Changed in version 2018.3.0
The service name can now be a glob (e.g. ``salt*``)
name
The name of the service to check
sig
Not implemented, but required to be accepted as it is passed by service
states
wait : 3
If the service is in the process of changing states (i.e. it is in
either the ``activating`` or ``deactivating`` state), wait up to this
amount of seconds (checking again periodically) before determining
whether the service is active.
New in version 2019.2.3
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. The password hash can be generated with this command:
``python -c "import crypt; print crypt.crypt('password',
'\$6\$SALTsalt')"``
``SALTsalt`` is the 8-character crpytographic salt. Valid characters in the
salt are ``.``, ``/``, and any alphanumeric character.
Keep in mind that the $6 represents a sha512 hash, if your OS is using a
different hashing algorithm this needs to be changed accordingly
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 Slacke 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.
: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
: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.deserialize:
Deserialize a Python object using a :py:mod:`serializer module
<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.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.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 'jinja'
salt '*' slsutil.renderer /path/to/file.sls 'jinja|yaml'
salt '*' slsutil.renderer string='Inline template! {{ saltenv }}'
salt '*' slsutil.renderer string='Hello, {{ name }}.' name='world'
slsutil.serialize:
Serialize a Python object using a :py:mod:`serializer module
<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. 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' '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
or ssh-dss
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
or ssh-dss
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``:
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,
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.
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
.. 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,
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.
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.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,
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.
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
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>`
* :py:mod:`Docs for the ``salt`` state module <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,
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.
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
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 existance 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.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,
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.
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 enpoint 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_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
Function names can be specified as globs.
New in version 2015.5.0
salt '*' sys.list_functions 'sys.list_*'
New in version ?
salt '*' sys.list_functions 'module.specific_function'
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 ?
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, it's 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 if this 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:
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.
: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.
: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 (+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.
: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 returns False.
: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:
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``
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 you don't pass the year, the
current system year will be used. (Used by set_system_date and
set_system_time)
Updates hardware clock, if present, in addition to software
(kernel) clock.
:param int years: Years digit, ie: 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.
: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 you may have to quote the text twice from 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.
: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.
Returns {"args": args, "kwargs": kwargs}.
CLI Example:
salt '*' test.arg 1 "two" 3.1 txt="hello" wow='{a: 1, b: "hello"}'
test.arg_clean:
Like 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.
Returns {"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
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.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 ``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
random_hash. This function will stay to
ensure backwards compatibility, but please
switch to using the prefered name 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 True return the exception.
This can be helpful in templates where running a module might fail as expected.
CLI Example:
<pre>
{% for i in range(0,230) %}
{{ salt['test.try'](module='ipmi.get_users', bmc_host='172.2.2.'+i)|yaml(False) }}
{% endfor %}
</pre>
test.tty:
Deprecated! Moved to cmdmod.
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 UCT (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-link 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'
tuned.active:
Return current active profile
CLI Example:
salt '*' tuned.active
tuned.list:
List the profiles available
CLI Example:
salt '*' tuned.list
tuned.off:
Turn off all profiles
CLI Example:
salt '*' tuned.off
tuned.profile:
Activate specified profile
CLI Example:
salt '*' tuned.profile virtual-guest
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 accoun
groups
List of supplementary groups of the new account
home
Home directory of the new account
shell
Login shell of the new account
unique
Allow to create users with duplicate
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
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
presist
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
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.delete_secret:
Delete secret at the path in vault. The vault policy used must allow this.
CLI Example:
salt '*' vault.delete_secret "secret/my/secret"
vault.list_secrets:
List secret keys at the path in vault. The vault policy used must allow this.
The path should end with a trailing slash.
CLI Example:
salt '*' vault.list_secrets "secret/my/"
vault.read_secret:
Return the value of key at path in vault, or entire secret
Jinja Example:
my-secret: {{ salt['vault'].read_secret('secret/my/secret', 'some-key') }}
{% set supersecret = salt['vault'].read_secret('secret/my/secret') %}
secrets:
first: {{ supersecret.first }}
second: {{ supersecret.second }}
vault.write_raw:
Set raw data at the path in vault. The vault policy used must allow this.
CLI Example:
salt '*' vault.write_raw "secret/my/secret" '{"user":"foo","password": "bar"}'
vault.write_secret:
Set secret at the path in vault. The vault policy used must allow this.
CLI Example:
salt '*' vault.write_secret "secret/my/secret" user="foo" password="bar"
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 it's 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
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
: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.gets_service_instance_via_proxy:
Decorator that connects to a target system (vCenter or ESXi host) using the
proxy details and passes the connection (vim.ServiceInstance) to
the decorated function.
Supported proxies: esxi, esxcluster, esxdatacenter.
Notes:
1. The decorated function must have a ``service_instance`` parameter
or a ``**kwarg`` type argument (name of argument is not important);
2. If the ``service_instance`` parameter is already defined, the value
is passed through to the decorated function;
3. If the ``service_instance`` parameter in not defined, the
connection is created using the proxy details and the service instance
is returned.
CLI Example:
None, this is a decorator
vsphere.ignores_kwargs:
Decorator to filter out unexpected keyword arguments from the call
kwarg_names:
List of argument names to ignore
vsphere.recursive_diff:
Returns a RecursiveDictDiffer object that computes the recursive diffs
between two dictionaries
past_dict
Past dictionary
current_dict
Current dictionary
ignore_missing_keys
Flag specifying whether to ignore keys that no longer exist in the
current_dict, but exist in the past_dict. If true, the diff will
not contain the missing keys.
Default is True.
vsphere.supports_proxies:
Decorator to specify which proxy types are supported by a function
proxy_types:
Arbitrary list of strings with the supported types of proxies
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
: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'
vsphere.wraps:
Decorator factory to apply update_wrapper() to a wrapper function
Returns a decorator that invokes update_wrapper() with the decorated
function as the wrapper argument and the arguments to wraps() as the
remaining arguments. Default arguments are as for update_wrapper().
This is a convenience function to simplify applying partial() to
update_wrapper().
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
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.
zabbix.configuration_import:
New in version 2017.7
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
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
zabbix.get_zabbix_id_mapper:
New in version 2017.7
Make ZABBIX_ID_MAPPER constant available to state modules.
:return: 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: 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.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
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
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.
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.
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
