Install Salt

Updated by James Stewart

Contribute on GitHub

View Project | View File | Edit File

Salt is a server management platform, designed to control a number of servers from a single master server. The following directions will walk you through configuring a salt master and multiple salt minions, and deploying your first Salt Formula. These instructions assume that you are using Debian 8 but can be adjusted to function on other distributions.

The steps required in this guide require root privileges. Be sure to run the steps below as root or with the sudo prefix. For more information on privileges see our Users and Groups guide.

Before You Begin

  1. You will need at least three Linodes: One Salt master, and at least two Salt minions.

  2. Ensure that each Linode’s hostname has been set. As the Linode’s hostname will be used to identify it within Salt, we recommend using descriptive hostnames. You should also designate one Linode as your Salt master and name it appropriately. If your Linodes are located within the same datacenter, we recommend that you configure private IP addresses for each system.

Add the Salt Repository

The steps in this section will need to be run on each of your Linodes.

  1. Create the file /etc/apt/sources.list.d/salt.list and enter the following lines to add the Salt repository:

    /etc/apt/sources.list.d/salt.list
    1
    2
    # salt
    deb http://debian.saltstack.com/debian jessie-saltstack main
    
  2. Add the repository key:

    1
    wget -q -O- "http://debian.saltstack.com/debian-salt-team-joehealy.gpg.key" | apt-key add -
    
  3. Update your Linode:

    1
    apt-get update
    

Configure Your Salt Master

The following steps will be run only on the Linode designated as your Salt master.

  1. Install the Salt master package:

    1
    apt-get install salt-master
    
  2. Open /etc/salt/master. Uncomment the #interface: line and replace <master's IP address> below with the address of your Salt master Linode. If your Linodes are located in the same datacenter, you can utilize your private network address for this purpose.

    /etc/salt/master
    1
    2
    # The address of the interface to bind to:
    interface: <master's IP address>
    

    As part of this step, you can also configure the user you wish to issue Salt commands to your minions. Uncomment the #user: line and enter your desired username to modify this setting. You will also need to issue the following command to set the required permissions for the user in question.

    1
    chown -R user /etc/salt /var/cache/salt /var/log/salt /var/run/salt
    

    Once this setting has been modified, you will need to issue any further Salt commands on your Salt Master while logged in as that user.

  3. Restart Salt:

    1
    systemctl restart salt-master
    

Installing and Configuring a Salt Minion

The following steps will need to be run on each of your Salt minions.

  1. Install Salt:

    1
    apt-get install salt-minion
    
  2. Edit the /etc/salt/minion file to uncomment the #master: salt line, and replace “salt” with the IP address of your Salt Master:

    /etc/salt/minion
    1
    2
    3
    # Set the location of the salt master server. If the master server cannot be
    # resolved, then the minion will fail to start. 
      master: <master's IP address>
    
  3. Restart Salt:

    1
    systemctl restart salt-minion
    

Configure Salt

  1. On your Salt master, issue the following command to list the known Salt Minions linked to the Salt Master:

    1
    salt-key -L
    
  2. For security purposes, verify the Minions’ IDs on both the Salt Master and the Salt Minions. Each Minion will be identified by its hostname.

    Run the following command from the Salt master to query each minion’s key ID:

    1
    salt-key -f <hostname>
    

    On the Salt Minions:

    1
    salt-call key.finger --local
    
  3. Once you have verified each of your Minion’s ID’s, accept the listed Salt Minions.

    To accept all Minions:

    1
    salt-key -A
    

    To accept an individual minion, run the command below, replacing the <hostname> value with your minion’s hostname:

    1
    salt-key -a <hostname>
    
  4. Check the status of accepted minions:

    1
    salt-run manage.up
    
  5. Ping the Minions, using * for all:

    1
    salt '*' test.ping
    

    It should return the value True for each minion.

Installing Individal Packages with Salt

Once you have completed the previous configuration steps, you can install packages using Salt on all of your minions. Packages can be targeted to individual minions, or installed to all minions via simple commands. For these examples we will use Apache.

  1. To install a package to a specific minion:

    1
    salt 'minionid' pkg.install apache2
    
  2. To install a package to all minions:

    1
    salt '*' pkg.install apache2
    
  3. To control services related to the installed package:

    1
    2
    salt '*' service.start apache2
    salt '*' service.stop apache2
    
  4. To remove a package from minions:

    1
    salt '*' pkg.remove apache2
    

Deploy Your First Salt Formula

Salt Formulas create a framework of software and configurations to be deployed to your minions. Multiple Salt Formulas can be deployed to your minions and this will allow you to manage package configuration and maintenance from the Salt Master. These steps will walk you through installing one of the premade formulas hosted on Salt’s Github.

  1. Create the directory for storing your Salt states and navigate to that directory:

    1
    2
    mkdir /srv/salt
    cd /srv/salt
    
  2. Create a state file to store your configuration. For this example, we’ll create a simple Apache state:

    /srv/salt/apache.sls
    1
    2
    3
    apache2:
      pkg:
        - installed
    
  3. To install the packages containted within the SLS file and enable the state, execute the following command. You can replace * with the ID of a specific minion:

    1
    salt '*' state.apply apache
    
  4. To disable or re-enable states installed on your Minions, run the following command:

    1
    2
    salt '*' state.disable apache
    salt '*' state.enable apache
    

This guide is published under a CC BY-ND 4.0 license.