neulab/tldr huggingface dataset:
default_acl Default acls to assign if a node is created in this connection (Default: None)
salt minion1 zookeeper.create /test/name daniel profile=prod
salt.modules.zookeeper.delete(path, version=- 1, recursive=False, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Delete znode
path   path to znode
version only delete if version matches (Default: -1 (always matches))
salt minion1 zookeeper.delete /test/name profile=prod
salt.modules.zookeeper.ensure_path(path, acls=None, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Ensure Znode path exists
path   Parent path to create
acls   list of acls dictionaries to be assigned (Default: None)
salt minion1 zookeeper.ensure_path /test/name profile=prod
salt.modules.zookeeper.exists(path, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Check if path exists
path   path to check
salt minion1 zookeeper.exists /test/name profile=prod
salt.modules.zookeeper.get(path, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Get value saved in znode
salt minion1 zookeeper.get /test/name profile=prod
salt.modules.zookeeper.get_acls(path, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Get acls on a znode
salt minion1 zookeeper.get_acls /test/name profile=prod
salt.modules.zookeeper.get_children(path, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Get children in znode path
salt minion1 zookeeper.get_children /test profile=prod
salt.modules.zookeeper.make_digest_acl(username, password, read=False, write=False, create=False, delete=False, admin=False, allperms=False) Generate acl object
NOTE: This is heavily used in the zookeeper state and probably is not useful as a cli module
username username of acl
password plain text password of acl
read   read acl
write  write acl
create create acl
delete delete acl
admin  admin acl
allperms set all other acls to True
salt minion1 zookeeper.make_digest_acl username=daniel password=mypass allperms=True
salt.modules.zookeeper.set(path, value, version=- 1, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Update znode with new value
path   znode to update
value  value to set in znode
version only update znode if version matches (Default: -1 (always matches))
salt minion1 zookeeper.set /test/name gtmanfred profile=prod
salt.modules.zookeeper.set_acls(path, acls, version=- 1, profile=None, hosts=None, scheme=None, username=None, password=None, default_acl=None) Set acls on a znode
acls   list of acl dictionaries to set on the znode
version only set acls if version matches (Default: -1 (always matches))
salt minion1 zookeeper.set_acls /test/name acls='[{"username": "gtmanfred", "password": "test", "all": True}]' profile=prod
salt.modules.zpool Module for running ZFS zpool command
salt.modules.zpool.add(zpool, *vdevs, **kwargs) Add the specified vdev's to the given storage pool
zpool  string Name of storage pool
vdevs  string One or more devices
force  boolean Forces use of device
salt '*' zpool.add myzpool /path/to/vdev1 /path/to/vdev2 [...]
salt.modules.zpool.attach(zpool, device, new_device, force=False) Attach specified device to zpool
device string Existing device name too
new_device string New device name (to be attached to device)
salt '*' zpool.attach myzpool /path/to/vdev1 /path/to/vdev2 [...]
salt.modules.zpool.clear(zpool, device=None) Clears device errors in a pool.
WARNING: The device must not be part of an active pool configuration.
zpool  string name of storage pool
device string (optional) specific device to clear
salt '*' zpool.clear mypool salt '*' zpool.clear mypool /path/to/dev
salt.modules.zpool.create(zpool, *vdevs, **kwargs) New in version 2015.5.0.
Create a simple zpool, a mirrored zpool, a zpool having nested VDEVs, a hybrid zpool with cache, spare and log drives or a zpool with RAIDZ-1, RAIDZ-2 or RAIDZ-3
vdevs  string One or move devices
force  boolean Forces use of vdevs, even if they appear in use or specify a conflicting replication level.
mountpoint string Sets the mount point for the root dataset
altroot string Equivalent to "-o cachefile=none,altroot=root"
properties dict Additional pool properties
filesystem_properties dict Additional filesystem properties
createboot boolean create a boot partition
salt '*' zpool.create myzpool /path/to/vdev1 [...] [force=True|False] salt '*' zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False] salt '*' zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False] salt '*' zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False] salt '*' zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False]
NOTE: Zpool properties can be specified at the time of creation of the pool by passing an additional argument called "properties" and specifying the properties with their respective values in the form of a python dictionary:
Filesystem properties can be specified at the time of creation of the pool by passing an additional argument called "filesystem_properties" and specifying the properties with their respective values in the form of a python dictionary:
filesystem_properties="{'property1': 'value1', 'property2': 'value2'}"
salt '*' zpool.create myzpool /path/to/vdev1 [...] properties="{'property1': 'value1', 'property2': 'value2'}"
salt.modules.zpool.create_file_vdev(size, *vdevs) Creates file based virtual devices for a zpool
salt '*' zpool.create_file_vdev 7G /path/to/vdev1 [/path/to/vdev2] [...]
NOTE: Depending on file size, the above command may take a while to return.
salt.modules.zpool.destroy(zpool, force=False) Destroys a storage pool
force  boolean Force destroy of pool
salt '*' zpool.destroy myzpool
salt.modules.zpool.detach(zpool, device) Detach specified device to zpool
device string Device to detach
salt '*' zpool.detach myzpool /path/to/vdev1
salt.modules.zpool.exists(zpool) Check if a ZFS storage pool is active
salt '*' zpool.exists myzpool
salt.modules.zpool.export(*pools, **kwargs) New in version 2015.5.0.
Export storage pools
pools  string One or more storage pools to export
force  boolean Force export of storage pools
salt '*' zpool.export myzpool ... [force=True|False] salt '*' zpool.export myzpool2 myzpool2 ... [force=True|False]
salt.modules.zpool.get(zpool, prop=None, show_source=False, parsable=True) New in version 2016.3.0.
Retrieves the given list of properties
prop   string Optional name of property to retrieve
show_source boolean Show source of property
parsable boolean Display numbers in parsable (exact) values
salt '*' zpool.get myzpool
salt.modules.zpool.healthy() Check if all zpools are healthy
salt '*' zpool.healthy
salt.modules.zpool.history(zpool=None, internal=False, verbose=False) New in version 2016.3.0.
Displays the command history of the specified pools, or all pools if no pool is specified
zpool  string Optional storage pool
internal boolean Toggle display of internally logged ZFS events
verbose boolean Toggle display of the user name, the hostname, and the zone in which the operation was performed
salt '*' zpool.upgrade myzpool
salt.modules.zpool.import_(zpool=None, new_name=None, **kwargs) New in version 2015.5.0.
Import storage pools or list pools available for import
zpool  string Optional name of storage pool
new_name string Optional new name for the storage pool
mntopts string Comma-separated list of mount options to use when mounting datasets within the pool.
force  boolean Forces import, even if the pool appears to be potentially active.
dir    string Searches for devices or files in dir, multiple dirs can be specified as follows: dir="dir1,dir2"
no_mount boolean Import the pool without mounting any file systems.
only_destroyed boolean Imports destroyed pools only. This also sets force=True.
recovery bool|str false: do not try to recovery broken pools true: try to recovery the pool by rolling back the latest transactions test: check if a pool can be recovered, but don't import it nolog: allow import without log device, recent transactions might be lost
NOTE: If feature flags are not support this forced to the default of 'false'
WARNING: When recovery is set to 'test' the result will be have imported set to True if the pool can be imported. The pool might also be imported if the pool was not broken to begin with.
salt '*' zpool.import [force=True|False] salt '*' zpool.import myzpool [mynewzpool] [force=True|False] salt '*' zpool.import myzpool dir='/tmp'
salt.modules.zpool.iostat(zpool=None, sample_time=5, parsable=True) Display I/O statistics for the given pools
zpool  string optional name of storage pool
sample_time int seconds to capture data before output default a sample of 5 seconds is used
parsable boolean display data in pythonc values (True, False, Bytes,...)
Changed in version 2018.3.1: Added `parsable` parameter that defaults to True
salt '*' zpool.iostat myzpool
salt.modules.zpool.labelclear(device, force=False) New in version 2018.3.0.
Removes ZFS label information from the specified device
device string Device name; must not be part of an active pool configuration.
force  boolean Treat exported or foreign devices as inactive
salt '*' zpool.labelclear /path/to/dev
salt.modules.zpool.list_(properties='size,alloc,free,cap,frag,health', zpool=None, parsable=True) New in version 2015.5.0.
Return information about (all) storage pools
properties string comma-separated list of properties to list
parsable boolean display numbers in parsable (exact) values
NOTE: The name property will always be included, while the frag property will get removed if not available
zpool  string optional zpool
NOTE: Multiple storage pool can be provided as a space separated list
salt '*' zpool.list salt '*' zpool.list zpool=tank salt '*' zpool.list 'size,free' salt '*' zpool.list 'size,free' tank
salt.modules.zpool.offline(zpool, *vdevs, **kwargs) New in version 2015.5.0.
Ensure that the specified devices are offline
WARNING: By default, the OFFLINE state is persistent. The device remains offline when the system is rebooted. To temporarily take a device offline, use temporary=True.
temporary boolean Enable temporarily offline
salt '*' zpool.offline myzpool /path/to/vdev1 [...] [temporary=True|False]
salt.modules.zpool.online(zpool, *vdevs, **kwargs) New in version 2015.5.0.
Ensure that the specified devices are online
vdevs  string one or more devices
expand boolean Expand the device to use all available space.
NOTE: If the device is part of a mirror or raidz then all devices must be expanded before the new space will become available to the pool.
salt '*' zpool.online myzpool /path/to/vdev1 [...]
salt.modules.zpool.reguid(zpool) Generates a new unique identifier for the pool
WARNING: You must ensure that all devices in this pool are online and healthy before performing this action.
salt '*' zpool.reguid myzpool
salt.modules.zpool.reopen(zpool) Reopen all the vdevs associated with the pool
salt '*' zpool.reopen myzpool
salt.modules.zpool.replace(zpool, old_device, new_device=None, force=False) Replaces old_device with new_device
NOTE: This is equivalent to attaching new_device, waiting for it to resilver, and then detaching old_device.
The size of new_device must be greater than or equal to the minimum size of all the devices in a mirror or raidz configuration.
old_device string Old device to replace
new_device string Optional new device
force  boolean Forces use of new_device, even if its appears to be in use.
salt '*' zpool.replace myzpool /path/to/vdev1 /path/to/vdev2
salt.modules.zpool.scrub(zpool, stop=False, pause=False) Scrub a storage pool
stop   boolean If True, cancel ongoing scrub
pause  boolean If True, pause ongoing scrub
NOTE: Pause is only available on recent versions of ZFS.
If both pause and stop are True, then stop will win.
salt '*' zpool.scrub myzpool
salt.modules.zpool.set(zpool, prop, value) Sets the given property on the specified pool
prop   string Name of property to set
value  string Value to set for the specified property
salt '*' zpool.set myzpool readonly yes
salt.modules.zpool.split(zpool, newzpool, **kwargs) New in version 2018.3.0.
Splits devices off pool creating newpool.
NOTE: All vdevs in pool must be mirrors.  At the time of the split, newzpool will be a replica of zpool.
After splitting, do not forget to import the new pool!
newzpool string Name of new storage pool
altroot string Sets altroot for newzpool
properties dict Additional pool properties for newzpool
salt '*' zpool.split datamirror databackup salt '*' zpool.split datamirror databackup altroot=/backup
salt '*' zpool.split datamirror databackup properties="{'readonly': 'on'}"
salt.modules.zpool.status(zpool=None) Return the status of the named zpool
salt '*' zpool.status myzpool
salt.modules.zpool.upgrade(zpool=None, version=None) New in version 2016.3.0.
Enables all supported features on the given pool
zpool  string Optional storage pool, applies to all otherwize
version int Version to upgrade to, if unspecified upgrade to the highest possible
WARNING: Once this is done, the pool will no longer be accessible on systems that do not support feature flags. See zpool-features(5) for details on compatibility with systems that support feature flags, but do not support all features enabled on the pool.
salt.modules.zypperpkg Package support for openSUSE via the zypper package manager
• rpm Python module.  Install with zypper install rpm-python
class salt.modules.zypperpkg.Wildcard(zypper) New in version 2017.7.0.
Converts string wildcard to a zypper query.  .. rubric:: Example
'1.2.3.4*' is '1.2.3.4.whatever.is.here' and is equal to: '1.2.3.4 >= and < 1.2.3.5'
Parameters ptn -- Pattern
Returns Query range
Z_OP = ['<', '<=', '=', '>=', '>']
salt.modules.zypperpkg.add_lock(name, root=None, **kwargs) Deprecated since version 3003: This function is deprecated. Please use hold() instead.
Add a package lock. Specify packages to lock by exact name.
salt '*' pkg.add_lock <package name> salt '*' pkg.add_lock <package1>,<package2>,<package3>
salt.modules.zypperpkg.available_version(*names, **kwargs) 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 dict will be returned for that package.
refresh force a refresh if set to True (default).  If set to False it depends on zypper if a refresh is executed or not.
salt.modules.zypperpkg.clean_locks(root=None) Remove unused locks that do not currently (with regard to repositories used) lock any package.
root   Operate on a different root directory.
salt '*' pkg.clean_locks
salt.modules.zypperpkg.del_repo(repo, root=None) Delete a repo.
salt '*' pkg.del_repo alias
salt.modules.zypperpkg.diff(*paths, **kwargs) 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.
The root parameter can also be passed via the keyword argument.
salt.modules.zypperpkg.download(*packages, **kwargs) Download packages to the local disk.
refresh force a refresh if set to True.  If set to False (default) it depends on zypper if a refresh is executed.
salt.modules.zypperpkg.file_dict(*packages, **kwargs) 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).
salt.modules.zypperpkg.file_list(*packages, **kwargs) 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).
salt.modules.zypperpkg.get_repo(repo, root=None, **kwargs) Display a repo.
salt '*' pkg.get_repo alias
salt.modules.zypperpkg.hold(name=None, pkgs=None, **kwargs) New in version 3003.
Add a package hold.  Specify one of name and pkgs.
name   A package name to hold, or a comma-separated list of package names to hold.
pkgs   A list of packages to hold.  The name parameter will be ignored if this option is passed.
salt '*' pkg.hold <package name> salt '*' pkg.hold <package1>,<package2>,<package3> salt '*' pkg.hold pkgs='["foo", "bar"]'
salt.modules.zypperpkg.info_available(*names, **kwargs) Return the information of the named package available for the system.
salt '*' pkg.info_available <package1> salt '*' pkg.info_available <package1> <package2> <package3> ...
salt.modules.zypperpkg.info_installed(*names, **kwargs) Return the information of the named package(s), installed on the system.
• names -- Names of the packages to get information about.
• errors --
Handle RPM field errors. If 'ignore' is chosen, then various mistakes are simply ignored and omitted from the texts or strings. If 'report' is chonen, then a field with a mistake is not returned, instead a 'N/A (broken)' (not available, broken) text is placed.
Valid attributes are: ignore, report
• all_versions -- Include information for all versions of the packages installed on the minion.
• root -- Operate on a different root directory.
salt '*' pkg.info_installed <package1> salt '*' pkg.info_installed <package1> <package2> <package3> ... salt '*' pkg.info_installed <package1> <package2> <package3> all_versions=True salt '*' pkg.info_installed <package1> attr=version,vendor all_versions=True salt '*' pkg.info_installed <package1> <package2> <package3> ... attr=version,vendor salt '*' pkg.info_installed <package1> <package2> <package3> ... attr=version,vendor errors=ignore salt '*' pkg.info_installed <package1> <package2> <package3> ... attr=version,vendor errors=report
salt.modules.zypperpkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, downloadonly=None, skip_verify=False, version=None, ignore_repo_failure=False, no_recommends=False, root=None, **kwargs) 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 zypper 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 config option called systemd.scope, with a value of False (no quotes).
Install the passed package(s), add refresh=True to force a 'zypper refresh' before package is installed.
skip_verify Skip the GPG verification check (e.g., --no-gpg-checks)
version Can be either a version number, or the combination of a comparison operator (<, >, <=, >=, =) and a version number (ex. '>1.2.3-4').  This parameter is ignored if pkgs or sources is passed.
resolve_capabilities If this option is set to True zypper will take capabilities into account. In this case names which are just provided by a package will get installed. Default is False.
salt '*' pkg.install sources='[{"foo": "salt://foo.rpm"},{"bar": "salt://bar.rpm"}]'
ignore_repo_failure Zypper returns error code 106 if one of the repositories are not available for various reasons.  In case to set strict check, this parameter needs to be set to True. Default: False.
no_recommends Do not install recommended packages, only required ones.
If an attribute list is specified in diff_attr, the dict will also contain any specified attribute, eg.:
salt.modules.zypperpkg.latest_version(*names, **kwargs) 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.
salt.modules.zypperpkg.list_downloaded(root=None, **kwargs) New in version 2017.7.0.
List prefetched packages downloaded by Zypper in the local disk.
salt.modules.zypperpkg.list_installed_patches(root=None, **kwargs) New in version 2017.7.0.
salt.modules.zypperpkg.list_installed_patterns(root=None) List installed patterns on the system.
salt '*' pkg.list_installed_patterns
salt.modules.zypperpkg.list_locks(root=None) List current package locks.
Return a dict containing the locked package with attributes:
{'<package>': {'case_sensitive': '<case_sensitive>', 'match_type': '<match_type>' 'type': '<type>'}}
salt '*' pkg.list_locks
salt.modules.zypperpkg.list_patches(refresh=False, root=None, **kwargs) New in version 2017.7.0.
salt.modules.zypperpkg.list_patterns(refresh=False, root=None) List all known patterns from available repos.
salt '*' pkg.list_patterns
salt.modules.zypperpkg.list_pkgs(versions_as_list=False, root=None, includes=None, **kwargs) List the packages currently installed as a dict. By default, the dict contains versions as a comma separated string:
root:  operate on a different root directory.
includes: List of types of packages to include (package, patch, pattern, product) By default packages are always included
removed: not supported
purge_desired: not supported
salt.modules.zypperpkg.list_products(all=False, refresh=False, root=None) List all available or installed SUSE products.
all    List all products available or only installed. Default is False.
Includes handling for OEM products, which read the OEM productline file and overwrite the release value.
salt '*' pkg.list_products salt '*' pkg.list_products all=True
salt.modules.zypperpkg.list_provides(root=None, **kwargs) New in version 2018.3.0.
List package provides of installed packages as a dict. {'<provided_name>': ['<package_name>', '<package_name>', ...]}
salt '*' pkg.list_provides
salt.modules.zypperpkg.list_repo_pkgs(*args, **kwargs) New in version 2017.7.5,2018.3.1.
# With byrepo=False (default) { 'bash': ['4.3-83.3.1', '4.3-82.6'], 'vim': ['7.4.326-12.1'] } { 'OSS': { 'bash': ['4.3-82.6'], 'vim': ['7.4.326-12.1'] }, 'OSS Update': { 'bash': ['4.3-83.3.1'] } }
salt '*' pkg.list_repo_pkgs salt '*' pkg.list_repo_pkgs foo bar baz salt '*' pkg.list_repo_pkgs 'python2-*' byrepo=True salt '*' pkg.list_repo_pkgs 'python2-*' fromrepo='OSS Updates'
salt.modules.zypperpkg.list_repos(root=None, **kwargs) Lists all repos.
salt.modules.zypperpkg.list_updates(refresh=True, root=None, **kwargs) This function is an alias of list_upgrades. List all available package upgrades on this system
refresh force a refresh if set to True (default).  If set to False it depends on zypper if a refresh is executed.
salt.modules.zypperpkg.list_upgrades(refresh=True, root=None, **kwargs) List all available package upgrades on this system
salt.modules.zypperpkg.mod_repo(repo, **kwargs) 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 or alias alias by which Zypper refers to the repo
url, mirrorlist or baseurl the URL for Zypper to reference
enabled Enable or disable (True or False) repository, but do not remove if disabled.
refresh Enable or disable (True or False) auto-refresh of the repository.
cache  Enable or disable (True or False) RPM files caching.
gpgcheck Enable or disable (True or False) GPG check for this repository.
gpgautoimport False If set to True, automatically trust and import public GPG key for the repository.
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 URL can only be deleted if a mirrorlist is specified (or vice versa).
salt '*' pkg.mod_repo alias alias=new_alias salt '*' pkg.mod_repo alias url= mirrorlist=http://host.com/
salt.modules.zypperpkg.modified(*packages, **flags) 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.
salt.modules.zypperpkg.normalize_name(name) Strips the architecture from the specified package name, if necessary.  Circumstances where this would be done include:
salt.modules.zypperpkg.owner(*paths, **kwargs) 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.
salt.modules.zypperpkg.parse_arch(name) Parse name and architecture from the specified package name.
salt.modules.zypperpkg.purge(name=None, pkgs=None, root=None, **kwargs) 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 zypper 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 config option called systemd.scope, with a value of False (no quotes).
Recursively remove a package and all dependencies which were installed with it, this will call a zypper -n remove -u
salt.modules.zypperpkg.refresh_db(force=None, root=None) Trigger a repository refresh by calling zypper refresh. Refresh will run with --force if the "force=True" flag is passed on the CLI or refreshdb_force is set to true in the pillar. The CLI option overrides the pillar setting.
It will return a dict:
salt '*' pkg.refresh_db [force=true|false]
zypper: refreshdb_force: false
salt.modules.zypperpkg.remove(name=None, pkgs=None, root=None, **kwargs) 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 zypper 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 config option called systemd.scope, with a value of False (no quotes).
Remove packages with zypper -n remove
salt.modules.zypperpkg.remove_lock(name, root=None, **kwargs) Deprecated since version 3003: This function is deprecated. Please use unhold() instead.
Remove specified package lock.
name   A package name, or a comma-separated list of package names.
salt '*' pkg.remove_lock <package name> salt '*' pkg.remove_lock <package1>,<package2>,<package3>
salt.modules.zypperpkg.resolve_capabilities(pkgs, refresh=False, root=None, **kwargs) New in version 2018.3.0.
Convert name provides in pkgs into real package names if resolve_capabilities parameter is set to True. In case of resolve_capabilities is set to False the package list is returned unchanged.
resolve_capabilities If this option is set to True the input will be checked if a package with this name exists. If not, this function will search for a package which provides this name. If one is found the output is exchanged with the real package name. In case this option is set to False (Default) the input will be returned unchanged.
salt '*' pkg.resolve_capabilities resolve_capabilities=True w3m_ssl
salt.modules.zypperpkg.search(criteria, refresh=False, **kwargs) List known packages, available to the system.
match (str) One of exact, words, substrings. Search for an exact match or for the whole words only. Default to substrings to patch partial words.
provides (bool) Search for packages which provide the search strings.
recommends (bool) Search for packages which recommend the search strings.
requires (bool) Search for packages which require the search strings.
suggests (bool) Search for packages which suggest the search strings.
conflicts (bool) Search packages conflicting with search strings.
obsoletes (bool) Search for packages which obsolete the search strings.
file_list (bool) Search for a match in the file list of packages.
search_descriptions (bool) Search also in package summaries and descriptions.
case_sensitive (bool) Perform case-sensitive search.
installed_only (bool) Show only installed packages.
not_installed_only (bool) Show only packages which are not installed.
details (bool) Show version and repository
salt '*' pkg.search <criteria>
salt.modules.zypperpkg.services_need_restart(root=None, **kwargs) New in version 3003.
salt.modules.zypperpkg.unhold(name=None, pkgs=None, **kwargs) New in version 3003.
Remove a package hold.
name   A package name to unhold, or a comma-separated list of package names to unhold.
pkgs   A list of packages to unhold.  The name parameter will be ignored if this option is passed.
salt '*' pkg.unhold <package name> salt '*' pkg.unhold <package1>,<package2>,<package3> salt '*' pkg.unhold pkgs='["foo", "bar"]'
salt.modules.zypperpkg.upgrade(refresh=True, dryrun=False, dist_upgrade=False, fromrepo=None, novendorchange=False, skip_verify=False, no_recommends=False, root=None, **kwargs) 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 zypper 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 config option called systemd.scope, with a value of False (no quotes).
Run a full system upgrade, a zypper upgrade
dryrun If set to True, it creates a debug solver log file and then perform a dry-run upgrade (no changes are made). Default: False
dist_upgrade Perform a system dist-upgrade. Default: False
fromrepo Specify a list of package repositories to upgrade from. Default: None
novendorchange If set to True, no allow vendor changes. Default: False
salt '*' pkg.upgrade salt '*' pkg.upgrade dist_upgrade=True fromrepo='["MyRepoName"]' novendorchange=True salt '*' pkg.upgrade dist_upgrade=True dryrun=True
salt.modules.zypperpkg.upgrade_available(name, **kwargs) Check whether or not an upgrade is available for a given package
salt.modules.zypperpkg.verify(*names, **kwargs) 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.
salt '*' pkg.verify salt '*' pkg.verify httpd salt '*' pkg.verify 'httpd postfix' salt '*' pkg.verify 'httpd postfix' ignore_types=['config','doc']
salt.modules.zypperpkg.version(*names, **kwargs) Returns a string representing the package version or an empty dict if not installed. If more than one package name is specified, a dict of name/version pairs is returned.
salt.modules.zypperpkg.version_cmp(ver1, ver2, ignore_epoch=False, **kwargs) New in version 2015.5.4.
netapi modules ┌──────────────┬───────────────────────────┐ │rest_cherrypy │ A script to start the     │ │              │ CherryPy WSGI server      │ ├──────────────┼───────────────────────────┤ │rest_tornado  │                           │ ├──────────────┼───────────────────────────┤ │rest_wsgi     │ A minimalist REST API for │ │              │ Salt                      │ └──────────────┴───────────────────────────┘
rest_cherrypy • A REST API for Salt
• Authentication
• Content negotiation
• Performance Expectations and Recommended Usage
• Long-Running HTTP Connections
• Timeouts
• Best Practices
• Performance Tuning
• Future Plans
• Deployment
• salt-api using the CherryPy server
• Using a WSGI-compliant web server
A script to start the CherryPy WSGI server
This is run by salt-api and started in a multiprocess.
A REST API for Salt NOTE: This module is Experimental on Windows platforms and supports limited configurations:
• doesn't support PAM authentication (i.e. external_auth: auto)
• doesn't support SSL (i.e. disable_ssl: True)
• CherryPy Python module.
Note: there is a known SSL traceback for CherryPy versions 3.2.5 through 3.7.x. Please use version 3.2.3 or the latest 10.x version instead.
• ws4py Python module for websockets support.
client_libraries
• Java: https://github.com/SUSE/salt-netapi-client
• Python: https://github.com/saltstack/pepper
setup  All steps below are performed on the machine running the Salt Master daemon. Configuration goes into the Master configuration file.
1. Install salt-api. (This step varies between OS and Linux distros.  Some package systems have a split package, others include salt-api in the main Salt package. Ensure the salt-api --version output matches the salt --version output.)
2. Install CherryPy. (Read the version caveat in the section above.)
3. Optional: generate self-signed SSL certificates.
Using a secure HTTPS connection is strongly recommended since Salt eauth authentication credentials will be sent over the wire.
1. Install the PyOpenSSL package.
2. Generate a self-signed certificate using the create_self_signed_cert() execution function.
salt-call --local tls.create_self_signed_cert
4. Edit the master config to create at least one external auth user or group following the full external auth instructions.
5. Edit the master config with the following production-ready example to enable the rest_cherrypy module. (Adjust cert paths as needed, or disable SSL (not recommended!).)
rest_cherrypy: port: 8000 ssl_crt: /etc/pki/tls/certs/localhost.crt ssl_key: /etc/pki/tls/certs/localhost.key
6. Restart the salt-master daemon.
7. Start the salt-api daemon.
configuration All available configuration options are detailed below. These settings configure the CherryPy HTTP server and do not apply when using an external server such as Apache or Nginx.
port   Required
The port for the webserver to listen on.
host   0.0.0.0 The socket interface for the HTTP server to listen on.
debug  False Starts the web server in development mode. It will reload itself when the underlying code is changed and will output more debugging info.
log_access_file Path to a file to write HTTP access logs.
log_error_file Path to a file to write HTTP error logs.
ssl_crt The path to a SSL certificate. (See below)
ssl_key The path to the private key for your SSL certificate. (See below)
ssl_chain (Optional when using PyOpenSSL) the certificate chain to pass to Context.load_verify_locations.
disable_ssl A flag to disable SSL. Warning: your Salt authentication credentials will be sent in the clear!
webhook_disable_auth False The Webhook URL requires authentication by default but external services cannot always be configured to send authentication.  See the Webhook documentation for suggestions on securing this interface.
webhook_url /hook Configure the URL endpoint for the Webhook entry point.
thread_pool 100 The number of worker threads to start up in the pool.
socket_queue_size 30 Specify the maximum number of HTTP connections to queue.
expire_responses True Whether to check for and kill HTTP responses that have exceeded the default timeout.
Deprecated since version 2016.11.9,2017.7.3,2018.3.0: The "expire_responses" configuration setting, which corresponds to the timeout_monitor setting in CherryPy, is no longer supported in CherryPy versions >= 12.0.0.
max_request_body_size 1048576 Maximum size for the HTTP request body.
collect_stats False Collect and report statistics about the CherryPy server
Reports are available via the Stats URL.
stats_disable_auth False Do not require authentication to access the /stats endpoint.
static A filesystem path to static HTML/JavaScript/CSS/image assets.
static_path /static The URL prefix to use when serving static assets out of the directory specified in the static setting.
enable_sessions True Enable or disable all endpoints that rely on session cookies. This can be useful to enforce only header-based authentication.
app    index.html A filesystem path to an HTML file that will be served as a static file.  This is useful for bootstrapping a single-page JavaScript app.
Warning! If you set this option to a custom web application, anything that uses cookie-based authentication is vulnerable to XSRF attacks.  Send the custom X-Auth-Token header instead and consider disabling the enable_sessions setting.
Changed in version 2017.7.0: Add a proof-of-concept JavaScript single-page app.
app_path /app The URL prefix to use for serving the HTML file specified in the app setting. This should be a simple name containing no slashes.
Any path information after the specified path is ignored; this is useful for apps that utilize the HTML5 history API.
root_prefix / A URL path to the main entry point for the application. This is useful for serving multiple applications from the same URL.
Authentication Authentication is performed by passing a session token with each request. Tokens are generated via the Login URL.
The token may be sent in one of two ways: as a custom header or as a session cookie. The latter is far more convenient for clients that support cookies.
• Include a custom header named X-Auth-Token.
For example, using curl:
curl -sSk https://localhost:8000/login \ -H 'Accept: application/x-yaml' \ -d username=saltdev \ -d password=saltdev \ -d eauth=pam
Copy the token value from the output and include it in subsequent requests:
curl -sSk https://localhost:8000 \ -H 'Accept: application/x-yaml' \ -H 'X-Auth-Token: 697adbdc8fe971d09ae4c2a3add7248859c87079'\ -d client=local \ -d tgt='*' \ -d fun=test.ping
• Sent via a cookie. This option is a convenience for HTTP clients that automatically handle cookie support (such as browsers).
# Write the cookie file: curl -sSk https://localhost:8000/login \ -c ~/cookies.txt \ -H 'Accept: application/x-yaml' \ -d username=saltdev \ -d password=saltdev \ -d eauth=auto
# Read the cookie file: curl -sSk https://localhost:8000 \ -b ~/cookies.txt \ -H 'Accept: application/x-yaml' \ -d client=local \ -d tgt='*' \ -d fun=test.ping
Another example using the requests library in Python:
>>> import requests >>> session = requests.Session() >>> session.post('http://localhost:8000/login', json={ 'username': 'saltdev', 'password': 'saltdev', 'eauth': 'auto', }) <Response [200]> >>> resp = session.post('http://localhost:8000', json=[{ 'client': 'local', 'tgt': '*', 'fun': 'test.arg', 'arg': ['foo', 'bar'], 'kwarg': {'baz': 'Baz!'}, }]) >>> resp.json() {u'return': [{ ...snip... }]}
SEE ALSO: You can bypass the session handling via the Run URL.
Usage This interface directly exposes Salt's Python API.  Everything possible at the CLI is possible through the Python API. Commands are executed on the Salt Master.
The root URL (/) is RPC-like in that it accepts instructions in the request body for what Salt functions to execute, and the response contains the result of those function calls.
% curl -sSi https://localhost:8000         -H 'Content-type: application/json'         -d '[{ "client": "local", "tgt": "*", "fun": "test.ping" }]' HTTP/1.1 200 OK Content-Type: application/json [...snip...]
{"return": [{"jerry": true}]}
The request body must be an array of commands. Use this workflow to build a command:
1. Choose a client interface.
2. Choose a function.
3. Fill out the remaining parameters needed for the chosen client.
The client field is a reference to the main Python classes used in Salt's Python API. Read the full Client APIs documentation, but in short:
• "local" uses LocalClient which sends commands to Minions. Equivalent to the salt CLI command.
• "runner" uses RunnerClient which invokes runner modules on the Master. Equivalent to the salt-run CLI command.
• "wheel" uses WheelClient which invokes wheel modules on the Master. Wheel modules do not have a direct CLI equivalent but they typically manage Master-side resources such as state files, pillar files, the Salt config files, and the key wheel module exposes similar functionality as the salt-key CLI command.
Most clients have variants like synchronous or asynchronous execution as well as others like batch execution. See the full list of client interfaces.
Each client requires different arguments and sometimes has different syntax.  For example, LocalClient requires the tgt argument because it forwards the command to Minions and the other client interfaces do not. LocalClient also takes arg (array) and kwarg (dictionary) arguments because these values are sent to the Minions and used to execute the requested function there. RunnerClient and WheelClient are executed directly on the Master and thus do not need or accept those arguments.
Read the method signatures in the client documentation linked above, but hopefully an example will help illustrate the concept. This example causes Salt to execute two functions -- the test.arg execution function using LocalClient and the test.arg runner function using RunnerClient; note the different structure for each command. The results for both are combined and returned as one response.
% curl -b ~/cookies.txt -sSi localhost:8000         -H 'Content-type: application/json'         -d ' [ { "client": "local", "tgt": "*", "fun": "test.arg", "arg": ["positional arg one", "positional arg two"], "kwarg": { "keyword arg one": "Hello from a minion", "keyword arg two": "Hello again from a minion" } }, { "client": "runner", "fun": "test.arg", "keyword arg one": "Hello from a master", "keyword arg two": "Runners do not support positional args" } ] ' HTTP/1.1 200 OK [...snip...] { "return": [ { "jerry": { "args": [ "positional arg one", "positional arg two" ], "kwargs": { "keyword arg one": "Hello from a minion", "keyword arg two": "Hello again from a minion", [...snip...] } }, [...snip; other minion returns here...] }, { "args": [], "kwargs": { "keyword arg two": "Runners do not support positional args", "keyword arg one": "Hello from a master" } } ] }
One more example, this time with more commonly used functions:
curl -b /tmp/cookies.txt -sSi localhost:8000         -H 'Content-type: application/json'         -d ' [ { "client": "local", "tgt": "*", "fun": "state.sls", "kwarg": { "mods": "apache", "pillar": { "lookup": { "wwwdir": "/srv/httpd/htdocs" } } } }, { "client": "runner", "fun": "cloud.create", "provider": "my-ec2-provider", "instances": "my-centos-6", "image": "ami-1624987f", "delvol_on_destroy", true } ] ' HTTP/1.1 200 OK [...snip...] { "return": [ { "jerry": { "pkg_|-install_apache_|-httpd_|-installed": { [...snip full state return here...] } } [...snip other minion returns here...] }, { [...snip full salt-cloud output here...] } ] }
Content negotiation This REST interface is flexible in what data formats it will accept as well as what formats it will return (e.g., JSON, YAML, urlencoded).
• Specify the format of data in the request body by including the Content-Type header.
• Specify the desired data format for the response body with the Accept header.
We recommend the JSON format for most HTTP requests. urlencoded data is simple and cannot express complex data structures -- and that is often required for some Salt commands, such as starting a state run that uses Pillar data. Salt's CLI tool can reformat strings passed in at the CLI into complex data structures, and that behavior also works via salt-api, but that can be brittle and since salt-api can accept JSON it is best just to send JSON.
Here is an example of sending urlencoded data:
curl -sSik https://localhost:8000 \ -b ~/cookies.txt \ -d client=runner \ -d fun='jobs.lookup_jid' \ -d jid='20150129182456704682'
urlencoded data caveats
• Only a single command may be sent per HTTP request.
• Repeating the arg parameter multiple times will cause those parameters to be combined into a single list.
Note, some popular frameworks and languages (notably jQuery, PHP, and Ruby on Rails) will automatically append empty brackets onto repeated query string parameters. E.g., ?foo[]=fooone&foo[]=footwo. This is not supported; send ?foo=fooone&foo=footwo instead, or send JSON or YAML.
A note about curl
The -d flag to curl does not automatically urlencode data which can affect passwords and other data that contains characters that must be encoded. Use the --data-urlencode flag instead. E.g.:
curl -ksi http://localhost:8000/login \ -H "Accept: application/json" \ -d username='myapiuser' \ --data-urlencode password='1234+' \ -d eauth='pam'
Performance Expectations and Recommended Usage This module provides a thin wrapper around Salt's Python API. Executing a Salt command via rest_cherrypy is directly analogous to executing a Salt command via Salt's CLI (which also uses the Python API) -- they share the same semantics, performance characteristics, and 98% of the same code. As a rule-of-thumb: if you wouldn't do it at the CLI don't do it via this API.
Long-Running HTTP Connections The CherryPy server is a production-ready, threading HTTP server written in Python. Because it makes use of a thread pool to process HTTP requests it is not ideally suited to maintaining large numbers of concurrent, synchronous connections. On moderate hardware with default settings it should top-out at around 30 to 50 concurrent connections.
That number of long-running, synchronous Salt processes is also not ideal. Like at the CLI, each Salt command run will start a process that instantiates its own LocalClient, which instantiates its own listener to the Salt event bus, and sends out its own periodic saltutil.find_job queries to determine if a Minion is still running the command. Not exactly a lightweight operation.
Timeouts In addition to the above resource overhead for long-running connections, there are the usual HTTP timeout semantics for the CherryPy server, any HTTP client being used, as well as any hardware in between such as proxies, gateways, or load balancers. rest_cherrypy can be configured not to time-out long responses via the expire_responses setting, and both LocalClient and RunnerClient have their own timeout parameters that may be passed as top-level keywords:
curl -b /tmp/cookies.txt -sSi localhost:8000         -H 'Content-type: application/json'         -d ' [ { "client": "local", "tgt": "*", "fun": "test.sleep", "kwarg": {"length": 30}, "timeout": 60 }, { "client": "runner", "fun": "test.sleep", "kwarg": {"s_time": 30}, "timeout": 60 } ] '
Best Practices Given the performance overhead and HTTP timeouts for long-running operations described above, the most effective and most scalable way to use both Salt and salt-api is to run commands asynchronously using the local_async, runner_async, and wheel_async clients.
Running asynchronous jobs results in being able to process 3x more commands per second for LocalClient and 17x more commands per second for RunnerClient, in addition to much less network traffic and memory requirements. Job returns can be fetched from Salt's job cache via the /jobs/<jid> endpoint, or they can be collected into a data store using Salt's Returner system.
The /events endpoint is specifically designed to handle long-running HTTP connections and it exposes Salt's event bus which includes job returns. Watching this endpoint first, then executing asynchronous Salt commands second, is the most lightweight and scalable way to use rest_cherrypy while still receiving job returns in real-time. But this requires clients that can properly handle the inherent asynchronicity of that workflow.
Performance Tuning The thread_pool and socket_queue_size settings can be used to increase the capacity of rest_cherrypy to handle incoming requests. Keep an eye on RAM usage as well as available file handles while testing changes to these settings. As salt-api is a thin wrapper around Salt's Python API, also keep an eye on the performance of Salt when testing.
Future Plans Now that Salt uses the Tornado concurrency library internally, we plan to improve performance in the API by taking advantage of existing processes and event listeners and to use lightweight coroutines to facilitate more simultaneous HTTP connections and better support for synchronous operations.  That effort can be tracked in issue 26505, but until that issue is closed rest_cherrypy will remain the officially recommended REST API.
Deployment The rest_cherrypy netapi module is a standard Python WSGI app. It can be deployed one of two ways.
salt-api using the CherryPy server The default configuration is to run this module using salt-api to start the Python-based CherryPy server. This server is lightweight, multi-threaded, encrypted with SSL, and should be considered production-ready.  See the section above for performance expectations.
Using a WSGI-compliant web server This module may be deployed on any WSGI-compliant server such as Apache with mod_wsgi or Nginx with FastCGI, to name just two (there are many).