Defining Server Paths

There are five variables that define the paths which the Puppet Server should use for its files. Unfortunately, these variables exist in two different files and must be kept in sync. See Table 21-1.

Again, it is essential to keep these variables in sync between the two configuration files. If they differ, then Puppet Server will be looking in one place, and Puppet commands like puppet certificate will be looking in another.

[user]
  vardir = /var/opt/puppetlabs/puppetserver
  ssldir = $vardir/ssl

[master]
  vardir = /var/opt/puppetlabs/puppetserver
  ssldir = $vardir/ssl

   master-var-dir = /var/opt/puppetlabs/puppetserver

[vagrant@puppetserver ~]$ mkdir -p /var/opt/puppetlabs/puppetserver
[vagrant@puppetserver ~]$ chown -R puppet:puppet /var/opt/puppetlabs/puppetserver

Limiting Memory Usage

By default, Puppet Server tries to allocate 2 gigabytes of RAM. This is not necessary for a test node, and won’t work with Vagrant unless you add more memory to the node settings.

Tune down the memory reserved by changing the startup parameters. Edit /etc/sysconfig/puppetserver and change the following line:

# Modify this if you'd like to change the memory allocation, enable JMX, etc.
JAVA_ARGS="-Xms512m -Xmx512m"

Note that the default file contains a MaxPermSize value in this field. It’s OK to remove it, as the server would simply tell you:

Aug 03 00:55:02 puppetserver.example.com java[14652]:
  OpenJDK 64-Bit Server VM warning: ignoring option MaxPermSize=256m;
    support was removed in 8.0

Configuring TLS Certificates

Puppet Server accepts configuration of TLS keys and certificates in two different places. You can define the following override settings in /etc/puppetlabs/puppetserver/conf.d/webserver.conf:

ssl-cert = /var/opt/puppetlabs/puppetserver/ssl/certs/puppet.example.com.pem
ssl-key = /var/opt/puppetlabs/puppetserver/ssl/private_keys/
  puppet.example.com.pem
ssl-ca-cert = /var/opt/puppetlabs/puppetserver/ssl/certs/ca.pem
ssl-crl-path = /var/opt/puppetlabs/puppetserver/ssl/crl.pem

If none of these variables are defined, Puppet Server will fall back to using the following defined or derived settings from /etc/puppetlabs/puppet/puppet.conf, according to Table 21-2.

You can use either the settings in the first column or the second column. If you use the settings in webserver.conf, then you must use all four together. Otherwise, leave all four undefined and use the settings in puppet.conf (which is backward compatible with the Puppet master).

At this time, the Certificate Authority continues to use the following settings from puppet.conf. There isn’t an equivalent in puppetserver/conf.d/ files yet:

[master]
  cacert = /etc/puppetlabs/puppet/ssl/certs/ca.pem
  cacrl = /etc/puppetlabs/puppet/ssl/crl.pem
  hostcert = /etc/puppetlabs/puppet/ssl/certs/puppet.example.com.pem
  hostprivkey = /etc/puppetlabs/puppet/ssl/private_keys/puppet.example.com.pem

Due to the current mixture of settings in two files, I recommend that you consolidate settings in /etc/puppetlabs/puppet/puppet.conf, and leave the settings blank in webserver.conf. This is the default, as-shipped configuration, so no changes are necessary.

The latest version of Puppet Server may have added new configuration options. Check the latest documentation at “Puppet Server: Differing Behavior in puppet.conf” on the Puppet docs site.

You can see the configuration values for the Puppet master and the Certificate Authority (defined or derived from defaults) with this command:

[vagrant@puppetserver ~]$ sudo puppet config print --section master
cfacter = false
confdir = /etc/puppetlabs/puppet
codedir = /etc/puppetlabs/code
vardir = /var/opt/puppetlabs/puppetserver
...etc

Avoiding Obsolete Settings

The following settings are valid for the Puppet master, but have been replaced by other configuration options in Puppet Server:

• autoflush—replaced by settings in logback.xml
• bindaddress—remove and configure ssl-host instead
• ca—uses CA information from bootstrap.cfg instead
• keylength—replaced by a fixed value of 4,096 bits
• logdir—replaced by settings in logback.xml
• masterhttplog—replaced by the access-log-config setting in webserver.conf
• masterlog—replaced by settings in logback.xml
• masterport—replaced by the ssl-port setting in webserver.conf
• ssl_client_header—ignored unless allow-header-cert-info is enabled in auth.conf
• ssl_client_verify_header—ignored unless allow-header-cert-info is enabled in auth.conf
• ssl_server_ca_auth—ignored in favor of ssl-ca-cert or cacert

The following settings used by the Puppet master are ignored by Puppet server, with no equivalent option:

• capass
• caprivatedir
• daemonize
• http_debug
• puppetdlog
• railslog
• syslogfacility
• user

The following three settings are valid for Puppet agents, but will be ignored by Puppet Server:

• configtimeout
• http_proxy_host
• http_proxy_port

Configuring Server Logs

Puppet Server uses the well-known JDK logback library. Logback is a successor to the log4j logging library provided with Java.

By default, the logback configuration file can be found at /etc/puppetlabs/puppetserver/logback.xml. This is the standard XML configuration file format as documented in “Logback configuration” on the Logback Project site.

By default, Puppet Server logs all messages at INFO level or higher to /var/log/puppetlabs/puppetserver/puppetserver.log. Review the bolded sections of this logback.xml configuration snippet:

    <appender name="F1" class="ch.qos.logback.core.FileAppender">
        <file>/var/log/puppetlabs/puppetserver/puppetserver.log</file>
        <append>true</append>
        <encoder>
            <pattern>%d %-5p [%t] [%c{2}] %m%n</pattern>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="F1"/>
    </root>

If you are familiar with logback or log4j, you can modify this file far beyond the simple examples here.

If you want to send Puppet Server messages to the system logger syslog, then you may want to replace or supplement the FileAppender with the following:

    <appender name="Syslog" class="ch.qos.logback.core.net.SyslogAppender">
        <syslogHost>loghost.example.com</file>
        <facility>DAEMON</facility>
    </appender>

    <root level="info">
        ...
        <appender-ref ref="Syslog"/>
    </root>

By default, logback scans for configuration files changes every minute. Restarting Puppet Server is not necessary. To disable this, change the scan attribute on the configuration element:

<configuration scan="true">

You can also adjust the scanning interval based on seconds, minutes, hours, or days:

<configuration scan="true" scanPeriod="30 minutes">

You will need to ensure the syslog server is configured to accept messages from the network. If logging to the local host, you will need to uncomment the following lines in /etc/rsyslog.conf:

# Provides UDP syslog reception
$ModLoad imudp
$UDPServerRun 514

Configuring Server Authentication

Puppet Server authentication and authorization is defined in the /etc/puppetlabs/puppetserver/conf.d/auth.conf configuration file utilizing the trapperkeeper-authorization format.

This file contains an authorization block that contains the rules used to approve or deny requests.

{
    # Allow nodes to retrieve only their own node definition
    match-request: {
        path: "^/puppet/v3/node/([^/]+)$"
        type: regex
        method: get
    }
    allow: "$1"
    sort-order: 500
    name: "puppetlabs node"
},

    # (optional) Authorize access to Puppet master endpoints via rules specified
    # in the legacy Puppet auth.conf file (if true or not specified) or via rules
    # specified in the Puppet Server HOCON-formatted auth.conf (if false).
    use-legacy-auth-conf: false

Adding Ruby Gems

Puppet Server has its own Ruby installation separate from your system Ruby, and even from the Puppet agent’s Ruby. If you are using server-side plugins that require additional gems, use the puppetserver gem command to install them.

First, examine the gems that come preinstalled:

[vagrant@puppetserver ~]$ sudo puppetserver gem list

*** LOCAL GEMS ***

jar-dependencies (0.1.13)
jruby-openssl (0.9.7 java)
json (1.8.0 java)
rake (10.1.0)
rdoc (4.1.2)

The puppetserver gem command is identical to Ruby’s gem command, but maintains the JRuby gem-store used by the Puppet Server. If you need other gems for a plugin running on the server, use puppetserver gem to install them exactly like you’d use Ruby’s gem command:

$ sudo puppetserver gem install bundler --no-ri --no-rdoc
Fetching: bundler-1.10.6.gem (100%)
Successfully installed bundler-1.10.6
1 gem installed

Puppet Server uses JRuby, a high-performance, threaded Ruby interpreter. It is compatible with all native Ruby gems, but not with gems that use binary or compiled extensions. It is best to adjust the plugin to use a native Ruby gem whenever possible.