22.9. Configuring the Salt Minion

The Salt system is amazingly simple and easy to configure, the two components of the Salt system each have a respective configuration file. The salt-master is configured via the master configuration file, and the salt-minion is configured via the minion configuration file.

The Salt Minion configuration is very simple, typically the only value that needs to be set is the master value so the minion can find its master.

By default, the salt-minion configuration will be in /etc/salt/minion. A notable exception is FreeBSD, where the configuration will be in /usr/local/etc/salt/minion.

22.9.1. Minion Primary Configuration

22.9.1.1. master

Default: salt

The hostname or ipv4 of the master.

Default: salt

master: salt

The option can can also be set to a list of masters, enabling multi-master mode.

master:
  - address1
  - address2

Changed in version 2014.7.0: The master can be dynamically configured. The master value can be set to an module function which will be executed and will assume that the returning value is the ip or hostname of the desired master. If a function is being specified, then the master_type option must be set to func, to tell the minion that the value is a function to be run and not a fully-qualified domain name.

master: module.function
master_type: func

In addition, instead of using multi-master mode, the minion can be configured to use the list of master addresses as a failover list, trying the first address, then the second, etc. until the minion successfully connects. To enable this behavior, set master_type to failover:

master:
  - address1
  - address2
master_type: failover

22.9.1.2. master_type

New in version 2014.7.0.

Default: str

The type of the master variable. Can be either func or failover.

If the master needs to be dynamically assigned by executing a function instead of reading in the static master value, set this to func. This can be used to manage the minion's master setting from an execution module. By simply changing the algorithm in the module to return a new master ip/fqdn, restart the minion and it will connect to the new master.

master_type: func

If this option is set to failover, master must be a list of master addresses. The minion will then try each master in the order specified in the list until it successfully connects.

master_type: failover

22.9.1.3. master_shuffle

New in version 2014.7.0.

Default: False

If master is a list of addresses, shuffle them before trying to connect to distribute the minions over all available masters. This uses Python's random.shuffle method.

master_shuffle: True

22.9.1.4. master_port

Default: 4506

The port of the master ret server, this needs to coincide with the ret_port option on the Salt master.

master_port: 4506

22.9.1.5. user

Default: root

The user to run the Salt processes

user: root

22.9.1.6. pidfile

Default: /var/run/salt-minion.pid

The location of the daemon's process ID file

pidfile: /var/run/salt-minion.pid

22.9.1.7. root_dir

Default: /

This directory is prepended to the following options: pki_dir, cachedir, log_file, sock_dir, and pidfile.

root_dir: /

22.9.1.8. pki_dir

Default: /etc/salt/pki

The directory used to store the minion's public and private keys.

pki_dir: /etc/salt/pki

22.9.1.9. id

Default: the system's hostname

See also

Salt Walkthrough

The Setting up a Salt Minion section contains detailed information on how the hostname is determined.

Explicitly declare the id for this minion to use. Since Salt uses detached ids it is possible to run multiple minions on the same machine but with different ids.

id: foo.bar.com

22.9.1.10. append_domain

Default: None

Append a domain to a hostname in the event that it does not exist. This is useful for systems where socket.getfqdn() does not actually result in a FQDN (for instance, Solaris).

append_domain: foo.org

22.9.1.11. cachedir

Default: /var/cache/salt

The location for minion cache data.

cachedir: /var/cache/salt

22.9.1.12. verify_env

Default: True

Verify and set permissions on configuration directories at startup.

verify_env: True

Note

When marked as True the verify_env option requires WRITE access to the configuration directory (/etc/salt/). In certain situations such as mounting /etc/salt/ as read-only for templating this will create a stack trace when state.highstate is called.

22.9.1.13. cache_jobs

Default: False

The minion can locally cache the return data from jobs sent to it, this can be a good way to keep track of the minion side of the jobs the minion has executed. By default this feature is disabled, to enable set cache_jobs to True.

cache_jobs: False

22.9.1.14. sock_dir

Default: /var/run/salt/minion

The directory where Unix sockets will be kept.

sock_dir: /var/run/salt/minion

22.9.1.15. backup_mode

Default: []

Backup files replaced by file.managed and file.recurse under cachedir.

backup_mode: minion

22.9.1.16. acceptance_wait_time

Default: 10

The number of seconds to wait until attempting to re-authenticate with the master.

acceptance_wait_time: 10

22.9.1.17. random_reauth_delay

When the master key changes, the minion will try to re-auth itself to receive the new master key. In larger environments this can cause a syn-flood on the master because all minions try to re-auth immediately. To prevent this and have a minion wait for a random amount of time, use this optional parameter. The wait-time will be a random number of seconds between 0 and the defined value.

random_reauth_delay: 60

22.9.1.18. acceptance_wait_time_max

Default: None

The maximum number of seconds to wait until attempting to re-authenticate with the master. If set, the wait will increase by acceptance_wait_time seconds each iteration.

acceptance_wait_time_max: None

22.9.1.19. ipc_mode

Default: ipc

Windows platforms lack POSIX IPC and must rely on slower TCP based inter- process communications. Set ipc_mode to tcp on such systems.

ipc_mode: ipc

22.9.1.20. tcp_pub_port

Default: 4510

Publish port used when ipc_mode is set to tcp.

tcp_pub_port: 4510

22.9.1.21. tcp_pull_port

Default: 4511

Pull port used when ipc_mode is set to tcp.

tcp_pull_port: 4511

22.9.2. Minion Module Management

22.9.2.1. disable_modules

Default: [] (all modules are enabled by default)

The event may occur in which the administrator desires that a minion should not be able to execute a certain module. The sys module is built into the minion and cannot be disabled.

This setting can also tune the minion, as all modules are loaded into ram disabling modules will lover the minion's ram footprint.

disable_modules:
  - test
  - solr

22.9.2.2. disable_returners

Default: [] (all returners are enabled by default)

If certain returners should be disabled, this is the place

disable_returners:
  - mongo_return

22.9.2.3. module_dirs

Default: []

A list of extra directories to search for Salt modules

module_dirs:
  - /var/lib/salt/modules

22.9.2.4. returner_dirs

Default: []

A list of extra directories to search for Salt returners

returners_dirs:
  - /var/lib/salt/returners

22.9.2.5. states_dirs

Default: []

A list of extra directories to search for Salt states

states_dirs:
  - /var/lib/salt/states

22.9.2.6. grains_dirs

Default: []

A list of extra directories to search for Salt grains

grains_dirs:
  - /var/lib/salt/grains

22.9.2.7. render_dirs

Default: []

A list of extra directories to search for Salt renderers

render_dirs:
  - /var/lib/salt/renderers

22.9.2.8. cython_enable

Default: False

Set this value to true to enable auto-loading and compiling of .pyx modules, This setting requires that gcc and cython are installed on the minion

cython_enable: False

22.9.2.9. providers

Default: (empty)

A module provider can be statically overwritten or extended for the minion via the providers option. This can be done on an individual basis in an SLS file, or globally here in the minion config, like below.

providers:
  service: systemd

22.9.3. State Management Settings

22.9.3.1. renderer

Default: yaml_jinja

The default renderer used for local state executions

renderer: yaml_jinja

22.9.3.2. state_verbose

Default: False

state_verbose allows for the data returned from the minion to be more verbose. Normally only states that fail or states that have changes are returned, but setting state_verbose to True will return all states that were checked

state_verbose: True

22.9.3.3. state_output

Default: full

The state_output setting changes if the output is the full multi line output for each changed state if set to 'full', but if set to 'terse' the output will be shortened to a single line.

state_output: full

22.9.3.4. autoload_dynamic_modules

Default: True

autoload_dynamic_modules Turns on automatic loading of modules found in the environments on the master. This is turned on by default, to turn of auto-loading modules when states run set this value to False

autoload_dynamic_modules: True

Default: True

clean_dynamic_modules keeps the dynamic modules on the minion in sync with the dynamic modules on the master, this means that if a dynamic module is not on the master it will be deleted from the minion. By default this is enabled and can be disabled by changing this value to False

clean_dynamic_modules: True

22.9.3.5. environment

Default: None

Normally the minion is not isolated to any single environment on the master when running states, but the environment can be isolated on the minion side by statically setting it. Remember that the recommended way to manage environments is to isolate via the top file.

environment: None

22.9.4. File Directory Settings

22.9.4.1. file_client

Default: remote

The client defaults to looking on the master server for files, but can be directed to look on the minion by setting this parameter to local.

file_client: remote

22.9.4.2. file_roots

Default:

base:
  - /srv/salt

When using a local file_client, this parameter is used to setup the fileserver's environments. This parameter operates identically to the master config parameter of the same name.

file_roots:
  base:
    - /srv/salt
  dev:
    - /srv/salt/dev/services
    - /srv/salt/dev/states
  prod:
    - /srv/salt/prod/services
    - /srv/salt/prod/states

22.9.4.3. hash_type

Default: md5

The hash_type is the hash to use when discovering the hash of a file on the local fileserver. The default is md5, but sha1, sha224, sha256, sha384 and sha512 are also supported.

hash_type: md5

22.9.4.4. pillar_roots

Default:

base:
  - /srv/pillar

When using a local file_client, this parameter is used to setup the pillar environments.

pillar_roots:
  base:
    - /srv/pillar
  dev:
    - /srv/pillar/dev
  prod:
    - /srv/pillar/prod

22.9.5. Security Settings

22.9.5.1. open_mode

Default: False

Open mode can be used to clean out the PKI key received from the Salt master, turn on open mode, restart the minion, then turn off open mode and restart the minion to clean the keys.

open_mode: False

22.9.5.2. verify_master_pubkey_sign

Default: False

Enables verification of the master-public-signature returned by the master in auth-replies. Please see the tutorial on how to configure this properly Multimaster-PKI with Failover Tutorial

New in version 2014.7.0.

verify_master_pubkey_sign: True

If this is set to True, master_sign_pubkey must be also set to True in the master configuration file.

22.9.5.3. master_sign_key_name

Default: master_sign

The filename without the *.pub-suffix of the public that should be used for verifying the signature from the master. The file must be located in the minions pki-directory.

New in version 2014.7.0.

master_sign_key_name: <filename_without_suffix>

22.9.5.4. always_verify_signature

Default: False

If verify_master_pubkey_sign is enabled, the signature is only verified, if the public-key of the master changes. If the signature should always be verified, this can be set to True.

New in version 2014.7.0.

always_verify_signature: True

22.9.6. Thread Settings

Default: True

Disable multiprocessing support by default when a minion receives a publication a new process is spawned and the command is executed therein.

multiprocessing: True

22.9.7. Minion Logging Settings

22.9.7.1. log_file

Default: /var/log/salt/minion

The minion log can be sent to a regular file, local path name, or network location. See also log_file.

Examples:

log_file: /var/log/salt/minion
log_file: file:///dev/log
log_file: udp://loghost:10514

22.9.7.2. log_level

Default: warning

The level of messages to send to the console. See also log_level.

log_level: warning

22.9.7.3. log_level_logfile

Default: warning

The level of messages to send to the log file. See also log_level_logfile.

log_level_logfile: warning

22.9.7.4. log_datefmt

Default: %H:%M:%S

The date and time format used in console log messages. See also log_datefmt.

log_datefmt: '%H:%M:%S'

22.9.7.5. log_datefmt_logfile

Default: %Y-%m-%d %H:%M:%S

The date and time format used in log file messages. See also log_datefmt_logfile.

log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'

22.9.7.6. log_fmt_console

Default: [%(levelname)-8s] %(message)s

The format of the console logging messages. See also log_fmt_console.

log_fmt_console: '[%(levelname)-8s] %(message)s'

22.9.7.7. log_fmt_logfile

Default: %(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s

The format of the log file logging messages. See also log_fmt_logfile.

log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s'

22.9.7.8. log_granular_levels

Default: {}

This can be used to control logging levels more specifically. See also log_granular_levels.

22.9.7.9. failhard

Default: False

Set the global failhard flag, this informs all states to stop running states at the moment a single state fails

failhard: False

22.9.8. Include Configuration

22.9.8.1. default_include

Default: minion.d/*.conf

The minion can include configuration from other files. Per default the minion will automatically include all config files from minion.d/*.conf where minion.d is relative to the directory of the minion configuration file.

22.9.8.2. include

Default: not defined

The minion can include configuration from other files. To enable this, pass a list of paths to this option. The paths can be either relative or absolute; if relative, they are considered to be relative to the directory the main minion configuration file lives in. Paths can make use of shell-style globbing. If no files are matched by a path passed to this option then the minion will log a warning message.

# Include files from a minion.d directory in the same
# directory as the minion config file
include: minion.d/*.conf

# Include a single extra file into the configuration
include: /etc/roles/webserver

# Include several files and the minion.d directory
include:
  - extra_config
  - minion.d/*
  - /etc/roles/webserver

22.9.9. Frozen Build Update Settings

These options control how salt.modules.saltutil.update() works with esky frozen apps. For more information look at https://github.com/cloudmatrix/esky/.

22.9.9.1. update_url

Default: False (Update feature is disabled)

The url to use when looking for application updates. Esky depends on directory listings to search for new versions. A webserver running on your Master is a good starting point for most setups.

update_url: 'http://salt.example.com/minion-updates'

22.9.9.2. update_restart_services

Default: [] (service restarting on update is disabled)

A list of services to restart when the minion software is updated. This would typically just be a list containing the minion's service name, but you may have other services that need to go with it.

update_restart_services: ['salt-minion']

These docs are for Salt's development version: 442ca77.

Docs for previous releases are available on readthedocs.org.

Latest Salt release: 2014.1.10

Try the shiny new release candidate of Salt, v2014.7.0rc1! More info here.

Table Of Contents

Previous topic

22.8. Configuring the Salt Master

Next topic

22.10. Running the Salt Master/Minion as an Unprivileged User

SaltStack News

Upcoming SaltStack events, webinars and local meet ups and user groups.

SaltStack training