neulab/tldr huggingface dataset:
remote If specified, then any remotes which contain the passed string will have their lock cleared. For example, a remote value of github will remove the lock from all github.com remotes.
type   update,checkout,mountpoint The types of lock to clear. Can be one or more of update, checkout, and mountpoint, and can be passed either as a comma-separated or Python list.
Changed in version 2018.3.0: mountpoint lock type added
salt-run cache.clear_git_lock gitfs salt-run cache.clear_git_lock git_pillar salt-run cache.clear_git_lock git_pillar type=update salt-run cache.clear_git_lock git_pillar type=update,checkout salt-run cache.clear_git_lock git_pillar type='["update", "mountpoint"]'
salt.runners.cache.clear_grains(tgt=None, tgt_type='glob') Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Clear the cached grains data of the targeted minions
salt-run cache.clear_grains
salt.runners.cache.clear_mine(tgt=None, tgt_type='glob') Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Clear the cached mine data of the targeted minions
salt-run cache.clear_mine
salt.runners.cache.clear_mine_func(tgt=None, tgt_type='glob', clear_mine_func_flag=None) Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Clear the cached mine function data of the targeted minions
salt-run cache.clear_mine_func tgt='*' clear_mine_func_flag='network.interfaces'
salt.runners.cache.clear_pillar(tgt=None, tgt_type='glob') Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Clear the cached pillar data of the targeted minions
salt-run cache.clear_pillar
salt.runners.cache.cloud(tgt, provider=None) Return cloud cache data for target.
NOTE: Only works with glob matching
tgt    Glob Target to match minion ids
provider Cloud Provider
salt-run cache.cloud 'salt*' salt-run cache.cloud glance.example.org provider=openstack
salt.runners.cache.fetch(bank, key, cachedir=None) Fetch data from a salt.cache bank.
salt-run cache.fetch cloud/active/ec2/myec2 myminion cachedir=/var/cache/salt/
salt.runners.cache.flush(bank, key=None, cachedir=None) Remove the key from the cache bank with all the key content. If no key is specified remove the entire bank with all keys and sub-banks inside.
salt-run cache.flush cloud/active/ec2/myec2 cachedir=/var/cache/salt/ salt-run cache.flush cloud/active/ec2/myec2 myminion cachedir=/var/cache/salt/
salt.runners.cache.grains(tgt, tgt_type='glob', **kwargs) Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Return cached grains of the targeted minions.
tgt    Target to match minion ids.
Changed in version 2017.7.5,2018.3.0: The tgt argument is now required to display cached grains. If not used, the function will not return grains. This optional argument will become mandatory in the Salt 3001 release.
tgt_type The type of targeting to use for matching, such as glob, list, etc.
salt-run cache.grains '*'
salt.runners.cache.list_(bank, cachedir=None) Lists entries stored in the specified bank.
salt-run cache.list cloud/active/ec2/myec2 cachedir=/var/cache/salt/
salt.runners.cache.mine(tgt=None, tgt_type='glob', **kwargs) Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Return cached mine data of the targeted minions
salt-run cache.mine
salt.runners.cache.pillar(tgt=None, tgt_type='glob', **kwargs) Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Return cached pillars of the targeted minions if tgt is set.  If tgt is not set will return cached pillars for all minions.
salt-run cache.pillar
salt.runners.cache.store(bank, key, data, cachedir=None) Lists entries stored in the specified bank.
salt-run cache.store mycache mykey 'The time has come the walrus said'
salt.runners.cloud The Salt Cloud Runner This runner wraps the functionality of salt cloud making salt cloud routines available to all internal apis via the runner system
salt.runners.cloud.action(func=None, cloudmap=None, instances=None, provider=None, instance=None, opts=None, **kwargs) Execute a single action on the given map/provider/instance
salt-run cloud.action start my-salt-vm
salt.runners.cloud.create(provider, instances, opts=None, **kwargs) Create an instance using Salt Cloud
salt-run cloud.create my-ec2-config myinstance \ image=ami-1624987f size='t1.micro' ssh_username=ec2-user \ securitygroup=default delvol_on_destroy=True
salt.runners.cloud.destroy(instances, opts=None) Destroy the named vm(s)
salt.runners.cloud.full_query(query_type='list_nodes_full') List all available cloud provider data
salt.runners.cloud.list_images(provider='all') List cloud provider images for the given providers
salt.runners.cloud.list_locations(provider='all') List cloud provider sizes for the given providers
salt.runners.cloud.list_sizes(provider='all') List cloud provider sizes for the given providers
salt.runners.cloud.map_run(path=None, opts=None, **kwargs) Execute a salt cloud map file
salt.runners.cloud.profile(prof=None, instances=None, opts=None, **kwargs) Create a cloud vm with the given profile and instances, instances can be a list or comma-delimited string
salt-run cloud.profile prof=my-ec2 instances=node1,node2,node3
salt.runners.cloud.query(query_type='list_nodes') List cloud provider data for all providers
salt.runners.cloud.select_query(query_type='list_nodes_select') List selected nodes
salt.runners.config This runner is designed to mirror the execution module config.py, but for master settings
salt.runners.config.get(key, default='', delimiter=':') Retrieve master config options, with optional nesting via the delimiter argument.
default If the key is not found, the default will be returned instead
delimiter Override the delimiter used to separate nested levels of a data structure.
salt-run config.get gitfs_remotes salt-run config.get file_roots:base salt-run config.get file_roots,base delimiter=','
salt.runners.ddns Dynamic DNS Runner New in version 2015.8.0.
Runner to interact with DNS server and create/delete/update DNS records
salt.runners.ddns.add_host(zone, name, ttl, ip, keyname, keyfile, nameserver, timeout, port=53, keyalgorithm='hmac-md5') Create both A and PTR (reverse) records for a host.
salt-run ddns.add_host domain.com my-test-vm 3600 10.20.30.40 my-tsig-key /etc/salt/tsig.keyring 10.0.0.1 5
salt.runners.ddns.create(zone, name, ttl, rdtype, data, keyname, keyfile, nameserver, timeout, port=53, keyalgorithm='hmac-md5') Create a DNS record. The nameserver must be an IP address and the master running this runner must have create privileges on that server.
salt-run ddns.create domain.com my-test-vm 3600 A 10.20.30.40 my-tsig-key /etc/salt/tsig.keyring 10.0.0.1 5
salt.runners.ddns.delete(zone, name, keyname, keyfile, nameserver, timeout, rdtype=None, data=None, port=53, keyalgorithm='hmac-md5') Delete a DNS record.
salt-run ddns.delete domain.com my-test-vm my-tsig-key /etc/salt/tsig.keyring 10.0.0.1 5 A
salt.runners.ddns.delete_host(zone, name, keyname, keyfile, nameserver, timeout, port=53, keyalgorithm='hmac-md5') Delete both forward (A) and reverse (PTR) records for a host only if the forward (A) record exists.
salt-run ddns.delete_host domain.com my-test-vm my-tsig-key /etc/salt/tsig.keyring 10.0.0.1 5
salt.runners.ddns.update(zone, name, ttl, rdtype, data, keyname, keyfile, nameserver, timeout, replace=False, port=53, keyalgorithm='hmac-md5') Replace, or update a DNS record. The nameserver must be an IP address and the master running this runner must have update privileges on that server.
NOTE: If replace is set to True, all records for this name and type will first be deleted and then recreated. Default is replace=False.
salt-run ddns.update domain.com my-test-vm 3600 A 10.20.30.40 my-tsig-key /etc/salt/tsig.keyring 10.0.0.1 5
salt.runners.digicertapi Support for Digicert.  Heavily based on the Venafi runner by Joseph Hall (jphall@saltstack.com).
Before using this module you need to register an account with Digicert's CertCentral.
Login to CertCentral, ensure you have a payment method configured and/or there are adequate funds attached to your account.  Click the Account item in the left sidebar, and select Account Access.  The right hand pane should show "Account Access" and a link to create an API key.  Create a new API key and assign it to the user that should be attached to requests coming from Salt.
NOTE CertCentral will not show the API key again after revealing it the first time.  Make sure you copy it right away or you will have to revoke it and generate a new one.
Now open /etc/salt/master and add the API key as shown below.
digicert: api_key: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABC
Restart your Salt Master.
You can also include default values of the following variables to help with creating CSRs:
digicert: api_key: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABC shatype: sha256
This API currently only supports RSA key types.  Support for other key types will be added if interest warrants.
salt.runners.digicertapi.del_cached_domain(domains) Delete cached domains from the master
salt-run digicert.del_cached_domain domain1.example.com,domain2.example.com
salt.runners.digicertapi.gen_csr(minion_id, dns_name, organization_id, ou_name=None, key_len=2048, shatype='sha256', password=None) CLI Example:
salt-run digicert.gen_csr <minion_id> <dns_name>
salt.runners.digicertapi.gen_key(minion_id, dns_name=None, password=None, key_len=2048) Generate and return a private_key. If a dns_name is passed in, the private_key will be cached under that name.
salt-run digicert.gen_key <minion_id> [dns_name] [password]
salt.runners.digicertapi.get_certificate(order_id=None, certificate_id=None, minion_id=None, cert_format='pem_all', filename=None) Retrieve a certificate by order_id or certificate_id and write it to stdout or a filename.
A list of permissible cert_formats is here: https://www.digicert.com/services/v2/documentation/appendix-certificate-formats
salt-run digicert.get_certificate order_id=48929454 cert_format=apache
Including a 'filename' will write the certificate to the desired file.  Note that some cert formats are zipped files, and some are binary.
If the certificate has not been issued, this function will return the order details inside of which will be a status (one of pending, rejected, processing, issued, revoked, canceled, needs_csr, and needs_approval)
If for some reason you want to pipe the output of this command to a file or other command you will want to leave off the filename argument and make sure to include --no-color so there will be no terminal ANSI escape sequences.
salt.runners.digicertapi.get_org_details(organization_id) Return the details for an organization
salt-run digicert.get_org_details 34
Returns a dictionary with the org details, or with 'error' and 'status' keys.
salt.runners.digicertapi.list_domain_cache() List domains that have been cached
salt-run digicert.list_domain_cache
salt.runners.digicertapi.list_domains(container_id=None) List domains that CertCentral knows about. You can filter by container_id (also known as "Division") by passing a container_id.
salt-run digicert.list_domains
salt.runners.digicertapi.list_orders(status=None) List certificate orders made to CertCentral.
salt-run digicert.list_orders
salt.runners.digicertapi.list_organizations(container_id=None, include_validation=True) List organizations that CertCentral knows about. You can filter by container_id (also known as "Division") by passing a container_id. This function returns validation information by default; pass include_validation=False to turn it off.
salt-run digicert.list_organizations
salt.runners.digicertapi.list_requests(status=None) List certificate requests made to CertCentral. You can filter by status: pending, approved, rejected
salt-run digicert.list_requests pending
salt.runners.digicertapi.order_certificate(minion_id, common_name, organization_id, validity_years, cert_key_passphrase=None, signature_hash=None, key_len=2048, dns_names=None, organization_units=None, server_platform=None, custom_expiration_date=None, comments=None, disable_renewal_notifications=False, product_type_hint=None, renewal_of_order_id=None) Order a certificate.  Requires that an Organization has been created inside Digicert's CertCentral.
See here for API documentation: https://www.digicert.com/services/v2/documentation/order/order-ssl-determinator
salt-run digicert.order_certificate my_minionid my.domain.com 10             3 signature_hash=sha256             dns_names=['this.domain.com', 'that.domain.com']             organization_units='My Domain Org Unit'             comments='Comment goes here for the approver'
This runner can also be used to renew a certificate by passing renewal_of_order_id.  Previous order details can be retrieved with digicertapi.list_orders.
salt.runners.digicertapi.show_csrs() Show certificate requests for this API key
salt-run digicert.show_csrs
salt.runners.digicertapi.show_organization(domain) Show organization information, especially the company id
salt-run digicert.show_company example.com
salt.runners.digicertapi.show_rsa(minion_id, dns_name) Show a private RSA key
salt-run digicert.show_rsa myminion domain.example.com
salt.runners.doc A runner module to collect and display the inline documentation from the various module types
salt.runners.doc.execution() Collect all the sys.doc output from each minion and return the aggregate
salt-run doc.execution
salt.runners.doc.runner() Return all inline documentation for runner modules
salt-run doc.runner
salt.runners.doc.wheel() Return all inline documentation for wheel modules
salt-run doc.wheel
salt.runners.drac Manage Dell DRAC from the Master
The login credentials need to be configured in the Salt master configuration file.
drac: username: admin password: secret
salt.runners.drac.poweroff(hostname, timeout=20, username=None, password=None) Power server off
salt-run drac.poweroff example.com
salt.runners.drac.poweron(hostname, timeout=20, username=None, password=None) Power server on
salt-run drac.poweron example.com
salt.runners.drac.pxe(hostname, timeout=20, username=None, password=None) Connect to the Dell DRAC and have the boot order set to PXE and power cycle the system to PXE boot
salt-run drac.pxe example.com
salt.runners.drac.reboot(hostname, timeout=20, username=None, password=None) Reboot a server using the Dell DRAC
salt-run drac.reboot example.com
salt.runners.drac.version(hostname, timeout=20, username=None, password=None) Display the version of DRAC
salt-run drac.version example.com
salt.runners.error Error generator to enable integration testing of salt runner error handling
salt.runners.error.error(name=None, message='') If name is None Then return empty dict
Otherwise raise an exception with __name__ from name, message from message
salt-run error salt-run error.error name="Exception" message="This is an error."
salt.runners.event Module for sending events using the runner system.
salt.runners.event.send(tag, data=None) Send an event with the given tag and data.
This is useful for sending events directly to the master from the shell with salt-run. It is also quite useful for sending events in orchestration states where the fire_event requisite isn't sufficient because it does not support sending custom data with the event.
Note that event tags will not be namespaced like events sent with the fire_event requisite! Whereas events produced from fire_event are prefixed with salt/state_result/<jid>/<minion_id>/<name>, events sent using this runner module will have no such prefix. Make sure your reactors don't expect a prefix!
• tag -- the tag to send with the event
• data -- an optional dictionary of data to send with the event
salt-run event.send my/custom/event '{"foo": "bar"}'
Orchestration Example:
# orch/command.sls
run_a_command: salt.function: - name: cmd.run - tgt: my_minion - arg: - exit {{ pillar['exit_code'] }}
send_success_event: salt.runner: - name: event.send - tag: my_event/success - data: foo: bar - require: - salt: run_a_command
send_failure_event: salt.runner: - name: event.send - tag: my_event/failure - data: baz: qux - onfail: - salt: run_a_command
salt-run state.orchestrate orch.command pillar='{"exit_code": 0}' salt-run state.orchestrate orch.command pillar='{"exit_code": 1}'
salt.runners.f5 Runner to provide F5 Load Balancer functionality
• pycontrol Python module
configuration In order to connect to a F5 Load Balancer, you must specify in the Salt master configuration the currently available load balancers
load_balancers: bigip1.example.com: username: admin password: secret bigip2.example.com: username: admin password: secret
class salt.runners.f5.F5Mgmt(lb, username, password)
add_pool_member(name, port, pool_name) Add a node to a pool
check_member_pool(member, pool_name) Check a pool member exists in a specific pool
check_pool(name) Check to see if a pool exists
check_virtualserver(name) Check to see if a virtual server exists
create_pool(name, method='ROUND_ROBIN') Create a pool on the F5 load balancer
create_vs(name, ip, port, protocol, profile, pool_name) Create a virtual server
lbmethods() List all the load balancer methods
salt.runners.f5.add_pool_member(lb, name, port, pool_name) Add a node to a pool
salt-run f5.add_pool_member load_balancer 10.0.0.1 80 my_pool
salt.runners.f5.check_member_pool(lb, member, pool_name) Check a pool member exists in a specific pool
salt-run f5.check_member_pool load_balancer 10.0.0.1 my_pool
salt.runners.f5.check_pool(lb, name) Check to see if a pool exists
salt-run f5.check_pool load_balancer pool_name
salt.runners.f5.check_virtualserver(lb, name) Check to see if a virtual server exists
salt-run f5.check_virtualserver load_balancer virtual_server
salt.runners.f5.create_pool(lb, name, method='ROUND_ROBIN') Create a pool on the F5 load balancer
salt-run f5.create_pool load_balancer pool_name loadbalance_method salt-run f5.create_pool load_balancer my_pool ROUND_ROBIN
salt.runners.f5.create_vs(lb, name, ip, port, protocol, profile, pool_name) Create a virtual server
salt-run f5.create_vs lbalancer vs_name 10.0.0.1 80 tcp http poolname
salt.runners.fileserver Directly manage the Salt fileserver plugins
salt.runners.fileserver.clear_cache(backend=None) New in version 2015.5.0.
Clear the fileserver cache from VCS fileserver backends (git, hg, svn). Executing this runner with no arguments will clear the cache for all enabled VCS fileserver backends, but this can be narrowed using the backend argument.
backend Only clear the update lock for the specified backend(s). If all passed backends start with a minus sign (-), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: backend=-roots,git) then the ones starting with a minus sign will be disregarded.
salt-run fileserver.clear_cache salt-run fileserver.clear_cache backend=git,hg salt-run fileserver.clear_cache hg salt-run fileserver.clear_cache -roots
salt.runners.fileserver.clear_file_list_cache(saltenv=None, backend=None) New in version 2016.11.0.
The Salt fileserver caches the files/directories/symlinks for each fileserver backend and environment as they are requested. This is done to help the fileserver scale better. Without this caching, when hundreds/thousands of minions simultaneously ask the master what files are available, this would cause the master's CPU load to spike as it obtains the same information separately for each minion.
saltenv By default, this runner will clear the file list caches for all environments. This argument allows for a list of environments to be passed, to clear more selectively. This list can be passed either as a comma-separated string, or a Python list.
backend Similar to the saltenv parameter, this argument will restrict the cache clearing to specific fileserver backends (the default behavior is to clear from all enabled fileserver backends). This list can be passed either as a comma-separated string, or a Python list.
Since the ability to clear these caches is often required by users writing custom runners which add/remove files, this runner can easily be called from within a custom runner using any of the following examples:
# Clear all file list caches __salt__['fileserver.clear_file_list_cache']() # Clear just the 'base' saltenv file list caches __salt__['fileserver.clear_file_list_cache'](saltenv='base') # Clear just the 'base' saltenv file list caches from just the 'roots' # fileserver backend __salt__['fileserver.clear_file_list_cache'](saltenv='base', backend='roots') # Clear all file list caches from the 'roots' fileserver backend __salt__['fileserver.clear_file_list_cache'](backend='roots')
NOTE: In runners, the __salt__ dictionary will likely be renamed to __runner__ in a future Salt release to distinguish runner functions from remote execution functions. See this GitHub issue for discussion/updates on this.
If using Salt's Python API (not a runner), the following examples are equivalent to the ones above:
import salt.config import salt.runner
opts = salt.config.master_config('/etc/salt/master') opts['fun'] = 'fileserver.clear_file_list_cache'
# Clear all file list_caches opts['arg'] = []  # No arguments runner = salt.runner.Runner(opts) cleared = runner.run()
# Clear just the 'base' saltenv file list caches opts['arg'] = ['base', None] runner = salt.runner.Runner(opts) cleared = runner.run()
# Clear just the 'base' saltenv file list caches from just the 'roots' # fileserver backend opts['arg'] = ['base', 'roots'] runner = salt.runner.Runner(opts) cleared = runner.run()
# Clear all file list caches from the 'roots' fileserver backend opts['arg'] = [None, 'roots'] runner = salt.runner.Runner(opts) cleared = runner.run()
This function will return a dictionary showing a list of environments which were cleared for each backend. An empty return dictionary means that no changes were made.
# Clear all file list caches salt-run fileserver.clear_file_list_cache # Clear just the 'base' saltenv file list caches salt-run fileserver.clear_file_list_cache saltenv=base # Clear just the 'base' saltenv file list caches from just the 'roots' # fileserver backend salt-run fileserver.clear_file_list_cache saltenv=base backend=roots # Clear all file list caches from the 'roots' fileserver backend salt-run fileserver.clear_file_list_cache backend=roots
salt.runners.fileserver.clear_lock(backend=None, remote=None) New in version 2015.5.0.
Clear the fileserver update lock from VCS fileserver backends (git, hg, svn). This should only need to be done if a fileserver update was interrupted and a remote is not updating (generating a warning in the Master's log file). Executing this runner with no arguments will remove all update locks from all enabled VCS fileserver backends, but this can be narrowed by using the following arguments:
backend Only clear the update lock for the specified backend(s).
salt-run fileserver.clear_lock salt-run fileserver.clear_lock backend=git,hg salt-run fileserver.clear_lock backend=git remote=github salt-run fileserver.clear_lock remote=bitbucket
salt.runners.fileserver.dir_list(saltenv='base', backend=None) Return a list of directories in the given environment
saltenv base The salt fileserver environment to be listed
backend Narrow fileserver backends to a subset of the enabled ones. If all passed backends start with a minus sign (-), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: backend=-roots,git) then the ones starting with a minus sign will be disregarded.
salt-run fileserver.dir_list salt-run fileserver.dir_list saltenv=prod salt-run fileserver.dir_list saltenv=dev backend=git salt-run fileserver.dir_list base hg,roots salt-run fileserver.dir_list -git
salt.runners.fileserver.empty_dir_list(saltenv='base', backend=None) New in version 2015.5.0.
Return a list of empty directories in the given environment
NOTE: Some backends (such as git and hg) do not support empty directories.  So, passing backend=git or backend=hg will result in an empty list being returned.
salt-run fileserver.empty_dir_list salt-run fileserver.empty_dir_list saltenv=prod salt-run fileserver.empty_dir_list backend=roots
salt.runners.fileserver.envs(backend=None, sources=False) Return the available fileserver environments. If no backend is provided, then the environments for all configured backends will be returned.
backend Narrow fileserver backends to a subset of the enabled ones.
Changed in version 2015.5.0: If all passed backends start with a minus sign (-), then these backends will be excluded from the enabled backends. However, if there is a mix of backends with and without a minus sign (ex: backend=-roots,git) then the ones starting with a minus sign will be disregarded.
Additionally, fileserver backends can now be passed as a comma-separated list. In earlier versions, they needed to be passed as a python list (ex: backend="['roots', 'git']")
salt-run fileserver.envs salt-run fileserver.envs backend=roots,git salt-run fileserver.envs git
salt.runners.fileserver.file_list(saltenv='base', backend=None) Return a list of files from the salt fileserver
salt-run fileserver.file_list salt-run fileserver.file_list saltenv=prod salt-run fileserver.file_list saltenv=dev backend=git salt-run fileserver.file_list base hg,roots salt-run fileserver.file_list -git
salt.runners.fileserver.lock(backend=None, remote=None) New in version 2015.5.0.
Set a fileserver update lock for VCS fileserver backends (git, hg, svn).
NOTE: This will only operate on enabled backends (those configured in fileserver_backend).
backend Only set the update lock for the specified backend(s).
remote If not None, then any remotes which contain the passed string will have their lock cleared. For example, a remote value of *github.com* will remove the lock from all github.com remotes.
salt-run fileserver.lock salt-run fileserver.lock backend=git,hg salt-run fileserver.lock backend=git remote='*github.com*' salt-run fileserver.lock remote=bitbucket
salt.runners.fileserver.symlink_list(saltenv='base', backend=None) Return a list of symlinked files and dirs
salt-run fileserver.symlink_list salt-run fileserver.symlink_list saltenv=prod salt-run fileserver.symlink_list saltenv=dev backend=git salt-run fileserver.symlink_list base hg,roots salt-run fileserver.symlink_list -git
salt.runners.fileserver.update(backend=None, **kwargs) Update the fileserver cache. If no backend is provided, then the cache for all configured backends will be updated.
kwargs Pass additional arguments to backend. See example below
salt-run fileserver.update salt-run fileserver.update backend=roots,git salt-run fileserver.update backend=git remotes=myrepo,yourrepo
salt.runners.git_pillar Runner module to directly manage the git external pillar
salt.runners.git_pillar.update(branch=None, repo=None) New in version 2014.1.0.
Changed in version 2015.8.4: This runner function now supports the git_pillar configuration schema introduced in 2015.8.0. Additionally, the branch and repo can now be omitted to update all git_pillar remotes. The return data has also changed to a dictionary. The values will be True only if new commits were fetched, and False if there were errors or no new commits were fetched.
Changed in version 2018.3.0: The return for a given git_pillar remote will now be None when no changes were fetched. False now is reserved only for instances in which there were errors.
Changed in version 3001: The repo parameter also matches against the repo name.
Fetch one or all configured git_pillar remotes.
NOTE: This will not fast-forward the git_pillar cachedir on the master. All it does is perform a git fetch. If this runner is executed with -l debug, you may see a log message that says that the repo is up-to-date. Keep in mind that Salt automatically fetches git_pillar repos roughly every 60 seconds (or whatever loop_interval is set to). So, it is possible that the repo was fetched automatically in the time between when changes were pushed to the repo, and when this runner was executed. When in doubt, simply refresh pillar data using saltutil.refresh_pillar and then use pillar.item to check if the pillar data has changed as expected.
# Update specific branch and repo salt-run git_pillar.update branch='branch' repo='https://foo.com/bar.git' # Update specific repo, by name salt-run git_pillar.update repo=myrepo # Update all repos salt-run git_pillar.update # Run with debug logging salt-run git_pillar.update -l debug
salt.runners.http Module for making various web calls. Primarily designed for webhooks and the like, but also useful for basic http testing.
salt.runners.http.query(url, output=True, **kwargs) Query a resource, and decode the return data
salt-run http.query http://somelink.com/ salt-run http.query http://somelink.com/ method=POST             params='key1=val1&key2=val2' salt-run http.query http://somelink.com/ method=POST             data='<xml>somecontent</xml>'
salt.runners.http.update_ca_bundle(target=None, source=None, merge_files=None) Update the local CA bundle file from a URL
salt-run http.update_ca_bundle salt-run http.update_ca_bundle target=/path/to/cacerts.pem salt-run 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 master. 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 master. 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!
salt-run http.update_ca_bundle merge_files=/path/to/mycert.pem
salt.runners.jobs A convenience system to manage jobs, both active and already run
salt.runners.jobs.active(display_progress=False) Return a report on all actively running jobs from a job id centric perspective
salt.runners.jobs.exit_success(jid, ext_source=None) Check if a job has been executed and exit successfully
jid    The jid to look up.
ext_source The external job cache to use. Default: None.
salt-run jobs.exit_success 20160520145827701627
salt.runners.jobs.last_run(ext_source=None, outputter=None, metadata=None, function=None, target=None, display_progress=False) New in version 2015.8.0.
List all detectable jobs and associated functions
salt-run jobs.last_run salt-run jobs.last_run target=nodename salt-run jobs.last_run function='cmd.run' salt-run jobs.last_run metadata="{'foo': 'bar'}"
salt.runners.jobs.list_job(jid, ext_source=None, display_progress=False) List a specific job given by its jid
ext_source If provided, specifies which external job cache to use.
display_progress False If True, fire progress events.
salt-run jobs.list_job 20130916125524463507 salt-run jobs.list_job 20130916125524463507 --out=pprint
salt.runners.jobs.list_jobs(ext_source=None, outputter=None, search_metadata=None, search_function=None, search_target=None, start_time=None, end_time=None, display_progress=False) List all detectable jobs and associated functions
FILTER OPTIONS
NOTE: If more than one of the below options are used, only jobs which match all of the filters will be returned.
search_metadata Specify a dictionary to match to the job's metadata. If any of the key-value pairs in this dictionary match, the job will be returned.  Example:
salt-run jobs.list_jobs search_metadata='{"foo": "bar", "baz": "qux"}'
search_function Can be passed as a string or a list. Returns jobs which match the specified function. Globbing is allowed. Example:
salt-run jobs.list_jobs search_function='test.*' salt-run jobs.list_jobs search_function='["test.*", "pkg.install"]'
Changed in version 2015.8.8: Multiple targets can now also be passed as a comma-separated list.  For example:
salt-run jobs.list_jobs search_function='test.*,pkg.install'
search_target Can be passed as a string or a list. Returns jobs which match the specified minion name. Globbing is allowed. Example:
salt-run jobs.list_jobs search_target='*.mydomain.tld' salt-run jobs.list_jobs search_target='["db*", "myminion"]'
salt-run jobs.list_jobs search_target='db*,myminion'
start_time Accepts any timestamp supported by the dateutil Python module (if this module is not installed, this argument will be ignored). Returns jobs which started after this timestamp.
end_time Accepts any timestamp supported by the dateutil Python module (if this module is not installed, this argument will be ignored). Returns jobs which started before this timestamp.
salt-run jobs.list_jobs salt-run jobs.list_jobs search_function='test.*' search_target='localhost' search_metadata='{"bar": "foo"}' salt-run jobs.list_jobs start_time='2015, Mar 16 19:00' end_time='2015, Mar 18 22:00'
salt.runners.jobs.list_jobs_filter(count, filter_find_job=True, ext_source=None, outputter=None, display_progress=False) List all detectable jobs and associated functions
salt-run jobs.list_jobs_filter 50 salt-run jobs.list_jobs_filter 100 filter_find_job=False
salt.runners.jobs.lookup_jid(jid, ext_source=None, returned=True, missing=False, display_progress=False) Return the printout from a previously executed job
returned True If True, include the minions that did return from the command.
missing False If True, include the minions that did not return from the command.
salt-run jobs.lookup_jid 20130916125524463507 salt-run jobs.lookup_jid 20130916125524463507 --out=highstate
salt.runners.jobs.master() Return the actively executing runners for the master
salt-run jobs.master
salt.runners.jobs.print_job(jid, ext_source=None) Print a specific job's detail given by its jid, including the return data.
salt-run jobs.print_job 20130916125524463507
salt.runners.launchd Manage launchd plist files
salt.runners.launchd.write_launchd_plist(program) Write a launchd plist for managing salt-master or salt-minion
salt-run launchd.write_launchd_plist salt-master
salt.runners.lxc Control Linux Containers via Salt
depends lxc execution module
salt.runners.lxc.cloud_init(names, host=None, quiet=False, **kwargs) Wrapper for using lxc.init in saltcloud compatibility mode
names  Name of the containers, supports a single name or a comma delimited list of names.
host   Minion to start the container on. Required.
saltcloud_mode init the container with the saltcloud opts format instead
salt.runners.lxc.find_guest(name, quiet=False, path=None) Returns the host for a container.
salt-run lxc.find_guest name
salt.runners.lxc.find_guests(names, path=None) Return a dict of hosts and named guests
salt.runners.lxc.freeze(name, quiet=False, path=None) Freeze the named container
salt-run lxc.freeze name
salt.runners.lxc.info(name, quiet=False, path=None) Returns information about a container.
salt-run lxc.info name
salt.runners.lxc.init(names, host=None, saltcloud_mode=False, quiet=False, **kwargs) Initialize a new container
salt-run lxc.init name host=minion_id [cpuset=cgroups_cpuset] \ [cpushare=cgroups_cpushare] [memory=cgroups_memory] \ [template=lxc_template_name] [clone=original name] \ [profile=lxc_profile] [network_proflile=network_profile] \ [nic=network_profile] [nic_opts=nic_opts] \ [start=(true|false)] [seed=(true|false)] \ [install=(true|false)] [config=minion_config] \ [snapshot=(true|false)]
host   Minion on which to initialize the container (required)
saltcloud_mode init the container with the saltcloud opts format instead See lxc.init_interface module documentation
cpuset cgroups cpuset.
template Name of LXC template on which to base this container
clone  Clone this container from an existing container
profile A LXC profile (defined in config or pillar).
nic    Deprecated since version 2015.5.0: Use network_profile instead
nic_opts Extra options for network interfaces. E.g.:
start  Start the newly created container.
seed   Seed the container with the minion config and autosign its key.  Default: true
install If salt-minion is not already installed, install it. Default: true
salt.runners.lxc.list_(host=None, quiet=False, path=None) List defined containers (running, stopped, and frozen) for the named (or all) host(s).
salt-run lxc.list [host=minion_id]
salt.runners.lxc.purge(name, delete_key=True, quiet=False, path=None) Purge the named container and delete its minion key if present. WARNING: Destroys all data associated with the container.
salt-run lxc.purge name
salt.runners.lxc.start(name, quiet=False, path=None) Start the named container.
salt-run lxc.start name
salt.runners.lxc.stop(name, quiet=False, path=None) Stop the named container.
salt-run lxc.stop name
salt.runners.lxc.unfreeze(name, quiet=False, path=None) Unfreeze the named container
salt-run lxc.unfreeze name
salt.runners.manage General management functions for salt, tools like seeing what hosts are up and what hosts are down
salt.runners.manage.alived(subset=None, show_ip=False) New in version 2015.8.0.
Print a list of all minions that are up according to Salt's presence detection (no commands will be sent to minions)
subset None Pass in a CIDR range to filter minions by IP address.
show_ip False Also show the IP address each minion is connecting from.
salt-run manage.alived
salt.runners.manage.allowed(subset=None, show_ip=False) New in version 2015.8.0.
salt-run manage.allowed
salt.runners.manage.bootstrap(version='develop', script=None, hosts='', script_args='', roster='flat', ssh_user=None, ssh_password=None, ssh_priv_key=None, tmp_dir='/tmp/.bootstrap', http_backend='tornado') Bootstrap minions with salt-bootstrap
version develop Git tag of version to install
script https://bootstrap.saltstack.com URL containing the script to execute
hosts  Comma-separated hosts [example: hosts='host1.local,host2.local']. These hosts need to exist in the specified roster.
script_args Any additional arguments that you want to pass to the script.
roster flat The roster to use for Salt SSH. More information about roster files can be found in Salt's Roster Documentation.
A full list of roster types, see the builtin roster modules documentation.
ssh_user If user isn't found in the roster, a default SSH user can be set here.  Keep in mind that ssh_user will not override the roster user value if it is already defined.
ssh_password If passwd isn't found in the roster, a default SSH password can be set here. Keep in mind that ssh_password will not override the roster passwd value if it is already defined.
ssh_privkey If priv isn't found in the roster, a default SSH private key can be set here. Keep in mind that ssh_password will not override the roster passwd value if it is already defined.
tmp_dir /tmp/.bootstrap The temporary directory to download the bootstrap script in. This directory will have -<uuid4> appended to it. For example: /tmp/.bootstrap-a19a728e-d40a-4801-aba9-d00655c143a7/
http_backend tornado The backend library to use to download the script. If you need to use a file:/// URL, then you should set this to urllib2.
salt-run manage.bootstrap hosts='host1,host2' salt-run manage.bootstrap hosts='host1,host2' version='v0.17' salt-run manage.bootstrap hosts='host1,host2' version='v0.17' script='https://bootstrap.saltstack.com/develop'
salt.runners.manage.bootstrap_psexec(hosts='', master=None, version=None, arch='win32', installer_url=None, username=None, password=None) Bootstrap Windows minions via PsExec.
hosts  Comma separated list of hosts to deploy the Windows Salt minion.
master Address of the Salt master passed as an argument to the installer.
version Point release of installer to download. Defaults to the most recent.
arch   Architecture of installer to download. Defaults to win32.
installer_url URL of minion installer executable. Defaults to the latest version from https://repo.saltproject.io/windows/
username Optional user name for login on remote computer.
password Password for optional username. If omitted, PsExec will prompt for one to be entered for each host.
salt-run manage.bootstrap_psexec hosts='host1,host2' salt-run manage.bootstrap_psexec hosts='host1,host2' version='0.17' username='DOMAIN\Administrator' salt-run manage.bootstrap_psexec hosts='host1,host2' installer_url='http://exampledomain/salt-installer.exe'
salt.runners.manage.down(removekeys=False, tgt='*', tgt_type='glob', timeout=None, gather_job_timeout=None) Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Print a list of all the down or unresponsive salt minions Optionally remove keys of down minions
salt-run manage.down salt-run manage.down removekeys=True salt-run manage.down tgt="webservers" tgt_type="nodegroup"
salt.runners.manage.joined(subset=None, show_ip=False) New in version 2015.8.0.
salt-run manage.joined
salt.runners.manage.key_regen() This routine is used to regenerate all keys in an environment. This is invasive! ALL KEYS IN THE SALT ENVIRONMENT WILL BE REGENERATED!!
The key_regen routine sends a command out to minions to revoke the master key and remove all minion keys, it then removes all keys from the master and prompts the user to restart the master. The minions will all reconnect and keys will be placed in pending.
After the master is restarted and minion keys are in the pending directory execute a salt-key -A command to accept the regenerated minion keys.
The master must be restarted within 60 seconds of running this command or the minions will think there is something wrong with the keys and abort.
Only Execute this runner after upgrading minions and master to 0.15.1 or higher!
salt-run manage.key_regen
salt.runners.manage.list_not_state(subset=None, show_ip=False) New in version 2015.8.0.
Print a list of all minions that are NOT up according to Salt's presence detection (no commands will be sent to minions)
salt-run manage.list_not_state
salt.runners.manage.list_state(subset=None, show_ip=False) New in version 2015.8.0.
salt-run manage.list_state
salt.runners.manage.not_alived(subset=None, show_ip=False) New in version 2015.8.0.
Print a list of all minions that are NOT up according to Salt's presence detection (no commands will be sent)
salt-run manage.not_alived
salt.runners.manage.not_allowed(subset=None, show_ip=False) New in version 2015.8.0.
salt-run manage.not_allowed
salt.runners.manage.not_joined(subset=None, show_ip=False) New in version 2015.8.0.
salt-run manage.not_joined
salt.runners.manage.not_present(subset=None, show_ip=False) New in version 2015.5.0.
salt-run manage.not_present
salt.runners.manage.not_reaped(subset=None, show_ip=False) New in version 2015.8.0.
salt-run manage.not_reaped
salt.runners.manage.present(subset=None, show_ip=False) Changed in version 2019.2.0.
salt-run manage.present
salt.runners.manage.reaped(subset=None, show_ip=False) New in version 2015.8.0.
salt-run manage.reaped
salt.runners.manage.safe_accept(target, tgt_type='glob') Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Accept a minion's public key after checking the fingerprint over salt-ssh
salt-run manage.safe_accept my_minion salt-run manage.safe_accept minion1,minion2 tgt_type=list
salt.runners.manage.status(output=True, tgt='*', tgt_type='glob', timeout=None, gather_job_timeout=None) Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Print the status of all known salt minions
salt-run manage.status salt-run manage.status tgt="webservers" tgt_type="nodegroup" salt-run manage.status timeout=5 gather_job_timeout=10
salt.runners.manage.up(tgt='*', tgt_type='glob', timeout=None, gather_job_timeout=None) Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Print a list of all of the minions that are up
salt-run manage.up salt-run manage.up tgt="webservers" tgt_type="nodegroup" salt-run manage.up timeout=5 gather_job_timeout=10
salt.runners.manage.versions() Check the version of active minions
salt-run manage.versions
salt.runners.mattermost Note for 2017.7 releases!
Due to the salt.runners.config module not being available in this release series, importing the salt.runners.config module from the master branch is required to make this module work.
Ref: Mattermost runner failing to retrieve config values due to unavailable config runner #43479
Module for sending messages to Mattermost
salt.runners.mattermost.post_event(event, channel=None, username=None, api_url=None, hook=None) Send an event to a Mattermost channel.  :param channel:     The channel name, either will work.  :param username:    The username of the poster.  :param event:       The event 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.
salt.runners.mattermost.post_message(message, channel=None, username=None, api_url=None, hook=None) 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.
salt-run mattermost.post_message message='Build is done'
salt.runners.mine A runner to access data from the salt mine
salt.runners.mine.get(tgt, fun, tgt_type='glob') Gathers the data from the specified minions' mine, pass in the target, function to look up and the target type
salt-run mine.get '*' network.interfaces
salt.runners.mine.update(tgt, tgt_type='glob', clear=False, mine_functions=None) New in version 2017.7.0.
Update the mine data on a certain group of minions.
tgt    Which minions to target for the execution.
tgt_type: glob The type of tgt.
clear: False Boolean flag specifying whether updating will clear the existing mines, or will update. Default: False (update).
mine_functions Update the mine data on certain functions only.  This feature can be used when updating the mine for functions that require refresh at different intervals than the rest of the functions specified under mine_functions in the minion/master config or pillar.
salt-run mine.update '*' salt-run mine.update 'juniper-edges' tgt_type='nodegroup'
salt.runners.nacl This module helps include encrypted passwords in pillars, grains and salt state files.
salt-run nacl.enc sk_file=/etc/salt/pki/master/nacl pk_file=/etc/salt/pki/master/nacl.pub
salt-run nacl.keygen sk_file=/etc/salt/pki/master/nacl # or if you want to work without files. salt-run nacl.keygen local: ---------- pk: /kfGX7PbWeu099702PBbKWLpG/9p06IQRswkdWHCDk0= sk: SVWut5SqNpuPeNzb1b9y6b2eXg2PLIog43GBzp48Sow=
salt-run nacl.enc asecretpass pk=/kfGX7PbWeu099702PBbKWLpG/9p06IQRswkdWHCDk0= tqXzeIJnTAM9Xf0mdLcpEdklMbfBGPj2oTKmlgrm3S1DTVVHNnh9h8mU1GKllGq/+cYsk6m5WhGdk58=
salt-run nacl.dec data='tqXzeIJnTAM9Xf0mdLcpEdklMbfBGPj2oTKmlgrm3S1DTVVHNnh9h8mU1GKllGq/+cYsk6m5WhGdk58='         sk='SVWut5SqNpuPeNzb1b9y6b2eXg2PLIog43GBzp48Sow='
salt-run nacl.enc apassword
salt-run nacl.enc_file /tmp/cert.crt out=/tmp/cert.nacl
salt.runners.nacl.dec(data, **kwargs) Alias to {box_type}_decrypt
salt.runners.nacl.dec_file(name, out=None, **kwargs) This is a helper function to decrypt a file and return its contents.
salt-run nacl.dec_file name=/tmp/id_rsa.nacl salt-run nacl.dec_file name=/tmp/id_rsa.nacl box_type=secretbox             sk_file=/etc/salt/pki/master/nacl.pub
salt.runners.nacl.enc(data, **kwargs) Alias to {box_type}_encrypt
salt.runners.nacl.enc_file(name, out=None, **kwargs) This is a helper function to encrypt a file and return its contents.
salt-run nacl.enc_file name=/tmp/id_rsa salt-run nacl.enc_file name=/tmp/id_rsa box_type=secretbox             sk_file=/etc/salt/pki/master/nacl.pub
salt.runners.nacl.keygen(sk_file=None, pk_file=None, **kwargs) Use libnacl to generate a keypair.
salt-run nacl.keygen salt-run nacl.keygen sk_file=/etc/salt/pki/master/nacl salt-run nacl.keygen sk_file=/etc/salt/pki/master/nacl pk_file=/etc/salt/pki/master/nacl.pub salt-run nacl.keygen
salt.runners.nacl.sealedbox_decrypt(data, **kwargs) Decrypt data using a secret key that was encrypted using a public key with nacl.sealedbox_encrypt.