Puppet's Services: The WEBrick Puppet Master
Included in Puppet Enterprise 2015.2. A newer version is available; see the version menu above for details.
Important: Deprecation Warning
The WEBrick Puppet master server is deprecated and will be removed in a future Puppet release.
Puppet master is the application that compiles configurations for any number of Puppet agent nodes, using Puppet code and various other data sources. (For more info, see Overview of Puppet’s Architecture.)
Puppet has the built-in capability to run a complete Puppet master server using Ruby’s WEBrick library.
The WEBrick Puppet master server is not capable of handling production-level numbers of agent nodes. Since it can’t handle concurrent connections, it will be quickly overwhelmed by as few as 10 agents. You should never run a WEBrick Puppet master in production, and should always configure a Rack Puppet master server instead.
For details about invoking the Puppet master command, see the puppet master man page.
The WEBrick Puppet master will run on any *nix platform, including all Linux variants and OS X.
You cannot run a Puppet master on Windows.
Controlling the Service
The WEBrick Puppet master runs as a single Ruby process. You can manage it from the command line.
puppet master on the Command Line
By default, running the
puppet master command will start a Puppet master server daemonized in the background. To stop the service, you’ll need to check the process table with something like
ps aux | grep puppet, then
kill the process.
If you’re testing something quickly and want to view logs in real time, it’s more useful to run
sudo puppet master --verbose --no-daemonize. This will keep the Puppet master process in the foreground and print verbose logs to your terminal.
The WEBrick Puppet Master’s Run Environment
The WEBrick Puppet master runs as a single Ruby process. This single process does everything related to handling Puppet agent requests: It terminates SSL, routes HTTP requests, and executes the Ruby methods that recognize agent requests and build responses to them.
The Puppet master process should generally be started as the root user, via
sudo. Once the process starts, it will drop privileges and start running as the user specified by the
user setting (usually
puppet). Any files and directories the Puppet master uses will need to be readable and writable by this user.
Note that you’ll need to manually create the
puppet user account, as the puppet-agent package does not create it. To create this account, run the following commands:
puppet resource group puppet ensure=present puppet resource user puppet ensure=present gid=puppet
By default, Puppet’s HTTPS traffic uses port 8140. The OS and firewall must allow the Puppet master’s Ruby process to accept incoming connections on this port.
The port can be changed by changing the
masterport setting across all agents and Puppet masters.
When running under WEBrick, Puppet master’s logging is split.
WEBrick will log all HTTPS requests and errors to the file specified by the
The Puppet master application itself logs its activity to syslog. This is where things like compilation errors and deprecation warnings go. Your syslog configuration dictates where these messages will be saved, but the default location is
/var/log/messages on Linux,
/var/log/system.log on Mac OS X, and
/var/adm/messages on Solaris.
You can adjust how verbose the logs are with the
log_level setting, which defaults to
notice. Setting it to
info is equivalent to running with the
--verbose option, and setting it to
debug is equivalent to
--debug. You can also make logs quieter by dialing back to
warning or lower.
When running in the foreground with the
--debug options, Puppet master logs directly to the terminal instead of to syslog.
When started with the
--logdest <FILE> option, Puppet master logs to the file specified by
Configuring a WEBrick Puppet Master
When running from the command line, Puppet master can directly accept command line options. When running via an init script, it sometimes gets command line options from an init script config file. The location and format of this file will vary depending on your platform.
To change the Puppet master’s settings, you should generally use puppet.conf. The only two options you may want to set on the command line or in the init script config file are
--debug, to change the amount of detail in the logs.