How To Create Your First Salt Formula

Published on August 20, 2013

Dave Boucha

How To Create Your First Salt Formula

Status: Deprecated

This article covers a version of Ubuntu that is no longer supported. If you are currently operate a server running Ubuntu 12.04, we highly recommend upgrading or migrating to a supported version of Ubuntu:

Reason: Ubuntu 12.04 reached end of life (EOL) on April 28, 2017 and no longer receives security patches or updates. This guide is no longer maintained.

See Instead: This guide might still be useful as a reference, but may not work on other Ubuntu releases. If available, we strongly recommend using a guide written for the version of Ubuntu you are using. You can use the search functionality at the top of the page to find a more recent version.

<b>An Article From the Makers of <a href=“http://saltstack.com”>SaltStack</a>, Submitted by: Dave Boucha</b>


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:http://docs.saltstack.com/ref/states/all/index.html. 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 them.

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 following:

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 http://docs.saltstack.com

Please come join the great Salt community! Our mailing list can be found here 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!

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

Tutorial Series: An Introduction to Salt

Salt is an open-source configuration management and remote execution tool. This tutorial series serves as an introduction to Salt, and will help beginners to get started with using the application.

About the authors
Default avatar
Dave Boucha


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Great tutorial thanks you I am getting some error, please check once

ID: jenkins Function: pkg.installed Result: False Comment: An error was encountered while installing package(s): W: The repository ‘http://ppa.launal Release’ does not have a Release file. E: Failed to fetch http://ppa.launchpad.net/saltstack/salt/ubuntu/dists/xenial/main/bina E: Some index files failed to download. They have been ignored, or old ones used instead Started: 14:34:54.182472 Duration: 10663.112 ms Changes:

      ID: jenkins
Function: service.running
  Result: False
 Comment: The named service jenkins is not available
 Started: 14:35:04.846391
Duration: 25.135 ms


Succeeded: 0 Failed: 2

Total states run: 2

Excellent tutorial, digital ocean I think have a great process for the review of these tutorials.

Great tutorial !!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel