# Configuring the Salt Master

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.

See also

example master configuration file

The configuration file for the salt-master is located at `/etc/salt/master`. The available options are as follows:

## Primary Master Configuration

### `interface`

Default: `0.0.0.0` (all interfaces)

The local interface to bind to.

    interface: 192.168.0.1

### `publish_port`

Default: `4505`

The network port to set up the publication interface

    publish_port: 4505

### `user`

Default: `root`

The user to run the Salt processes

    user: root

### `max_open_files`

Default: `max_open_files`

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)

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

If you wish 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 your OS and/or distribution, a good way to find the limit is to search the internet for(for example):

    raise max open files hard limit debian

    max_open_files: 100000

### `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

### `cachedir`

Default: `/var/cache/salt`

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

    cachedir: /var/cache/salt

### `keep_jobs`

Default: `24`

Set the number of hours to keep old job information

### `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

### `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

### `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 pre determine what minions are expected to reply from executions.

    minion_cache_dir: True

### `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

### `sock_dir`

Default:: `/tmp/salt-unix`

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

## Master Security Settings

### `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 the minions

    auto_accept: False

### `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 is insecure!

### `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 Module Management

### `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

## Master State System Settings

### `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

### `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

### `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

### `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

### `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

## Master File Server Settings

### `fileserver_backend`

Default:

    fileserver_backend:
      - 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
      - gitfs

### `file_roots`

Default:

    base:
      - /srv/salt

Salt runs a lightweight file server written in ZeroMQ to deliver files to minions. This file server is built into the master daemon and does not require a dedicated port.

The file server works on environments passed to the master. Each environment can have multiple root directories. The subdirectories in the multiple file roots cannot match, otherwise the downloaded files will not be able to be reliably ensured. A base environment is required to house the top file. Example:

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

### `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

## Pillar Configuration

### `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

## Syndic Server Settings

A Salt syndic is a Salt master used to pass commands from a higher Salt master to minions below the syndic. Using the syndic is simple. If this is a master that will have syndic servers(s) below it, set the "order_masters" setting to True. If this is a master that will be running a syndic daemon for passthrough the "syndic_master" setting needs to be set to the location of the master server

Do not not forget that in other word it means that it shares with the local minion it's ID and PKI_DIR.

### `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_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

### `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

## Peer Publish Settings

Salt minions can send commands to other minions, but only if the minion is allowed to. By default "Peer Publication" is disabled, and when enabled it is enabled for specific minions and specific commands. This allows secure compartmentalization of commands based on individual minions.

### `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

## Node Groups

Default: `{}`

Node groups allow for logical groupings of minion nodes. A group consists of a group name and a compound target.

    nodegroups:
      group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com'
      group2: 'G@os:Debian and foo.domain.com'

## Master Logging Settings

### `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`.

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

## Include Configuration

### `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

Current Salt release: 0.17.1

### Table Of Contents

- Configuring the Salt Master
  - Primary Master Configuration
    - `interface`
    - `publish_port`
    - `user`
    - `max_open_files`
    - `worker_threads`
    - `ret_port`
    - `pidfile`
    - `root_dir`
    - `pki_dir`
    - `cachedir`
    - `keep_jobs`
    - `job_cache`
    - `ext_job_cache`
    - `minion_data_cache`
    - `enforce_mine_cache`
    - `sock_dir`
  - Master Security Settings
    - `open_mode`
    - `auto_accept`
    - `autosign_file`
    - `client_acl`
    - `client_acl_blacklist`
    - `external_auth`
    - `token_expire`
    - `file_recv`
  - Master Module Management
    - `runner_dirs`
    - `cython_enable`
  - Master State System Settings
    - `state_verbose`
    - `state_output`
    - `state_top`
    - `external_nodes`
    - `renderer`
    - `failhard`
    - `test`
  - Master File Server Settings
    - `fileserver_backend`
    - `file_roots`
    - `hash_type`
    - `file_buffer_size`
  - Pillar Configuration
    - `pillar_roots`
    - `ext_pillar`
  - Syndic Server Settings
    - `order_masters`
    - `syndic_master`
    - `syndic_master_port`
    - `syndic_log_file`
    - `syndic_pidfile`
  - Peer Publish Settings
    - `peer`
    - `peer_run`
  - Node Groups
  - Master Logging Settings
    - `log_file`
    - `log_level`
    - `log_level_logfile`
    - `log_datefmt`
    - `log_datefmt_logfile`
    - `log_fmt_console`
    - `log_fmt_logfile`
    - `log_granular_levels`
  - Include Configuration
    - `default_include`
    - `include`

#### Previous topic

Configuration file examples

#### Next topic

Configuring the Salt Minion

### Quick search

Enter search terms or a module, class or function name.

### Upcoming SaltStack Events

My conferences on Lanyrd