Document many core opts

Although these are documented in other places, we need somewhere that we
can store more in-depth, interface-specific information about various options.

This way, we can make implementation-specific comments which would not be approrpiate
for user configuration files.

conf/master

@@ -67,6 +67,8 @@
 #pki_dir: /etc/salt/pki/master
 
 # Directory to store job and cache data:
+# This directory may contain sensitive data and should be protected accordingly.
+# 
 #cachedir: /var/cache/salt/master
 
 # Directory for custom modules. This directory can contain subdirectories for
@@ -547,10 +549,11 @@
 #####          Syndic settings       #####
 ##########################################
 # The Salt syndic is used to pass commands through a master from a higher
-# master. 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
+# master. Using the syndic is simple. If this is a master that will have
+# syndic servers(s) below it, then set the "order_masters" setting to True.
+#
+# If this is a master that will be running a syndic daemon for passthrough, then
+# the "syndic_master" setting needs to be set to the location of the master server
 # to receive commands from.
 
 # Set the order_masters setting to True if this master will command lower

conf/minion

@@ -70,6 +70,7 @@
 #  cab_u: 14-15
 #
 # Where cache data goes.
+# This data may contain sensitive data and should be protected accordingly.
 #cachedir: /var/cache/salt/minion
 
 # Verify and set permissions on configuration directories at startup.
@@ -332,9 +333,7 @@
 # failure detected in the state execution. Defaults to False.
 #failhard: False
 #
-# 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
-# autoloading modules when states run, set this value to False.
+# Reload the modules prior to a highstate run.
 #autoload_dynamic_modules: True
 #
 # clean_dynamic_modules keeps the dynamic modules on the minion in sync with

doc/ref/configuration/master.rst

@@ -234,6 +234,8 @@ Default: :file:`/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.
+
 .. code-block:: yaml
 
     cachedir: /var/cache/salt

doc/ref/configuration/minion.rst

@@ -234,6 +234,8 @@ Default: ``/var/cache/salt``
 
 The location for minion cache data.
 
+This directory may contain sensitive data and should be protected accordingly.
+
 .. code-block:: yaml
 
     cachedir: /var/cache/salt

salt/config.py

@@ -59,115 +59,362 @@ FLO_DIR = os.path.join(
         'daemons', 'flo')
 
 VALID_OPTS = {
+    # The address of the salt master. May be specified as IP address or hostname
     'master': str,
+
+    # The TCP/UDP port of the master to connect to in order to listen to publications
     'master_port': int,
+
+    # The behaviour of the minion when connecting to a master. Can specify 'failover',
+    # or 'func'. If 'func' is specified, the 'master' option should be set to an exec
+    # module function to run to determine the master hostname.
     'master_type': str,
+
+    # The fingerprint of the master key may be specified to increase security. Generate
+    # a master fingerprint with `salt-key -F master`
     'master_finger': str,
+
+    # Selects a random master when starting a minion up in multi-master mode
     'master_shuffle': bool,
+
+    # When in mulit-master mode, temporarily remove a master from the list if a conenction
+    # is interrupted and try another master in the list.
     'master_alive_interval': int,
+
+    # The name of the signing key-pair
     'master_sign_key_name': str,
+
+    # Sign the master auth-replies with a cryptographic signature of the masters public key.
     'master_sign_pubkey': bool,
+
+    # Enables verification of the master-public-signature returned by the master in auth-replies.
+    # Must also set master_sign_pubkey for this to work
     'verify_master_pubkey_sign': bool,
+
+    # 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.
     'always_verify_signature': bool,
+
+    # The name of the file in the masters pki-directory that holds the pre-calculated signature of the masters public-key.
     'master_pubkey_signature': str,
+
+    # 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': bool,
+
+    # The key fingerprint of the higher-level master for the syndic to verify it is talking to the intended
+    # master
     'syndic_finger': str,
+
+    # The user under which the daemon should run
     'user': str,
+
+    # The root directory prepended to these options: pki_dir, cachedir,
+    # sock_dir, log_file, autosign_file, autoreject_file, extension_modules,
+    # key_logfile, pidfile:
     'root_dir': str,
+
+    # The directory used to store public key data
     'pki_dir': str,
+
+    # A unique identifier for this daemon
     'id': str,
+
+    # The directory to store all cache files.
     'cachedir': str,
+
+    # Flag to cache jobs locally.
     'cache_jobs': bool,
+
+    # The path to the salt configuration file
     'conf_file': str,
+
+    # The directory containing unix sockets for things like the event bus
     'sock_dir': str,
+
+    # Specifies how the file server should backup files, if enabled. The backups
+    # live in the cache dir.
     'backup_mode': str,
+
+    # A default renderer for all operations on this host
     'renderer': str,
+
+    # A flag indicating that a highstate run should immediately cease if a failure occurs.
     'failhard': bool,
+
+    # A flag to indicate that highstate runs should force refresh the modules prior to execution
     'autoload_dynamic_modules': bool,
+
+    # Force the minion into a single environment when it fetches files from the master
     'environment': str,
+
+    # Allows a user to provide an alternate name for top.sls
     'state_top': str,
+
+    # States to run when a minion starts up
     'startup_states': str,
+
+    # List of startup states
     'sls_list': list,
+
+    # A top file to execute if startup_states == 'top'
     'top_file': str,
+
+    # Location of the files a minion should look for. Set to 'local' to never ask the master.
     'file_client': str,
+
+    # When using a local file_client, this parameter is used to allow the client to connect to
+    # a master for remote execution.
     'use_master_when_local': bool,
+
+    # A map of saltenvs and fileserver backend locations
     'file_roots': dict,
+
+    # A map of saltenvs and fileserver backend locations
     'pillar_roots': dict,
+
+    # The type of hashing algorithm to use when doing file comparisons
     'hash_type': str,
+
+    # FIXME Does not appear to be implemented
     'disable_modules': list,
+
+    # FIXME Does not appear to be implemented
     'disable_returners': list,
+
+    # Tell the loader to only load modules in this list
     'whitelist_modules': list,
+
+    # A list of additional directories to search for salt modules in
     'module_dirs': list,
+
+    # A list of additional directories to search for salt returners in
     'returner_dirs': list,
+
+    # A list of additional directories to search for salt states in
     'states_dirs': list,
+
+    # A list of additional directories to search for salt grains in
     'grains_dirs': list,
+
+    # A list of additional directories to search for salt renderers in
     'render_dirs': list,
+
+    # A list of additional directories to search for salt outputters in
     'outputter_dirs': list,
+
+    # A list of additional directories to search for salt utilities in. (Used by the loader
+    # to populate __utils__)
     'utils_dirs': list,
+
+    # salt cloud providers
     'providers': dict,
+
+    # First remove all modules during any sync operation
     'clean_dynamic_modules': bool,
+
+    # A flag indicating that a master should accept any minion connection without any authentication
     'open_mode': bool,
+
+    # Whether or not processes should be forked when needed. The altnerative is to use threading.
     'multiprocessing': bool,
+
+    # Schedule a mine update every n number of seconds
     'mine_interval': int,
+
+    # The ipc strategy. (i.e., sockets versus tcp, etc)
     'ipc_mode': str,
+
+    # Enable ipv6 support for deamons
     'ipv6': bool,
+
+    # The chunk size to use when streaming files with the file server
     'file_buffer_size': int,
+
+    # The TCP port on which minion events should be published if ipc_mode is TCP
     'tcp_pub_port': int,
+
+    # The TCP port on which minion events should be pulled if ipc_mode is TCP
     'tcp_pull_port': int,
+
+    # The TCP port on which events for the master should be pulled if ipc_mode is TCP
     'tcp_master_pub_port': int,
+
+    # The TCP port on which events for the master should be pulled if ipc_mode is TCP
     'tcp_master_pull_port': int,
+
+    # The TCP port on which events for the master should pulled and then republished onto
+    # the event bus on the master
     'tcp_master_publish_pull': int,
+
+    # The TCP port for mworkers to connect to on the master
     'tcp_master_workers': int,
+
+    # The file to send logging data to
     'log_file': str,
+
+    # The level of verbosity at which to log
     'log_level': bool,
+
+    # The log level to log to a given file
     'log_level_logfile': bool,
+
+    # The format to construct dates in log files
     'log_datefmt': str,
+
+    # The dateformat for a given logfile
     'log_datefmt_logfile': str,
+
+    # The format for console logs
     'log_fmt_console': str,
+
+    # The format for a given log file
     'log_fmt_logfile': tuple,
+
+    # A dictionary of logging levels
     'log_granular_levels': dict,
+
+    # If an event is above this size, it will be trimmed before putting it on the event bus
     'max_event_size': int,
+
+    # Always execute states with test=True if this flag is set
     'test': bool,
+
+    # Tell the loader to attempt to import *.pyx cython files if cython is available
     'cython_enable': bool,
+
+    # Tell the client to show minions that have timed out
     'show_timeout': bool,
+
+    # Tell the client to display the jid when a job is published
     'show_jid': bool,
+
+    # Tells the highstate outputter to show successful states. False will omit successes.
     'state_verbose': bool,
+
+    # Specify the format for state outputs. See highstate outputter for additional details.
     'state_output': str,
+
+    # When true, states run in the order defined in an SLS file, unless requisites re-order them
     'state_auto_order': bool,
+
+    # Fire events as state chunks are processed by the state compiler
     'state_events': bool,
+
+    # The number of seconds a minion should wait before retry when attempting authentication
     'acceptance_wait_time': float,
+
+    # The number of seconds a minion should wait before giving up during authentication
     'acceptance_wait_time_max': float,
+
+    # Retry a connection attempt if the master rejects a minion's public key
     'rejected_retry': bool,
+
+    # The interval in which a daemon's main loop should attempt to perform all necessary tasks
+    # for normal operation
     'loop_interval': float,
+
+    # Perform pre-flight verification steps before daemon startup, such as checking configuration
+    # files and certain directories.
     'verify_env': bool,
+
+    # The grains dictionary for a minion, containing specific "facts" about the minion
     'grains': dict,
+
+    # Allow a deamon to function even if the key directories are not secured
     'permissive_pki_access': bool,
+
+    # The path to a directory to pull in configuration file includes
     'default_include': str,
+
+    # If a minion is running an esky build of salt, upgrades can be performed using the url
+    # defined here. See saltutil.update() for additional information
     'update_url': bool,
+
+    # If using update_url with saltutil.update(), provide a list of services to be restarted
+    # post-install
     'update_restart_services': list,
+
+    # The number of seconds to sleep between retrying an attempt to resolve the hostname of a
+    # salt master
     'retry_dns': float,
+
+    # set the zeromq_reconnect_ivl option on the minion.
+    # http://lists.zeromq.org/pipermail/zeromq-dev/2011-January/008845.html
     'recon_max': float,
+
+    # If recon_randomize is set, this specifies the lower bound for the randomized period
     'recon_default': float,
-    'recon_randomize': float,
+
+    # Tells the minion to choose a bounded, random interval to have zeromq attempt to reconnect
+    # in the event of a disconnect event
+    'recon_randomize': float,  # FIXME This should really be a bool, according to the implementation
+
+    # Specify a returner in which all events will be sent to. Requires that the returner in question
+    # have an event_return(event) function!
     'event_return': str,
+
+    # The number of events to queue up in memory before pushing them down the pipe to an event returner
+    # specified by 'event_return'
     'event_return_queue': int,
+
+    # Only forward events to an event returner if it matches one of the tags in this list
     'event_return_whitelist': list,
+
+    # Events matching a tag in this list should never be sent to an event returner.
     'event_return_blacklist': list,
+
+    # The file cache for the win_pkg module
     'win_repo_cachefile': str,
+
+    # This pidfile to write out to when a deamon starts
     'pidfile': str,
+
+    # Used with the SECO range master tops system
     'range_server': str,
+
+    # The tcp keepalive interval to set on TCP ports. This setting can be used to tune salt connectivity
+    # issues in messy network environments with misbeahving firewalls
     'tcp_keepalive': bool,
+
+    # Sets zeromq TCP keepalive idle. May be used to tune issues with minion disconnects
     'tcp_keepalive_idle': float,
+
+    # Sets zeromq TCP keepalive count. May be used to tune issues with minion disconnects
     'tcp_keepalive_cnt': float,
+
+    # Sets zeromq TCP keepalive interval. May be used to tune issues with minion disconnects.
     'tcp_keepalive_intvl': float,
+
+    # The network interface for a daemon to bind to
     'interface': str,
+
+    # The port for a salt master to broadcast publications on. This will also be the port minions
+    # connect to to listen for publications.
     'publish_port': int,
+
+    # TODO unknown option!
     'auth_mode': int,
+
+    # Set the zeromq high water mark on the publisher interface.
+    # http://api.zeromq.org/3-2:zmq-setsockopt
     'pub_hwm': int,
+
+    # The number of MWorker processes for a master to startup. This number needs to scale up as
+    # the number of connected minions increases.
     'worker_threads': int,
+
+    # The port for the master to listen to returns on. The minion needs to connect to this port
+    # to send returns.
     'ret_port': int,
+
+    # The number of hours to keep jobs around in the job cache on the master
     'keep_jobs': int,
+
+    # A master-only copy of the file_roots dictionary, used by the state compiler
     'master_roots': dict,
+
+
     'gitfs_remotes': list,
     'gitfs_mountpoint': str,
     'gitfs_root': str,
@@ -199,9 +446,17 @@ VALID_OPTS = {
     'minionfs_mountpoint': str,
     'minionfs_whitelist': list,
     'minionfs_blacklist': list,
+
+    # Specify a list of external pillar systems to use
     'ext_pillar': list,
+
+    # Reserved for future use to version the pillar structure
     'pillar_version': int,
+
+    # Whether or not a copy of the master opts dict should be rendered into minion pillars
     'pillar_opts': bool,
+
+
     'pillar_safe_render_error': bool,
     'pillar_source_merging_strategy': str,
     'ping_on_rotate': bool,
@@ -222,48 +477,134 @@ VALID_OPTS = {
     'fileserver_followsymlinks': bool,
     'fileserver_ignoresymlinks': bool,
     'fileserver_limit_traversal': bool,
+
+    # The number of open files a daemon is allowed to have open. Frequently needs to be increased
+    # higher than the system default in order to account for the way zeromq consumes file handles.
     'max_open_files': int,
+
+    # Automatically accept any key provided to the master. Implies that the key will be preserved
+    # so that subsequent connections will be authenticated even if this option has later been
+    # turned off.
     'auto_accept': bool,
     'autosign_timeout': int,
-    'master_tops': bool,
+
+    # A mapping of external systems that can be used to generate topfile data.
+    'master_tops': bool,  # FIXME Should be dict?
+
+    # A flag that should be set on a top-level master when it is ordering around subordinate masters
+    # via the use of a salt syndic
     'order_masters': bool,
+
+    # Whether or not to cache jobs so that they can be examined later on
     'job_cache': bool,
+
+    # Define a returner to be used as an external job caching storage backend
     'ext_job_cache': str,
+
+    # Specify a returner for the master to use as a backend storage system to cache jobs returns
+    # that it receives
     'master_job_cache': str,
+
+    # 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': bool,
+
+    # The number of seconds between AES key rotations on the master
     'publish_session': int,
+
+    # Defines a salt reactor. See http://docs.saltstack.com/en/latest/topics/reactor/
     'reactor': list,
+
+    # The TTL for the cache of the reactor configuration
     'reactor_refresh_interval': int,
+
+    # The number of workers for the runner/wheel in the reactor
     'reactor_worker_threads': int,
+
+    # The queue size for workers in the reactor
     'reactor_worker_hwm': int,
+
     'serial': str,
     'search': str,
+
+    # The update interval, in seconds, for the master maintenance process to update the search
+    # index
     'search_index_interval': int,
+
+    # A compound target definition. See: http://docs.saltstack.com/en/latest/topics/targeting/nodegroups.html
     'nodegroups': dict,
+
+    # The logfile location for salt-key
     'key_logfile': str,
+
     'win_repo': str,
     'win_repo_mastercachefile': str,
     'win_gitrepos': list,
+
+    # Set a hard limit for the amount of memory modules can consume on a minion.
     'modules_max_memory': int,
+
+    # The number of minutes between the minion refreshing its cache of grains
     'grains_refresh_every': int,
+
+    # Use lspci to gather system data for grains on a minion
     'enable_lspci': bool,
+
+    # The number of seconds for the salt client to wait for additional syndics to
+    # check in with their lists of expected minions before giving up
     'syndic_wait': int,
+
+    # If this is set to True leading spaces and tabs are stripped from the start
+    # of a line to a block.
     'jinja_lstrip_blocks': bool,
+
+    # If this is set to True the first newline after a Jinja block is removed
     'jinja_trim_blocks': bool,
+
+    # FIXME Appears to be unused
     'minion_id_caching': bool,
+
+    # If set, the master will sign all publications before they are sent out
     'sign_pub_messages': bool,
+
+    # The size of key that should be generated when creating new keys
     'keysize': int,
+
+    # The transport system for this deamon. (i.e. zeromq, raet, etc)
     'transport': str,
+
+    # FIXME Appears to be unused
     'enumerate_proxy_minions': bool,
+
+    # The number of seconds to wait when the client is requesting information about running jobs
     'gather_job_timeout': int,
+
+    # The number of seconds to wait before timing out an authentication request
     'auth_timeout': int,
+
+    # The number of attempts to authenticate to a master before giving up
     'auth_tries': int,
+
+    # Never give up when trying to authenticate to a master
     'auth_safemode': bool,
+
     'random_master': bool,
+
+    # An upper bound for the amount of time for a minion to sleep before attempting to
+    # reauth after a restart.
     'random_reauth_delay': int,
+
+    # The number of seconds for a syndic to poll for new messages that need to be forwarded
     'syndic_event_forward_timeout': float,
+
+    # The number of seconds for the syndic to spend polling the event bus
     'syndic_max_event_process_time': float,
+
+    # The length that the syndic event queue must hit before events are popped off and forwarded
     'syndic_jid_forward_cache_hwm': int,
+
     'ssh_passwd': str,
     'ssh_port': str,
     'ssh_sudo': bool,
@@ -271,10 +612,19 @@ VALID_OPTS = {
     'ssh_user': str,
     'ssh_scan_ports': str,
     'ssh_scan_timeout': float,
+
+    # Enable ioflo verbose logging. Warning! Very verbose!
     'ioflo_verbose': int,
+
     'ioflo_period': float,
+
+    # Set ioflo to realtime. Useful only for testing/debugging to simulate many ioflo periods very quickly.
     'ioflo_realtime': bool,
+
+    # Location for ioflo logs
     'ioflo_console_logdir': str,
+
+    # The port to bind to when bringing up a RAET daemon
     'raet_port': int,
     'raet_alt_port': int,
     'raet_mutable': bool,
@@ -284,17 +634,38 @@ VALID_OPTS = {
     'cluster_mode': bool,
     'cluster_masters': list,
     'sqlite_queue_dir': str,
+
     'queue_dirs': list,
+
+    # Instructs the minion to ping its master(s) ever n number of seconds. Used
+    # primarily as a mitigation technique against minion disconnects.
     'ping_interval': int,
+
+    # Instructs the salt CLI to print a summary of a minion reponses before returning
     'cli_summary': bool,
+
+    # The number of minions the master should allow to connect. Can have performance implications
+    # in large setups.
     'max_minions': int,
+
+
     'username': str,
     'password': str,
+
+    # Use zmq.SUSCRIBE to limit listening sockets to only process messages bound for them
     'zmq_filtering': bool,
+
+    # Connection caching. Can greatly speed up salt performance.
     'con_cache': bool,
     'rotate_aes_key': bool,
+
+    # Cache ZeroMQ connections. Can greatly improve salt performance.
     'cache_sreqs': bool,
+
+    # Can be set to override the python_shell=False default in the cmd module
     'cmd_safe': bool,
+
+    # Used strictly for performance testing in RAET.
     'dummy_publisher': bool,
 }