These release notes are for an old release of Salt. This release might contain known security and other issues that are fixed in the latest release.

# Salt 3001 Release Notes - Codename Sodium

## Python 2 Dropped

Python 2 support has been dropped in Salt 3001. See https://community.saltstack.com/blog/sunsetting-python-2-support/ for more info.

## Salt mine updates

### Syntax update

The syntax for defining salt functions in config or pillar files has changed to also support the syntax used in `module.run`. The old syntax for the mine_function - as a dict, or as a list with dicts that contain more than exactly one key - is still supported but discouraged in favor of the more uniform syntax of module.run.

## State updates

The `creates` state requisite has been migrated from the `docker_container` and `cmd` states to become a global option. This acts similar to an equivalent `unless: test -f filename` but can also accept a list of filenames. This allows all states to take advantage of the enhanced functionality released in Neon, of allowing salt execution modules for requisite checks.

When using salt functions `onlyif` or `unless` requisites, a `get_return` key can now be used to specify a key to evaluate for truthiness. This can be used for execution modules which return status in a nested key.

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

## State Execution Module

The `state.test` function can be used to test a state on a minion. This works by executing the `state.apply` function while forcing the `test` kwarg to `True` so that the `state.apply` function is not required to be called by the user directly. This also allows you to add the `state.test` function to a minion's `minion_blackout_whitelist` pillar if you wish to be able to test a state while a minion is in blackout.

## New Grains

### systempath

This grain provides the same information as the `path` grain, only formatted as a list of directories.

## Salt-SSH updates

### ssh_pre_flight

A new Salt-SSH roster option `ssh_pre_flight` has been added. This enables you to run a script before Salt-SSH tries to run any commands. You can set this option in the roster for a specific minion or use the `roster_defaults` to set it for all minions.

Example for setting `ssh_pre_flight` for specific host in roster file

    minion1:
      host: localhost
      user: root
      passwd: P@ssword
      ssh_pre_flight: /srv/salt/pre_flight.sh

Example for setting `ssh_pre_flight` using roster_defaults, so all minions run this script.

    roster_defaults:
      ssh_pre_flight: /srv/salt/pre_flight.sh

The `ssh_pre_flight` script will only run if the thin dir is not currently on the minion. If you want to force the script to run you have the following options:

- Wipe the thin dir on the targeted minion using the -w arg.

- Set ssh_run_pre_flight to True in the config.

- Run salt-ssh with the --pre-flight arg.

### set_path

A new salt-ssh roster option set_path has been added. This allows you to set the path environment variable used to run the salt-ssh command on the target minion. You can set this setting in your roster file like so:

    minion1:
      host: localhost
      user: root
      passwd: P@ssword
      set_path: '$PATH:/usr/local/bin/'

### auto_detect

You can now auto detect the dependencies to be packed into the salt thin when using the `ssh_ext_alternatives` feature.

    ssh_ext_alternatives:
        2019.2:                     # Namespace, can be anything.
            py-version: [2, 7]      # Constraint to specific interpreter version
            path: /opt/2019.2/salt  # Main Salt installation directory.
            auto_detect: True       # Auto detect dependencies
            py_bin: /usr/bin/python2.7 # Python binary path used to auto detect dependencies

This new `auto_detect` option needs to be set to True in your `ssh_ext_alternatives` configuration. Salt-ssh will attempt to auto detect the file paths required for the default dependencies to include in the thin. If you have a dependency already set in your configuration, it will not attempt to auto detect for that dependency.

You can also set the `py_bin` option to set the python binary to be used to auto detect the dependencies. If `py_bin` is not set, it will attempt to use the major Python version set in `py-version`. For example, if you set `py-version` to be `[2, 7]` it will attempt to find and use the `python2` binary.

## State Changes

- Adding a new option for the State compiler, `disabled_requisites` will allow requisites to be disabled during State runs.

## Salt Renderer updates

A new renderer for toml files has been added.

    #!jinja|toml

    {% set myvar = "sometext" %}

    [["some id"."test.nop"]]
    name = "{{ myvar }}"
    [["some id"."test.nop"]]
    txt = "hello"
    [["some id"."test.nop"]]
    "somekey" = "somevalue"

## Execution Module updates

### Vault Module

The `vault module` has been updated with the ability to cache generated tokens. By specifying `uses` and optionally `ttl`, the token generated on behalf of the minion will be allowed to persist and function for the defined time period or number of uses. Setting `uses: 0` creates an unlimited use token, that is only constrained by the `ttl`.

    vault:
      auth:
        uses: 25

This functionality is configured by default on the master and is thus shared behavior for all minion token generation. To delegate use count to individual minions, specify `allow_minion_override: True` in the master config, and define `uses` and `ttl` in the minion config as directed above.

    vault:
    auth:
      method: token
      allow_minion_override: True

Additionally, the vault module now supports Vault secrets backend version 2. The approperate secrets backend will be automatically detected, and cached in the same credentials file as long lived vault tokens mentioned above. For any configurations that worked around KV v2 handling by adding a manual data key to the end of vault lookups, `salt['vault'].read_secret('secret/my/secret')['data']`, these are automatically detected and will continue to function, but will generate a debug log message and can be removed.

The long lived token and secret metadata cache file can be cleared with the new `vault.clear_token_cache` execution function.