Articles February 26, 2013 at 7:00 am

Setting up a basic Puppet 3.1.x master on OS X 10.8

Between OS X 10.7 and 10.8, some changes were made with how directory services functioned.  This caused Puppet 2.7.x to not be fully functional on 10.8. Thankfully, these changes have been adjusted for in the latest version of Puppet (3.x).  Now that we have full 10.8 support, lets make a OS X 10.8-based Puppet Master.

First, some prerequisites.  You need a machine that has 10.8 installed on it.  This can be a vanilla install of 10.8 or have installed, it will work perfectly fine either way.  Make sure that your machine is named properly…it is important, so use scutil to check LocalHostName, HostName and ComputerName to make sure they are all correct.  I highly suggest naming the master something such as puppet (Clients look for this by default) or puppetmaster01.  It is advisable to make a DHCP reservation for this machine and to create a DNS record for the machine as well (Typically an ‘A’ record).  If you do not have the ability to create DNS records, you will want to modify the hosts file (/etc/hosts) on each client so that they resolve the master correctly.  Editing the hosts file is beyond the scope of this article, but there is a lot of good information out there regarding this.

This article follows the documentation found in the Puppet 3 Reference Manual (Which goes into greater detail than this article will).  If there is any question on how to do something specific , reference the manual for more detail.

Next we must install Puppet on our master.  The Reference Manual has a section specifically for OS X regarding the puppet install.  Puppet 3.x requires that FacterHiera and Puppet are installed.

Download each of these here.  For the purposes of this guide, we will be using Facter 1.6.17, Hiera 1.1.2 and Puppet 3.1.0.  Install each of these on your puppet master in the order listed above.  Note: The packages are not signed, so you will have to control-click (or right click) to open the packages.

As of the Puppet 3.1.0 installer, the puppet service account should be created automatically.  I suggest double checking this by running ‘id puppet‘.  It should list the puppet user’s uidgid and groups.  If you get ‘id: puppet: no such user’ instead, then you will need to create the user manually.  Create the service account and puppet group using the following two commands (As per the Reference Manual):

sudo puppet resource group puppet ensure=present
sudo puppet resource user puppet ensure=present gid=puppet shell='/sbin/nologin'

view raw
hosted with ❤ by GitHub

Also, if you do not want this puppet user to appear at the login window, run the following command to hide it (or you can set it via MCX, Profile, etc):

sudo defaults write /Library/Preferences/ Hide500Users -boolean YES

view raw
hosted with ❤ by GitHub

We now need to configure some settings on our master.  Everyone’s environment is different and as a result each setting you choose for your master can vary depending upon your needs.  For a full list of all possible settings and more detail about what they do, please see the Configuring Puppet documentation.

Luckily, puppet uses some sensible default settings:

# Default Puppet Settings
server = puppet
report = true
pluginsync = true
certname = (The FQDN of the machine that is running puppet)

view raw
hosted with ❤ by GitHub

The only setting here you may want to change is the certname setting.  If your server is not named ‘puppet’ and/or you have flaky DNS, you will want to set the certname to your machine’s fqdn (Example:  So for a simple master setup, your /etc/puppet.conf file would contain the following:

certname =

view raw
hosted with ❤ by GitHub

Also, since pluginsync is enabled by default, create the modules folder and make sure the puppet user owns it:

sudo mkdir /etc/puppet/modules
sudo chown puppet /etc/puppet/modules

view raw
hosted with ❤ by GitHub

Now run puppet as a master for the first time using the following command:

sudo puppet master –debug –verbose –no-daemonize

view raw
hosted with ❤ by GitHub

Because we are running puppet as a master, it will generate a CA (Certificate Authority) so it can securely talk to clients and create other folder structure that the master needs to function.

Puppet is now fully configured as a basic master, but we are missing one key component: a service to make sure that Puppet is running.  Since we are setting this up on OS X, we will use a launchd job.  The Puppet Documentation on setting up the launchd item can be found here.  In this documentation, Puppet Labs has provided us with a launchd item that can take care of starting our puppet master for us.  You can download the plist here or copy it from the box below.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
<plist version="1.0">
<string>Puppetmaster Daemon</string>

Save the contents of this file into /Library/LaunchDaemons/com.puppetlabs.puppetmaster.plist . Also, make sure the permissions are correct on the file:

sudo chown root:wheel /Library/LaunchDaemons/com.puppetlabs.puppetmaster.plist
sudo chmod 644 /Library/LaunchDaemons/com.puppetlabs.puppetmaster.plist

view raw
hosted with ❤ by GitHub

And finally, load the launchd using launchctl:

sudo launchctl load -w /Library/LaunchDaemons/com.puppetlabs.puppetmaster.plist

view raw
hosted with ❤ by GitHub

You now have a fully functional but basic Puppet master installed on OS X 10.8.  It is worth noting that this setup uses the WEBrick server that Puppet comes with.  This web server is great for development work, but it does not scale well and you would want something more substantial for a production environment.  Methods for scaling Puppet can be found on the Scaling Puppet page.

For more information on using Puppet on OS X, check out Graham Gilbert’s ongoing series here, here and here as well as his post on creating a development puppet master using vagrant.

Nate Walck

Nate is a Systems Reliability Engineer at Dropbox, Inc in San Francisco, CA. He runs along with Sam Keeley and is one of the founding members of the ##osx-server IRC channel on He loves being involved in the Mac Admin community and using Open Source projects whenever possible, especially Munki, The Luggage and Puppet.

More Posts

Follow Me:

Leave a reply

You must be logged in to post a comment.