Overview
This section includes notes on configuring the Salt Master server for use with the SaltStack project.
Example configuration
- Create all the required directories
SALT_HOME="/srv"
declare -a ENVIRONMENTS=(base production staging development)
for ENVIRONMENT in ${ENVIRONMENTS[@]};
do
mkdir -p ${SALT_HOME}/{pillar,salt}/${ENVIRONMENT}
mkdir ${SALT_HOME}/salt/${ENVIRONMENT}/formulas
done
- If required, symlink to
/srv/salt
ln -s /home/salt/srv /srv/salt
The following examples can be placed in /etc/salt/master.d/
- Primary configuration
cat << __EOF__ > /etc/salt/master.d/primary.conf
#######################################
# Name: primary.conf
# Description: Salt Master Primary configuration
#######################################
# Network interface to bind to
interface: 0.0.0.0
# Disable or Enable IPv6
ipv6: False
# The network port for the publish interface
publish_port: 4505
# Master ID
# This is used for the minion to return the job to the requesting master
master_id: None
# Salt User
# The user under which the salt master will run.
# Salt will update all permissions to allow the user to run the master.
# The exception is job cache, which must be deleted if this user is changed.
# If the modified files cause conflicts, set verify_env to False.
user: salt
# Returning Port
# The port used by the return server.
# This is used by Salt to receive execution returns and command executions
ret_port: 4506
# Location of the PID file
pidfile: /var/run/salt/salt-master.pid
# Root directory
# The default root directory to operate from
# This directory is prepended to:
# pki_dir, cachedir, sock_dir, log_file, autosign_file, autoreject_file, pidfile
root_dir: /
# Configuration file
# The path to the Salt master configuration file
conf_file: /etc/salt/master
# PKI directory
# The directory to store all the pki authentication keys
pki_dir: /etc/salt/pki/master
# Modules directory
# The directory where Salt will look for modules types:
# runners, output, wheel, modules, states, engines, utils
extension_modules: /var/cache/salt/master/extmods
# Modules Whitelist
#extmod_whitelist:
# Modules Blacklist
#extmod_blacklist:
# Cache directory
cachedir: /var/cache/salt/master
# Verify Environment
# Enable to verify and set permissions on master startup
verify_env: True
# Keep Jobs
# The number of hours to keep old job information
keep_jobs: 24
# Gather Jobs timeout
# The number of seconds to wait when the client is requesting info about running jobs
gather_job_timeout: 30
# Timeout
# The time in seconds for the Salt command and API
timeout: 10
# Loop interval
# The time in seconds the master's maintenance process runs.
loop_interval: 60
# Output
# The default outputter used by the salt command
output: nested
# Show Timeout
# Tell the client to show minions that have reached the timeout
show_timeout: True
# Show Job ID
# Tell the client to show the Job ID when a job is published
show_jid: False
# Colour
# Use colour on the output
color: True
# Summary
# Enable to show a summary of the minions targeted and returned
cli_summary: True
# Socket directory
# The location for the Salt socket
sock_dir: /var/run/salt/master
# Enable GPU Grains
# Uses lspci/dmidecode during startup, so can slow master start
enable_gpu_grains: True
__EOF__
- Performance configuration
cat << __EOF__ > /etc/salt/master.d/performance.conf
#######################################
# Name: performance.conf
# Description: Salt Master Performance configuration
#######################################
# Max open files
# By default this value will be the one of `ulimit -Hn`, ie, 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.
max_open_files: 10000
# The number of worker threads to start. These threads are used to manage
# return calls made from minions to the master. If the master seems to be
# running slowly, increase the number of threads. This setting can not be
# set lower than 3.
worker_threads: 5
# Use Job Cache
# Can be an I/O burden for 5000+ minions
job_cache: True
# Minion Data Cache
# A cache of information about the minions connected to the master
minion_data_cache: True
# Cache sub-system
# Which sub-system to use for the Minion data cache
cache: localfs
# Memcache Expiry Time
# The amount of time before the memory cache of minion data is cleared
memcache_expire_seconds: 30
# Memcache Max Items
# The maximum number of items that are stored in the Memcache
memcache_max_items: 1024
# Memcache Full Cleanup
# If the max items is exceed, delete the entire Memcache
memcache_full_cleanup: False
# Memcache Debug
# Enable collecting Memcache logging at a Debug level
memcache_debug: False
# Default Minion Returner
# Used to specify a default returner for all minions.
# Example include, redis, consul, slack
# Enabling this also disables the job cache on the master
ext_job_cache: ''
# Event Returner
# Specify the returner(s) to use to log events.
#event_return:
# - syslog
# - elasticsearch
# - slack
event_return: ''
# Event Return Queue
# On bust systems, enable event returns can cause high load
# Events can be queued on the master
event_return_queue: 0
# Event Return Whitelist
#event_return_whitelist:
# - salt/master/tag
# - salt/run/*/ret
# Event Return Blacklist
#event_return_blacklist:
# - salt/master/not_this_tag
# - salt/wheel/*/ret
# Maximum Event Size
# Parsing large events causes the minion to consume memory.
# Set the Max Size of a single event on the bus in bytes
# 1MB
max_event_size: 1000000
# Ping on Key Rotation
# By default, AES keys rotate every 24 hours
# Enable this to have the master ping after each rotation
# This can mitigate minions appearing to not respond after a rotation
# WARNING: This will cause a performance spike for a high number of minions (5000+)
ping_on_rotate: True
# Master Job Cache
# Specify the returner to be used by the Master for the job cache.
master_job_cache: local_cache
# Enforce Mine Cache
# When the minion_data_cache is disabled, so is the Mine cache.
# Enable this for override
enforce_minion_cache: False
# Maximum Minions
# The max number of Minions allowed to connect to the Master
max_minions: 0
# Connection Cache
# If max_minions is used, cache the connection Minion IDs
con_cache: True
# Presence Events
# Enable to have the Master periodically check for connected Minions.
presence_events: False
# Transport
# Changes the underlying transport layer
# Valid options are: zeromq, raet(experimental), tcp(experimental)
transport: zeromq
# Socket Pool Size
# Increase if using the Salt API, default is 1
sock_pool_size: 1
# IPC Mode
# The IPC strategy, sockets vs tcp
# Set to tcp on Windows, ipc on Linux
ipc_mode: ipc
# TCP Master Publisher Port
# The TCP port on which events should be published if ipc_mode is TCP
tcp_master_pub_port: 4512
# TCP Master Pull Port
# The TCP port on which events for the master should be pulled if ipc_mode is TCP.
tcp_master_pull_port: 4513
# TCP Master Publish Pull Port
# The TCP port on which events for the master should be pulled from
# and then republished onto the event bus on the master.
tcp_master_publish_pull: 4514
# TCP Master Workers
# The TCP port for mworkers to connect to on the Master.
tcp_master_workers: 4515
# ZeroMQ Backlog
# The listen queue size of the ZeroMQ backlog
zmq_backlog: 1000
__EOF__
- Salt-SSH configuration
cat << __EOF__ > /etc/salt/master.d/salt-ssh.conf
#######################################
# Name: salt-ssh.conf
# Description: Salt Master Salt-SSH configuration
#######################################
# Roster File location
roster_file: /etc/salt/roster
# The SSH Password
ssh_passwd: ''
# The SSH Port
ssh_port: 22
# SSH Scan Ports
# Comma separated list of ports to scan for SSH servers
ssh_scan_ports: 22
# SSH Scan Timeout
ssh_scan_timeout: 0.05
# SSH Sudo
# Boolean to run ssh command via sudo
ssh_sudo: False
# SSH Timeout
# Number of seconds to wait for response when establishing SSH connection
ssh_timeout: 60
# SSH User
# Default user to login over SSH
ssh_user: root
# SSH Log File
ssh_log_file: /var/log/salt/ssh
# SSH Minion Options
# Pass in minion option overrides that will be inserted into the SHIM for salt-ssh calls
#ssh_minion_opts:
# gpg_keydir: /root/gpg
# SSH Use Home Key
# Enable this to automatically use ~/.ssh/id_rsa for authentication with minions
ssh_use_home_key: False
# SSH Identities only
# Enable to have salt-ssh run with -o IdentitiesOnly=yes
ssh_identities_only: False
# SSH Nodegroups
# Define Nodegroups as a YAML list
#ssh_list_nodegroups:
# - groupA:
# - minion1
# - minion2
# - groupB:
# - minion3
# - minion4
__EOF__
- Security configuration
cat << __EOF__ > /etc/salt/master.d/security.conf
#######################################
# Name: security.conf
# Description: Salt Master Security configuration
#######################################
# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open mode
# you do so at your own risk!
open_mode: True
# Enable auto_accept, this setting will automatically accept all incoming
# public keys from the minions. Note that this is insecure.
auto_accept: True
# The size of key that should be generated when creating new keys.
keysize: 4096
# Auto Sign Timeout
# The time in minutes that a matching keyid is automatically accepted.
# Expired keys are removed when the master checks the minion _autosign dir
autosign_timeout: 180
# Allow users on the master access to execute specific commands on minions.
# This setting should be treated with care since it opens up execution
# capabilities to non root users. By default this capability is completely
# disabled. Groups end with percent.
publisher_acl:
# Salt Admins can do everything
salt-admins%:
- .*
# Salt Users can use test,pkg module on everything
salt-users%:
- .*
- test.*
- pkg.*
# Sudo ACL
# Enforce the publisher_acl when users have access to sudo
sudo_acl: False
# External Authentication
# pam:
# salt-users:
# - test.*
# Token Expiry
# Time in seconds for a newly generated token to live
token_expire: 43200
# File Receive
# Allow Minions to be able to push files to the Master
file_recv: False
# File Receive Max Size
# Megabytes
file_revc_max_size: 100
# Master Sign Public Key
# Sign the auth-replies with the signature of the masters pub key
master_sign_pubkey: False
# Master Sign Key Name
# The customisable name of the signing-key-pair
master_sign_key_name: master_sign
# Master Public Key Signature
# The name of the file holding the master's public key
master_pubkey_signature: master_pubkey_signature
# Master Use Pub Key Signature
# Instead of computing a signature for each reply, use a pre-computed
master_use_pubkey_signature: False
# Rotate AES Keys
# Automatically rotate the AES key when a minion is deleted with salt-key
# If you disable, a deleted minion can listen to the zeromq messages
rotate_aes_key: True
# Publish Session
# The number of seconds between automatic AES key rotation
publish_session: 86400
# Allow Minion Key revocation
# The Master deletes the cache for a minion when a minion is removed
# Enable this to preserve the cache
preserve_minion_cache: False
# Rotate AES Key
# Controls whether a Minion can request its own key to be revoked
allow_minion_key_revoke: True
__EOF__
- State configuration
cat << __EOF__ > /etc/salt/master.d/state.conf
#######################################
# Name: state.conf
# Description: Salt Master State configuration
#######################################
# State Top
# The name the minions will look for the top file
state_top: top.sls
# State Top Salt Environment
# This option has no default
# Set it to ensure that ONLY the top file from this environment is considered
state_top_saltenv: base
# Fail Hard
# Enabling this causes all states to stop running the moment a single state fails
failhard: True
# State Verbose
# Enable this to see output from all states during a run
# Disable to only see changes and failed states
state_verbose: False
# State Output
# Changes the output from a state run. Options are
# Full: Full details from every state
# Terse: Single line from every state
# Mixed: Single line unless state failed, otherwise full
# Changes: Output will be full is there was changes
state_output: changes
# State Output Diff
# Whether or not output from successful states is returned
# Set to True to ignore successful output
state_output_diff: False
# State Aggregate
# Automatically aggregate all states that have support for mod_aggregate.
# Alternatively, pass a list of state modules to only aggregate those types.
state_aggregate: True
# Runner Returns
# Enable if you want runner jobs saved to the cache
runner_returns: False
__EOF__
- Fileserver configuration
cat << __EOF__ > /etc/salt/master.d/fileserver.conf
#######################################
# Name: fileserver.conf
# Description: Salt Master FileServer configuration
#######################################
# File Server Backends
#
# 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" uses the "file_roots" option
# * "git" uses the "GitFS" option
fileserver_backend:
- roots
- git
# Fileserver Follow Symlinks
fileserver_followsymlinks: True
# Fileserver Ignore Symlinks
# Disable to have symlinks treated as the file they are pointing too
fileserver_ignoresymlinks: False
# Fileserver Limit Traversal
# Enable to only traverse directories with SLS and special Salt directories
fileserver_limit_traversal: False
# Fileserver List Cache Time
# The time in seconds that Salt will cache a list of files for
fileserver_list_cache_time: 30
# Fileserver Verify Configuration
# Salt Master will verify configuration on start and abort if error
fileserver_verify_config: True
# Hash Type
# The hash type to use on tole
hash_type: sha256
# File Buffer Size (bytes)
file_buffer_size: 1048576
# File Ignore Regex
# 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.
file_ignore_regex:
- '/\.svn($|/)'
- '/\.git($|/)'
- '/\.pyc($|/)'
# File Ignore Glob
# 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'
- '\*.bak'
- '\*.swp'
# For each environment:
# * apply the top.sls
# * if top.sls doesn't exist, apply the "default_top" top.sls
# On a Minion, "default_top" defaults to "base"
top_file_merging_strategy: same
# Default Minion renderer
renderer: yaml_jinja
# Master Root
# A master only copy of the file_roots, used by the state compiler
master_roots: /srv/salt/salt-master
# 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.
# Each Environment will:
# * Check the associated environment directory first
# * If a file is not found, DO NOT default to the base
file_roots:
# Base Environment
base:
- /srv/salt/base
# Development Environment
development:
- /srv/salt/development
# Staging Environment
staging:
- /srv/salt/staging
# Production Environment
production:
- /srv/salt/production
__EOF__
- GitFS configuration
cat << __EOF__ > /etc/salt/master.d/gitfs.conf
#######################################
# Name: gitfs.conf
# Description: Salt Master GitFS configuration
#######################################
# NOTE: A good way of testing what is being served from repos on salt
# salt '*' cp.list_master
# salt '*' cp.list_master_dirs
# GitFS Provider
# If unset, both pygit2 and gitpython will be tried in that order.
#gitfs_provider: gitpython
# GitFS SSL Verify
# Specifies whether to verify SSL certificates
gitfs_ssl_verify: True
# GitFS Global Lock
# When set to true, salt will flag a warning when an update lock present
# When set to false, salt will clear the lock and a new lock obtained
gitfs_global_lock: True
/ # The branch/tag to be used for base environment
gitfs_base: base
# The default mountpoint for repositories
gitfs_mountpoint: ''
# The relative path to a subdirectory in a git repository for salt to serve files
gitfs_root: ''
# GitFS defaults for environments
# These can be overridden per repo
gitfs_saltenv:
# Base Environment
- base:
- ref: base
# Production Environment
- production:
- ref: production
# Staging Environment
- staging:
- ref: staging
# Development Environment
- development:
- ref: development
# Repository specific settings
gitfs_remotes:
# Repo used by all environments
- https://gitlab.com/SaltWorks/Salt:
- name: salt_top
- root: salt
- mountpoint: salt://
# Example of the same repo with the base env re-mapped.
- https://gitlab.com/SaltWorks/Salt:
- name: salt_grains
- base: development
- root: salt
- mountpoint: salt://
# HAProxy Formula:
- https://gitlab.com/SaltWorks/Salt-Formulas/HAProxy-Formula.git:
- root: haproxy
- mountpoint: salt://formulas/haproxy
__EOF__
- Pillar configuration
cat << __EOF__ > /etc/salt/master.d/pillar.conf
#######################################
# Name: pillar.conf
# Description: Salt Master Pillar configuration
#######################################
# Salt Pillars allow for the building of global data that can be made selectively
# available to different minions based on minion grain filtering. The Salt
# Pillar is laid out in the same fashion as the file server, with environments,
# a top file and sls files. However, pillar data does not need to be in the
# highstate format, and is generally just key/value pairs.
# NOTE: Pillar root must not be in a subdirectory of the state tree
pillar_roots:
# Base Environment
base:
- /srv/pillar/base
# Development Environment
development:
- /srv/pillar/development
# Staging Environment
staging:
- /srv/pillar/staging
# Production Environment
production:
- /srv/pillar/production
# The pillar_opts option adds the master configuration file data to a dict in
# the pillar called "master". This is used to set simple configurations in the
# master config file that can then be used on minions.
pillar_opts: False
# Enable to prevent pillar errors from being pushed to minions. These errors
# could allow a minion to ger information it shouldn't have, e.g a password.
pillar_safe_render_error: True
# External Pillar First
# Enable to have the external pillars processed before pillar_roots
ext_pillar_first: False
# Pillar Environment from Salt Environment
# Enable this to have the Pillar environment assume the the Salt Environment
# when running states.
pillar_env_from_saltenv: True
# Pillar raise on missing
# Enable to raise a KeyError when an attempt to retrieve a named value from a pillar fails.
# Disable to return an empty string on error
pillar_raise_on_missing: False
# Git Pillar Provider (pygit2, gitpython)
git_pillar_provider: pygit2
# Git Pillar Ref
# The branch/tag to be used for base environment
git_pillar_base: base
# Git Pillar Root
# Default location of the repositories for the top.sls
git_pillar_root: pillar
# Git Pillar Branch
# If the branch is omitted, default to this
git_pillar_branch: master
# Git Pillar SSL Verify
# Whether to ignore SSL certificate errors when connecting to the repo
git_pillar_ssl_verify: True
# Git Pillar Global Lock
# When set to true, salt will flag a warning when an update lock present
# When set to false, salt will clear the lock and a new lock obtained
git_pillar_global_lock: True
# Git Pillar Includes
# Enable to allow one Git pillar to access files for another pillar
# in the same environment.
git_pillar_includes: True
# Git Pillar Verify Config
# Verify the Git Pillar configuration on master start
# Salt master will abort on error
git_pillar_verify_config: True
# Pillar Source Merging Strategy
# None: only parse the pillar from the environment, or base if no environment specified
# Recurse: Recursively merge pillar data
# Smart: Guess the best strategy based on the renderer
pillar_source_merging_strategy: none
# Pillar Cache
# A master can cache pillars locally bypassing the expense of having to render the pillar
pillar_cache: false
# Pillar Cache TTL
# The amount of time before the cache is considered invalid and a fresh pillar is recompiled
pillar_cache_ttl: 3600
# Pillar Cache Backend
# Disk: Store the pillars unncrypted in the master cache
# Memory: Experimental backend that stores the pillar cache unencrypted in memory
pillar_cache_backend: disk
# NOTE: Each environment needs it's own top.sls. This is different to the pillar_roots
ext_pillar:
- git:
- __env__ https://gitlab.com/SaltWorks/Pillar.git:
- root: pillar
__EOF__
- Reactor configuration
cat << __EOF__ > /etc/salt/master.d/reactor.conf
#######################################
# Name: reactor.conf
# Description: Salt Master Reactor configuration
#######################################
reactor:
# React when the Minion starts
- 'salt/minion/*/start':
- salt://reactor/minion_start.sls
- salt://reactor/sync_grains.sls
# React when a Cloud is destroyed
- 'salt/cloud/*/destroyed':
- salt://reactor/cloud_destroyed.sls
# React to a Custom event
- 'custom/event/tag':
- salt://reactor/custom_event.sls
# Reactor Refresh Interval
reactor_refresh_interval: 60
# Reactor Worker Threads
reactor_worker_threads: 10
# Reactor Worked HWM
# The Queue size for the workers in the reactor
reactor_worker_hwm: 10000
__EOF__
- Syncdic configuration
cat << __EOF > /etc/salt/master.d/syncdic.conf
########################################
# Name: syncdic.conf
# Description: Salt Master Syncdic configuration
#######################################
# Order Masters
# If this is a master that will have syncdic slaves, set True
order_masters: False
__EOF__
- Logging configuration
cat << __EOF > /etc/salt/master.d/logging.conf
#######################################
# Name: logging.conf
# Description: Salt Master Logging configuration
#######################################
# The location of the master log file
# The master log can be sent to a regular file, local path name, or network
# location. Remote logging works best when configured to use rsyslogd(8) (e.g.:
# ``file:///dev/log``), with rsyslogd(8) configured for network logging. The URI
# format is: <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>
#log_file: /var/log/salt/master
#log_file: file:///dev/log
#log_file: udp://loghost:10514
log_file: /var/log/salt/master
key_logfile: /var/log/salt/key
# The level of messages to send to the console.
# One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
#
# The following log levels are considered INSECURE and may log sensitive data:
# ['garbage', 'trace', 'debug']
#
log_level: warning
# The level of messages to send to the log file.
# One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
# If using 'log_granular_levels' this must be set to the highest desired level.
log_level_logfile: warning
__EOF__
- Salt-Cloud configuration
cat << __EOF__ > /etc/salt/master.d/salt-cloud.conf
#######################################
# Name: salt-cloud.conf
# Description: Salt Master Salt-Cloud configuration
#######################################
# User Data Template
# The rendered to use for templating userdata in salt-cloud
userdata_template: jinja
__EOF__
