neulab/tldr huggingface dataset:
Configurable via state_top.
SEE ALSO: A detailed description of the top file
Include declaration Defines a list of Module reference strings to include in this SLS.
Occurs only in the top level of the SLS data structure.
include: - edit.vim - http.server
Module reference The name of a SLS module defined by a separate SLS file and residing on the Salt Master. A module named edit.vim is a reference to the SLS file salt://edit/vim.sls.
ID declaration Defines an individual highstate component. Always references a value of a dictionary containing keys referencing State declaration and Requisite declaration. Can be overridden by a Name declaration or a Names declaration.
Occurs on the top level or under the Extend declaration.
Must be unique across entire state tree. If the same ID declaration is used twice, only the first one matched will be used. All subsequent ID declarations with the same name will be ignored.
NOTE: Naming gotchas
In Salt versions earlier than 0.9.7, ID declarations containing dots would result in unpredictable output.
Extend declaration Extends a Name declaration from an included SLS module. The keys of the extend declaration always refer to an existing ID declaration which have been defined in included SLS modules.
Occurs only in the top level and defines a dictionary.
States cannot be extended more than once in a single state run.
Extend declarations are useful for adding-to or overriding parts of a State declaration that is defined in another SLS file. In the following contrived example, the shown mywebsite.sls file is include -ing and extend -ing the apache.sls module in order to add a watch declaration that will restart Apache whenever the Apache configuration file, mywebsite changes.
extend: apache: service: - watch: - file: mywebsite
mywebsite: file.managed: - name: /var/www/mysite
SEE ALSO: watch_in and require_in
Sometimes it is more convenient to use the watch_in or require_in syntax instead of extending another SLS file.
State Requisites
State declaration A list which contains one string defining the Function declaration and any number of Function arg declaration dictionaries.
Can, optionally, contain a number of additional components like the name override components — name and names. Can also contain requisite declarations.
Occurs under an ID declaration.
Requisite declaration A list containing requisite references.
Used to build the action dependency tree. While Salt states are made to execute in a deterministic order, this order is managed by requiring and watching other Salt states.
Occurs as a list component under a State declaration or as a key under an ID declaration.
Requisite reference A single key dictionary. The key is the name of the referenced State declaration and the value is the ID of the referenced ID declaration.
Occurs as a single index in a Requisite declaration list.
Function declaration The name of the function to call within the state. A state declaration can contain only a single function declaration.
For example, the following state declaration calls the installed function in the pkg state module:
httpd: pkg.installed: []
The function can be declared inline with the state as a shortcut.  The actual data structure is compiled to this form:
httpd: pkg: - installed
Where the function is a string in the body of the state declaration. Technically when the function is declared in dot notation the compiler converts it to be a string in the state declaration list. Note that the use of the first example more than once in an ID declaration is invalid yaml.
INVALID:
httpd: pkg.installed service.running
When passing a function without arguments and another state declaration within a single ID declaration, then the long or "standard" format needs to be used since otherwise it does not represent a valid data structure.
VALID:
httpd: pkg.installed: [] service.running: []
Occurs as the only index in the State declaration list.
Function arg declaration A single key dictionary referencing a Python type which is to be passed to the named Function declaration as a parameter. The type must be the data type expected by the function.
Occurs under a Function declaration.
For example in the following state declaration user, group, and mode are passed as arguments to the managed function in the file state module:
/etc/http/conf/http.conf: file.managed: - user: root - group: root - mode: 644
Name declaration Overrides the name argument of a State declaration. If name is not specified the ID declaration satisfies the name argument.
The name is always a single key dictionary referencing a string.
Overriding name is useful for a variety of scenarios.
For example, avoiding clashing ID declarations. The following two state declarations cannot both have /etc/motd as the ID declaration:
motd_perms: file.managed: - name: /etc/motd - mode: 644
motd_quote: file.append: - name: /etc/motd - text: "Of all smells, bread; of all tastes, salt."
Another common reason to override name is if the ID declaration is long and needs to be referenced in multiple places. In the example below it is much easier to specify mywebsite than to specify /etc/apache2/sites-available/mywebsite.com multiple times:
mywebsite: file.managed: - name: /etc/apache2/sites-available/mywebsite.com - source: salt://mywebsite.com
a2ensite mywebsite.com: cmd.wait: - unless: test -L /etc/apache2/sites-enabled/mywebsite.com - watch: - file: mywebsite
apache2: service.running: - watch: - file: mywebsite
Names declaration Expands the contents of the containing State declaration into multiple state declarations, each with its own name.
For example, given the following state declaration:
python-pkgs: pkg.installed: - names: - python-django - python-crypto - python-yaml
Once converted into the lowstate data structure the above state declaration will be expanded into the following three state declarations:
python-django: pkg.installed
python-crypto: pkg.installed
python-yaml: pkg.installed
Other values can be overridden during the expansion by providing an additional dictionary level.
ius: pkgrepo.managed: - humanname: IUS Community Packages for Enterprise Linux 6 - $basearch - gpgcheck: 1 - baseurl: http://mirror.rackspace.com/ius/stable/CentOS/6/$basearch - gpgkey: http://dl.iuscommunity.org/pub/ius/IUS-COMMUNITY-GPG-KEY - names: - ius - ius-devel: - baseurl: http://mirror.rackspace.com/ius/development/CentOS/6/$basearch
Large example Here is the layout in yaml using the names of the highdata structure components.
<Include Declaration>: - <Module Reference> - <Module Reference>
<Extend Declaration>: <ID Declaration>: [<overrides>]
# standard declaration
<ID Declaration>: <State Module>: - <Function> - <Function Arg> - <Function Arg> - <Function Arg> - <Name>: <name> - <Requisite Declaration>: - <Requisite Reference> - <Requisite Reference>
# inline function and names
<ID Declaration>: <State Module>.<Function>: - <Function Arg> - <Function Arg> - <Function Arg> - <Names>: - <name> - <name> - <name> - <Requisite Declaration>: - <Requisite Reference> - <Requisite Reference>
# multiple states for single id
<ID Declaration>: <State Module>: - <Function> - <Function Arg> - <Name>: <name> - <Requisite Declaration>: - <Requisite Reference> <State Module>: - <Function> - <Function Arg> - <Names>: - <name> - <name> - <Requisite Declaration>: - <Requisite Reference>
Include and Exclude Salt SLS files can include other SLS files and exclude SLS files that have been otherwise included. This allows for an SLS file to easily extend or manipulate other SLS files.
Include When other SLS files are included, everything defined in the included SLS file will be added to the state run. When including define a list of SLS formulas to include:
include: - http - libvirt
The include statement will include SLS formulas from the same environment that the including SLS formula is in. But the environment can be explicitly defined in the configuration to override the running environment, therefore if an SLS formula needs to be included from an external environment named "dev" the following syntax is used:
include: - dev: http
NOTE: include does not simply inject the states where you place it in the SLS file. If you need to guarantee order of execution, consider using requisites.
Relative Include In Salt 0.16.0, the capability to include SLS formulas which are relative to the running SLS formula was added.  Simply precede the formula name with a .:
include: - .virt - .virt.hyper
In Salt 2015.8, the ability to include SLS formulas which are relative to the parents of the running SLS formula was added.  In order to achieve this, precede the formula name with more than one . (dot). Much like Python's relative import abilities, two or more leading dots represent a relative include of the parent or parents of the current package, with each .  representing one level after the first.
The following SLS configuration, if placed within example.dev.virtual, would result in example.http and base being included respectively:
include: - ..http - ...base
Exclude The exclude statement, added in Salt 0.10.3, allows an SLS to hard exclude another SLS file or a specific id. The component is excluded after the high data has been compiled, so nothing should be able to override an exclude.
Since the exclude can remove an id or an sls the type of component to exclude needs to be defined. An exclude statement that verifies that the running highstate does not contain the http sls and the /etc/vimrc id would look like this:
exclude: - sls: http - id: /etc/vimrc
NOTE: The current state processing flow checks for duplicate IDs before processing excludes. An error occurs if duplicate IDs are present even if one of the IDs is targeted by an exclude.
State System Layers The Salt state system is comprised of multiple layers. While using Salt does not require an understanding of the state layers, a deeper understanding of how Salt compiles and manages states can be very beneficial.
Function Call The lowest layer of functionality in the state system is the direct state function call. State executions are executions of single state functions at the core. These individual functions are defined in state modules and can be called directly via the state.single command.
salt '*' state.single pkg.installed name='vim'
Low Chunk The low chunk is the bottom of the Salt state compiler. This is a data representation of a single function call. The low chunk is sent to the state caller and used to execute a single state function.
A single low chunk can be executed manually via the state.low command.
salt '*' state.low '{name: vim, state: pkg, fun: installed}'
The passed data reflects what the state execution system gets after compiling the data down from sls formulas.
Low State The Low State layer is the list of low chunks "evaluated" in order. To see what the low state looks like for a highstate, run:
This will display the raw lowstate in the order which each low chunk will be evaluated. The order of evaluation is not necessarily the order of execution, since requisites are evaluated at runtime. Requisite execution and evaluation is finite; this means that the order of execution can be ascertained with 100% certainty based on the order of the low state.
High Data High data is the data structure represented in YAML via SLS files. The High data structure is created by merging the data components rendered inside sls files (or other render systems). The High data can be easily viewed by executing the state.show_highstate or state.show_sls functions. Since this data is a somewhat complex data structure, it may be easier to read using the json, yaml, or pprint outputters:
salt '*' state.show_highstate --out yaml salt '*' state.show_sls edit.vim --out pprint
SLS Above "High Data", the logical layers are no longer technically required to be executed, or to be executed in a hierarchy. This means that how the High data is generated is optional and very flexible. The SLS layer allows for many mechanisms to be used to render sls data from files or to use the fileserver backend to generate sls and file data from external systems.
The SLS layer can be called directly to execute individual sls formulas.
NOTE: SLS Formulas have historically been called "SLS files". This is because a single SLS was only constituted in a single file. Now the term "SLS Formula" better expresses how a compartmentalized SLS can be expressed in a much more dynamic way by combining pillar and other sources, and the SLS can be dynamically generated.
To call a single SLS formula named edit.vim, execute state.apply and pass edit.vim as an argument:
salt '*' state.apply edit.vim
HighState Calling SLS directly logically assigns what states should be executed from the context of the calling minion. The Highstate layer is used to allow for full contextual assignment of what is executed where to be tied to groups of, or individual, minions entirely from the master. This means that the environment of a minion, and all associated execution data pertinent to said minion, can be assigned from the master without needing to execute or configure anything on the target minion. This also means that the minion can independently retrieve information about its complete configuration from the master.
To execute the highstate use state.apply:
Orchestrate The orchestrate layer expresses the highest functional layer of Salt's automated logic systems. The Overstate allows for stateful and functional orchestration of routines from the master. The orchestrate defines in data execution stages which minions should execute states, or functions, and in what order using requisite logic.
The Orchestrate Runner NOTE: This documentation has been moved here.
Ordering States The way in which configuration management systems are executed is a hotly debated topic in the configuration management world. Two major philosophies exist on the subject, to either execute in an imperative fashion where things are executed in the order in which they are defined, or in a declarative fashion where dependencies need to be mapped between objects.
Imperative ordering is finite and generally considered easier to write, but declarative ordering is much more powerful and flexible but generally considered more difficult to create.
Salt has been created to get the best of both worlds. States are evaluated in a finite order, which guarantees that states are always executed in the same order, and the states runtime is declarative, making Salt fully aware of dependencies via the requisite system.
State Auto Ordering Salt always executes states in a finite manner, meaning that they will always execute in the same order regardless of the system that is executing them. This evaluation order makes it easy to know what order the states will be executed in, but it is important to note that the requisite system will override the ordering defined in the files, and the order option, described below, will also override the order in which states are executed.
This ordering system can be disabled in preference of lexicographic (classic) ordering by setting the state_auto_order option to False in the master configuration file. Otherwise, state_auto_order defaults to True.
How compiler ordering is managed is described further in compiler-ordering.
Requisite Statements NOTE: The behavior of requisites changed in version 0.9.7 of Salt.  This documentation applies to requisites in version 0.9.7 and later.
Often when setting up states any single action will require or depend on another action. Salt allows for the building of relationships between states with requisite statements. A requisite statement ensures that the named state is evaluated before the state requiring it. There are three types of requisite statements in Salt, require, watch, and prereq.
These requisite statements are applied to a specific state declaration:
httpd: pkg.installed: [] file.managed: - name: /etc/httpd/conf/httpd.conf - source: salt://httpd/httpd.conf - require: - pkg: httpd
In this example, the require requisite is used to declare that the file /etc/httpd/conf/httpd.conf should only be set up if the pkg state executes successfully.
The requisite system works by finding the states that are required and executing them before the state that requires them. Then the required states can be evaluated to see if they have executed correctly.
Require statements can refer to any state defined in Salt. The basic examples are pkg, service, and file, but any used state can be referenced.
In addition to state declarations such as pkg, file, etc., sls type requisites are also recognized, and essentially allow 'chaining' of states. This provides a mechanism to ensure the proper sequence for complex state formulas, especially when the discrete states are split or groups into separate sls files:
include: - network
httpd: pkg.installed: [] service.running: - require: - pkg: httpd - sls: network
In this example, the httpd service running state will not be applied (i.e., the httpd service will not be started) unless both the httpd package is installed AND the network state is satisfied.
NOTE: Requisite matching
Requisites match on both the ID Declaration and the name parameter. Therefore, if using the pkgs or sources argument to install a list of packages in a pkg state, it's important to note that it is impossible to match an individual package in the list, since all packages are installed as a single state.
Multiple Requisites The requisite statement is passed as a list, allowing for the easy addition of more requisites. Both requisite types can also be separately declared:
httpd: pkg.installed: [] service.running: - enable: True - watch: - file: /etc/httpd/conf/httpd.conf - require: - pkg: httpd - user: httpd - group: httpd file.managed: - name: /etc/httpd/conf/httpd.conf - source: salt://httpd/httpd.conf - require: - pkg: httpd user.present: [] group.present: []
In this example, the httpd service is only going to be started if the package, user, group, and file are executed successfully.
Requisite Documentation For detailed information on each of the individual requisites, please look here.
The Order Option Before using the order option, remember that the majority of state ordering should be done with a requisite-declaration, and that a requisite declaration will override an order option, so a state with order option should not require or required by other states.
The order option is used by adding an order number to a state declaration with the option order:
vim: pkg.installed: - order: 1
By adding the order option to 1 this ensures that the vim package will be installed in tandem with any other state declaration set to the order 1.
Any state declared without an order option will be executed after all states with order options are executed.
But this construct can only handle ordering states from the beginning. Certain circumstances will present a situation where it is desirable to send a state to the end of the line. To do this, set the order to last:
vim: pkg.installed: - order: last
Running States in Parallel Introduced in Salt version 2017.7.0 it is now possible to run select states in parallel. This is accomplished very easily by adding the parallel: True option to your state declaration:
nginx: service.running: - parallel: True
Now nginx will be started in a separate process from the normal state run and will therefore not block additional states.
Parallel States and Requisites Parallel States still honor requisites. If a given state requires another state that has been run in parallel then the state runtime will wait for the required state to finish.
Given this example:
sleep 10: cmd.run: - parallel: True
nginx: service.running: - parallel: True - require: - cmd: sleep 10
sleep 5: cmd.run: - parallel: True
The sleep 10 will be started first, then the state system will block on starting nginx until the sleep 10 completes. Once nginx has been ensured to be running then the sleep 5 will start.
This means that the order of evaluation of Salt States and requisites are still honored, and given that in the above case, parallel: True does not actually speed things up.
To run the above state much faster make sure that the sleep 5 is evaluated before the nginx state
Now both of the sleep calls will be started in parallel and nginx will still wait for the state it requires, but while it waits the sleep 5 state will also complete.
Things to be Careful of Parallel States do not prevent you from creating parallel conflicts on your system. This means that if you start multiple package installs using Salt then the package manager will block or fail. If you attempt to manage the same file with multiple states in parallel then the result can produce an unexpected file.
Make sure that the states you choose to run in parallel do not conflict, or else, like in any parallel programming environment, the outcome may not be what you expect. Doing things like just making all states run in parallel will almost certainly result in unexpected behavior.
With that said, running states in parallel should be safe the vast majority of the time and the most likely culprit for unexpected behavior is running multiple package installs in parallel.
State Providers New in version 0.9.8.
Salt predetermines what modules should be mapped to what uses based on the properties of a system. These determinations are generally made for modules that provide things like package and service management.
Sometimes in states, it may be necessary to use an alternative module to provide the needed functionality. For instance, an very old Arch Linux system may not be running systemd, so instead of using the systemd service module, you can revert to the default service module:
httpd: service.running: - enable: True - provider: service
In this instance, the basic service module (which manages sysvinit-based services) will replace the systemd module which is used by default on Arch Linux.
This change only affects this one state though. If it is necessary to make this override for most or every service, it is better to just override the provider in the minion config file, as described here.
Also, keep in mind that this only works for states with an identically-named virtual module (pkg, service, etc.).
Arbitrary Module Redirects The provider statement can also be used for more powerful means, instead of overwriting or extending the module used for the named service an arbitrary module can be used to provide certain functionality.
emacs: pkg.installed: - provider: - cmd: customcmd
In this example, the state is being instructed to use a custom module to invoke commands.
Arbitrary module redirects can be used to dramatically change the behavior of a given state.
Requisites and Other Global State Arguments Requisites The Salt requisite system is used to create relationships between states. This provides a method to easily define inter-dependencies between states. These dependencies are expressed by declaring the relationships using state names and IDs or names. The generalized form of a requisite target is <state name>: <ID or name>. The specific form is defined as a Requisite Reference.
A common use-case for requisites is ensuring a package has been installed before trying to ensure the service is running. In the following example, Salt will ensure nginx has been installed before trying to manage the service. If the package could not be installed, Salt will not try to manage the service.
nginx: pkg.installed: - name: nginx-light service.running: - enable: True - require: - pkg: nginx
Without the requisite defined, salt would attempt to install the package and then attempt to manage the service even if the installation failed.
These requisites always form dependencies in a predictable single direction.  Each requisite has an alternate <requisite>_in form that can be used to establish a "reverse" dependency--useful in for loops.
In the end, a single dependency map is created and everything is executed in a finite and predictable order.
Requisite matching Requisites typically need two pieces of information for matching:
• The state module name (e.g. pkg or service)
• The state identifier (e.g. nginx or /etc/nginx/nginx.conf)
nginx: pkg.installed: [] file.managed: - name: /etc/nginx/nginx.conf service.running: - require: - pkg: nginx - file: /etc/nginx/nginx.conf
Glob matching in requisites New in version 0.9.8.
Glob matching is supported in requisites. This is mostly useful for file changes. In the example below, a change in /etc/apache2/httpd.conf or /etc/apache2/sites-available/default.conf will reload/restart the service:
apache2: service.running: - watch: - file: /etc/apache2/*
Omitting state module in requisites New in version 2016.3.0.
In version 2016.3.0, the state module name was made optional. If the state module is omitted, all states matching the ID will be required, regardless of which module they are using.
- require: - vim
State target matching In order to understand how state targets are matched, it is helpful to know how the state compiler is working. Consider the following example:
Deploy server package: file.managed: - name: /usr/local/share/myapp.tar.xz - source: salt://myapp.tar.xz
Extract server package: archive.extracted: - name: /usr/local/share/myapp - source: /usr/local/share/myapp.tar.xz - archive_format: tar - onchanges: - file: Deploy server package
The first formula is converted to a dictionary which looks as follows (represented as YAML, some properties omitted for simplicity) as High Data:
Deploy server package: file: - managed - name: /usr/local/share/myapp.tar.xz - source: salt://myapp.tar.xz
The file.managed format used in the formula is essentially syntactic sugar: at the end, the target is file, which is used in the Extract server package state above.
Identifier matching Requisites match on both the ID Declaration and the name parameter.  This means that, in the "Deploy server package" example above, a require requisite would match with Deploy server package or /usr/local/share/myapp.tar.xz, so either of the following versions for "Extract server package" is correct:
# (Archive arguments omitted for simplicity)
# Match by ID declaration Extract server package: archive.extracted: - onchanges: - file: Deploy server package
# Match by name parameter Extract server package: archive.extracted: - onchanges: - file: /usr/local/share/myapp.tar.xz
Requisites Types All requisite types have a corresponding <requisite>_in form:
• require: Requires that a list of target states succeed before execution
• onchanges: Execute if any target states succeed with changes
• watch: Similar to onchanges; modifies state behavior using mod_watch
• listen: Similar to onchanges; delays execution to end of state run using mod_wait
• prereq: Execute prior to target state if target state expects to produce changes
• onfail: Execute only if a target state fails
• use: Copy arguments from another state
Several requisite types have a corresponding requisite_any form:
• require_any
• watch_any
• onchanges_any
• onfail_any
Lastly, onfail has one special onfail_all form to account for when AND logic is desired instead of the default OR logic of onfail/onfail_any (which are equivalent).
All requisites define specific relationships and always work with the dependency logic defined above.
require The use of require builds a dependency that prevents a state from executing until all required states execute successfully. If any required state fails, then the state will fail due to requisites.
In the following example, the service state will not be checked unless both file states execute without failure.
nginx: service.running: - require: - file: /etc/nginx/nginx.conf - file: /etc/nginx/conf.d/ssl.conf
Require SLS File As of Salt 0.16.0, it is possible to require an entire sls file. Do this by first including the sls file and then setting a state to require the included sls file:
include: - foo
bar: pkg.installed: - require: - sls: foo
This will add a require to all of the state declarations found in the given sls file. This means that bar will require every state within foo. This makes it very easy to batch large groups of states easily in any requisite statement.
onchanges New in version 2014.7.0.
The onchanges requisite makes a state only apply if the required states generate changes, and if the watched state's "result" is True (does not fail).  This can be a useful way to execute a post hook after changing aspects of a system.
If a state has multiple onchanges requisites then the state will trigger if any of the watched states changes.
myservice: file.managed: - name: /etc/myservice/myservice.conf - source: salt://myservice/files/myservice.conf cmd.run: - name: /usr/local/sbin/run-build - onchanges: - file: /etc/myservice/myservice.conf
In the example above, cmd.run will run only if there are changes in the file.managed state.
An easy mistake to make is using onchanges_in when onchanges is the correct choice, as seen in this next example.
myservice: file.managed: - name: /etc/myservice/myservice.conf - source: salt://myservice/files/myservice.conf cmd.run: - name: /usr/local/sbin/run-build - onchanges_in:  # <-- broken logic - file: /etc/myservice/myservice.conf
This will set up a requisite relationship in which the cmd.run state always executes, and the file.managed state only executes if the cmd.run state has changes (which it always will, since the cmd.run state includes the command results as changes).
It may semantically seem like the cmd.run state should only run when there are changes in the file state, but remember that requisite relationships involve one state watching another state, and a requisite_in does the opposite: it forces the specified state to watch the state with the requisite_in.
NOTE: An onchanges requisite has no effect on SLS requisites (monitoring for changes in an included SLS). Only the individual state IDs from an included SLS can be monitored.
watch A watch requisite is used to add additional behavior when there are changes in other states. This is done using the mod_watch function available from the execution module and will execute any time a watched state changes.
NOTE: If a state should only execute when another state has changes, and otherwise do nothing, the onchanges requisite should be used instead of watch. watch is designed to add additional behavior when there are changes, but otherwise the state executes normally.
NOTE: A watch requisite has no effect on SLS requisites (watching for changes in an included SLS). Only the individual state IDs from an included SLS can be watched.
A good example of using watch is with a service.running state. When a service watches a state, then the service is reloaded/restarted when the watched state changes, in addition to Salt ensuring that the service is running.
ntpd: service.running: - watch: - file: /etc/ntp.conf file.managed: - name: /etc/ntp.conf - source: salt://ntp/files/ntp.conf
Another useful example of watch is using salt to ensure a configuration file is present and in a correct state, ensure the service is running, and trigger service nginx reload instead of service nginx restart in order to avoid dropping any connections.
nginx: service.running: - reload: True - watch: - file: nginx file.managed: - name: /etc/nginx/conf.d/tls-settings.conf - source: salt://nginx/files/tls-settings.conf
NOTE: Not all state modules contain mod_watch. If mod_watch is absent from the watching state module, the watch requisite behaves exactly like a require requisite.
The state containing the watch requisite is defined as the watching state. The state specified in the watch statement is defined as the watched state. When the watched state executes, it will return a dictionary containing a key named "changes". Here are two examples of state return dictionaries, shown in json for clarity:
{ "local": { "file_|-/tmp/foo_|-/tmp/foo_|-directory": { "comment": "Directory /tmp/foo updated", "__run_num__": 0, "changes": { "user": "bar" }, "name": "/tmp/foo", "result": true } } }
{ "local": { "pkgrepo_|-salt-minion_|-salt-minion_|-managed": { "comment": "Package repo 'salt-minion' already configured", "__run_num__": 0, "changes": {}, "name": "salt-minion", "result": true } } }
If the "result" of the watched state is True, the watching state will execute normally, and if it is False, the watching state will never run. This part of watch mirrors the functionality of the require requisite.
If the "result" of the watched state is True and the "changes" key contains a populated dictionary (changes occurred in the watched state), then the watch requisite can add additional behavior. This additional behavior is defined by the mod_watch function within the watching state module. If the mod_watch function exists in the watching state module, it will be called in addition to the normal watching state. The return data from the mod_watch function is what will be returned to the master in this case; the return data from the main watching function is discarded.
If the "changes" key contains an empty dictionary, the watch requisite acts exactly like the require requisite (the watching state will execute if "result" is True, and fail if "result" is False in the watched state).
NOTE: If the watching state changes key contains values, then mod_watch will not be called. If you're using watch or watch_in then it's a good idea to have a state that only enforces one attribute - such as splitting out service.running into its own state and have service.enabled in another.
One common source of confusion is expecting mod_watch to be called for every necessary change. You might be tempted to write something like this:
httpd: service.running: - enable: True - watch: - file: httpd-config
httpd-config: file.managed: - name: /etc/httpd/conf/httpd.conf - source: salt://httpd/files/apache.conf
If your service is already running but not enabled, you might expect that Salt will be able to tell that since the config file changed your service needs to be restarted. This is not the case. Because the service needs to be enabled, that change will be made and mod_watch will never be triggered. In this case, changes to your apache.conf will fail to be loaded. If you want to ensure that your service always reloads the correct way to handle this is either ensure that your service is not running before applying your state, or simply make sure that service.running is in a state on its own:
enable-httpd: service.enabled: - name: httpd
start-httpd: service.running: - name: httpd - watch: - file: httpd-config
Now that service.running is its own state, changes to service.enabled will no longer prevent mod_watch from getting triggered, so your httpd service will get restarted like you want.
listen New in version 2014.7.0.
A listen requisite is used to trigger the mod_wait function of an execution module. Rather than modifying execution order, the mod_wait state created by listen will execute at the end of the state run.
restart-apache2: service.running: - name: apache2 - listen: - file: /etc/apache2/apache2.conf
configure-apache2: file.managed: - name: /etc/apache2/apache2.conf - source: salt://apache2/apache2.conf
This example will cause apache2 to restart when the apache2.conf file is changed, but the apache2 restart will happen at the end of the state run.
restart-apache2: service.running: - name: apache2
configure-apache2: file.managed: - name: /etc/apache2/apache2.conf - source: salt://apache2/apache2.conf - listen_in: - service: apache2
This example does the same as the above example, but puts the state argument on the file resource, rather than the service resource.
prereq New in version 0.16.0.
The prereq requisite works similar to onchanges except that it uses the result from test=True on the observed state to determine if it should run prior to the observed state being run.
The best way to define how prereq operates is displayed in the following practical example: When a service should be shut down because underlying code is going to change, the service should be off-line while the update occurs. In this example, graceful-down is the pre-requiring state and site-code is the pre-required state.
graceful-down: cmd.run: - name: service apache graceful - prereq: - file: site-code
site-code: file.recurse: - name: /opt/site_code - source: salt://site/code
In this case, the apache server will only be shut down if the site-code state expects to deploy fresh code via the file.recurse call. The site-code deployment will only be executed if the graceful-down run completes successfully.
When a prereq requisite is evaluated, the pre-required state reports if it expects to have any changes. It does this by running the pre-required single state as a test-run by enabling test=True. This test-run will return a dictionary containing a key named "changes". (See the watch section above for examples of "changes" dictionaries.)
If the "changes" key contains a populated dictionary, it means that the pre-required state expects changes to occur when the state is actually executed, as opposed to the test-run. The pre-requiring state will now run. If the pre-requiring state executes successfully, the pre-required state will then execute. If the pre-requiring state fails, the pre-required state will not execute.
If the "changes" key contains an empty dictionary, this means that changes are not expected by the pre-required state. Neither the pre-required state nor the pre-requiring state will run.
onfail New in version 2014.7.0.
The onfail requisite allows for reactions to happen strictly as a response to the failure of another state. This can be used in a number of ways, such as sending a notification or attempting an alternate task or thread of tasks when an important state fails.
The onfail requisite is applied in the same way as require and watch:
primary_mount: mount.mounted: - name: /mnt/share - device: 10.0.0.45:/share - fstype: nfs
backup_mount: mount.mounted: - name: /mnt/share - device: 192.168.40.34:/share - fstype: nfs - onfail: - mount: primary_mount
build_site: cmd.run: - name: /srv/web/app/build_site
notify-build_failure: hipchat.send_message: - room_id: 123456 - message: "Building website fail on {{ salt.grains.get('id') }}"
The default behavior of the onfail when multiple requisites are listed is the opposite of other requisites in the salt state engine, it acts by default like any() instead of all(). This means that when you list multiple onfail requisites on a state, if any fail the requisite will be satisfied.  If you instead need all logic to be applied, you can use onfail_all form:
test_site_a: cmd.run: - name: ping -c1 10.0.0.1
test_site_b: cmd.run: - name: ping -c1 10.0.0.2
notify_site_down: hipchat.send_message: - room_id: 123456 - message: "Both primary and backup sites are down!" - onfail_all: - cmd: test_site_a - cmd: test_site_b
In this contrived example notify_site_down will run when both 10.0.0.1 and 10.0.0.2 fail to respond to ping.
NOTE: Setting failhard (globally or in the failing state) to True will cause onfail, onfail_in and onfail_any requisites to be ignored.  If you want to combine a global failhard set to True with onfail, onfail_in or onfail_any, you will have to explicitly set failhard to False (overriding the global setting) in the state that could fail.
NOTE: Beginning in the 2016.11.0 release of Salt, onfail uses OR logic for multiple listed onfail requisites. Prior to the 2016.11.0 release, onfail used AND logic. See Issue #22370 for more information. Beginning in the Neon release of Salt, a new onfail_all requisite form is available if AND logic is desired.
use The use requisite is used to inherit the arguments passed in another id declaration. This is useful when many files need to have the same defaults.
/etc/foo.conf: file.managed: - source: salt://foo.conf - template: jinja - mkdirs: True - user: apache - group: apache - mode: 755
/etc/bar.conf: file.managed: - source: salt://bar.conf - use: - file: /etc/foo.conf
The use statement was developed primarily for the networking states but can be used on any states in Salt. This makes sense for the networking state because it can define a long list of options that need to be applied to multiple network interfaces.
The use statement does not inherit the requisites arguments of the targeted state. This means also a chain of use requisites would not inherit inherited options.
The _in version of requisites Direct requisites form a dependency in a single direction. This makes it possible for Salt to detect cyclical dependencies and helps prevent faulty logic. In some cases, often in loops, it is desirable to establish a dependency in the opposite direction.
All direct requisites have an _in counterpart that behaves the same but forms the dependency in the opposite direction. The following sls examples will produce the exact same dependency mapping.
httpd: pkg.installed: [] service.running: - require: - pkg: httpd
httpd: pkg.installed: - require_in: - service: httpd service.running: []
In the following example, Salt will not try to manage the nginx service or any configuration files unless the nginx package is installed because of the pkg: nginx requisite.
nginx: pkg.installed: [] service.running: - enable: True - reload: True - require: - pkg: nginx
php.sls
include: - http
php: pkg.installed: - require_in: - service: httpd
mod_python.sls
mod_python: pkg.installed: - require_in: - service: httpd
Now the httpd server will only start if both php and mod_python are first verified to be installed. Thus allowing for a requisite to be defined "after the fact".
{% for cfile in salt.pillar.get('nginx:config_files') %} /etc/nginx/conf.d/{{ cfile }}: file.managed: - source: salt://nginx/configs/{{ cfile }} - require: - pkg: nginx - listen_in: - service: nginx {% endfor %}
In this scenario, listen_in is a better choice than require_in because the listen requisite will trigger mod_wait behavior which will wait until the end of state execution and then reload the service.
The _any version of requisites New in version 2018.3.0.
Some requisites have an _any counterpart that changes the requisite behavior from all() to any().
A: cmd.run: - name: echo A - require_any: - cmd: B - cmd: C
B: cmd.run: - name: echo B
C: cmd.run: - name: /bin/false
In this example A will run because at least one of the requirements specified, B or C, will succeed.
myservice: pkg.installed
/etc/myservice/myservice.conf: file.managed: - source: salt://myservice/files/myservice.conf
/etc/yourservice/yourservice.conf: file.managed: - source: salt://yourservice/files/yourservice.conf
/usr/local/sbin/myservice/post-changes-hook.sh cmd.run: - onchanges_any: - file: /etc/myservice/myservice.conf - file: /etc/your_service/yourservice.conf - require: - pkg: myservice
In this example, cmd.run would be run only if either of the file.managed states generated changes and at least one of the watched state's "result" is True.
Altering States The state altering system is used to make sure that states are evaluated exactly as the user expects. It can be used to double check that a state preformed exactly how it was expected to, or to make 100% sure that a state only runs under certain conditions. The use of unless or onlyif options help make states even more stateful. The check_cmd option helps ensure that the result of a state is evaluated correctly.
reload reload_modules is a boolean option that forces salt to reload its modules after a state finishes. reload_pillar and reload_grains can also be set. See Reloading Modules.
grains_refresh: module.run: - name: saltutil.refresh_grains - reload_grains: true
grains_read: module.run: - name: grains.items
unless New in version 2014.7.0.
The unless requisite specifies that a state should only run when any of the specified commands return False. The unless requisite operates as NAND and is useful in giving more granular control over when a state should execute.
NOTE: Under the hood unless calls cmd.retcode with python_shell=True. This means the commands referenced by unless will be parsed by a shell, so beware of side-effects as this shell will be run with the same privileges as the salt-minion. Also be aware that the boolean value is determined by the shell's concept of True and False, rather than Python's concept of True and False.
vim: pkg.installed: - unless: - rpm -q vim-enhanced - ls /usr/bin/vim
In the example above, the state will only run if either the vim-enhanced package is not installed (returns False) or if /usr/bin/vim does not exist (returns False). The state will run if both commands return False.
However, the state will not run if both commands return True.
Unless checks are resolved for each name to which they are associated.
deploy_app: cmd.run: - names: - first_deploy_cmd - second_deploy_cmd - unless: some_check
In the above case, some_check will be run prior to _each_ name -- once for first_deploy_cmd and a second time for second_deploy_cmd.
Changed in version 3000: The unless requisite can take a module as a dictionary field in unless.  The dictionary must contain an argument fun which is the module that is being run, and everything else must be passed in under the args key or will be passed as individual kwargs to the module function.
install apache on debian based distros: cmd.run: - name: make install - cwd: /path/to/dir/whatever-2.1.5/ - unless: - fun: file.file_exists path: /usr/local/bin/whatever
set mysql root password: debconf.set: - name: mysql-server-5.7 - data: 'mysql-server/root_password': {'type': 'password', 'value': {{pillar['mysql.pass']}} } - unless: - fun: pkg.version args: - mysql-server-5.7
Changed in version sodium: For modules which return a deeper data structure, the get_return key can be used to access results.
test: test.nop: - name: foo - unless: - fun: consul.get consul_url: http://127.0.0.1:8500 key:  not-existing get_return: res
onlyif New in version 2014.7.0.
The onlyif requisite specifies that if each command listed in onlyif returns True, then the state is run. If any of the specified commands return False, the state will not run.
NOTE: Under the hood onlyif calls cmd.retcode with python_shell=True. This means the commands referenced by onlyif will be parsed by a shell, so beware of side-effects as this shell will be run with the same privileges as the salt-minion. Also be aware that the boolean value is determined by the shell's concept of True and False, rather than Python's concept of True and False.
stop-volume: module.run: - name: glusterfs.stop_volume - m_name: work - onlyif: - gluster volume status work - order: 1
remove-volume: module.run: - name: glusterfs.delete - m_name: work - onlyif: - gluster volume info work - watch: - cmd: stop-volume
The above example ensures that the stop_volume and delete modules only run if the gluster commands return a 0 ret value.
Changed in version 3000: The onlyif requisite can take a module as a dictionary field in onlyif.  The dictionary must contain an argument fun which is the module that is being run, and everything else must be passed in under the args key or will be passed as individual kwargs to the module function.
install apache on redhat based distros: pkg.latest: - name: httpd - onlyif: - fun: match.grain tgt: 'os_family:RedHat'
install apache on debian based distros: pkg.latest: - name: apache2 - onlyif: - fun: match.grain tgt: 'os_family:Debian'
arbitrary file example: file.touch: - name: /path/to/file - onlyif: - fun: file.search args: - /etc/crontab - 'entry1'
test: test.nop: - name: foo - onlyif: - fun: consul.get consul_url: http://127.0.0.1:8500 key:  does-exist get_return: res
Creates New in version 3001.
The creates requisite specifies that a state should only run when any of the specified files do not already exist. Like unless, creates requisite operates as NAND and is useful in giving more granular control over when a state should execute. This was previously used by the cmd and docker_container states.
contrived creates example: file.touch: - name: /path/to/file - creates: /path/to/file
creates also accepts a list of files, in which case this state will run if any of the files do not exist:
creates list: file.cmd: - name: /path/to/command - creates: - /path/file - /path/file2
runas New in version 2017.7.0.
The runas global option is used to set the user which will be used to run the command in the cmd.run module.
django: pip.installed: - name: django >= 1.6, <= 1.7 - runas: daniel - require: - pkg: python-pip
In the above state, the pip command run by cmd.run will be run by the daniel user.
runas_password New in version 2017.7.2.
The runas_password global option is used to set the password used by the runas global option. This is required by cmd.run on Windows when runas is specified. It will be set when runas_password is defined in the state.