Configuring the Salt Master¶

interface¶

Default: 0.0.0.0 (all interfaces)

The local interface to bind to.

interface: 192.168.0.1

ipv6¶

Default: False

Whether the master should listen for IPv6 connections. If this is set to True, the interface option must be adjusted too (for example: "interface: '::'")

ipv6: True

publish_port¶

Default: 4505

The network port to set up the publication interface.

publish_port: 4505

master_id¶

Default: None

The id to be passed in the publish job to minions. This is used for MultiSyndics to return the job to the requesting master.

master_id: MasterOfMaster

user¶

Default: root

The user to run the Salt processes

user: root

max_open_files¶

Default: 100000

Each minion connecting to the master uses AT LEAST one file descriptor, the master subscription connection. If enough minions connect you might start seeing on the console(and then salt-master crashes):

Too many open files (tcp_listener.cpp:335)
Aborted (core dumped)

max_open_files: 100000

By default this value will be the one of ulimit -Hn, i.e., the hard limit for max open files.

To set a different value than the default one, uncomment, and configure this setting. Remember that this value CANNOT be higher than the hard limit. Raising the hard limit depends on the OS and/or distribution, a good way to find the limit is to search the internet for something like this:

raise max open files hard limit debian

worker_threads¶

Default: 5

The number of threads to start for receiving commands and replies from minions. If minions are stalling on replies because you have many minions, raise the worker_threads value.

Worker threads should not be put below 3 when using the peer system, but can drop down to 1 worker otherwise.

worker_threads: 5

ret_port¶

Default: 4506

The port used by the return server, this is the server used by Salt to receive execution returns and command executions.

ret_port: 4506

pidfile¶

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

Specify the location of the master pidfile.

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

root_dir¶

Default: /

The system root directory to operate from, change this to make Salt run from an alternative root.

root_dir: /

pki_dir¶

Default: /etc/salt/pki

The directory to store the pki authentication keys.

pki_dir: /etc/salt/pki

extension_modules¶

Directory for custom modules. This directory can contain subdirectories for each of Salt's module types such as "runners", "output", "wheel", "modules", "states", "returners", etc. This path is appended to root_dir.

extension_modules: srv/modules

module_dirs¶

Default: []

Like extension_modules, but a list of extra directories to search for Salt modules.

module_dirs:
  - /var/cache/salt/minion/extmods

cachedir¶

Default: /var/cache/salt

The location used to store cache information, particularly the job information for executed salt commands.

This directory may contain sensitive data and should be protected accordingly.

cachedir: /var/cache/salt

verify_env¶

Default: True

Verify and set permissions on configuration directories at startup.

verify_env: True

keep_jobs¶

Default: 24

Set the number of hours to keep old job information.

timeout¶

Default: 5

Set the default timeout for the salt command and api.

loop_interval¶

Default: 60

The loop_interval option controls the seconds for the master's maintenance process check cycle. This process updates file server backends, cleans the job cache and executes the scheduler.

output¶

Default: nested

Set the default outputter used by the salt command.

color¶

Default: True

By default output is colored, to disable colored output set the color value to False.

color: False

sock_dir¶

Default: /var/run/salt/master

Set the location to use for creating Unix sockets for master process communication.

sock_dir: /var/run/salt/master

enable_gpu_grains¶

Default: False

The master can take a while to start up when lspci and/or dmidecode is used to populate the grains for the master. Enable if you want to see GPU hardware data for your master.

job_cache¶

Default: True

The master maintains a job cache, while this is a great addition it can be a burden on the master for larger deployments (over 5000 minions). Disabling the job cache will make previously executed jobs unavailable to the jobs system and is not generally recommended. Normally it is wise to make sure the master has access to a faster IO system or a tmpfs is mounted to the jobs dir.

minion_data_cache¶

Default: True

The minion data cache is a cache of information about the minions stored on the master, this information is primarily the pillar and grains data. The data is cached in the Master cachedir under the name of the minion and used to predetermine what minions are expected to reply from executions.

minion_data_cache: True

ext_job_cache¶

Default: ''

Used to specify a default returner for all minions, when this option is set the specified returner needs to be properly configured and the minions will always default to sending returns to this returner. This will also disable the local job cache on the master.

ext_job_cache: redis

event_return¶

Default: ''

Specify the returner to use to log events. A returner may have installation and configuration requirements. Read the returner's documentation.

event_return: cassandra_cql

master_job_cache¶

Default: 'local_cache'

Specify the returner to use for the job cache. The job cache will only be interacted with from the salt master and therefore does not need to be accessible from the minions.

master_job_cache: redis

enforce_mine_cache¶

Default: False

By-default when disabling the minion_data_cache mine will stop working since it is based on cached data, by enabling this option we explicitly enabling only the cache for the mine system.

enforce_mine_cache: False

max_minions¶

Default: 0

The number of minions the master should allow to connect. Use this to accommodate the number of minions per master if you have different types of hardware serving your minions. The default of 0 means unlimited connections. Please note, that this can slow down the authentication process a bit in large setups.

max_minions: 100

con_cache¶

Default: False

If max_minions is used in large installations, the master might experience high-load situations because of having to check the number of connected minions for every authentication. This cache provides the minion-ids of all connected minions to all MWorker-processes and greatly improves the performance of max_minions.

con_cache: True

presence_events¶

Default: False

Causes the master to periodically look for actively connected minions. Presence events are fired on the event bus on a regular interval with a list of connected minions, as well as events with lists of newly connected or disconnected minions. This is a master-only operation that does not send executions to minions. Note, this does not detect minions that connect to a master via localhost.

presence_events: False

roster_file¶

Default: '/etc/salt/roster'

Pass in an alternative location for the salt-ssh roster file.

roster_file: /root/roster

ssh_minion_opts¶

Default: None

Pass in minion option overrides that will be inserted into the SHIM for salt-ssh calls. The local minion config is not used for salt-ssh. Can be overridden on a per-minion basis in the roster (minion_opts)

minion_opts:
  gpg_keydir: /root/gpg

open_mode¶

Default: False

Open mode is a dangerous security feature. One problem encountered with pki authentication systems is that keys can become "mixed up" and authentication begins to fail. Open mode turns off authentication and tells the master to accept all authentication. This will clean up the pki keys received from the minions. Open mode should not be turned on for general use. Open mode should only be used for a short period of time to clean up pki keys. To turn on open mode set this value to True.

open_mode: False

auto_accept¶

Default: False

Enable auto_accept. This setting will automatically accept all incoming public keys from minions.

auto_accept: False

autosign_timeout¶

Default: 120

Time in minutes that a incoming public key with a matching name found in pki_dir/minion_autosign/keyid is automatically accepted. Expired autosign keys are removed when the master checks the minion_autosign directory. This method to auto accept minions can be safer than an autosign_file because the keyid record can expire and is limited to being an exact name match. This should still be considered a less than secure option, due to the fact that trust is based on just the requesting minion id.

autosign_file¶

Default: not defined

If the autosign_file is specified incoming keys specified in the autosign_file will be automatically accepted. Matches will be searched for first by string comparison, then by globbing, then by full-string regex matching. This should still be considered a less than secure option, due to the fact that trust is based on just the requesting minion id.

autoreject_file¶

Default: not defined

Works like autosign_file, but instead allows you to specify minion IDs for which keys will automatically be rejected. Will override both membership in the autosign_file and the auto_accept setting.

client_acl¶

Default: {}

Enable user accounts on the master to execute specific modules. These modules can be expressed as regular expressions.

client_acl:
  fred:
    - test.ping
    - pkg.*

client_acl_blacklist¶

Default: {}

Blacklist users or modules

This example would blacklist all non sudo users, including root from running any commands. It would also blacklist any use of the "cmd" module.

This is completely disabled by default.

client_acl_blacklist:
  users:
    - root
    - '^(?!sudo_).*$'   #  all non sudo users
  modules:
    - cmd

external_auth¶

Default: {}

The external auth system uses the Salt auth modules to authenticate and validate users to access areas of the Salt system.

external_auth:
  pam:
    fred:
      - test.*

token_expire¶

Default: 43200

Time (in seconds) for a newly generated token to live.

Default: 12 hours

token_expire: 43200

file_recv¶

Default: False

Allow minions to push files to the master. This is disabled by default, for security purposes.

file_recv: False

master_sign_pubkey¶

Default: False

Sign the master auth-replies with a cryptographic signature of the masters public key. Please see the tutorial how to use these settings in the Multimaster-PKI with Failover Tutorial

master_sign_pubkey: True

master_sign_key_name¶

Default: master_sign

The customizable name of the signing-key-pair without suffix.

master_sign_key_name: <filename_without_suffix>

master_pubkey_signature¶

Default: master_pubkey_signature

The name of the file in the masters pki-directory that holds the pre-calculated signature of the masters public-key.

master_pubkey_signature: <filename>

master_use_pubkey_signature¶

Default: False

Instead of computing the signature for each auth-reply, use a pre-calculated signature. The master_pubkey_signature must also be set for this.

master_use_pubkey_signature: True

rotate_aes_key¶

Default: True

Rotate the salt-masters AES-key when a minion-public is deleted with salt-key. This is a very important security-setting. Disabling it will enable deleted minions to still listen in on the messages published by the salt-master. Do not disable this unless it is absolutely clear what this does.

rotate_aes_key: True

runner_dirs¶

Default: []

Set additional directories to search for runner modules.

cython_enable¶

Default: False

Set to true to enable Cython modules (.pyx files) to be compiled on the fly on the Salt master.

cython_enable: False

state_top¶

Default: top.sls

The state system uses a "top" file to tell the minions what environment to use and what modules to use. The state_top file is defined relative to the root of the base environment.

state_top: top.sls

master_tops¶

Default: {}

The master_tops option replaces the external_nodes option by creating a pluggable system for the generation of external top data. The external_nodes option is deprecated by the master_tops option. To gain the capabilities of the classic external_nodes system, use the following configuration:

master_tops:
  ext_nodes: <Shell command which returns yaml>

external_nodes¶

Default: None

The external_nodes option allows Salt to gather data that would normally be placed in a top file from and external node controller. The external_nodes option is the executable that will return the ENC data. Remember that Salt will look for external nodes AND top files and combine the results if both are enabled and available!

external_nodes: cobbler-ext-nodes

renderer¶

Default: yaml_jinja

The renderer to use on the minions to render the state data.

renderer: yaml_jinja

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

state_verbose¶

Default: True

Controls the verbosity of state runs. By default, the results of all states are returned, but setting this value to False will cause salt to only display output for states which either failed, or succeeded without making any changes to the minion.

state_verbose: False

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. If set to 'mixed', the output will be terse unless a state failed, in which case that output will be full. If set to 'changes', the output will be full unless the state didn't change.

state_output: full

yaml_utf8¶

Default: False

Enable extra routines for YAML renderer used states containing UTF characters.

yaml_utf8: False

test¶

Default: False

Set all state calls to only test if they are going to actually make changes or just post what changes are going to be made.

test: False

fileserver_backend¶

Default: ['roots']

Salt supports a modular fileserver backend system, this system allows the salt master to link directly to third party systems to gather and manage the files available to minions. Multiple backends can be configured and will be searched for the requested file in the order in which they are defined here. The default setting only enables the standard backend roots, which is configured using the file_roots option.

Example:

fileserver_backend:
  - roots
  - git

hash_type¶

Default: md5

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

hash_type: md5

file_buffer_size¶

Default: 1048576

The buffer size in the file server in bytes.

file_buffer_size: 1048576

file_ignore_regex¶

Default: ''

A regular expression (or a list of expressions) that will be matched against the file path before syncing the modules and states to the minions. This includes files affected by the file.recurse state. For example, if you manage your custom modules and states in subversion and don't want all the '.svn' folders and content synced to your minions, you could set this to '/.svn($|/)'. By default nothing is ignored.

file_ignore_regex:
  - '/\.svn($|/)'
  - '/\.git($|/)'

file_ignore_glob¶

Default ''

A file glob (or list of file globs) that will be matched against the file path before syncing the modules and states to the minions. This is similar to file_ignore_regex above, but works on globs instead of regex. By default nothing is ignored.

file_ignore_glob:
  - '\*.pyc'
  - '\*/somefolder/\*.bak'
  - '\*.swp'

roots: Master's Local File Server¶

base:
  - /srv/salt

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

git: Git Remote File Server Backend¶

gitfs_remotes:
  - git://github.com/saltstack/salt-states.git
  - file:///var/git/saltmaster

gitfs_provider: dulwich

gitfs_ssl_verify: True

gitfs_mountpoint: salt://foo/bar

gitfs_root: somefolder/otherfolder

gitfs_base: salt

gitfs_env_whitelist:
  - base
  - v1.*
  - 'mybranch\d+'

gitfs_env_blacklist:
  - base
  - v1.*
  - 'mybranch\d+'

gitfs_user: git

gitfs_password: mypassword

gitfs_insecure_auth: True

gitfs_pubkey: /path/to/key.pub

gitfs_privkey: /path/to/key

gitfs_passphrase: mypassphrase

hg: Mercurial Remote File Server Backend¶

hgfs_remotes:
  - https://username@bitbucket.org/username/reponame

hgfs_remotes:
  - https://username@bitbucket.org/username/repo1
    - base: saltstates
  - https://username@bitbucket.org/username/repo2:
    - root: salt
    - mountpoint: salt://foo/bar/baz
  - https://username@bitbucket.org/username/repo3:
    - root: salt/states
    - branch_method: mixed

hgfs_branch_method: mixed

hgfs_mountpoint: salt://foo/bar

hgfs_root: somefolder/otherfolder

hgfs_base: salt

hgfs_env_whitelist:
  - base
  - v1.*
  - 'mybranch\d+'

hgfs_env_blacklist:
  - base
  - v1.*
  - 'mybranch\d+'

svn: Subversion Remote File Server Backend¶

svnfs_remotes:
  - svn://foo.com/svn/myproject

svnfs_remotes:
  - svn://foo.com/svn/project1
  - svn://foo.com/svn/project2:
    - root: salt
    - mountpoint: salt://foo/bar/baz
  - svn//foo.com/svn/project3:
    - root: salt/states
    - branches: branch
    - tags: tag

svnfs_mountpoint: salt://foo/bar

svnfs_root: somefolder/otherfolder

svnfs_trunk: trunk

svnfs_branches: branches

svnfs_tags: tags

svnfs_env_whitelist:
  - base
  - v1.*
  - 'mybranch\d+'

svnfs_env_blacklist:
  - base
  - v1.*
  - 'mybranch\d+'

minion: MinionFS Remote File Server Backend¶

minionfs_env: minionfs

minionfs_mountpoint: salt://foo/bar

minionfs_whitelist:
  - base
  - v1.*
  - 'mybranch\d+'

minionfs_blacklist:
  - base
  - v1.*
  - 'mybranch\d+'

pillar_roots¶

Default:

base:
  - /srv/pillar

Set the environments and directories used to hold pillar sls data. This configuration is the same as file_roots:

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

ext_pillar¶

The ext_pillar option allows for any number of external pillar interfaces to be called when populating pillar data. The configuration is based on ext_pillar functions. The available ext_pillar functions can be found herein:

https://github.com/saltstack/salt/blob/develop/salt/pillar

By default, the ext_pillar interface is not configured to run.

Default: None

ext_pillar:
  - hiera: /etc/hiera.yaml
  - cmd_yaml: cat /etc/salt/yaml
  - reclass:
      inventory_base_uri: /etc/reclass

There are additional details at Pillars

ext_pillar_first¶

The ext_pillar_first option allows for external pillar sources to populate before file system pillar. This allows for targeting file system pillar from ext_pillar.

Default: False

ext_pillar_first: False

pillar_source_merging_strategy¶

Default: smart

The pillar_source_merging_strategy option allows you to configure merging strategy between different sources. It accepts 4 values:

• recurse:

  it will merge recursively mapping of data. For example, theses 2 sources:

  foo: 42
  bar:
      element1: True
  

  bar:
      element2: True
  baz: quux
  

  will be merged as:

  foo: 42
  bar:
      element1: True
      element2: True
  baz: quux
  

• aggregate:

  instructs aggregation of elements between sources that use the #!yamlex renderer.

  For example, these two documents:

  #!yamlex
  foo: 42
  bar: !aggregate {
    element1: True
  }
  baz: !aggregate quux
  

  #!yamlex
  bar: !aggregate {
    element2: True
  }
  baz: !aggregate quux2
  

  will be merged as:

  foo: 42
  bar:
    element1: True
    element2: True
  baz:
    - quux
    - quux2
  

• overwrite:

  Will use the behaviour of the 2014.1 branch and earlier.

  Overwrites elements according the order in which they are processed.

  First pillar processed:

  A:
    first_key: blah
    second_key: blah
  

  Second pillar processed:

  A:
    third_key: blah
    fourth_key: blah
  

  will be merged as:

  A:
    third_key: blah
    fourth_key: blah
  

• smart (default):

  Guesses the best strategy based on the "renderer" setting.

order_masters¶

Default: False

Extra data needs to be sent with publications if the master is controlling a lower level master via a syndic minion. If this is the case the order_masters value must be set to True

order_masters: False

syndic_master¶

Default: None

If this master will be running a salt-syndic to connect to a higher level master, specify the higher level master with this configuration value.

syndic_master: masterofmasters

syndic_master_port¶

Default: 4506

If this master will be running a salt-syndic to connect to a higher level master, specify the higher level master port with this configuration value.

syndic_master_port: 4506

syndic_pidfile¶

Default: salt-syndic.pid

If this master will be running a salt-syndic to connect to a higher level master, specify the pidfile of the syndic daemon.

syndic_pidfile: syndic.pid

syndic_log_file¶

Default: syndic.log

If this master will be running a salt-syndic to connect to a higher level master, specify the log_file of the syndic daemon.

syndic_log_file: salt-syndic.log

peer¶

Default: {}

The configuration uses regular expressions to match minions and then a list of regular expressions to match functions. The following will allow the minion authenticated as foo.example.com to execute functions from the test and pkg modules.

peer:
  foo.example.com:
      - test.*
      - pkg.*

This will allow all minions to execute all commands:

peer:
  .*:
      - .*

This is not recommended, since it would allow anyone who gets root on any single minion to instantly have root on all of the minions!

By adding an additional layer you can limit the target hosts in addition to the accessible commands:

peer:
  foo.example.com:
    'db*':
      - test.*
      - pkg.*

peer_run¶

Default: {}

The peer_run option is used to open up runners on the master to access from the minions. The peer_run configuration matches the format of the peer configuration.

The following example would allow foo.example.com to execute the manage.up runner:

peer_run:
  foo.example.com:
      - manage.up

log_file¶

Default: /var/log/salt/master

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

Examples:

log_file: /var/log/salt/master

log_file: file:///dev/log

log_file: udp://loghost:10514

log_level¶

Default: warning

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

log_level: warning

log_level_logfile¶

Default: warning

The level of messages to send to the log file. See also log_level_logfile. When it is not set explicitly it will inherit the level set by log_level option.

log_level_logfile: warning

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'

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'

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'

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'

log_granular_levels¶

Default: {}

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

range_server¶

Default: ''

The range server (and optional port) that serves your cluster information https://github.com/ytoolshed/range/wiki/%22yamlfile%22-module-file-spec

range_server: range:80

default_include¶

Default: master.d/*.conf

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

include¶

Default: not defined

The master 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 master will log a warning message.

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

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

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

win_repo¶

Default: /srv/salt/win/repo

Location of the repo on the master

win_repo: '/srv/salt/win/repo'

win_repo_mastercachefile¶

Default: /srv/salt/win/repo/winrepo.p

win_repo_mastercachefile: '/srv/salt/win/repo/winrepo.p'

win_gitrepos¶

Default: ''

List of git repositories to include with the local repo.

win_gitrepos:
  - 'https://github.com/saltstack/salt-winrepo.git'