neulab/tldr huggingface dataset:
allow_fail Pass in the number of minions to allow for failure before setting the result of the execution to False
exclude Pass exclude kwarg to state
concurrent Allow multiple state runs to occur at once.
WARNING: This flag is potentially dangerous. It is designed for use when multiple state runs can safely be run at the same Do not use this flag for performance optimization.
queue  Pass queue=true through to the state function
Run a list of sls files via state.sls on target minions:
webservers: salt.state: - tgt: 'web*' - sls: - apache - django - core - saltenv: prod
Run sls file via state.sls on target minions with exclude:
docker: salt.state: - tgt: 'docker*' - sls: docker - exclude: docker.swarm - saltenv: prod
Run a full state.highstate on target mininons.
databases: salt.state: - tgt: role:database - tgt_type: grain - highstate: True
salt.states.saltmod.wait_for_event(name, id_list, event_id='id', timeout=300, node='master') Watch Salt's event bus and block until a condition is met
name   An event tag to watch for; supports Reactor-style globbing.
id_list A list of event identifiers to watch for -- usually the minion ID. Each time an event tag is matched the event data is inspected for event_id, if found it is removed from id_list. When id_list is empty this function returns success.
event_id id The name of a key in the event data. Default is id for the minion ID, another common value is name for use with orchestrating salt-cloud events.
timeout 300 The maximum time in seconds to wait before failing.
The following example blocks until all the listed minions complete a restart and reconnect to the Salt master:
reboot_all_minions: salt.function: - name: system.reboot - tgt: '*'
wait_for_reboots: salt.wait_for_event: - name: salt/minion/*/start - id_list: - jerry - stuart - dave - phil - kevin - mike - require: - salt: reboot_all_minions
salt.states.saltmod.wheel(name, **kwargs) Execute a wheel module on the master
accept_minion_key: salt.wheel: - name: key.accept - match: frank
salt.states.saltutil Saltutil State This state wraps the saltutil execution modules to make them easier to run from a states. Rather than needing to to use module.run this state allows for improved change detection. New in version 3000.
salt.states.saltutil.sync_all(name, **kwargs) Performs the same task as saltutil.sync_all module See saltutil module for full list of options
sync_everything: saltutil.sync_all: - refresh: True
salt.states.saltutil.sync_beacons(name, **kwargs) Performs the same task as saltutil.sync_beacons module See saltutil module for full list of options
sync_everything: saltutil.sync_beacons: - refresh: True
salt.states.saltutil.sync_clouds(name, **kwargs) Performs the same task as saltutil.sync_clouds module See saltutil module for full list of options
sync_everything: saltutil.sync_clouds: - refresh: True
salt.states.saltutil.sync_engines(name, **kwargs) Performs the same task as saltutil.sync_engines module See saltutil module for full list of options
sync_everything: saltutil.sync_engines: - refresh: True
salt.states.saltutil.sync_executors(name, **kwargs) Performs the same task as saltutil.sync_executors module See saltutil module for full list of options
sync_everything: saltutil.sync_executors: - refresh: True
salt.states.saltutil.sync_grains(name, **kwargs) Performs the same task as saltutil.sync_grains module See saltutil module for full list of options
sync_everything: saltutil.sync_grains: - refresh: True
salt.states.saltutil.sync_log_handlers(name, **kwargs) Performs the same task as saltutil.sync_log_handlers module See saltutil module for full list of options
sync_everything: saltutil.sync_log_handlers: - refresh: True
salt.states.saltutil.sync_matchers(name, **kwargs) Performs the same task as saltutil.sync_matchers module See saltutil module for full list of options
sync_everything: saltutil.sync_matchers: - refresh: True
salt.states.saltutil.sync_modules(name, **kwargs) Performs the same task as saltutil.sync_modules module See saltutil module for full list of options
sync_everything: saltutil.sync_modules: - refresh: True
salt.states.saltutil.sync_output(name, **kwargs) Performs the same task as saltutil.sync_output module See saltutil module for full list of options
sync_everything: saltutil.sync_output: - refresh: True
salt.states.saltutil.sync_outputters(name, **kwargs) Performs the same task as saltutil.sync_outputters module See saltutil module for full list of options
sync_everything: saltutil.sync_outputters: - refresh: True
salt.states.saltutil.sync_pillar(name, **kwargs) Performs the same task as saltutil.sync_pillar module See saltutil module for full list of options
sync_everything: saltutil.sync_pillar: - refresh: True
salt.states.saltutil.sync_proxymodules(name, **kwargs) Performs the same task as saltutil.sync_proxymodules module See saltutil module for full list of options
sync_everything: saltutil.sync_proxymodules: - refresh: True
salt.states.saltutil.sync_renderers(name, **kwargs) Performs the same task as saltutil.sync_renderers module See saltutil module for full list of options
sync_everything: saltutil.sync_renderers: - refresh: True
salt.states.saltutil.sync_returners(name, **kwargs) Performs the same task as saltutil.sync_returners module See saltutil module for full list of options
sync_everything: saltutil.sync_returners: - refresh: True
salt.states.saltutil.sync_sdb(name, **kwargs) Performs the same task as saltutil.sync_sdb module See saltutil module for full list of options
sync_everything: saltutil.sync_sdb: - refresh: True
salt.states.saltutil.sync_serializers(name, **kwargs) Performs the same task as saltutil.sync_serializers module See saltutil module for full list of options
sync_everything: saltutil.sync_serializers: - refresh: True
salt.states.saltutil.sync_states(name, **kwargs) Performs the same task as saltutil.sync_states module See saltutil module for full list of options
sync_everything: saltutil.sync_states: - refresh: True
salt.states.saltutil.sync_thorium(name, **kwargs) Performs the same task as saltutil.sync_thorium module See saltutil module for full list of options
sync_everything: saltutil.sync_thorium: - refresh: True
salt.states.saltutil.sync_utils(name, **kwargs) Performs the same task as saltutil.sync_utils module See saltutil module for full list of options
sync_everything: saltutil.sync_utils: - refresh: True
salt.states.schedule Management of the Salt scheduler job3: schedule.present: - function: test.ping - seconds: 3600 - splay: 10
This will schedule the command: test.ping every 3600 seconds (every hour) splaying the time between 0 and 10 seconds
job2: schedule.present: - function: test.ping - seconds: 15 - splay: start: 10 end: 20
This will schedule the command: test.ping every 15 seconds splaying the time between 10 and 20 seconds
job1: schedule.present: - function: state.sls - job_args: - httpd - job_kwargs: test: True - when: - Monday 5:00pm - Tuesday 3:00pm - Wednesday 5:00pm - Thursday 3:00pm - Friday 5:00pm
This will schedule the command: state.sls httpd test=True at 5pm on Monday, Wednesday and Friday, and 3pm on Tuesday and Thursday.  Requires that python-dateutil is installed on the minion.
job1: schedule.present: - function: state.sls - job_args: - httpd - job_kwargs: test: True - cron: '*/5 * * * *'
Scheduled jobs can also be specified using the format used by cron.  This will schedule the command: state.sls httpd test=True to run every 5 minutes.  Requires that python-croniter is installed on the minion.
job1: schedule.present: - function: state.sls - job_args: - httpd - job_kwargs: test: True - when: - Monday 5:00pm - Tuesday 3:00pm - Wednesday 5:00pm - Thursday 3:00pm - Friday 5:00pm - returner: xmpp - return_config: xmpp_state_run - return_kwargs: recipient: user@domain.com
This will schedule the command: state.sls httpd test=True at 5pm on Monday, Wednesday and Friday, and 3pm on Tuesday and Thursday.  Using the xmpp returner to return the results of the scheduled job, with the alternative configuration options found in the xmpp_state_run section.
job1: schedule.present: - function: state.sls - job_args: - httpd - job_kwargs: test: True - hours: 1 - skip_during_range: - start: 2pm - end: 3pm - run_after_skip_range: True
salt.states.schedule.absent(name, **kwargs) Ensure a job is absent from the schedule
name   The unique name that is given to the scheduled job.
persist Whether the job should persist between minion restarts, defaults to True.
salt.states.schedule.disabled(name, **kwargs) Ensure a job is disabled in the schedule
salt.states.schedule.enabled(name, **kwargs) Ensure a job is enabled in the schedule
salt.states.schedule.present(name, **kwargs) Ensure a job is present in the schedule
seconds The scheduled job will be executed after the specified number of seconds have passed.
minutes The scheduled job will be executed after the specified number of minutes have passed.
hours  The scheduled job will be executed after the specified number of hours have passed.
days   The scheduled job will be executed after the specified number of days have passed.
when   This will schedule the job at the specified time(s).  The when parameter must be a single value or a dictionary with the date string(s) using the dateutil format.  Requires python-dateutil.
cron   This will schedule the job at the specified time(s) using the crontab format.  Requires python-croniter.
run_on_start Whether the job will run when Salt minion starts, or the job will be skipped once and run at the next scheduled run. Value should be a boolean.
function The function that should be executed by the scheduled job.
job_args The arguments that will be used by the scheduled job.
job_kwargs The keyword arguments that will be used by the scheduled job.
maxrunning Ensure that there are no more than N copies of a particular job running.
jid_include Include the job into the job cache.
splay  The amount of time in seconds to splay a scheduled job. Can be specified as a single value in seconds or as a dictionary range with 'start' and 'end' values.
range  This will schedule the command within the range specified. The range parameter must be a dictionary with the date strings using the dateutil format. Requires python-dateutil.
once   This will schedule a job to run once on the specified date.
once_fmt The default date format is ISO 8601 but can be overridden by also specifying the once_fmt option.
enabled Whether the job should be enabled or disabled.  Value should be a boolean.
return_job Whether to return information to the Salt master upon job completion.
metadata Using the metadata parameter special values can be associated with a scheduled job.  These values are not used in the execution of the job, but can be used to search for specific jobs later if combined with the return_job parameter.  The metadata parameter must be specified as a dictionary, othewise it will be ignored.
returner The returner to use to return the results of the scheduled job.
return_config The alternative configuration to use for returner configuration options.
return_kwargs Any individual returner configuration items to override. Should be passed as a dictionary.
skip_during_range This will ensure that the scheduled command does not run within the range specified.  The range parameter must be a dictionary with the date strings using the dateutil format. Requires python-dateutil.
run_after_skip_range Whether the job should run immediately after the skip_during_range time period ends.
salt.states.selinux Management of SELinux rules If SELinux is available for the running system, the mode can be managed and booleans can be set.
enforcing: selinux.mode
samba_create_home_dirs: selinux.boolean: - value: True - persist: True
nginx: selinux.module: - enabled: False
NOTE: Use of these states require that the selinux execution module is available.
salt.states.selinux.boolean(name, value, persist=False) Set up an SELinux boolean
name   The name of the boolean to set
value  The value to set on the boolean
persist Defaults to False, set persist to true to make the boolean apply on a reboot
salt.states.selinux.fcontext_policy_absent(name, filetype='a', sel_type=None, sel_user=None, sel_level=None) New in version 2017.7.0.
Makes sure an SELinux file context policy for a given filespec (name), filetype and SELinux context type is absent.
sel_type The SELinux context type. There are many.
sel_user The SELinux user.
sel_level The SELinux MLS range.
salt.states.selinux.fcontext_policy_applied(name, recursive=False) New in version 2017.7.0.
Checks and makes sure the SELinux policies for a given filespec are applied.
salt.states.selinux.fcontext_policy_present(name, sel_type, filetype='a', sel_user=None, sel_level=None) New in version 2017.7.0.
Makes sure a SELinux policy for a given filespec (name), filetype and SELinux context type is present.
salt.states.selinux.mode(name) Verifies the mode SELinux is running in, can be set to enforcing, permissive, or disabled
NOTE: A change to or from disabled mode requires a system reboot. You will need to perform this yourself.
name   The mode to run SELinux in, permissive, enforcing, or disabled.
salt.states.selinux.module(name, module_state='Enabled', version='any', **opts) Enable/Disable and optionally force a specific version for an SELinux module
name   The name of the module to control
module_state Should the module be enabled or disabled?
version Defaults to no preference, set to a specified value if required.  Currently can only alert if the version is incorrect.
install Setting to True installs module
source Points to module source file, used only when install is True
remove Setting to True removes module
salt.states.selinux.module_install(name) Installs custom SELinux module from given file
name   Path to file with module to install
salt.states.selinux.module_remove(name) Removes SELinux module
name   The name of the module to remove
salt.states.selinux.port_policy_absent(name, sel_type=None, protocol=None, port=None) New in version 2019.2.0.
Makes sure an SELinux port policy for a given port, protocol and SELinux context type is absent.
sel_type The SELinux Type. Optional; can be used in determining if policy is present, ignored by semanage port --delete.
salt.states.selinux.port_policy_present(name, sel_type, protocol=None, port=None, sel_range=None) New in version 2019.2.0.
Makes sure an SELinux port policy for a given port, protocol and SELinux context type is present.
salt.states.serverdensity_device Monitor Server with Server Density New in version 2014.7.0.
Server Density Is a hosted monitoring service.
WARNING: This state module is beta. It might be changed later to include more or less automation.
NOTE: This state module requires a pillar for authentication with Server Density To install a v1 agent:
serverdensity: api_token: "b97da80a41c4f61bff05975ee51eb1aa" account_url: "https://your-account.serverdensity.io"
To install a v2 agent:
serverdensity: api_token: "b97da80a41c4f61bff05975ee51eb1aa" account_name: "your-account"
NOTE: Although Server Density allows duplicate device names in its database, this module will raise an exception if you try monitoring devices with the same name.
'server_name': serverdensity_device.monitored
salt.states.serverdensity_device.monitored(name, group=None, salt_name=True, salt_params=True, agent_version=1, **params) Device is monitored with Server Density.
name   Device name in Server Density.
salt_name If True (default), takes the name from the id grain. If False, the provided name is used.
group  Group name under with device will appear in Server Density dashboard.  Default - None.
agent_version The agent version you want to use. Valid values are 1 or 2. Default - 1.
salt_params If True (default), needed config parameters will be sourced from grains and from status.all_status.
params Add parameters that you want to appear in the Server Density dashboard.  Will overwrite the salt_params parameters. For more info, see the API docs.
'server_name': serverdensity_device.monitored: - group: web-servers
'my_special_server': serverdensity_device.monitored: - salt_name: False - group: web-servers - cpuCores: 2 - os: '{"code": "linux", "name": "Linux"}'
salt.states.service Starting or restarting of services and daemons Services are defined as system daemons and are typically launched using system init or rc scripts. This service state uses whichever service module is loaded on the minion with the virtualname of service. Services can be defined as either running or dead.
If you need to know if your init system is supported, see the list of supported service modules for your desired init system (systemd, sysvinit, launchctl, etc.).
Note that Salt's service execution module, and therefore this service state, uses OS grains to ascertain which service module should be loaded and used to execute service functions. As existing distributions change init systems or new distributions are created, OS detection can sometimes be incomplete.  If your service states are running into trouble with init system detection, please see the Overriding Virtual Module Providers section of Salt's module documentation to work around possible errors.
NOTE: The current status of a service is determined by the return code of the init/rc script status command. A status return code of 0 it is considered running.  Any other return code is considered dead.
httpd: service.running: []
The service can also be set to start at runtime via the enable option:
openvpn: service.running: - enable: True
By default if a service is triggered to refresh due to a watch statement the service is restarted. If the desired behavior is to reload the service, then set the reload value to True:
redis: service.running: - enable: True - reload: True - watch: - pkg: redis
NOTE: More details regarding watch can be found in the Requisites documentation.
salt.states.service.dead(name, enable=None, sig=None, init_delay=None, **kwargs) Ensure that the named service is dead by stopping the service if it is running
name   The name of the init or rc script used to manage the service
enable Set the service to be enabled at boot time, True sets the service to be enabled, False sets the named service to be disabled. The default is None, which does not enable or disable anything.
sig    The string to search for when looking for the service process with ps
init_delay Add a sleep command (in seconds) before the check to make sure service is killed.
no_block False For systemd minions only. Stops the service using --no-block.
timeout For Windows minions only.
The time in seconds to wait for the service to stop before returning.  Default is the default for win_service.stop.
salt.states.service.disabled(name, **kwargs) Ensure that the service is disabled on boot, only use this state if you don't want to manage the running process, remember that if you want to disable a service to use the enable: False option for the running or dead function.
salt.states.service.enabled(name, **kwargs) Ensure that the service is enabled on boot, only use this state if you don't want to manage the running process, remember that if you want to enable a running service to use the enable: True option for the running or dead function.
salt.states.service.masked(name, runtime=False) New in version 2017.7.0.
NOTE: This state is only available on minions which use systemd.
Ensures that the named service is masked (i.e. prevented from being started).
name   Name of the service to mask
runtime False By default, this state will manage an indefinite mask for the named service. Set this argument to True to runtime mask the service.
NOTE: It is possible for a service to have both indefinite and runtime masks set for it. Therefore, this state will manage a runtime or indefinite mask independently of each other. This means that if the service is already indefinitely masked, running this state with runtime set to True will _not_ remove the indefinite mask before setting a runtime mask. In these cases, if it is desirable to ensure that the service is runtime masked and not indefinitely masked, pair this state with a service.unmasked state, like so:
mask_runtime_foo: service.masked: - name: foo - runtime: True
unmask_indefinite_foo: service.unmasked: - name: foo - runtime: False
salt.states.service.mod_beacon(name, **kwargs) Create a beacon to monitor a service based on a beacon state argument.
salt.states.service.mod_watch(name, sfun=None, sig=None, reload=False, full_restart=False, init_delay=None, force=False, **kwargs) The service watcher, called to invoke the watch command.  When called, it will restart or reload the named service.
Parameters for this function should be set by the watching service (e.g. service.running).
name   The name of the service to control.
sfun   The original function which triggered the mod_watch call (service.running, for example).
sig    The string to search for when looking for the service process with ps.
reload When set, reload the service instead of restarting it (e.g. service nginx reload).
full_restart Perform a full stop/start of a service by passing --full-restart.  This option is ignored if reload is set and is supported by only a few service modules.
force  Use service.force_reload instead of reload (needs reload to be set to True).
init_delay Add a sleep command (in seconds) before the service is restarted/reloaded.
salt.states.service.running(name, enable=None, sig=None, init_delay=None, **kwargs) Ensure that the service is running
init_delay Some services may not be truly available for a short period after their startup script indicates to the system that they are. Provide an 'init_delay' to specify that this state should wait an additional given number of seconds after a service has started before returning. Useful for requisite states wherein a dependent state might assume a service has started but is not yet fully initialized.
no_block False For systemd minions only. Starts the service using --no-block.
The time in seconds to wait for the service to start before returning.  Default is the default for win_service.start.
unmask False For systemd minions only. Set to True to remove an indefinite mask before attempting to start the service.
New in version 2017.7.0: In previous releases, Salt would simply unmask a service before making any changes. This behavior is no longer the default.
unmask_runtime False For systemd minions only. Set to True to remove a runtime mask before attempting to start the service.
wait   3 For systemd minions only. Passed through when using service.status to determine whether the service is running or not.
New in version 2019.2.3.
watch can be used with service.running to restart a service when another state changes ( example: a file.managed state that creates the service's config file ). More details regarding watch can be found in the Requisites documentation.
salt.states.service.unmasked(name, runtime=False) New in version 2017.7.0.
Ensures that the named service is unmasked
name   Name of the service to unmask
runtime False By default, this state will manage an indefinite mask for the named service. Set this argument to True to ensure that the service is runtime masked.
NOTE: It is possible for a service to have both indefinite and runtime masks set for it. Therefore, this state will manage a runtime or indefinite mask independently of each other. This means that if the service is indefinitely masked, running this state with runtime set to True will _not_ remove the indefinite mask.
salt.states.slack Send a message to Slack This state is useful for sending messages to Slack during state runs.
slack-message: slack.post_message: - channel: '#general' - from_name: SuperAdmin - message: 'This state was executed successfully.' - api_key: peWcBiMOS9HrZG15peWcBiMOS9HrZG15
The api key can be specified in the master or minion configuration like below:
salt.states.slack.post_message(name, **kwargs) Send a message to a Slack channel.
api_key parameters:
channel The channel to send the message to. Can either be the ID or the name.
from_name The name of that is to be shown in the "from" field.
message The message that is to be sent to the Slack channel.
api_key The api key for Slack to use for authentication, if not specified in the configuration options of master or minion.
icon   URL to an image to use as the icon for this message
webhook parameters:
color  The color of border of left side
short  An optional flag indicating whether the value is short enough to be displayed side-by-side with other values.
webhook The identifier of WebHook (URL or token).
channel The channel to use instead of the WebHook default.
username Username to use instead of WebHook default.
icon_emoji Icon to use instead of WebHook default.
salt.states.smartos Management of SmartOS Standalone Compute Nodes
depends vmadm, imgadm
vmtest.example.org: smartos.vm_present: - config: reprovision: true - vmconfig: image_uuid: c02a2044-c1bd-11e4-bd8c-dfc1db8b0182 brand: joyent alias: vmtest quota: 5 max_physical_memory: 512 tags: label: 'test vm' owner: 'sjorge' nics: "82:1b:8e:49:e9:12": nic_tag: trunk mtu: 1500 ips: - 172.16.1.123/16 - 192.168.2.123/24 vlan_id: 10 "82:1b:8e:49:e9:13": nic_tag: trunk mtu: 1500 ips: - dhcp vlan_id: 30 filesystems: "/bigdata": source: "/bulk/data" type: lofs options: - ro - nodevices
kvmtest.example.org: smartos.vm_present: - vmconfig: brand: kvm alias: kvmtest cpu_type: host ram: 512 vnc_port: 9 tags: label: 'test kvm' owner: 'sjorge' disks: disk0: size: 2048 model: virtio compression: lz4 boot: true nics: "82:1b:8e:49:e9:15": nic_tag: trunk mtu: 1500 ips: - dhcp vlan_id: 30
docker.example.org: smartos.vm_present: - config: auto_import: true reprovision: true - vmconfig: image_uuid: emby/embyserver:latest brand: lx alias: mydockervm quota: 5 max_physical_memory: 1024 tags: label: 'my emby docker' owner: 'sjorge' resolvers: - 172.16.1.1 nics: "82:1b:8e:49:e9:18": nic_tag: trunk mtu: 1500 ips: - 172.16.1.118/24 vlan_id: 10 filesystems: "/config: source: "/vmdata/emby_config" type: lofs options: - nodevices
cleanup_images: smartos.image_vacuum
NOTE: Keep in mind that when removing properties from vmconfig they will not get removed from the vm's current configuration, except for nics, disk, tags, ...  they get removed via add_*, set_*, update_*, and remove_*. Properties must be manually reset to their default value. The same behavior as when using 'vmadm update'.
WARNING: For HVM (bhyve and KVM) brands the image_uuid field should go on the boot disks, this disk should NOT have a size specified. (See man vmadm)
salt.states.smartos.config_absent(name) Ensure configuration property is absent in /usbkey/config
name   string name of property
salt.states.smartos.config_present(name, value) Ensure configuration property is set to value in /usbkey/config
salt.states.smartos.image_absent(name) Ensure image is absent on the computenode
name   string uuid of image
NOTE: computenode.image_absent will only remove the image if it is not used by a vm.
salt.states.smartos.image_present(name) Ensure image is present on the computenode
salt.states.smartos.image_vacuum(name) Delete images not in use or installed via image_present
WARNING: Only image_present states that are included via the top file will be detected.
salt.states.smartos.source_absent(name) Ensure an image source is absent on the computenode
name   string source url
salt.states.smartos.source_present(name, source_type='imgapi') Ensure an image source is present on the computenode
source_type string source type (imgapi or docker)
salt.states.smartos.vm_absent(name, archive=False) Ensure vm is absent on the computenode
name   string hostname of vm
archive boolean toggle archiving of vm on removal
NOTE: State ID is used as hostname. Hostnames must be unique.
salt.states.smartos.vm_present(name, vmconfig, config=None) Ensure vm is present on the computenode
vmconfig dict options to set for the vm
config dict fine grain control over vm_present
The following configuration properties can be toggled in the config parameter.
• kvm_reboot (true)                - reboots of kvm zones if needed for a config update
• auto_import (false)              - automatic importing of missing images
• auto_lx_vars (true)              - copy kernel_version and docker:* variables from image
• reprovision (false)              - reprovision on image_uuid changes
• enforce_tags (true)              - false = add tags only, true =  add, update, and remove tags
• enforce_routes (true)            - false = add tags only, true =  add, update, and remove routes
• enforce_internal_metadata (true) - false = add metadata only, true =  add, update, and remove metadata
• enforce_customer_metadata (true) - false = add metadata only, true =  add, update, and remove metadata
NOTE: If hostname is provided in vmconfig this will take president over the State ID.  This allows multiple states to be applied to the same vm.
The following instances should have a unique ID.
• nic : mac
• filesystem: target
• disk : path or diskN for zvols
e.g. disk0 will be the first disk added, disk1 the 2nd,...
Changed in version 2019.2.0: Added support for docker image uuids, added auto_lx_vars configuration, documented some missing configuration options.
salt.states.smartos.vm_running(name) Ensure vm is in the running state on the computenode
salt.states.smartos.vm_stopped(name) Ensure vm is in the stopped state on the computenode
salt.states.smtp Sending Messages via SMTP New in version 2014.7.0.
This state is useful for firing messages during state runs, using the SMTP protocol
server-warning-message: smtp.send_msg: - name: 'This is a server warning message' - profile: my-smtp-account - recipient: admins@example.com
salt.states.smtp.send_msg(name, recipient, subject, sender=None, profile=None, use_ssl='True', attachments=None) Send a message via SMTP
server-warning-message: smtp.send_msg: - name: 'This is a server warning message' - profile: my-smtp-account - subject: 'Message from Salt' - recipient: admin@example.com - sender: admin@example.com - use_ssl: True - attachments: - /var/log/syslog - /var/log/messages
name   The message to send via SMTP
salt.states.snapper Managing implicit state and baselines using snapshots New in version 2016.11.0.
Salt can manage state against explicitly defined state, for example if your minion state is defined by:
/etc/config_file: file.managed: - source: salt://configs/myconfig
If someone modifies this file, the next application of the highstate will allow the admin to correct this deviation and the file will be corrected.
Now, what happens if somebody creates a file /etc/new_config_file and deletes /etc/important_config_file? Unless you have a explicit rule, this change will go unnoticed.
The snapper state module allows you to manage state implicitly, in addition to explicit rules, in order to define a baseline and iterate with explicit rules as they show that they work in production.
The workflow is: once you have a working and audited system, you would create your baseline snapshot (eg. with salt tgt snapper.create_snapshot) and define in your state this baseline using the identifier of the snapshot (in this case: 20):
my_baseline: snapper.baseline_snapshot: - number: 20 - include_diff: False - ignore: - /var/log - /var/cache
Baseline snapshots can be also referenced by tag. Most recent baseline snapshot is used in case of multiple snapshots with the same tag:
my_baseline_external_storage:
snapper.baseline_snapshot:
• tag: my_custom_baseline_tag
• config: external
• ignore: - /mnt/tmp_files/
If you have this state, and you haven't done changes to the system since the snapshot, and you add a user, the state will show you the changes (including full diffs) to /etc/passwd, /etc/shadow, etc if you call it with test=True and will undo all changes if you call it without.
This allows you to add more explicit state knowing that you are starting from a very well defined state, and that you can audit any change that is not part of your explicit configuration.
So after you made this your state, you decided to introduce a change in your configuration:
my_baseline: snapper.baseline_snapshot: - number: 20 - ignore: - /var/log - /var/cache
hosts_entry: file.blockreplace: - name: /etc/hosts - content: 'First line of content' - append_if_not_found: True
The change in /etc/hosts will be done after any other change that deviates from the specified snapshot are reverted. This could be for example, modifications to the /etc/passwd file or changes in the /etc/hosts that could render your the hosts_entry rule void or dangerous.
Once you take a new snapshot and you update the baseline snapshot number to include the change in /etc/hosts the hosts_entry rule will basically do nothing. You are free to leave it there for documentation, to ensure that the change is made in case the snapshot is wrong, but if you remove anything that comes after the snapper.baseline_snapshot as it will have no effect; by the moment the state is evaluated, the baseline state was already applied and include this change.
WARNING: Make sure you specify the baseline state before other rules, otherwise the baseline state will revert all changes if they are not present in the snapshot.
WARNING: Do not specify more than one baseline rule as only the last one will affect the result.
salt.states.snapper.baseline_snapshot(name, number=None, tag=None, include_diff=True, config='root', ignore=None) Enforces that no file is modified comparing against a previously defined snapshot identified by number.
number Number of selected baseline snapshot.
tag    Tag of the selected baseline snapshot. Most recent baseline baseline snapshot is used in case of multiple snapshots with the same tag.  (tag and number cannot be used at the same time)
include_diff Include a diff in the response (Default: True)
config Snapper config name (Default: root)
ignore List of files to ignore. (Default: None)
salt.states.solrcloud States for solrcloud alias and collection configuration
salt.states.solrcloud.alias(name, collections, **kwargs) Create alias and enforce collection list.
Use the solrcloud module to get alias members and set them.
You can pass additional arguments that will be forwarded to http.query
name   The collection name
collections list of collections to include in the alias
salt.states.solrcloud.collection(name, options=None, **kwargs) Create collection and enforce options.
Use the solrcloud module to get collection parameters.
options {} options to ensure
salt.states.splunk Splunk User State Module
This state is used to ensure presence of users in splunk.
ensure example test user 1: splunk.present: - name: 'Example TestUser1' - email: example@domain.com
salt.states.splunk.absent(email, profile='splunk', **kwargs) Ensure a splunk user is absent
ensure example test user 1: splunk.absent: - email: 'example@domain.com' - name: 'exampleuser'
email  This is the email of the user in splunk
name   This is the splunk username used to identify the user.
salt.states.splunk.present(email, profile='splunk', **kwargs) Ensure a user is present
ensure example test user 1: splunk.user_present: - realname: 'Example TestUser1' - name: 'exampleuser' - email: 'example@domain.com' - roles: ['user']
salt.states.splunk_search Splunk Search State Module
This state is used to ensure presence of splunk searches.
server-warning-message: splunk_search.present: - name: This is the splunk search name - search: index=main sourcetype=
salt.states.splunk_search.absent(name, profile='splunk') Ensure a search is absent
API Error Search: splunk_search.absent
name   This is the name of the search in splunk
salt.states.splunk_search.present(name, profile='splunk', **kwargs) Ensure a search is present
API Error Search: splunk_search.present: search: index=main sourcetype=blah template: alert_5min
salt.states.sqlite3 Management of SQLite3 databases New in version 2016.3.0.
• SQLite3 Python Module
configuration See salt.modules.sqlite3 for setup instructions
The sqlite3 module is used to create and manage sqlite3 databases and execute queries
Here is an example of creating a table using sql statements:
users: sqlite3.table_present: - db: /var/www/data/app.sqlite - schema: CREATE TABLE `users` (`username` TEXT COLLATE NOCASE UNIQUE NOT NULL, `password` BLOB NOT NULL, `salt` BLOB NOT NULL, `last_login` INT)
Here is an example of creating a table using yaml/jinja instead of sql:
users: sqlite3.table_present: - db: /var/www/app.sqlite - schema: - email TEXT COLLATE NOCASE UNIQUE NOT NULL - firstname TEXT NOT NULL - lastname TEXT NOT NULL - company TEXT NOT NULL - password BLOB NOT NULL - salt BLOB NOT NULL
Here is an example of making sure a table is absent:
badservers: sqlite3.table_absent: - db: /var/www/data/users.sqlite
Sometimes you would to have specific data in tables to be used by other services Here is an example of making sure rows with specific data exist:
user_john_doe_xyz: sqlite3.row_present: - db: /var/www/app.sqlite - table: users - where_sql: email='john.doe@companyxyz.com' - data: email: john.doe@companyxyz.com lastname: doe firstname: john company: companyxyz.com password: abcdef012934125 salt: abcdef012934125 - require: - sqlite3: users
Here is an example of removing a row from a table:
user_john_doe_abc: sqlite3.row_absent: - db: /var/www/app.sqlite - table: users - where_sql: email="john.doe@companyabc.com" - require: - sqlite3: users
Note that there is no explicit state to perform random queries, however, this can be approximated with sqlite3's module functions and module.run:
zone-delete: module.run: - name: sqlite3.modify - db: {{ db }} - sql: "DELETE FROM records WHERE id > {{ count[0] }} AND domain_id = {{ domain_id }}" - watch: - sqlite3: zone-insert-12
salt.states.sqlite3.row_absent(name, db, table, where_sql, where_args=None) Makes sure the specified row is absent in db.  If multiple rows match where_sql, then the state will fail.
name   Only used as the unique ID
db     The database file name
table  The table name to check
where_sql The sql to select the row to check
where_args The list parameters to substitute in where_sql
salt.states.sqlite3.row_present(name, db, table, data, where_sql, where_args=None, update=False) Checks to make sure the given row exists. If row exists and update is True then row will be updated with data. Otherwise it will leave existing row unmodified and check it against data. If the existing data doesn't match data_check the state will fail.  If the row doesn't exist then it will insert data into the table. If more than one row matches, then the state will fail.
table  The table name to check the data
data   The dictionary of key/value pairs to check against if row exists, insert into the table if it doesn't
update True will replace the existing row with data When False and the row exists and data does not equal the row data then the state will fail
salt.states.sqlite3.table_absent(name, db) Make sure the specified table does not exist
name   The name of the table
db     The name of the database file
salt.states.sqlite3.table_present(name, db, schema, force=False) Make sure the specified table exists with the specified schema
schema The dictionary containing the schema information
force  If the name of the table exists and force is set to False, the state will fail.  If force is set to True, the existing table will be replaced with the new table
salt.states.ssh_auth Control of entries in SSH authorized_key files The information stored in a user's SSH authorized key file can be easily controlled via the ssh_auth state. Defaults can be set by the enc, options, and comment keys. These defaults can be overridden by including them in the name.
Since the YAML specification limits the length of simple keys to 1024 characters, and since SSH keys are often longer than that, you may have to use a YAML 'explicit key', as demonstrated in the second example below.
AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==: ssh_auth.present: - user: root - enc: ssh-dss
? AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==... : ssh_auth.present: - user: root - enc: ssh-dss
thatch: ssh_auth.present: - user: root - source: salt://ssh_keys/thatch.id_rsa.pub - config: '%h/.ssh/authorized_keys'
sshkeys: ssh_auth.present: - user: root - enc: ssh-rsa - options: - option1="value1" - option2="value2 flag2" - comment: myuser - names: - AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY== - ssh-dss AAAAB3NzaCL0sQ9fJ5bYTEyY== user@domain - option3="value3" ssh-dss AAAAB3NzaC1kcQ9J5bYTEyY== other@testdomain - AAAAB3NzaC1kcQ9fJFF435bYTEyY== newcomment
sshkeys: ssh_auth.manage: - user: root - enc: ssh-rsa - options: - option1="value1" - option2="value2 flag2" - comment: myuser - ssh_keys: - AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY== - ssh-dss AAAAB3NzaCL0sQ9fJ5bYTEyY== user@domain - option3="value3" ssh-dss AAAAB3NzaC1kcQ9J5bYTEyY== other@testdomain - AAAAB3NzaC1kcQ9fJFF435bYTEyY== newcomment
salt.states.ssh_auth.absent(name, user, enc='ssh-rsa', comment='', source='', options=None, config='.ssh/authorized_keys', fingerprint_hash_type=None) Verifies that the specified SSH key is absent
name   The SSH key to manage
user   The user who owns the SSH authorized keys file to modify
enc    Defines what type of key is being used; can be ed25519, ecdsa, ssh-rsa or ssh-dss
comment The comment to be placed with the SSH public key
options The options passed to the key, pass a list object
source The source file for the key(s). Can contain any number of public keys, in standard "authorized_keys" format. If this is set, comment, enc and options will be ignored.
config The location of the authorized keys file relative to the user's home directory, defaults to ".ssh/authorized_keys". Token expansion %u and %h for username and home path supported.
New in version 2016.11.7.
salt.states.ssh_auth.manage(name, ssh_keys, user, enc='ssh-rsa', comment='', source='', options=None, config='.ssh/authorized_keys', fingerprint_hash_type=None, **kwargs) New in version 3000.
Ensures that only the specified ssh_keys are present for the specified user
ssh_keys The SSH key to manage
source The source file for the key(s). Can contain any number of public keys, in standard "authorized_keys" format. If this is set, comment and enc will be ignored.
NOTE: The source file must contain keys in the format <enc> <key> <comment>. If you have generated a keypair using PuTTYgen, then you will need to do the following to retrieve an OpenSSH-compatible public key.
1. In PuTTYgen, click Load, and select the private key file (not the public key), and click Open.
2. Copy the public key from the box labeled Public key for pasting into OpenSSH authorized_keys file.
3. Paste it into a new file.
options The options passed to the keys, pass a list object
salt.states.ssh_auth.present(name, user, enc='ssh-rsa', comment='', source='', options=None, config='.ssh/authorized_keys', fingerprint_hash_type=None, **kwargs) Verifies that the specified SSH key is present for the specified user
salt.states.ssh_known_hosts Control of SSH known_hosts entries Manage the information stored in the known_hosts files.
github.com: ssh_known_hosts: - present - user: root - fingerprint: 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 - fingerprint_hash_type: md5
example.com: ssh_known_hosts: - absent - user: root
salt.states.ssh_known_hosts.absent(name, user=None, config=None) Verifies that the specified host is not known by the given user
name   The host name Note that only single host names are supported.  If foo.example.com and bar.example.com are the same machine and you need to exclude both, you will need one Salt state for each.
salt.states.ssh_known_hosts.present(name, user=None, fingerprint=None, key=None, port=None, enc=None, config=None, hash_known_hosts=True, timeout=5, fingerprint_hash_type=None) Verifies that the specified host is known by the specified user
On many systems, specifically those running with openssh 4 or older, the enc option must be set, only openssh 5 and above can detect the key type.
name   The name of the remote host (e.g. "github.com") Note that only a single hostname is supported, if foo.example.com and bar.example.com have the same host you will need two separate Salt States to represent them.
key    The public key which must be present in the known_hosts file (optional if fingerprint specified)
port   optional parameter, port which will be used to when requesting the public key from the remote host, defaults to port 22.
salt.states.stateconf Stateconf System The stateconf system is intended for use only with the stateconf renderer. This State module presents the set function. This function does not execute any functionality, but is used to interact with the stateconf renderer.
salt.states.stateconf.context(name, **kwargs) No-op state to support state config via the stateconf renderer.
salt.states.stateconf.set(name, **kwargs) No-op state to support state config via the stateconf renderer.
salt.states.status Minion status monitoring
Maps to the status execution module.
salt.states.status.loadavg(name, maximum=None, minimum=None) Return the current load average for the specified minion. Available values for name are 1-min, 5-min and 15-min. minimum and maximum values should be passed in as strings.
salt.states.status.process(name) Return whether the specified signature is found in the process tree. This differs slightly from the services states, in that it may refer to a process that is not managed via the init system.
salt.states.statuspage StatusPage Manage the StatusPage configuration.
salt.states.statuspage.create(name, endpoint='incidents', api_url=None, page_id=None, api_key=None, api_version=None, **kwargs) Insert a new entry under a specific endpoint.
kwargs Other params.
create-my-component: statuspage.create: - endpoint: components - name: my component - group_id: 993vgplshj12
salt.states.statuspage.delete(name, endpoint='incidents', id=None, api_url=None, page_id=None, api_key=None, api_version=None) Remove an entry from an endpoint.
delete-my-component: statuspage.delete: - endpoint: components - id: ftgks51sfs2d
salt.states.statuspage.managed(name, config, api_url=None, page_id=None, api_key=None, api_version=None, pace=1, allow_empty=False) Manage the StatusPage configuration.
config Dictionary with the expected configuration of the StatusPage.  The main level keys of this dictionary represent the endpoint name.  If a certain endpoint does not exist in this structure, it will be ignored / not configured.
pace: 1 Max requests per second allowed by the API.
allow_empty: False Allow empty config.
SLS example:
my-statuspage-config: statuspage.managed: - config: components: - name: component1 group_id: uy4g37rf - name: component2 group_id: 3n4uyu4gf incidents: - name: incident1 status: resolved impact: major backfilled: false - name: incident2 status: investigating impact: minor
salt.states.statuspage.update(name, endpoint='incidents', id=None, api_url=None, page_id=None, api_key=None, api_version=None, **kwargs) Update attribute(s) of a specific endpoint.
update-my-incident: statuspage.update: - id: dz959yz2nd4l - status: resolved
salt.states.supervisord Interaction with the Supervisor daemon wsgi_server: supervisord.running: - require: - pkg: supervisor - watch: - file: /etc/nginx/sites-enabled/wsgi_server.conf
salt.states.supervisord.dead(name, user=None, conf_file=None, bin_env=None, **kwargs) Ensure the named service is dead (not running).
name   Service name as defined in the supervisor configuration file
user   Name of the user to run the supervisorctl command
conf_file path to supervisorctl config file
salt.states.supervisord.mod_watch(name, restart=True, update=False, user=None, conf_file=None, bin_env=None, **kwargs) The supervisord watcher, called to invoke the watch command. Always restart on watch
salt.states.supervisord.running(name, restart=False, update=False, user=None, conf_file=None, bin_env=None, **kwargs) Ensure the named service is running.
restart Whether to force a restart
update Whether to update the supervisor configuration.
salt.states.svn Manage SVN repositories Manage repository checkouts via the svn vcs system. Note that subversion must be installed for these states to be available, so svn states should include a requisite to a pkg.installed state for the package which provides subversion (subversion in most cases). Example:
subversion: pkg.installed
http://unladen-swallow.googlecode.com/svn/trunk/: svn.latest: - target: /tmp/swallow
salt.states.svn.dirty(name, target, user=None, username=None, password=None, ignore_unversioned=False) Determine if the working directory has been changed.
salt.states.svn.export(name, target=None, rev=None, user=None, username=None, password=None, force=False, overwrite=False, externals=True, trust=False, trust_failures=None) Export a file or directory from an SVN repository
name   Address and path to the file or directory to be exported.