How To Create Your First Salt Formula
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
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
- Apache web server
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
- 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
Let's start by creating a Salt Formula to make sure
Vim is installed.
Add the following text to your vim.sls:
vim: pkg: - installed
What's going on here? Let me describe each line.
The first line is called the ID Declaration; essentially the "label" for this
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:
vim: pkg: - installed nano: pkg: - 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":
Let's add the following to "webserver.sls"
webserver_stuff: pkg: - 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?
git: pkg: - 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
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
/srv/salt/top.sls. Let's look at what a basic top file looks like:
base: '*': - vim 'minion*': - git - webserver 'minion02': - 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
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
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!