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: |
|
---|
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
Forcibly removes job cache folders and files on a minion.
New in version 2018.3.0.
WARNING: The safest way to clear a minion cache is by first stopping the minion and then deleting the cache files before restarting it.
CLI Example:
salt '*' saltutil.clear_job_cache hours=12
Changed in version 2017.7.0: The expr_form
argument has been renamed to tgt_type
, earlier releases must use expr_form
.
Assuming this minion is a master, execute a salt command
CLI Example:
salt '*' saltutil.cmd
Changed in version 2017.7.0: The expr_form
argument has been renamed to tgt_type
, earlier releases must use expr_form
.
Assuming this minion is a master, execute a salt command
CLI Example:
salt '*' saltutil.cmd_iter
Return the data for a specific cached job id. Note this only works if cache_jobs has previously been set to True on the minion.
CLI Example:
salt '*' saltutil.find_cached_job <job id>
Return the data for a specific job id that is currently running.
CLI Example:
salt '*' saltutil.find_job <job id>
Note that the find_job function only returns job information when the job is still running. If the job is currently running, the output looks something like this:
# salt my-minion saltutil.find_job 20160503150049487736 my-minion: ---------- arg: - 30 fun: test.sleep jid: 20160503150049487736 pid: 9601 ret: tgt: my-minion tgt_type: glob user: root
If the job has already completed, the job cannot be found and therefore the function returns an empty dictionary, which looks like this on the CLI:
# salt my-minion saltutil.find_job 20160503150049487736 my-minion: ----------
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
Sends a kill signal (SIGKILL 9) to all currently running jobs
CLI Example:
salt '*' saltutil.kill_all_jobs
Sends a kill signal (SIGKILL 9) to the named salt job's process
CLI Example:
salt '*' saltutil.kill_job <job id>
New in version 2017.7.0.
List Salt modules which have been synced externally
CLI Examples:
salt '*' saltutil.list_extmods
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
Signal the minion to refresh the beacons.
CLI Example:
salt '*' saltutil.refresh_beacons
New in version 2016.3.6,2016.11.4,2017.7.0.
Refresh the minion's grains without syncing custom grains modules from salt://_grains
.
Note
The available execution modules will be reloaded as part of this proceess, as grains can affect which modules are available.
False
to keep pillar data from being refreshed.CLI Examples:
salt '*' saltutil.refresh_grains
Signal the minion to refresh its matchers.
CLI Example:
salt '*' saltutil.refresh_matchers
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
Signal the minion to refresh the pillar data.
CLI Example:
salt '*' saltutil.refresh_pillar
Used to regenerate the minion keys.
CLI Example:
salt '*' saltutil.regen_keys
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
Execute a runner function. This function must be run on the master, either by targeting a minion running on a master or by using salt-call on a master.
New in version 2014.7.0.
CLI Example:
In this example, assume that master_minion is a minion running on a master.
salt master_minion saltutil.runner jobs.list_jobs salt master_minion saltutil.runner test.arg arg="['baz']" kwarg="{'foo': 'bar'}"
Return the data on all running salt processes on the minion
CLI Example:
salt '*' saltutil.running
Sends a signal to the named salt job's process
CLI Example:
salt '*' saltutil.signal_job <job id> 15
Changed in version 2015.8.11,2016.3.2: On masterless minions, pillar modules are now synced, and refreshed when refresh
is set to True
.
Sync down all of the dynamic modules from the file server for a specific environment. This function synchronizes custom modules, states, beacons, grains, returners, output modules, renderers, and utils.
False
to prevent this refresh.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 refresh
argument is added to the state, like so:
load_my_custom_module: module.run: - name: saltutil.sync_all - refresh: True
See here for a more detailed explanation of why this is necessary.
CLI Examples:
salt '*' saltutil.sync_all salt '*' saltutil.sync_all saltenv=dev salt '*' saltutil.sync_all saltenv=base,dev salt '*' saltutil.sync_all extmod_whitelist={'modules': ['custom_module']}
New in version 2015.5.1.
Sync beacons from salt://_beacons
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for beacons to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available beacons on the minion. This refresh will be performed even if no new beacons are synced. Set to False
to prevent this refresh.CLI Example:
salt '*' saltutil.sync_beacons salt '*' saltutil.sync_beacons saltenv=dev salt '*' saltutil.sync_beacons saltenv=base,dev
New in version 2017.7.0.
Sync cloud modules from salt://_cloud
to the minion
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new utility modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_clouds salt '*' saltutil.sync_clouds saltenv=dev salt '*' saltutil.sync_clouds saltenv=base,dev
New in version 2016.3.0.
Sync engine modules from salt://_engines
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for engines to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new engine modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_engines salt '*' saltutil.sync_engines saltenv=base,dev
New in version 2019.2.1.
Sync executors from salt://_executors
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for log handlers to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new log handlers are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_executors salt '*' saltutil.sync_executors saltenv=dev salt '*' saltutil.sync_executors saltenv=base,dev
New in version 0.10.0.
Sync grains modules from salt://_grains
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for grains modules to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules and recompile pillar data for the minion. This refresh will be performed even if no new grains modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_grains salt '*' saltutil.sync_grains saltenv=dev salt '*' saltutil.sync_grains saltenv=base,dev
New in version 2015.8.0.
Sync log handlers from salt://_log_handlers
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for log handlers to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new log handlers are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_log_handlers salt '*' saltutil.sync_log_handlers saltenv=dev salt '*' saltutil.sync_log_handlers saltenv=base,dev
New in version 2019.2.0.
Sync engine modules from salt://_matchers
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for engines to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new matcher modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_matchers salt '*' saltutil.sync_matchers saltenv=base,dev
New in version 0.10.0.
Sync execution modules from salt://_modules
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for execution modules to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new execution modules are synced. Set to False
to prevent this refresh.Important
If this function is executed using a module.run
state, the SLS file will not have access to newly synced execution modules unless a refresh
argument is added to the state, like so:
load_my_custom_module: module.run: - name: saltutil.sync_modules - refresh: True
See here for a more detailed explanation of why this is necessary.
CLI Example:
salt '*' saltutil.sync_modules salt '*' saltutil.sync_modules saltenv=dev salt '*' saltutil.sync_modules saltenv=base,dev
Sync outputters from salt://_output
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for outputters to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new outputters are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_output salt '*' saltutil.sync_output saltenv=dev salt '*' saltutil.sync_output saltenv=base,dev
This function is an alias of sync_output
.
Sync outputters from
salt://_output
to the minion
- saltenv
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for outputters to sync. If no top files are found, then the
base
environment will be synced.- refresh : True
- If
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new outputters are synced. Set toFalse
to prevent this refresh.- extmod_whitelist : None
- comma-seperated list of modules to sync
- extmod_blacklist : None
- comma-seperated list of modules to blacklist based on type
CLI Examples:
salt '*' saltutil.sync_output salt '*' saltutil.sync_output saltenv=dev salt '*' saltutil.sync_output saltenv=base,dev
New in version 2015.8.11,2016.3.2.
Sync pillar modules from the salt://_pillar
directory on the Salt fileserver. This function is environment-aware, pass the desired environment to grab the contents of the _pillar
directory from that environment. The default environment, if none is specified, is base
.
Note
This function will raise an error if executed on a traditional (i.e. not masterless) minion
CLI Examples:
salt '*' saltutil.sync_pillar salt '*' saltutil.sync_pillar saltenv=dev
New in version 2015.8.2.
Sync proxy modules from salt://_proxy
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for proxy modules to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new proxy modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_proxymodules salt '*' saltutil.sync_proxymodules saltenv=dev salt '*' saltutil.sync_proxymodules saltenv=base,dev
New in version 0.10.0.
Sync renderers from salt://_renderers
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for renderers to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new renderers are synced. Set to False
to prevent this refresh. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_renderers salt '*' saltutil.sync_renderers saltenv=dev salt '*' saltutil.sync_renderers saltenv=base,dev
New in version 0.10.0.
Sync returners from salt://_returners
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for returners to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new returners are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_returners salt '*' saltutil.sync_returners saltenv=dev
New in version 2015.5.8,2015.8.3.
Sync sdb modules from salt://_sdb
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for sdb modules to sync. If no top files are found, then the base
environment will be synced.
CLI Example:
salt '*' saltutil.sync_sdb salt '*' saltutil.sync_sdb saltenv=dev salt '*' saltutil.sync_sdb saltenv=base,dev
New in version 2019.2.0.
Sync serializers from salt://_serializers
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for serializer modules to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new serializer modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_serializers salt '*' saltutil.sync_serializers saltenv=dev salt '*' saltutil.sync_serializers saltenv=base,dev
New in version 0.10.0.
Sync state modules from salt://_states
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for state modules to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available states on the minion. This refresh will be performed even if no new state modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_states salt '*' saltutil.sync_states saltenv=dev salt '*' saltutil.sync_states saltenv=base,dev
New in version 2018.3.0.
Sync Thorium modules from salt://_thorium
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for engines to sync. If no top files are found, then the base
environment will be synced.
True
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new Thorium modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_thorium salt '*' saltutil.sync_thorium saltenv=base,dev
New in version 2014.7.0.
Sync utility modules from salt://_utils
to the minion
The fileserver environment from which to sync. To sync from more than one environment, pass a comma-separated list.
If not passed, then all environments configured in the top files will be checked for utility modules to sync. If no top files are found, then the base
environment will be synced.
True
, refresh the available execution modules on the minion. This refresh will be performed even if no new utility modules are synced. Set to False
to prevent this refresh.CLI Examples:
salt '*' saltutil.sync_utils salt '*' saltutil.sync_utils saltenv=dev salt '*' saltutil.sync_utils saltenv=base,dev
Sends a termination signal (SIGTERM 15) to all currently running jobs
CLI Example:
salt '*' saltutil.term_all_jobs
Sends a termination signal (SIGTERM 15) to the named salt job's process
CLI Example:
salt '*' saltutil.term_job <job id>
Update the salt minion from the URL defined in opts['update_url'] SaltStack, Inc provides the latest builds here: update_url: https://repo.saltstack.com/windows/
Be aware that as of 2014-8-11 there's a bug in esky such that only the latest version available in the update_url can be downloaded and installed.
This feature requires the minion to be running a bdist_esky build.
The version number is optional and will default to the most recent version available at opts['update_url'].
Returns details about the transaction upon completion.
CLI Examples:
salt '*' saltutil.update salt '*' saltutil.update 0.10.3
Execute a wheel module and function. This function must be run against a minion that is local to the master.
New in version 2014.7.0.
Any positional arguments to pass to the wheel function. A common example of this would be the match
arg needed for key functions.
New in version v2015.8.11.
CLI Example:
salt my-local-minion saltutil.wheel key.accept jerry salt my-local-minion saltutil.wheel minions.connected
Note
Since this function must be run against a minion that is running locally on the master in order to get accurate returns, if this function is run against minions that are not local to the master, "empty" returns are expected. The remote minion does not have access to wheel functions and their return data.
© 2019 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.saltutil.html