Requisites and Other Global State Arguments¶

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

Wildcard matching in requisites¶

Wildcard matching is supported for state identifiers.

• * matches zero or more characters

• ? matches a single character

• [] matches a single character from the enclosed set

Note that this does not follow glob rules - dots and slashes are not special, and it is matching against state identifiers, not file paths.

In the example below, a change in any state managing an apache config file will reload/restart the service:

apache2:
  service.running:
    - watch:
      - file: /etc/apache2/*

A leading or bare * must be quoted to avoid confusion with YAML references:

/etc/letsencrypt/renewal-hooks/deploy/install.sh:
  cmd.run:
    - onchanges:
      - acme: '*'

Omitting state module¶

In version 2016.3.0, the state module name was made optional. If the state module is omitted, all states matching the identifier will be required, regardless of which module they are using.

- require:
  - vim

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

include:
  - foo

bar:
  pkg.installed:
    - require:
      - sls: foo

onchanges¶

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.

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.

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

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).

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

httpd-config:
  file.managed:
    - name: /etc/httpd/conf/httpd.conf
    - source: salt://httpd/files/apache.conf

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¶

A listen requisite is used to trigger the mod_watch function of a state module. Rather than modifying execution order, the mod_watch 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¶

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¶

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.

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

include:
  - http

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_watch behavior which will wait until the end of state execution and then reload the service.

The _any version of requisites¶

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.

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¶

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.

For example:

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.

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

test:
  test.nop:
    - name: foo
    - unless:
      - fun: consul.get
        consul_url: http://127.0.0.1:8500
        key:  not-existing
        get_return: res

jim_nologin:
  user.present:
    - name: jim
    - shell: /sbin/nologin
    - unless:
      - echo hello world
    - cmd_opts_exclude:
      - shell

onlyif¶

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.

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

jim_nologin:
  user.present:
    - name: jim
    - shell: /sbin/nologin
    - onlyif:
      - echo hello world
    - cmd_opts_exclude:
      - shell

creates¶

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¶

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¶

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.

run_script:
  cmd.run:
    - name: Powershell -NonInteractive -ExecutionPolicy Bypass -File C:\\Temp\\script.ps1
    - runas: frank
    - runas_password: supersecret

In the above state, the Powershell script run by cmd.run will be run by the frank user with the password supersecret.

check_cmd¶

Check Command is used for determining that a state did or did not run as expected.

NOTE: Under the hood check_cmd calls cmd.retcode with python_shell=True. This means the command 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.

comment-repo:
  file.replace:
    - name: /etc/yum.repos.d/fedora.repo
    - pattern: '^enabled=0'
    - repl: enabled=1
    - check_cmd:
      - "! grep 'enabled=0' /etc/yum.repos.d/fedora.repo"

This will attempt to do a replace on all enabled=0 in the .repo file, and replace them with enabled=1. The check_cmd is just a bash command. It will do a grep for enabled=0 in the file, and if it finds any, it will return a 0, which will be inverted by the leading !, causing check_cmd to set the state as failed. If it returns a 1, meaning it didn't find any enabled=0, it will be inverted by the leading !, returning a 0, and declaring the function succeeded.

NOTE: This requisite check_cmd functions differently than the check_cmd of the file.managed state.

Overriding Checks¶

There are two commands used for the above checks.

mod_run_check is used to check for onlyif and unless. If the goal is to override the global check for these to variables, include a mod_run_check in the salt/states/ file.

mod_run_check_cmd is used to check for the check_cmd options. To override this one, include a mod_run_check_cmd in the states file for the state.