We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Create Your First Salt Formula

Posted Aug 20, 2013 48k views Configuration Management Apache PHP Ubuntu

An Article From the Makers of SaltStack,
Submitted by: Dave Boucha


Salt is an awesome 100% open source configuration management and remote
execution tool. Salt is a new approach to infrastructure management. Easy
enough to get running in minutes, scalable enough to manage tens of thousands
of servers, and fast enough to communicate with them in seconds.

SaltStack is the awesome and open company behind Salt.
All Salt code and features are released under the Apache 2.0 license and can be
downloaded at
https://github.com/saltstack/salt and your
preferred OS's package manager.

In this article we will accomplish the following:

  • Create your first Salt Formula that will configure your server with the following software
    • Vim
    • Apache web server
    • PHP
    • git

This article assumes the following:

  • You've already completed the previous tutorial Install Salt on Ubuntu 12.04
  • You're already logged in as the default root user
  • We're going to assume your server's name is 'minion01'. In any commmands where you see 'minion01' replace that with your server's name as found in salt-key -L
  • That's it!

In the first article on installing Salt we ran a few simple commands, including
a command to install Nginx. This is a great way to execute ad-hoc commands, but
you don't really want to continually configure your infrastructure this way. By
creating a set of Salt Formulas you can reliably reproduce any configuration
over and over. Your Salt Formulas also become great documentation of what is
installed on your servers. No more wondering what's on that old server that's
been sitting in that closet for 5 years!

Salt Formulas are simple yaml text files and by default reside on your Salt
Master in /srv/salt/

Let's start by creating a Salt Formula to make sure Vim is installed.

vi /srv/salt/vim.sls

Add the following text to your vim.sls:

    - installed

What's going on here? Let me describe each line.

The first line is called the ID Declaration; essentially the "label" for this
stanza. vim will be used for our package name. The name you use here must
match up with the actual package name used by your package manager. "vim" for
Ubuntu, "vim-core" for CentOS, for example. (In reality, the ID Declaration can
be any arbitrary text and you can specify the actual package name below, but
we'll do it this way right now for simplicity's sake)

The second line is called the State Declaration. This refers to the specific
Salt State that we're going to make use of. In this example we're using the
"pkg" state. You can find a list of all the states that Salt provides here:
You can even easily create your own states!

The third line is called the Function Declaration. This refers to the name of
the function inside the state module that we're going to execute. In this
example it's "installed". Notice the tense here. Salt States are idempotent.
You can execute them over and over and nothing on your server will be
altered if your server already conforms to the desired state.

And that's all! Now we can apply this state to our server like this:

salt 'minion01' state.sls vim

What if we want to make sure nano is removed from our system at the same time?
Make your vim.sls look like this:

    - installed

    - removed

Are you seeing the pattern here?

In the next example we're going to install the Apache web server and PHP at the
same time. Create a file named "webserver.sls":

vi /srv/salt/webserver.sls

Let's add the following to "webserver.sls"

    - installed
    - pkgs:
      - apache2
      - php5
      - php5-mysql

In this example, notice the "- pkgs:" argument. Each item in the list below "-
pkgs:" will be passed together to your OS's package manager to be installed
together. This means only one call to "apt" or "yum" will occur. If you have a
large list of packages to install this is the most efficient way to install

Again, you can apply this Formula to your server like this:

salt 'minion01' state.sls webserver

OK, now we're down to our last example of installing git. Can you guess how
we're going to do it?

vi /srv/salt/git.sls

The contents:

    - installed

And again to apply this new config do the following:

salt 'minion01' state.sls git

If we wanted to apply each of these configs at the same time we can execute the

salt 'minion01' state.sls vim,webserver,git

Easy, huh?

Now for the last part of this tutorial we're going to learn the concept of a
"highstate". A "highstate" is a way for Salt to dynamically determine which
Salt Formulas should be applied to a certain minion. To start with you execute
a "highstate" like this:

salt 'minion01' state.highstate

This command causes the Minion to download and examine a file from the Salt
Master called the "top file". By default this file is found on the Salt Master
at /srv/salt/top.sls. Let's look at what a basic top file looks like:

    - vim
    - git
    - webserver
    - mongodb

In this example top.sls we have a "base" environment. For now we're going to
stick with just a default "base" environment. When the minion is told to
execute a highstate, as mentioned before, the minion requests the top.sls from
the master and searches for formulas that it matches. The '*' is a wildcard
and means that ALL minions should apply the list of formulas below it; in
this case just the "vim" formula. The fourth line, 'minion*', also matches our
minion. So that means our minion will apply the "git" and "webserver" formulas.
Our minion does NOT match against 'minion02' so our minion will not attempt
to apply the "mongodb" formula.

You'll notice that in this example we're only matching on the minion's ID or
name with standard globbing. You can also match on pcre, ip address and ip
address range, grains and various other things. You can find a list of ways to
match here.


We've created some basic Salt formulas that make use of Salt's built in states
to configure our server. This is just the very beginning of what you can do
with Salt!

The Official SaltStack Walkthrough is a great way to learn more about Salt.

To learn more about all the ways Salt can help you manage your infrastructure
read through the extensive documentation for Salt at

Please come join the great Salt community! Our mailing list is here
https://groups.google.com/forum/#!forum/salt-users and our IRC channel is
#salt on freenode.

Development of Salt takes place here: https://github.com/saltstack/salt

Please feel free to stop by and ask for help!


Creative Commons License