Don't look back...

© 2015 Dennis Leeuw dleeuw at made-it dot com
License: GPLv2 or later


    1. Minion Setup
    2. Master Setup
    3. Control the minion
    4. Read more

There are two parts to the equation, the master and the slave or in this case the salt-master and the salt-minion. The master provides the information of what has to be done on a minion, and from the master you can control every minion, one by one or all at the same time. This document will describe a basic setup that will get you started. the complete documentation can be found at or just google what you want to know.

Minion Setup

In a basic setup of the minion the minion needs to know 2 things:

  1. Who am I
  2. Where is my master

The who am I part is controlled by /etc/salt/minion_id or if that file is not present by the hostname (FQDN) of the client. The master can be configured through the /etc/salt/minion configuration file by setting something like: 

master: salt-master.domain.local

That is all you have to do to get a basic salt minion running. So start the process.

Master Setup

To setup a basic salt master we have to tell the master a couple of things in /etc/salt/master: 

ipv6: False
    - /srv/salt/
  - '/\.svn($|/)'
  - '/\.git($|/)'

Make sure the /srv/salt directory exists and is accessable by the salt master. To make some sense out of salt we are going to fill that directory with some data. Note that salt assumes that .sls files are things salt needs to do and all other files are stuff that can or needs to be copied to a minion.

Create in the /srv/salt directory a top.sls file. There are two special .sls files. One is the just mentioned top.sls which is where salt starts reading. The other one is the init.sls file, which is described later. For now the content of our top.sls file should be like this:

      - cron
      - ssh.server
      - ssh.root-key

Make sure the prefixed white space is done with real spaces and not tabs. Now create the following directories: 

mkdir cron vim ssh

Within the cron/ directory we create a file called init.sls with the following content:

      - managed
      - source: salt://cron/salt-minion

As you can see this tells salt to manage a file called /etc/cron.d/salt-minion. This file is retrieved from "base"/cron/salt-minion. And "base" is the one that is defined in the master configuration file. Now we add that file as /srv/salt/cron/salt-minion with the following content:

*/30 * * * * root salt-call state.highstate

When we later tell our minion to install this file it is installed in the cron.d directory. Cron well then run this file and the minion will call the master every half hour to see if there is anything new to be done. This way we know for sure that the minion will call "home" every half hour.

The next step in controlling the minion is making sure we can access the minion, actually we don't anymore since we have salt, but it is always a good idea to have two paths and not rely on one. We like to access the minion through SSH so we need an SSH server on the minion. In the top.sls file refer to the installation of the server as ssh.server. This notation means that salt assumes there is a directory ssh and in that directory should be a file called server.sls. So create the server.sls file in the ssh directory with the following content:

      - name: openssh-server
      - name: sshd
      - require:
         - pkg: openssh-server
      - watch:
         - file: /etc/ssh/sshd_config

    - source: salt://ssh/sshd_config
    - user: root
    - group: root
    - mode: 644
    - require:
      - pkg: openssh-server

We define a package to be install (openssh-server), which needs to be running and which watches changes to its configuration file. Of course we define the configuration file as well. Now add to the ssh directory the sshd_config file and fill it with the settings you like. Make sure the following line is present since we need it in our last example:

PermitRootLogin without-password

The last part of our example installation is the possibility for root to log in on the minion without a password. This way only the root with the private key can acces the minion, and the configuration of the minion only contains the root public-key. So the first step is to create a public/private key pair for root. On the master do:

mkdir ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -t rsa -b 4096

mkdir /srv/salt/ssh/keys
chmod 700 /srv/salt/ssh/keys
cp ~/.ssh/ /srv/salt/ssh/keys/
chmod 600 /srv/salt/ssh/keys/*

Now we create a /srv/salt/ssh/root-key.sls file and fill it with:

    - user: root
    - source: salt://ssh/keys/

We call here a predefined function called ssh_auth.present that will install then pub key in the authorized_hosts file.

With this the master is configured. Start the master.

The next section will describe how we get what we defined operational on the client.

Control the minion

SaltStack has no "auto-deployment" function so there is no daemon on the minion that calls the master, nor is there a daemon on the master that pushes data to the client. There are however commands that pull the data from the master (salt-call) or push the data to the client (salt). It is up to you how you want your minions controlled. As you have seen in the Master Setup we told the client to call home every half our to fetch its configuration. Since the minion does not yet have this configuration it does not have the crons-snippet. We could use SSH or use the console to log in to the client to run salt-call, but it is easier is to push the configuration from the master. Before we can do that we need to do some extra stuff:

With salt-key -L you get an overview of the minions that contacted the master to tell it that they want to communicate. You should see your minion in the list of "Unaccepted Keys". To approve the key run:

salt-key -a <minion_id>

This will add the key to "Accepted Keys". Make sure to check this with salt-key -L.

Now that we proved our minion, we can run a test like:

salt <minion_id>
Which should return "True" for our minion.

Now that we know that we can communicate with our minion let's push our pre-made configuration to it:

salt <minion_id> state.highstate
The output should show you what is being done and how succesful it was. Congratulations, you just configured your first minion. Now you are ready to explore the system on your own.

Read more