.. _configure-master-minion: ===================================== Configure the Salt master and minions ===================================== For a basic Salt setup, you only need to edit the Salt minion's configuration file to add the IP address of the Salt master it will connect to. See `Basic minion configuration`_ for more information. This page will explain other configuration options or considerations if needed. .. Note:: Before you can configure the Salt master and minions, you must first install the ``salt-master`` and ``salt-minion`` services on your nodes. For installation instructions, see :ref:`overview`. Basic master configuration ========================== * The ``salt-master`` service comes with default server configurations. * The default master YAML configuration at ``/etc/salt/master`` contains all the commented settings. * Recommended: you can add custom settings in YAML to ``/etc/salt/master.d/`` as ``.conf`` files on the Salt master. * Use the default master file as a reference for various settings as needed. Best practices -------------- While the ``/etc/salt/master`` file can accept configuration settings, the best practice is to use the ``/etc/salt/master.d/`` configuration directory. Using this directory allows you to put configuration options into logical separations. For example, if you want to set up a different number of ``worker_threads``, you could store those configurations in the ``/etc/salt/master.d/tuning.conf`` directory and keep all tuning-related configurations in that file. .. Warning:: When using multiple ``.conf`` files, take care not to use duplicate configuration settings. (For example, setting the number of worker threads in more than one configuration file.) Salt applies the settings from the last ``.conf`` file it evaluates and it evaluates the files in alphabetical order. If you use duplicate configuration settings, you could accidentally override the setting you intended to apply. Salt master network settings ---------------------------- By default, the master binds to all available network interfaces, then listens on ports ``4505`` and ``4506``. This example overrides the default settings: .. code-block:: yaml :caption: /etc/salt/master.d/network.conf # The network interface to bind to interface: 192.0.2.20 # The Request/Reply port ret_port: 4506 # The port minions bind to for commands, aka the publish port publish_port: 4505 Salt master process management ------------------------------ If your cluster has thousands of minions, and your minion reports are stalling, the master might be timing out the job's minion responses. This may mean that the minions failed their job, but it could instead mean that the master doesn’t have enough worker threads to process all the reports. To manage the ``salt-minion`` return calls, the master threads out worker processes with the ``worker_threads`` setting. The default limit for the processes is five workers. The minimum limit is three workers. Example setting in a master configuration file: .. code-block:: yaml :caption: /etc/salt/master.d/thread_options.conf worker_threads: 5 Standards for busy environments: * Use one worker thread per 200 minions. * The value of ``worker_threads`` should not exceed 1½ times the available CPU cores. Basic minion configuration =========================== * The ``salt-minion`` service comes with a DNS/hostname configuration setup by default. * The default minion YAML configuration at ``/etc/salt/minion`` contains all the commented settings. * Recommended: you can add custom settings in YAML to ``/etc/salt/minion.d/`` as ``.conf`` files on the minion. * Use the default minion file as a reference for various settings as needed. Best practices -------------- While ``/etc/salt/minion`` file can accept configuration settings, the best practice is to use the ``/etc/salt/minion.d/`` configuration directory. Using this directory allows you to put configuration options into logical separations. .. Warning:: When using multiple ``.conf`` files, take care not to use duplicate configuration settings. (For example, setting the number of worker threads in more than one configuration file.) Salt applies the settings from the last ``.conf`` file it evaluates and it evaluates the files in alphabetical order. If you use duplicate configuration settings, you could accidentally override the setting you intended to apply. Connecting to the Salt master ----------------------------- By default, the minions assume that the Salt master can be resolved in DNS using the hostname ``salt``. An example that overrides the master default setting: .. code-block:: yaml :caption: /etc/salt/minion.d/master.conf master: 192.0.2.20 Declaring the minion ID ----------------------- The ``salt-minion`` will identify itself to the master by the system's hostname unless explicitly set: .. code-block:: yaml :caption: /etc/salt/minion.d/id.conf id: rebel_1 Most strings are allowed. If you decide to customize your minion IDs, try to keep the ID brief but descriptive of its role. For example, you could use ``apache-server-1`` to name one of your web servers or you could use ``datacenter-3-rack-2`` after its location in a datacenter. The goal is to make the names descriptive and helpful for future reference. Additional configuration files ============================== In addition to the standard Salt master and minion configuration files, you can create the Saltfile and the ``~/.saltrc`` file for configuration purposes. Saltfile -------- The ``~/.salt/Saltfile`` is a separate configuration file that is read at runtime by the CLI client in use. It can help automate processes if you find yourself running the same options over and over again in the CLI. It uses the following format: .. code:: yaml :