Puppet's Services: The WEBrick Puppet Master

This version is no longer supported, maintained, or updated. For current versions, see Puppet versions and packages.

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.

Note: We recommend using Puppet Server for production-quality Puppet master servers. Puppet 4 deprecates WEBrick and Rack Puppet master servers, which will be removed in Puppet 5.

For details about invoking the Puppet master command, see the puppet master man page.

Supported Platforms

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 in one of two ways.

Use the puppetmaster Init Script

The Puppet master packages for most platforms install an init script (usually called puppetmaster) that lets you manage the Puppet master as a service. You can usually do sudo puppet resource service puppetmaster ensure=running to start the service. (Use ensure=stopped to stop it.)

Run 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.


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 masterhttplog setting.

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.

When running in the foreground with the --verbose or --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 <FILE>.

Configuring a WEBrick Puppet Master

As described elsewhere, the Puppet master application reads most of its settings from puppet.conf and can accept additional settings on the command line.

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 --verbose or --debug, to change the amount of detail in the logs.

How helpful was this page?
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.