Note: This document covers open source releases of Puppet version 3.8 and lower. For current versions, you should see instructions for installing the latest version of Puppet or installing Puppet Enterprise.
Perform the following tasks after you finish installing Puppet. You should have already done the pre-install tasks and followed the installation instructions for your OS.
After installing Puppet on a node that will act as a puppet master server, you need to:
When you create the puppet master’s certificate, you must include every DNS name at which agent nodes might try to contact the master.
Decide on a main name for Puppet services at your site, and make sure your DNS resolves it to the puppet master (or its load balancer). Unconfigured agents will try to find a master at
puppet, so if you use this name it can reduce setup time.
dns_alt_names = puppet,puppet.example.com,puppetmaster01,puppetmaster01.example.com
If this is the only puppet master in your deployment, or if it will be acting as the CA server for a multi-master site, you should now run:
$ sudo puppet master --verbose --no-daemonize
This will create the CA certificate and the puppet master certificate, with the appropriate DNS names included. Once it says
Notice: Starting Puppet master version <VERSION>, type ctrl-C to kill the process.
You have two main options:
puppet cert generate <NAME> --dns_alt_names=<NAME 1>,<NAME 2>,<NAME 3>on your CA server, then manually copy the new master’s cert, private key, and public key into place on the new master. You will also need to give it a copy of the CA’s certificate and the CRL. See the reference page on the ssldir for more info about these files.
puppet agent --test --ca_server=<SERVER>to request a certificate. On the CA server, run
puppet cert listand
puppet cert --allow-dns-alt-names sign <NAME>to sign the certificate. On the new master, run
puppet agent --test --ca_server=<SERVER>again to retrieve the cert.
You’ll want to set a few settings in puppet.conf before putting the new master to work. See the list of master-related settings for details. You may also want to read about how Puppet loads settings and the syntax of the puppet.conf file.
If you already have a set of modules and a main manifest you use in your deployment, put them into place now. You will probably be checking them out with version control.
Relevant reference pages:
Puppet includes a basic puppet master web server, but you cannot use it for real-life loads. You must configure a production quality web server before you start managing your nodes with Puppet.
If you have no particular preference, you should use Passenger with Apache, since it works well and is simple to set up. If you installed the
puppetmaster-passenger package on Debian or Ubuntu, this is already configured; otherwise, follow the instructions in the Puppet with Passenger setup guide.
Alternately, Puppet supports the Rack interface, and you can configure your puppet master with any Rack web server stack. You can follow the Passenger guide for general guidelines. You will need to:
ext/rackdirectory in the Puppet source, and set its ownership to the
puppetuser and group.
SSL_CLIENT_CERTenvironment variable and the
The exact service you need to start will depend on the web server you configured. If you followed the Passenger guide, you’ll want to start the
apache2 service, depending on your OS.
After installing Puppet on a normal puppet agent node, you’ll need to:
You will probably need to configure some settings in each agent’s puppet.conf file, to connect it to your puppet master server and change certain behavior.
If the puppet agent service isn’t already running, you should now start it and configure it to start on boot. Alternately, you may want to run puppet agent via a cron job instead, or run puppet apply with a cron job for a standalone deployment.
The name of the puppet agent service may vary by platform. On Windows and most *nix platforms, it will be
puppet; on OS X, it is
You can start and enable the service by running:
$ sudo puppet resource service <NAME> ensure=running enable=true
(Although on Windows you would omit the
You may want to run puppet agent with cron rather than its init script; this can sometimes perform better and use less memory. You can create this cron job with Puppet:
$ sudo puppet resource cron puppet-agent ensure=present user=root minute=30 command='/usr/bin/puppet agent --onetime --no-daemonize --splay'
(On Windows nodes, you should just run the service.)
If you are creating a standalone deployment, you can create a similar cron job to run puppet apply instead of puppet agent:
$ sudo puppet resource cron puppet-apply ensure=present user=root minute=30 command='/usr/bin/puppet apply $(puppet apply --configprint manifest)'
In an agent/master deployment, an admin must approve a certificate request for each agent node before that node can fetch configurations. Agent nodes will request certificates the first time they attempt to run.
sudo puppet cert listto view outstanding requests.
sudo puppet cert sign <NAME>to sign a request, or
sudo puppet cert sign --allto sign all pending requests.
An agent node whose request has been signed on the master will run normally on its next attempt.
At this point, the new agent node will fetch and apply configurations from the puppet master server. It’s up to you to make sure the configurations it fetches will actually do something. You can do this by assigning Puppet classes to the node.