salt.modules.saltutil¶

The Saltutil module is used to manage the state of the salt minion itself. It is used to manage minion modules as well as automate updates to the salt minion.

depends:	esky Python module for update functionality

salt.modules.saltutil.clear_cache()¶

Forcibly removes all caches on a minion.

New in version 2014.7.0.

WARNING: The safest way to clear a minion cache is by first stopping the minion and then deleting the cache files before restarting it.

CLI Example:

salt '*' saltutil.clear_cache

salt.modules.saltutil.cmd(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, ssh=False, **kwargs)¶

Assuming this minion is a master, execute a salt command

CLI Example:

salt '*' saltutil.cmd

salt.modules.saltutil.cmd_iter(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, ssh=False, **kwargs)¶

Assuming this minion is a master, execute a salt command

CLI Example:

salt '*' saltutil.cmd_iter

salt.modules.saltutil.find_cached_job(jid)¶

Return the data for a specific cached job id

CLI Example:

salt '*' saltutil.find_cached_job <job id>

salt.modules.saltutil.find_job(jid)¶

Return the data for a specific job id

CLI Example:

salt '*' saltutil.find_job <job id>

salt.modules.saltutil.is_running(fun)¶

If the named function is running return the data associated with it/them. The argument can be a glob

CLI Example:

salt '*' saltutil.is_running state.highstate

salt.modules.saltutil.kill_job(jid)¶

Sends a kill signal (SIGKILL 9) to the named salt job's process

CLI Example:

salt '*' saltutil.kill_job <job id>

salt.modules.saltutil.mmodule(saltenv, fun, *args, **kwargs)¶

Loads minion modules from an environment so that they can be used in pillars for that environment

CLI Example:

salt '*' saltutil.mmodule base test.ping

salt.modules.saltutil.pillar_refresh()¶

Signal the minion to refresh the pillar data.

CLI Example:

salt '*' saltutil.refresh_pillar

salt.modules.saltutil.refresh_beacons()¶

Signal the minion to refresh the beacons.

CLI Example:

salt '*' saltutil.refresh_beacons

salt.modules.saltutil.refresh_modules(async=True)¶

Signal the minion to refresh the module and grain data

The default is to refresh module asynchronously. To block until the module refresh is complete, set the 'async' flag to False.

CLI Example:

salt '*' saltutil.refresh_modules

salt.modules.saltutil.refresh_pillar()¶

Signal the minion to refresh the pillar data.

CLI Example:

salt '*' saltutil.refresh_pillar

salt.modules.saltutil.regen_keys()¶

Used to regenerate the minion keys.

CLI Example:

salt '*' saltutil.regen_keys

salt.modules.saltutil.revoke_auth(preserve_minion_cache=False)¶

The minion sends a request to the master to revoke its own key. Note that the minion session will be revoked and the minion may not be able to return the result of this command back to the master.

If the 'preserve_minion_cache' flag is set to True, the master cache for this minion will not be removed.

CLI Example:

salt '*' saltutil.revoke_auth

salt.modules.saltutil.runner(fun, **kwargs)¶

Execute a runner module (this function must be run on the master)

New in version 2014.7.

name: The name of the function to run
kwargs: Any keyword arguments to pass to the runner function

CLI Example:

salt '*' saltutil.runner jobs.list_jobs

salt.modules.saltutil.running()¶

Return the data on all running salt processes on the minion

CLI Example:

salt '*' saltutil.running

salt.modules.saltutil.signal_job(jid, sig)¶

Sends a signal to the named salt job's process

CLI Example:

salt '*' saltutil.signal_job <job id> 15

salt.modules.saltutil.sync_all(saltenv=None, refresh=True)¶

Sync down all of the dynamic modules from the file server for a specific environment

refresh : True: Also refresh the execution modules available to the minion.

Important

If this function is executed using a module.run state, the SLS file will not have access to newly synced execution modules unless a reload_modules argument is added to the state, like so:

load_my_custom_module:
  module.run:
    - name: saltutil.sync_all
    - refresh: True
    - reload_modules: True

See here for a more detailed explanation of why this is necessary.

CLI Example:

salt '*' saltutil.sync_all

salt.modules.saltutil.sync_beacons(saltenv=None, refresh=True)¶

Sync the beacons from the _beacons directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _beacons directory, base is the default environment.

New in version 2015.5.1.

CLI Example:

salt '*' saltutil.sync_beacons

salt.modules.saltutil.sync_grains(saltenv=None, refresh=True)¶

Sync the grains from the _grains directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _grains directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_grains

salt.modules.saltutil.sync_log_handlers(saltenv=None, refresh=True)¶

New in version Beryllium.

Sync utility source files from the _log_handlers directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _log_handlers directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_log_handlers

salt.modules.saltutil.sync_modules(saltenv=None, refresh=True)¶

Sync the modules from the _modules directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _modules directory, base is the default environment.

Important

If this function is executed using a module.run state, the SLS file will not have access to newly synced execution modules unless a reload_modules argument is added to the state, like so:

load_my_custom_module:
  module.run:
    - name: saltutil.sync_modules
    - reload_modules: True

See here for a more detailed explanation of why this is necessary.

New in version 2015.5.1.

CLI Example:

salt '*' saltutil.sync_modules

salt.modules.saltutil.sync_outputters(saltenv=None, refresh=True)¶

Sync the outputters from the _outputters directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _outputters directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_outputters

salt.modules.saltutil.sync_renderers(saltenv=None, refresh=True)¶

Sync the renderers from the _renderers directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _renderers directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_renderers

salt.modules.saltutil.sync_returners(saltenv=None, refresh=True)¶

Sync the returners from the _returners directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _returners directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_returners

salt.modules.saltutil.sync_states(saltenv=None, refresh=True)¶

Sync the states from the _states directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _states directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_states

salt.modules.saltutil.sync_utils(saltenv=None, refresh=True)¶

Sync utility source files from the _utils directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _utils directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_utils

salt.modules.saltutil.term_job(jid)¶

Sends a termination signal (SIGTERM 15) to the named salt job's process

CLI Example:

salt '*' saltutil.term_job <job id>

salt.modules.saltutil.update(version=None)¶

Update the salt minion from the URL defined in opts['update_url'] SaltStack, Inc provides the latest builds here: update_url: http://docs.saltstack.com/downloads/

Be aware that as of 2014-8-11 there's a bug in esky such that only the latest version available in the update_url can be downloaded and installed.

This feature requires the minion to be running a bdist_esky build.

The version number is optional and will default to the most recent version available at opts['update_url'].

Returns details about the transaction upon completion.

CLI Example:

salt '*' saltutil.update
salt '*' saltutil.update 0.10.3

salt.modules.saltutil.wheel(fun, **kwargs)¶

Execute a wheel module (this function must be run on the master)

New in version 2014.7.

name: The name of the function to run
kwargs: Any keyword arguments to pass to the wheel function

CLI Example:

salt '*' saltutil.wheel key.accept match=jerry