Puppet Manual

Puppet Documentation(Generated on July 01, 2013, from git revision 46784ac1656bd7b57fcfb51d0865ec765533d9)

This is the documentation for Puppet, the industry-leading conguration management toolkit. Mostof the content here applies equally to Puppet Enterprise and open source releases of Puppet.

Drive-ThruSmall documents for getting help fast.

Core Types Cheat Sheet A double-sided reference to the most common resource types. (HTMLversion)Module Cheat Sheet A one-page reference to Puppet module layout, covering classes anddened types, les, templates, and plugins. (HTML version)Frequently Asked QuestionsGlossary

Learning PuppetLearn to use Puppet! New users: start here.

Introduction and Index

IntroductionPart one: Serverless Puppet

Resources and the RALManifestsOrderingVariables, Conditionals, FactsModules and ClassesTemplatesClass ParametersDened Types

Part two: Master/Agent PuppetPreparing an Agent VMBasic Agent/Master Puppet

Reference ShelfPuppet 3 Reference ManualPuppet Documentation Drive-Thru 2/434

A concise reference to Puppet 3s usage and internals. Use the left sidebar of any reference manualpage to navigate between pages.

OverviewLanguageModules

Puppet 2.7 Reference ManualA concise reference to Puppet 2.7s usage and internals. Use the left sidebar of any referencemanual page to navigate between pages.

Table of ContentsLanguage A complete reference to the Puppet language.Modules

Miscellaneous ReferencesHTTP API reference of API-accessible resourcesPuppet Language Guide an older version of the Puppet reference manuals language referencePuppet Manpages detailed help for each Puppet application

Generated ReferencesComplete and up-to-date references for Puppets resource types, functions, metaparameters,conguration options, indirection termini, and reports, served piping hot directly from the sourcecode.

Resource Types all default typesFunctions all built in functionsMetaparameters all type-independent resource attributesConguration all conguration le settingsReport all available report handlers

These references are automatically generated from the inline documentation in Puppets sourcecode. References generated from each version of Puppet are archived here:

Versioned References inline reference docs from Puppets past and present

Puppet GuidesLearn about dierent areas of Puppet, x problems, and design solutions.

ComponentsLearn more about major working parts of the Puppet system.

Puppet commands: master, agent, apply, resource, and more components of the system

Installing and Conguring

Puppet Documentation Puppet Guides 3/434

Get Puppet up and running at your site.

An Introduction to PuppetSupported PlatformsInstalling Puppet from packages, source, or gemsUpgrading Puppet general advice and suggestions for upgrading critical infrastructureConguring Puppet use puppet.conf to congure Puppets behaviorSetting Up Puppet includes server setup & testing

Basic Features and UsePuppet Language Guide all the language detailsModule Fundamentals nearly all Puppet code should be in modules.Installing Modules from the Puppet Forge save time by using pre-existing modulesTechniques common design patterns, tips, and tricksTroubleshooting avoid common problems and confusionsParameterized Classes use parameterized classes to write more eective, versatile, andencapsulated codeModule Smoke Testing write and run basic smoke tests for your modulesScope and Puppet understand and banish dynamic lookup warnings with Puppet 2.7Puppet File Serving serving les with PuppetStyle Guide Puppet community conventionsBest Practices use Puppet eectively

Puppet on WindowsManage Windows nodes side by side with your *nix infrastructure, with Puppet 2.7 and higher(including Puppet Enterprise 2.5).

OverviewInstalling Puppet on WindowsRunning Puppet on WindowsWriting Manifests for WindowsTroubleshooting Puppet on WindowsDevelopers Only: Running Puppet from Source on Windows

Tuning and ScalingPuppets default conguration is meant for prototyping and designing a site. Once youre ready forproduction deployment, learn how to adjust Puppet for peak performance.

Scaling Puppet general tips & tricksUsing Multiple Puppet Masters a guide to deployments with multiple Puppet mastersScaling With Passenger for Puppet 0.24.6 and laterScaling With Mongrel for older versions of Puppet

Advanced Features

Puppet Documentation Puppet Guides 4/434

Go beyond basic manifests.

Templating template out cong les using ERBVirtual ResourcesExported Resources share data between hostsEnvironments separate dev, stage, & productionReporting learn what your nodes are up toGetting Started With Cloud Provisioner create and bootstrap new nodes with the experimentalcloud provisioner extensionPublishing Modules on the Puppet Forge preparing your best modules to go public

Hacking and ExtendingBuild your own tools and workows on top of Puppet.USING THE PUPPET DATA LIBRARY

Puppet Data Library: Overview Puppet automatically gathers reams of data about yourinfrastructure. Learn where that data is, how to access it, and how to mine it for knowledge.Inventory Service use Puppets inventory of nodes at your site in your own custom applications

USING APIS AND INTERFACESHTTP Access Control secure API access with auth.confExternal Nodes specify what your machines do using external data sources

USING RUBY PLUGINSPlugins In Modules where to put plugins, how to sync to clientsWriting Custom FactsWriting Custom FunctionsWriting Custom Types & ProvidersComplete Resource Example more information on custom types & providersProvider Development more about providers

DEVELOPING PUPPETRunning Puppet from Source preview the leading edgeDevelopment Life Cycle learn how to contribute codePuppet Internals understand how Puppet works internally

Other ResourcesPuppet Wiki & Bug TrackerPuppet Patterns (Recipes)

ToolsThis guide covers the major tools that comprise Puppet.

Puppet Documentation Other Resources 5/434

Single binaryStarting with Puppet 2.6, Puppet uses a single puppet binary with multiple subcommands, in thestyle of Git. Each of the pre-2.6 commands corresponds directly to one of the new subcommands.

Pre-2.6 Post-2.6

puppetmasterd puppet master

puppetd puppet agent

puppet puppet apply

puppetca puppet cert

ralsh puppet resource

puppetrun puppet kick

puppetqd puppet queue

lebucket puppet lebucket

puppetdoc puppet doc

pi puppet describe

This also results in a change in the puppet.conf conguration le. The sections, previously thingslike [puppetd], now should be renamed to match the new binary names. So [puppetd] becomes[agent]. You will be prompted to do this when you start Puppet. A log message will be generatedfor each section that needs to be renamed. This is merely a warning existing conguration le willwork unchanged.

Manpage documentationAdditional information about each tool is provided in the relevant manpage. You can consult thelocal version of each manpage, or view the web versions of the manuals.

puppet master (or puppetmasterd)Puppet master is a central management daemon. In most installations, youll have one puppetmaster server and each managed machine will run puppet agent. By default, puppet masteroperates a certicate authority, which can be managed using puppet cert.

Puppet master serves compiled congurations, les, templates, and custom plugins to managednodes.

The main conguration le for puppet master, puppet agent, and puppet apply is/etc/puppet/puppet.conf , which has sections for each application.

Note: As of Puppet 3, the old standalone commands have been removed completely. Notealso that puppet without any subcommand will no longer default to puppet apply.


puppet agent (or puppetd)Puppet agent runs on each managed node. By default, it will wake up every 30 minutes(congurable), check in with puppetmasterd, send puppetmasterd new information about thesystem (facts), and receive a compiled catalog describing the desired system conguration. Puppetagent is then responsible for making the system match the compiled catalog. If pluginsync isenabled in a given nodes conguration, custom plugins stored on the Puppet Master server aretransferred to it automatically.

The puppet master server determines what information a given managed node should see basedon its unique identier (certname); that node will not be able to see congurations intended forother machines.

puppet apply (or puppet)When running Puppet locally (for instance, to test manifests, or in a non-networked disconnectedcase), puppet apply is run instead of puppet agent. It then uses local les, and does not try tocontact the central server. Otherwise, it behaves the same as puppet agent.

puppet cert (or puppetca)The puppet cert command is used to sign, list and examine certicates used by Puppet to securethe connection between the Puppet master and agents. The most common usage is to sign thecerticates of Puppet agents awaiting authorisation:

>puppetcert--listagent.example.com

>puppetcert--signagent.example.com

You can also list all signed and unsigned certicates:

>puppetcert--alland--list+agent.example.comagent2.example.com

Certicates with a + next to them are signed. All others are awaiting signature.

puppet doc (or puppetdoc)Puppet doc generates documentation about Puppet and your manifests, which it can output inHTML, Markdown and RDoc.

puppet resource (or ralsh)Puppet resource (also known as ralsh , for Resource Abstraction Layer SHell) uses Puppetsresource abstraction layer to interactively view and manipulate your local system.

For example, to list information about the user xyz:Puppet Documentation Other Resources 7/434

>puppetresourceUser"xyz"

user{'xyz':home=>'/home/xyz',shell=>'/bin/bash',uid=>'1000',comment=>'xyz,,,',gid=>'1000',groups=>['adm','dialout','cdrom','sudo','plugdev','lpadmin','admin','sambashare','libvirtd'],

ensure=>'present'}

It can also be used to make additions and removals, as well as to list resources found on a system:

>puppetresourceUser"bob"ensure=presentgroup=admin

notice:/User[bob]/ensure:createduser{'bob':shell=>'/bin/sh',home=>'/home/bob',uid=>'1001',gid=>'1001',ensure=>'present',password=>'!'}

>puppetresourceUser"bob"ensure=absent...

>puppetresourceUser...

Puppet resource is most frequently used as a learning tool, but it can also be used to avoidmemorizing dierences in common commands when maintaining multiple platforms. (Note thatpuppet resource can be used the same way on OS X as on Linux, e.g.)

puppet inspectPuppet inspect generates an inspection report and sends it to the puppet master. It cannot be runas a daemon.

Inspection reports dier from standard Puppet reports, as they do not record the actions taken byPuppet when applying a catalog; instead, they document the current state of all resource attributeswhich have been marked as auditable with the audit metaparameter. (The most recent cachedcatalog is used to determine which resource attributes are auditable.)

Inspection reports are handled identically to standard reports, and must be dierentiated at parsetime by your report tools; see the report format documentation for more details. Although a futureversion of Puppet Dashboard will support viewing of inspection reports, Puppet Labs does notcurrently ship any inspection report tools.


Puppet inspect was added in Puppet 2.6.5.

facterPuppet agent nodes use a library (and associated front-end tool) called facter to provideinformation about the hardware and OS (version information, IP address, etc) to the puppet masterserver. These facts are exposed to Puppet manifests as global variables, which can be used inconditionals, string expressions, and templates. To see a list of the facts any node oers, simplyopen a shell session on that node and run facter . Facter is included with (and required by) allPuppet installations.

Introduction to PuppetWhy PuppetAs system administrators acquire more and more systems to manage, automation of mundanetasks is increasingly important. Rather than develop in-house scripts, it is desirable to share asystem that everyone can use, and invest in tools that can be used regardless of ones employer.Certainly doing things manually doesnt scale.

Puppet has been developed to help the sysadmin community move to building and sharing maturetools that avoid the duplication of everyone solving the same problem. It does so in two ways:

It provides a powerful framework to simplify the majority of the technical tasks that sysadminsneed to performThe sysadmin work is written as code in Puppets custom language which is shareable just likeany other code.

This means that your work as a sysadmin can get done much faster, because you can have Puppethandle most or all of the details, and you can download code from other sysadmins to help you getdone even faster. The majority of Puppet implementations use at least one or two modulesdeveloped by someone else, and there are already hundreds of modules developed and shared bythe community.

Learning RecommendationsWere glad you want to learn Puppet. Youre free to browse around the documentation as you like,though we generally recommend trying out Puppet locally rst (without the daemon andclient/server setup), so you can understand the basic concepts. From there, move on to centrallymanaged server infrastructure. Ralsh is also a great way to get your feet wet exploring the Puppetmodel, after you have read some of the basic information you can quickly see how the declarativemodel works for simple things like users, services, and le permissions.

Once youve learned the basics, make sure you understand classes and modules, then move on tothe advanced sections and read more about the features that are useful to you. Learning all at onceis denitely not required. If you nd something confusing, le a ticket or email us at

Puppet Documentation Introduction to Puppet 9/434

[email protected] to let us know.

System ComponentsPuppet is typically (but not always) used in a client/server formation, with all of your clients talkingto one or more central servers. Each client contacts the server periodically (every half hour, bydefault), downloads the latest conguration, and makes sure it is in sync with that conguration.Once done, the client can send a report back to the server indicating if anything needed to change.This diagram shows the data ow in a regular Puppet implementation:

Puppets functionality is built as a stack of separate layers, each responsible for a xed aspect ofthe system, with tight controls on how information passes between layers:

See also Conguring Puppet. For more information about components (puppetmasterd, puppetd,puppet, and so on), see the Tools section.

Features of the SystemIdempotencyOne big dierence between Puppet and most other tools is that Puppet congurations areidempotent, meaning they can safely be run multiple times. Once you develop your conguration,your machines will apply the conguration often by default, every 30 minutes and Puppet willonly make any changes to the system if the system state does not match the congured state.

If you tell the system to operate in no-op (aka dry-run), mode, using the --noop argument to oneof the Puppet tools, puppet will guarantee that no work happens on your system. Similarly, if anychanges do happen when running without that ag, puppet will ensure those changes are logged.

Because of this, you can use Puppet to manage a machine throughout its lifecycle from initial


installation, to ongoing upgrades, and nally to end-of-life, where you move services elsewhere.Unlike system install tools like Suns Jumpstart or Red Hats Kickstart, Puppet congurations cankeep machines up to date for years, rather than just building them correctly only the rst time andthen neccessitating a rebuild. Puppet users usually do just enough with their host install tools toboostrap Puppet, then they use Puppet to do everything else.

Cross PlatformPuppets Resource Abstraction Layer (RAL) allows you to focus on the parts of the system you careabout, ignoring implementation details like command names, arguments, and le formats yourtools should treat all users the same, whether the user is stored in NetInfo or /etc/passwd . We callthese system entities resources .

Ralsh, listed in the Tools section is a fun way to try out the RAL before you get too deep into Puppetlanguage.

Model & Graph BasedRESOURCE TYPESThe concept of each resource (like service, le, user, group, etc) is modelled as a type. Puppetdecouples the denition from how that implementation is fullled on a particular operating system,for instance, a Linux user versus an OS X user can be talked about in the same way but areimplemented dierently inside of Puppet.

See the types reference for a list of managed types and information about how to use them.PROVIDERSProviders are the fulllment of a resource. For instance, for the package type, both yum and aptare valid ways to manage packages. Sometimes more than one provider will be available on aparticular platform, though each platform always has a default provider. There are currently 17providers for the package type.MODIFYING THE SYSTEMPuppet resource providers are what are responsible for directly managing the bits on disk. You donot directly modify a system from Puppet language you use the language to specify a resource,which then modies the system. This way puppet language behaves exactly the same way in acentrally managed server setup as it does locally without a server. Rather than tacking a couple oflines onto the end of your fstab , you use the mount type to create a new resource that knows howto modify the fstab , or NetInfo, or wherever mount information is kept.

Resources have attributes called properties which change the way a resource is managed. Forinstance, users have an attribute that species whether the home directory should be created.

Metaparams are another special kind of attribute, those exist on all resources. This include thingslike the log level for the resource, whether the resource should be in noop mode so it nevermodies the system, and the relationships between resources.RESOURCE RELATIONSHIPSPuppet has a system of modelling relationships between resources what resources should beevaluated before or after one another. They also are used to determine whether a resource needs


to respond to changes in another resource (such as if a service needs to restart if the congurationle for the service has changed). This ordering reduces unneccessary commands, such as avoidingrestarting a service if the conguration has not changed.

Because the system is graph based, its actually possible to generate a diagram (from Puppet) of therelationships between all of your resources.

Learning The LanguageSeeing a few examples in action will greatly help in learning the system.

For information about the Puppet language, see the excellent language guide

Puppet Open Source Supported PlatformsThis page lists supported platforms for the open source version of Puppet. For Puppet Enterprisessupported platforms visit the PE system requirements page.

Please contact Puppet Labs if you are interested in a platform not on this list.

See Installing Puppet for more details about the packages available for your platform(s).

Puppet 2.6, 2.7, and 3 can run on the following platforms:

LinuxRed Hat Enterprise Linux, version 4 and higherCentOS, version 4 and higherScientic Linux, version 4 and higherOracle Linux, version 4 and higherDebian, version 5 (Lenny) and higherUbuntu, version 8.04 LTS and higherFedora, version 15 and higherSUSE Linux Enterprise Server, version 11 and higherGentoo LinuxMandriva Corporate Server 4ArchLinux

BSDFreeBSD 4.7 and laterOpenBSD 4.1 and later

Other UnixMac OS X, version 10.5 (Leopard) and higher (Puppet 2.7 and earlier also support 10.4)Oracle Solaris, version 10 and higher

Puppet Documentation Puppet Open Source Supported Platforms 12/434

AIX, version 5.3 and higherHP-UX

WindowsWindows Server 2003 and 2008 (Puppet version 2.7.6 and higher)Windows 7 (Puppet version 2.7.6 and higher)

Ruby VersionsPuppet requires an MRI Ruby interpreter. Certain versions of Ruby work better with Puppet thanothers, and some versions are not supported at all. Run ruby--version to check the version ofRuby on your system.

Ruby version Puppet 2.6 Puppet 2.7 Puppet 3.x

1.8.5* Supported Supported No

1.8.7 Supported Supported Supported

1.9.3** No No Supported

1.9.2 No No No

1.9.1 No No No

1.9.0 No No No

1.8.6 No No No

1.8.1 No No No

Puppet Enterprise does not rely on the OSs Ruby version, as it maintains its own Rubyenvironment. You can install PE alongside any version of Ruby or on systems without Rubyinstalled.

The Windows installers provided by Puppet Labs dont rely on the OSs Ruby version, andcan be installed alongside any version of Ruby or on systems without Ruby installed.

* Note that although Ruby 1.8.5 is fully supported on Puppet 2.6 and 2.7, Ruby 1.8.7generally gives better performance and memory use. To support the large installed base ofRHEL5 systems which ship with Ruby 1.8.5, Puppet Labs packages a drop-in replacementRuby 1.8.7 package. Read the Enterprise Linux and Derivatives section of the InstallingPuppet guide to learn how to install these packages.

** Ruby 1.9.3-p0 has bugs that cause a number of known issues with Puppet, and youshould use a dierent release. To the best of our knowledge, these issues were xed in thesecond public release of Ruby 1.9.3 (p125), and we are positive they are resolved in p392(which ships with Fedora 18). Unfortunately, Ubuntu Precise ships with p0 for some reason,and theres not a lot we can do about it. If youre using Precise, we recommend using PuppetEnterprise or installing a third-party Ruby package.

Puppet Documentation Puppet Open Source Supported Platforms 13/434

Versions marked as Supported are recommended by Puppet Labs and are under extensiveautomated test coverage. Other versions are not recommended and we make no guarantees abouttheir performance with Puppet.

PrerequisitesPuppet has a very small number of external dependencies:

Dependency Puppet 2.x Puppet 3.x

Facter Required Required

Hiera Optional Required

rgen Optional

Rgen is only needed if you are using Puppet 3.2 with parser=future enabled. The ocialPuppet Labs packages will install it as a dependency.

All other prerequisite Ruby libraries should come with any standard Ruby 1.8.5+ install. Shouldyour OS not come with the complete standard library (or you are using a custom Ruby build), theseinclude:

base64cgidigest/md5etcleutilsipaddropenssl (>= 0.9.8o if using a 3.x Puppet master or newer)strscansysloguriwebrickwebrick/httpsxmlrpc

Installing Puppet

Puppet Documentation Installing Puppet 14/434

Installing Puppet

Pre-InstallCheck the following before you install Puppet.

OS/Ruby VersionSee the supported platforms guide.If your OS is older than the supported versions, you may still be able to run Puppet if you installan updated version of Ruby. See the list of supported Ruby versions.

Deployment TypeDecide on a deployment type before installing:

Agent/masterAgent nodes pull their congurations from a puppet master server. Admins must managenode certicates, but will only have to maintain manifests and modules on the puppet masterserver(s), and can more easily take advantage of features like reporting and external datasources.

You must decide in advance which server will be the master; install Puppet on it beforeinstalling on any agents. The master should be a dedicated machine with a fast processor,lots of RAM, and a fast disk.

StandaloneEvery node compiles its own conguration from manifests. Admins must regularly syncPuppet manifests and modules to every node.

NetworkIn an agent/master deployment, you must prepare your network for Puppets trac.

Firewalls: The puppet master server must allow incoming connections on port 8140, and agentnodes must be able to connect to the master on that port.Name resolution: Every node must have a unique hostname. Forward and reverse DNS must bothbe congured correctly. Instructions for conguring DNS are beyond the scope of this guide. Ifyour site lacks DNS, you must write an /etc/hosts le on each node.

Installing Puppet

This document covers open source releases of Puppet. See here for instructions on installingPuppet Enterprise.

Note: The default master hostname is puppet . Your agent nodes will be ready sooner if thishostname resolves to your puppet master.


The best way to install Puppet varies by operating system. Use the links below to skip to your OSsinstructions.

Enterprise Linux (and Derivatives)Debian and UbuntuFedoraMac OS XWindowsInstalling from Gems (Not Recommended)Installing from a Tarball (Not Recommended)Running Directly from Source (Not Recommended)

Enterprise Linux (and Derivatives)These instructions apply to Enterprise Linux (EL) variants, including but not limited to:

Red Hat Enterprise Linux 5 and 6CentOS 5 and 6Scientic Linux 5 and 6Ascendos 5 and 6

These distributions are also supported by Puppet Enterprise.

Users of out-of-production EL systems (i.e. RHEL 4) may need to compile their own copy of Rubybefore installing, or use an older snapshot of EPEL.1. CHOOSE A PACKAGE SOURCEEL 5 and 6 releases can install Puppet from Puppet Labs ocial repo, or from EPEL.USING PUPPET LABS PACKAGESPuppet Labs provides an ocial package repo at yum.puppetlabs.com. It contains up-to-datepackages, and can install Puppet and its prerequisites without requiring any other externalrepositories.

To use the Puppet Labs repo, follow the instructions here.USING EPELThe Extra Packages for Enterprise Linux (EPEL) repo includes Puppet and its prerequisites. Thesepackages are usually older Puppet versions with security patches. As of April 2012, EPEL wasshipping a Puppet version from the prior, maintenance-only release series.

To install Puppet from EPEL, follow EPELs own instructions for enabling their repository on all ofyour target systems.2. INSTALL THE PUPPET MASTERSkip this step for a standalone deployment.

On your puppet master node, run sudoyuminstallpuppet-server . This will install Puppet andan init script (/etc/init.d/puppetmaster ) for running a test-quality puppet master server.


3. INSTALL PUPPET ON AGENT NODESOn your other nodes, run sudoyuminstallpuppet . This will install Puppet and an init script(/etc/init.d/puppet ) for running the puppet agent daemon.

For a standalone deployment, install this same package on all nodes.4. CONFIGURE AND ENABLEContinue reading here and follow any necessary post-install steps.

Debian and UbuntuThese instructions apply to Debian, Ubuntu, and derived Linux distributions, including

Debian 6 Squeeze (current stable release) (also supported by Puppet Enterprise)Debian Wheezy (current testing distribution)Debian Sid (current unstable distribution)Ubuntu 12.04 LTS Precise Pangolin (also supported by Puppet Enterprise)Ubuntu 10.04 LTS Lucid Lynx (also supported by Puppet Enterprise)Ubuntu 8.04 LTS Hardy HeronUbuntu 12.10 Quantal QuetzalUbuntu 11.10 Oneiric Ocelot

Users of out-of-production versions may have vendor packages of Puppet available, but cannot usethe Puppet Labs packages.1. CHOOSE A PACKAGE SOURCEDebian and Ubuntu systems can install Puppet from Puppet Labs ocial repo, or from the OSvendors default repo.USING PUPPET LABS PACKAGESPuppet Labs provides an ocial package repo at apt.puppetlabs.com. It contains up-to-datepackages, and can install Puppet and its prerequisites without requiring any other externalrepositories.

To use the Puppet Labs repo, follow the instructions here.USING VENDOR PACKAGESDebian and Ubuntu distributions include Puppet in their default package repos. No extra steps arenecessary to enable it.

Older OS versions will have outdated Puppet versions, which are updated only with security patches.As of April 2012:

Debian unstables Puppet was current.Debian testings Puppet was nearly current (one point release behind the current version).Debian stables Puppet was more than 18 months old, with additional security patches.The latest Ubuntus Puppet was nearly current (one point release behind).The prior (non-LTS) Ubuntus Puppet was nine months old, with additional security patches.The prior LTS Ubuntus Puppet was more than two years old, with additional security patches.


2. INSTALL THE PUPPET MASTERSkip this step for a standalone deployment.

On your puppet master node, run sudoapt-getinstallpuppetmaster . This will install Puppet,its prerequisites, and an init script (/etc/init.d/puppetmaster ) for running a test-quality puppetmaster server.

If you are using vendor packages, a puppetmaster-passenger package may be available. If youinstall this package instead of puppetmaster , it will automatically congure a production-capacityweb server for the Puppet master, using Passenger and Apache. In this conguration, do not usethe puppetmaster init script; instead, control the puppet master by turning the Apache web serveron and o or by disabling the puppet master vhost.3. INSTALL PUPPET ON AGENT NODESOn your other nodes, run sudoapt-getinstallpuppet . This will install Puppet and an init script(/etc/init.d/puppet ) for running the puppet agent daemon.

For a standalone deployment, run sudoapt-getinstallpuppet-common on all nodes instead.This will install Puppet without the agent init script.4. CONFIGURE AND ENABLEContinue reading here and follow any necessary post-install steps.

FedoraThese instructions apply to Fedora releases, including:

Fedora 17Fedora 16

Users of out-of-production versions may have vendor packages of Puppet available, but cannot usethe Puppet Labs packages.1. CHOOSE A PACKAGE SOURCEFedora systems can install Puppet from Puppet Labs ocial repo, or from the OS vendors defaultrepo.USING PUPPET LABS PACKAGESPuppet Labs provides an ocial package repo at yum.puppetlabs.com. It contains up-to-datepackages, and can install Puppet and its prerequisites without requiring any other externalrepositories.

To use the Puppet Labs repo, follow the instructions here.USING VENDOR PACKAGESFedora includes Puppet in its default package repos. No extra steps are necessary to enable it.

These packages are usually older Puppet versions with security patches. As of April 2012, bothcurrent releases of Fedora had Puppet versions from the prior, maintenance-only release series.2. INSTALL THE PUPPET MASTER


Skip this step for a standalone deployment.

On your puppet master node, run sudoyuminstallpuppet-server . This will install Puppet andan init script (/etc/init.d/puppetmaster ) for running a test-quality puppet master server.

3. INSTALL PUPPET ON AGENT NODESOn your other nodes, run sudoyuminstallpuppet . This will install Puppet and an init script(/etc/init.d/puppet ) for running the puppet agent daemon.

For a standalone deployment, install this same package on all nodes.4. CONFIGURE AND ENABLEContinue reading here and follow any necessary post-install steps.

Mac OS X1. DOWNLOAD THE PACKAGEOS X users should install Puppet with ocial Puppet Labs packages. Download them here. You willneed:

The most recent Facter packageThe most recent Hiera packageThe most recent Puppet package

2. INSTALL FACTERMount the Facter disk image, and run the installer package it contains.3. INSTALL HIERAMount the Hiera disk image, and run the installer package it contains.4. INSTALL PUPPETMount the Puppet disk image, and run the installer package it contains.5. CONFIGURE AND ENABLEThe OS X packages are currently fairly minimal, and do not create launchd jobs, users, or defaultconguration or manifest les. You will have to:

Manually create a puppet group, by running sudopuppetresourcegrouppuppetensure=present .Manually create a puppet user, by running sudopuppetresourceuserpuppetensure=presentgid=puppetshell='/sbin/nologin' .If you intend to run the puppet agent daemon regularly, or if you intend to automatically runpuppet apply at a set interval, you must create and register your own launchd services. See thepost-installation instructions for a model.

Continue reading here and follow any necessary post-install steps.

WindowsSee the Windows installation instructions.


Installing from Gems (Not Recommended)On *nix platforms without native packages available, you can install Puppet with Rubys gempackage manager.1. ENSURE PREREQUISITES ARE INSTALLEDUse your OSs package tools to install both Ruby and RubyGems. In some cases, you may need tocompile and install these yourself.

On Linux platforms, you should also ensure that the LSB tools are installed; at a minimum, werecommend installing lsb_release . See your OSs documentation for details about its LSB tools.

2. INSTALL PUPPETTo install Puppet and Facter, run:

$sudogeminstallpuppet

3. CONFIGURE AND ENABLEInstalling with gem requires some additional steps:

Manually create a puppet group, by running sudopuppetresourcegrouppuppetensure=present .Manually create a puppet user, by running sudopuppetresourceuserpuppetensure=presentgid=puppetshell='/sbin/nologin' .Create and install init scripts for the puppet agent and/or puppet master services. See the ext/directory in the Puppet source for example init scripts (Red Hat, Debian, SUSE, systemd, FreeBSD,Gentoo, Solaris).Manually create an /etc/puppet/puppet.conf le.Locate the Puppet source on disk, and manually copy the auth.conf le from the /confdirectory to /etc/puppet/auth.conf .If you get the error require:nosuchfiletoload when trying to run Puppet, dene theRUBYOPT environment variable as advised in the post-install instructions of the RubyGems UserGuide.


Installing from a Tarball (Not Recommended)This is almost never recommended, but may be necessary in some cases.1. ENSURE PREREQUISITES ARE INSTALLEDUse your OSs package tools to install Ruby. In some cases, you may need to compile and install ityourself.

On Linux platforms, you should also ensure that the LSB tools are installed; at a minimum, werecommend installing lsb_release . See your OSs documentation for details about its LSB tools.


If you wish to use Puppet 3.2 with parser=future enabled, you should also install the rgengem.2. DOWNLOAD PUPPET AND FACTER

Download Puppet here.Download Facter here.

3. INSTALL FACTERUnarchive the Facter tarball, navigate to the resulting directory, and run:

$sudorubyinstall.rb

4. INSTALL PUPPETUnarchive the Puppet tarball, navigate to the resulting directory, and run:

$sudorubyinstall.rb

5. CONFIGURE AND ENABLEInstalling from a tarball requires some additional steps:

Manually create a puppet group, by running sudopuppetresourcegrouppuppetensure=present .Manually create a puppet user, by running sudopuppetresourceuserpuppetensure=presentgid=puppetshell='/sbin/nologin' .Create and install init scripts for the puppet agent and/or puppet master services. See the ext/directory in the Puppet source for example init scripts (Red Hat, Debian, SUSE, systemd, FreeBSD,Gentoo, Solaris).Manually create an /etc/puppet/puppet.conf le.


Running Directly from Source (Not Recommended)This is recommended only for developers and testers.

See Running Puppet from Source.

Post-InstallPerform the following tasks after you nish installing Puppet.

Congure PuppetPuppets main conguration le is found at /etc/puppet/puppet.conf . See Conguring Puppet formore details.

Most users should specify the following settings:


ON AGENT NODESSettings for agent nodes should go in the [agent] or [main] block of puppet.conf .

server : The hostname of your puppet master server. Defaults to puppet .report : Most users should set this to true .pluginsync : Most users should set this to true .certname : The sitewide unique identier for this node. Defaults to the nodes fully qualieddomain name, which is usually ne.

ON PUPPET MASTERSSettings for puppet master servers should go in the [master] or [main] block of puppet.conf .

dns_alt_names : A list of valid hostnames for the master, which will be embedded in itscerticate. Defaults to the puppet masters certname and puppet , which is usually ne. If you areusing a non-default setting, set it before starting the puppet master for the rst time.

ON STANDALONE NODESSettings for standalone puppet nodes should go in the [main] block of puppet.conf .

Puppets default settings are generally appropriate for standalone nodes. No additionalconguration is necessary unless you intend to use centralized reporting or an external nodeclassier.

Start and Enable the Puppet ServicesSome packages do not automatically start the puppet services after installing the software. You mayneed to start them manually in order to use Puppet.WITH INIT SCRIPTSMost packages create init scripts called puppet and puppetmaster , which run the puppet agent andpuppet master services.

You can start and permanently enable these services using Puppet:

$sudopuppetresourceservicepuppetensure=runningenable=true$sudopuppetresourceservicepuppetmasterensure=runningenable=true

WITH CRON

Note: puppet masters are usually also agent nodes; settings in [main] will be available toboth services, and settings in the [master] and [agent] blocks will override the settings in

[main] .

Note: If you have congured puppet master to use a production web server, do not use thedefault init script; instead, start and stop the web server that is managing the puppet masterservice.


Standalone deployments do not use services with init scripts; instead, they require a cron task toregularly run puppet apply on a main manifest (usually the same /etc/puppet/manifests/site.ppmanifest that puppet master uses). You can create this cron job with Puppet:

$sudopuppetresourcecronpuppet-applyensure=presentuser=rootminute=30command='/usr/bin/puppetapply$(puppet--configprintmanifest)'

In an agent/master deployment, you may wish to run puppet agent with cron rather than its initscript; this can sometimes perform better and use less memory. You can create this cron job withPuppet:

$sudopuppetresourcecronpuppet-agentensure=presentuser=rootminute=30command='/usr/bin/puppetagent--onetime--no-daemonize--splay'

WITH LAUNCHDApple recommends you use launchd to manage the execution of services and daemons. You candene a launchd service with XML property lists (plists), and manage it with the launchctlcommand line utility. If youd like to use launchd to manage execution of your puppet master oragent, download the following les and copy each into /Library/LaunchDaemons/ :

com.puppetlabs.puppetmaster.plist (to manage launch of a puppet master)com.puppetlabs.puppet.plist (to manage launch of a puppet agent)

Set the correct owner and permissions on the les. Both must be owned by the root user and bothmust be writable only by the root user:

$sudochownroot:wheel/Library/LaunchDaemons/com.puppetlabs.puppet.plist$sudochmod644/Library/LaunchDaemons/com.puppetlabs.puppet.plist$sudochownroot:wheel/Library/LaunchDaemons/com.puppetlabs.puppetmaster.plist$sudochmod644/Library/LaunchDaemons/com.puppetlabs.puppetmaster.plist

Make launchd aware of the new services:

$sudolaunchctlload-w/Library/LaunchDaemons/com.puppetlabs.puppet.plist$sudolaunchctlload-w/Library/LaunchDaemons/com.puppetlabs.puppetmaster.plist

Note that the les we provide here are responsible only for initial launch of a puppet master orpuppet agent at system start. How frequently each conducts a run is determined by Puppetsconguration, not the plists.

See the OS X launchctl man page for more information on how to stop, start, and manage launchdjobs.

Sign Node CerticatesIn an agent/master deployment, an admin must approve a certicate request for each agent node


before that node can fetch congurations. Agent nodes will request certicates the rst time theyattempt to run.

Periodically log into the puppet master server and run sudopuppetcertlist to viewoutstanding requests.Run sudopuppetcertsign to sign a request, or sudopuppetcertsign--all tosign all pending requests.

An agent node whose request has been signed on the master will run normally on its next attempt.

Change Puppet Masters Web ServerIn an agent/master deployment, you must congure the puppet master to run under a scalable webserver after you have done some reasonable testing. The default web server is simpler to congureand better for testing, but cannot support real-life workloads.

A replacement web server can be congured at any time, and does not aect the conguration ofagent nodes.

NextNow that you have installed and congured Puppet:

Learn to Use PuppetIf you have not used Puppet before, you should read the Learning Puppet series and experiment,either with the Learning Puppet VM or with your own machines. This series will introduce theconcepts underpinning Puppet, and will guide you through the process of writing Puppet code,using modules, and classifying nodes.

Install Optional SoftwareYou can extend and improve Puppet with other software:

Puppet Dashboard is an open-source report analyzer, node classier, and web GUI for Puppet.The stdlib module adds extra functions, an easier way to write custom facts, and more.For Puppet 2.6 and 2.7, the Hiera data lookup tool can help you separate your data from yourPuppet manifests and write cleaner code.User-submitted modules that solve common problems are available at the Puppet Forge. Searchhere rst before writing a new Puppet module from scratch; you can often nd something thatmatches your need or can be quickly hacked to do so.

Upgrading PuppetSince Puppet is likely managing your entire infrastructure, it should be upgraded with care. Thispage describes our recommendations for upgrading Puppet.

Upgrade IntentionallyIf you are using ensure=>latest on the Puppet package or running large-scale package upgradePuppet Documentation Upgrading Puppet 24/434

commands, you might receive a Puppet upgrade you were not expecting, especially if you subscribeto the Puppet Labs package repos, which always contain the most recent version of Puppet. Wehighly recommend avoiding unintentional upgrades. Although we try our best not to break things,especially between minor releases, Puppet has a lot of surface area, and bugs can and do slip in.

We recommend doing one of the following:

Maintain your own package repositories, test new Puppet releases in a dev environment, andonly introduce known-good versions into your production repo. Many sysadmins consider thisto be best practice for any mission-critical packages.Use Apts pinning feature or Yums versionlock plugin to lock Puppet to a specic version, andonly upgrade when you have a roll-out plan in place.

Apt Pinning ExampleYou can pin package versions by adding special .pref les to your systems

/etc/apt/preferences.d/ directory:

#/etc/apt/preferences.d/00-puppet.prefPackage:puppetpuppet-commonPin:version2.7*Pin-Priority:501

This pref le will lock puppet and puppet-common to the latest 2.7 release they will be upgradedwhen new 2.7.x releases are added, but will not jump a major version. It will also downgrade aPuppet 3 to Puppet 2.7 if the pin-priority of the Puppet 3 is less than 501 (the default is 500). Aseparate le could be used to pin puppetmaster and puppetmaster-common, or they could beadded to the package list.

Yum Versionlock ExampleUnfortunately, Yum versionlock is less exible than Apt pinning: it cant allow bugx upgrades, andcan only lock specic versions. For this reason, maintaining your own repo is a more attractiveoption for RPM systems.

$sudoyuminstallyum-versionlock$sudoyuminstallpuppet-2.7.19$sudoyumversionlockpuppet

These commands will install the versionlock plugin and lock Puppet to version 2.7.19. When youwant to upgrade, edit /etc/yum/pluginconf.d/versionlock.list and remove the Puppet lock,then run:

$sudoyuminstallpuppet-$sudoyumversionlockpuppet

Always Upgrade the Puppet Master FirstOlder agent nodes can get catalogs from a newer puppet master. The inverse is not always true.

Puppet Documentation Upgrading Puppet 25/434

Use More Care With Major ReleasesUpgrading to a new major release presents more possibility for things to go wrong, and werecommend extra caution.

Additional PrecautionsWhen upgrading to a new major release, we recommend the following:

Avoid jumping over a whole major release. If you are on Puppet 2.6, you should upgrade toPuppet 2.7 before going to 3.x, unless you are prepared to spend a lot of time xing yourmanifests without a net.Read the release notes, in particular any sections that refer to backwards-incompatiblechanges. Follow any specic recommendations for the new version. (Backwards-incompatiblechanges for Puppet 3.0.)If you tend to just upgrade everything for bug x releases, use a more conservative roll-out planfor major ones.

The denition of a major release has occasionally changed:

Versioning in Puppet 3 and LaterStarting with Puppet 3, there are three kinds of Puppet release:

Bug x releases increment the last segment of the version number. (E.g. 3.0.1.) They areintended to x bugs without introducing new features or breaking backwards compatibility.These releases should be safe to upgrade to, but you should test them anyway.Minor releases increment the middle segment of the version number. (E.g. 3.1.0.) They mayintroduce new features, but shouldnt break backwards compatibility.Major releases increment the rst segment of the version number. (E.g. 3.0.0.) They mayintentionally break backwards compatibility with previous versions, in addition to addingfeatures and xing bugs.

Versioning in Puppet 2.xIn the 2.x series:

Minor releases are not distinguished from bug x releases. A release that increments the lastsegment of the version number (e.g. 2.7.18) may or may not add new features or break smallareas of backwards compatibility, and you must check the release notes to nd out.Major releases increment the second segment of the version number. (E.g. 2.7.0.) They mayintentionally break backwards compatibility with previous versions, in addition to addingfeatures and xing bugs.

Roll Out In StagesWhen upgrading, especially between major versions, we recommend rolling out the upgrade instages. Use one of the following three options:

Option 1: Spin Up Temporary Puppet Master, or Cull a Master From Your Load Balancer PoolThe best approach is to spin up a temporary puppet master, then point a few test nodes at it.

Puppet Documentation Upgrading Puppet 26/434

If you run a multi-master site and can pull a puppet master out of the load balancer pool fortemporary test duty, do that. Upgrade Puppet on it, and follow steps 5-10 below.If you run a multi-master site and use Puppet to congure new puppet masters, you can alsospin up a new node and use Puppet to congure it. Upgrade Puppet on it, and follow steps 5-10below.Otherwise, follow steps 1-10 below.

Option 2: Run Two Instances of Puppet Master at OnceYou can also run a second instance of puppet master on your production puppet master server,using the same modules, manifests, data, ENC, and SSL conguration.

1. Provision a new node and install Puppet on it.2. Set its server setting to the existing puppet master, and use puppetagent--test to request a

certicate; sign the cert.3. Provision the new puppet master by checking out your latest modules, manifests, and data from

version control. If you use an ENC and/or PuppetDB or storecongs, congure the master to talkto those services.

4. In a terminal window, run puppetmaster--no-daemonize--verbose . This will run a puppetmaster in the foreground so you can easily see log messages and warnings. Use care to limitconcurrent checkins on your test nodes; this WEBrick puppet master cannot handle sustainedload.

5. Choose a subset of your nodes to test with the new master, or spin up new nodes. UpgradePuppet to the new version on them, and change their server setting to point to the temporarypuppet master.

6. Trigger a puppetagent--test run on every test node, so you can see log messages in theforeground. Look for changes to their resources; if you see anything you didnt expect,investigate it. If something seems dangerous and you cant gure it out, you may want to post tothe Puppet users list or ask other users in #puppet on Freenode.

7. Check the log messages in the terminal window or log le on your puppet master. Look forwarnings and deprecation notices.

8. Check the actual congurations of your test nodes. Make sure everything is still working asexpected.

9. Repeat steps 5-8 with more test nodes if youre still not sure.10. Revert the server setting on all test nodes. Decommission the temporary puppet master.

Upgrade your production puppet master(s) by stopping their web server, upgrading the puppetpackage, and restarting their web server. Upgrade all your production nodes. (Most packagingsystems allow you to use Puppet to upgrade Puppet.)

Note: This is generally reliable, but has a small chance of yielding inaccurate results. (Thisproblem would require a major version to remove a given code path but not fail hard whenattempting to access the code path; we are not currently aware of a situation that wouldcause that.)

1. Download a tarball of the Puppet source code for the new version. Unzip it somewhere otherthan your normal Ruby library directory. (tar-xfpuppet- )

2. Open a root shell, which should stay open for the duration of this test. (sudo-i )3. Change directory into the source tarball. (cdpuppet- )4. Add the lib directory to your shells RUBYLIB. (exportRUBYLIB=$(pwd)/lib:$RUBYLIB )5. Run puppetmaster--no-daemonize--verbose--port8141 . This will run a puppet master on

a dierent port in the foreground so you can easily see log messages and warnings. Use care toPuppet Documentation Upgrading Puppet 27/434

Option 3: Upgrade Master and Roll Back if NeededFor minor and bug x releases, you can often take a simpler path. This is not universallyrecommended, but many users do it and survive.

Setting Up PuppetOnce Puppet is installed, learn how to set it up for initial operation.

Open Firewall Ports On Server and Agent NodeIn order for the puppet master server to centrally manage agent nodes, you may need to open port8140 for incoming tcp connections on the puppet master. Consult your rewall documentation formore details.

limit concurrent checkins on your test nodes; this WEBrick puppet master cannot handlesustained load.

6. Choose a subset of your nodes to test with the new master, or spin up new nodes. UpgradePuppet to the new version on them, and change their port setting to point to 8141.


8. Check the log messages in the terminal window on your puppet master. Look for warnings anddeprecation notices.

9. Check the actual congurations of your test nodes. Make sure everything is still working asexpected.

10. Repeat steps 6-9 with more test nodes if youre still not sure.11. Revert the port setting on all test nodes. Kill the temporary puppet master process, delete the

temporary copy of the puppet source. Upgrade your production puppet master(s) by stoppingtheir web server, upgrading the puppet package, and restarting their web server. Upgrade all ofyour production nodes. (Most packaging systems allow you to use Puppet to upgrade Puppet.)

1. Disable puppet agent on all of your production nodes. This is best done with MCollective and thepuppetd plugin, which can stop the agent on all nodes in a matter of seconds.

2. Upgrade your puppet master(s) to the new version of Puppet by stopping their web server,upgrading the puppet package, and restarting their web server.

3. Choose a subset of your nodes to test with the new master, or spin up new nodes. UpgradePuppet to the new version on them.


5. Check your puppet masters log les. Look for warnings and deprecation notices.6. Check the actual congurations of your test nodes. Make sure everything is still working as

expected.7. Repeat steps 3-6 with more test nodes if youre still not sure.8. Do one of the following:

Upgrade Puppet and reactivate puppet agent on all of your production nodes.Downgrade Puppet to a known-good version on your Puppet master and any test nodes.

Puppet Documentation Setting Up Puppet 28/434

Conguration FilesThe main conguration le for Puppet is /etc/puppet/puppet.conf . A package based installationle will have created this le automatically. Unlisted settings have reasonable defaults. To see allthe possible values, you may run:

$puppet--genconfig

Congure DNS (Optional)The puppet agent looks for a server named puppet by default. If you choose, you can set up apuppet DNS CNAME record to avoid having to specify your puppet master hostname in theconguration of each agent node.

If you have local DNS zone les, you can add a CNAME record pointing to the server machine in theappropriate zone le.

puppetINCNAMEcrabcake.picnic.edu.

See the book DNS and Bind by Cricket Liu et al if you need help with CNAME records. After addingthe CNAME record, restart your name server. You can also add a host entry in the /etc/hosts leon both the server and agent nodes.

For the server:

127.0.0.1localhost.localdomainlocalhostpuppet

For the agent nodes:

192.168.1.67crabcake.picnic.educrabcakepuppet

NOTE: If you can ping the server by the name puppet but Syslog (for example /var/log/messages )on the agent nodes still has entries stating the puppet agent cannot connect to the server, verifyport 8140 is open on the server.

Puppet Language SetupCreate Your Site ManifestPuppet is a declarative system, so it does not make much sense to speak of executing Puppetprograms or scripts. Instead, we choose to use the word manifest to describe our Puppet code, andwe speak of applying those manifests to the managed systems. Thus, a manifest is a text documentwritten in the Puppet language and meant to describe and result in a desired conguration.

Puppet assumes that you will have one central manifest capable of conguring an entire site, whichwe call the site manifest. You could have multiple, separate site manifests if you wanted, though ifPuppet Documentation Setting Up Puppet 29/434

doing this each of them would need their own puppet servers. Individual system dierences can beseparated out, node by node, in the site manifest.

Puppet will start with /etc/puppet/manifests/site.pp as the primary manifest, so create/etc/puppet/manifests and add your manifest, along with any les it includes, to that directory. Itis highly recommended that you use some form of version control (git, svn, etc) to keep track ofchanges to manifests.

Example ManifestThe site manifest can do as little or as much as you want. A good starting point is a manifest thatmakes sure that your sudoers le has the appropriate permissions:

#site.ppfile{"/etc/sudoers":owner=>root,group=>root,mode=>440}

For more information on how to create the site manifest, see the Manifests chapter of the LearningPuppet tutorial.

Start the Central DaemonMost sites should only need one puppet master server. Puppet Labs will be publishing a documentdescribing best practices for scale-out and failover, though there are various ways to addresshandling in larger infrastructures. For now, well explain how to work with the one server, andothers can be added as needed.

First, decide which machine will be the central server; this is where puppet master will be run.

The best way to start any daemon is using the local servers service management system, often inthe form of init scripts.

If youre running on Red Hat, CentOS, Fedora, Debian, Ubuntu, or Solaris, the OS package alreadycontains a suitable init script. If you dont have one, you can either create your own using anexisting init script as an example, or simply run without one (though this is not advisable forproduction environments).

It is also neccessary to create the puppet user and group that the daemon will use. Either createthese manually, or start the daemon with the --mkusers ag to create them.

#puppetmaster--mkusers

Starting the puppet daemon will automatically create all necessary certicates, directories, and les.

NOTE: To enable the daemon to also function as a le server, so that agent nodes can copy lesfrom it, create a leserver conguration le and restart puppet master.

Verifying InstallationPuppet Documentation Setting Up Puppet 30/434

To verify that your daemon is working as expected, pick a single agent node to use as a testbed.Once Puppet is installed on that machine, run the agent against the central server to verify thateverything is working appropriately. You should start the agent in verbose mode the rst time andwith the --waitforcert ag enabled:

#puppetagent--servermyserver.example.com--waitforcert60--test

Adding the test ag causes the puppet agent to stay in the foreground; print extra output; onlyrun once, then exit; and to exit immediately if the puppet master fails to compile the congurationcatalog (by default, puppet agent will use a cached conguration if there is a problem with theremote manifests).

In running the agent, you should see the message:

info:Requestingcertificatewarning:peercertificatewon'tbeverifiedinthisSSLsessionnotice:Didnotreceivecertificate

INFO: This message will repeat every 60 seconds with the above command.

This is normal, since your server is not auto-signing certicates as a security precaution.

On your server, list the waiting certicates:

#puppetcert--list

You should see the name of the test agent node. Now go ahead and sign the certicate:

#puppetcert--signmytestagent.example.com

Within 60 seconds, your test agent should receive its certicate from the server, receive itsconguration, apply it locally, and exit normally.

NOTE: By default, puppet agent runs with a waitforcert of ve minutes; set the value to 0 to disablethis wait-polling period entirely.

Scaling your InstallationFor more about how to tune Puppet for large environments, see Scaling Puppet.

Conguring PuppetPuppets behavior can be customized with a rather large collection of settings. Most of these can besafely ignored, but youll almost denitely have to modify some of them.

This document describes how Puppets conguration settings work, and describes all of Puppets

Puppet Documentation Conguring Puppet 31/434

auxiliary cong les.

Puppets SettingsPuppet is able to automatically generate a reference of all its cong settings (puppetdoc--referenceconfiguration ), and the documentation site includes archived references for everyrecent version of Puppet. You will generally want to consult the the most recent stable versionsreference.

When retrieving the value for a given setting, Puppet follows a simple lookup path, stopping at therst value it nds. In order, it will check:

Values specied on the command lineValues in environment blocks in puppet.confValues in run mode blocks in puppet.confValues in the main block of puppet.confThe default values

The settings youll have to interact with will vary a lot, depending on what youre doing with Puppet.But at the least, you should get familiar with the following:

certname The locally unique name for this node. If you arent using DNS names to identifyyour nodes, youll need to set it yourself.

server The puppet master server to request congurations from. If your puppet masterserver isnt reachable at the default hostname of puppet , youll need to set this yourself.

pluginsync Whether to use plugins from modules. Most users should set this to true on allagent nodes.

report Whether to send reports to the puppet master. Most users should set this to true on allagent nodes.

reports On the puppet master, which report handler(s) to use.modulepath The search path for Puppet modules. Defaults to/etc/puppet/modules:/usr/share/puppet/modules .environment On agent nodes, the environment to request conguration in.node_terminus How puppet master should get node denitions; if you use an ENC, youllneed to set this to exec on the master (or on all nodes if running in a standalonearrangement).

external_nodes The script to run for node denitions (if node_terminus is set to exec).confdir One of Puppets main working directories, which usually contains cong les,manifests, modules, and certicates.

vardir Puppets other main working directory, which usually contains cached data andcongurations, reports, and le backups.

puppet.confPuppet Documentation Conguring Puppet 32/434

Puppets main cong le is puppet.conf , which is located in Puppets confdir .

Finding puppet.confPERSONAL CONFDIRS

When Puppet is not running as root (*nix) or not running with elevated privileges (Windows), itwill read its cong les from the .puppet directory in the current users home directory.

*NIX SYSTEMSPuppet Enterprises confdir is /etc/puppetlabs/puppet .Most open source Puppet distributions use /etc/puppet as Puppets confdir.If you are unsure where the confdir is, run sudopuppetagent--configprintconfdir tolocate it.

WINDOWS SYSTEMSOn Windows, Puppet Enterprise and open source Puppet use the same confdir.

On Windows 2003, Puppets confdir is %ALLUSERSPROFILE%\PuppetLabs\puppet\etc . This isusually located on disk at C:\DocumentsandSettings\AllUsers\ApplicationData\PuppetLabs\puppet\etc .On Windows 7 and Windows 2008, Puppets confdir is %PROGRAMDATA%\PuppetLabs\puppet\etc .This is usually located on disk at C:\ProgramData\PuppetLabs\puppet\etc .

File Formatpuppet.conf uses an INI-like format, with [configblocks] containing indented groups ofsetting=value lines. Comment lines #startwithanoctothorpe ; partial-line comments arenot allowed.

You can interpolate the value of a setting by using its name as a $variable . (Note that$environment has special behavior: most of the Puppet applications will interpolate their ownenvironment, but puppet master will use the environment of the agent node it is serving.)

If a setting has multiple values, they should be a comma-separated list. Path-type settings madeup of multiple directories should use the system path separator (colon, on most Unices).

Finally, for settings that accept only a single le or directory, you can set the owner, group, and/ormode by putting their desired states in curly braces after the value.

Putting that all together:

#ablock:[main]#setting=valuepairs:server=master.example.com

Note: On Windows systems, the puppet.conf le is allowed to use Windows-style CRLF lineendings as well as *nix-style LF line endings.


certname=005056c00008.localcloud.example.com

#variableinterpolation:rundir=$vardir/runmodulepath=/etc/puppet/modules/$environment:/usr/share/puppet/modules[master]#alist:reports=store,http

#amulti-directorymodulepath:modulepath=/etc/puppet/modules:/usr/share/puppet/modules

#settingownerandmodeforadirectory:vardir=/Volumes/zfs/vardir{owner=puppet,mode=644}

Cong BlocksSettings in dierent cong blocks take eect under varying conditions. Settings in a more specicblock can override those in a less specic block, as per the lookup path described above.THE [MAIN] BLOCKThe [main] cong block is the least specic. Settings here are always eective, unless overriddenby a more specic block.

[AGENT] , [MASTER] , AND [USER] BLOCKSThese three blocks correspond to Puppets run modes. Settings in [agent] will only be used bypuppet agent; settings in [master] will be used by puppet master and puppet cert; and settings in

[user] will only be used by puppet apply. The faces subcommands introduced in Puppet 2.7default to the user run mode, but their mode can be changed at run time with the --mode option.Note that not every setting makes sense for every run mode, but specifying a setting in a blockwhere it is irrelevant has no observable eect.NOTES ON PUPPET 0.25.5 AND OLDERPrior to Puppet 2.6, blocks were assigned by application name rather than by run mode; e.g.

[puppetd] , [puppetmasterd] , [puppet] , and [puppetca] . Although these names still work, theiruse is deprecated, and they interact poorly with the modern run mode blocks. If you have an oldercong le and are using Puppet 2.6 or later, you should consider changing [puppetd] to [agent] ,

[puppet] to [user] , and combining [puppetmasterd] and [puppetca] into [master] .

PER-ENVIRONMENT BLOCKSBlocks named for environments are the most specic, and can override settings in the run modeblocks. Only a small number of settings (specically: modulepath,manifest,manifestdir, and

templatedir ) can be set in a per-environment block; any other settings will be ignored and readfrom a run mode or main block.

Like with the $environment variable, puppet master treats environments dierently from the otherrun modes: instead of using the block corresponding to its own environment setting, it will use theblock corresponding to each agent nodes environment. The puppet masters own environmentsetting is eectively inert.

You may not create environments named main , master , agent , or user , as these are already taken


by the primary cong blocks.

Command-Line OptionsYou can override any cong setting at runtime by specifying it as a command-line option to almostany Puppet application. (Puppet doc is the main exception.)

Boolean settings are handled a little dierently: use a bare option for a true value, and add a prexof no- for false:

#Equivalenttolisten=true:$puppetagent--listen#Equivalenttolisten=false:$puppetagent--no-listen

For non-boolean settings, just follow the option with the desired value:

$puppetagent--certnamemagpie.example.com#Anequalssignisoptional:$puppetagent--certname=magpie.example.com

Inspecting SettingsPuppet agent, apply, and master all accept the --configprint option, which makesthem print their local value of the requested setting and exit. In Puppet 2.7, you can also use the

puppetconfigprint action, and view values in dierent run modes with the --modeag. Either way, you can view all settings by passing all instead of a specic setting.

$puppetmaster--configprintmodulepath#or:$puppetconfigprintmodulepath--modemaster

/etc/puppet/modules:/usr/share/puppet/modules

Puppet agent, apply, and master also accept a --genconfig option, which behaves similarly to --configprintall but outputs a complete puppet.conf le, with descriptive comments for eachsetting, default values explicitly declared, and settings irrelevant to the requested run modecommented out. Having the documentation inline and the default values laid out explicitly can behelpful for setting up your cong le, or it can be noisy and hard to work with; it comes down topersonal taste.

You can also inspect settings for specic environments with the --environment option:

$puppetagent--environmenttesting--configprintmodulepath/etc/puppet/testing/modules:/usr/share/puppet/modules

(As implied above, this doesnt work in the master run mode, since the master eectively has no


environment.)

Other conguration lesIn addition to the main conguration le, there are ve special-purpose cong les you might needto interact with: auth.conf , fileserver.conf , tagmail.conf , autosign.conf , and device.conf .

auth.conf

See the auth.conf documentation for more details about this le.

Access to Puppets HTTP API is congured in auth.conf , the location of which is determined by therest_authconfig setting. (Default: /etc/puppet/auth.conf .) It consists of a series of ACL stanzas,and behaves quite dierently from puppet.conf .

#Exampleauth.conf:

path/authtrueenvironmentoverrideallowmagpie.example.com

path/certificate_statusauthtrueenvironmentproductionallowmagpie.example.com

path/factsmethodsaveauthtrueallowmagpie.example.com

path/factsauthtruemethodfind,searchallowmagpie.example.com,dashboard.example.com,finch.example.com

puppetdb.conf

The puppetdb.conf le contains the hostname and port of the PuppetDB server. It is only used ifyou are using PuppetDB and have connected your puppet master to it.

This le uses the same ini-like format as puppet.conf , but only uses a [main] block and only hastwo settings (server and port ):

[main]server=puppetdb.example.comport=8081

See the PuppetDB manual for more information.

routes.yaml


This le overrides conguration settings involving indirector termini, and allows termini to be set ingreater detail than puppet.conf allows.

This le should be a YAML hash. Each top level key should be the name of a run mode (master,agent, user), and its value should be another hash. Each key of these second-level hashes shouldbe the name of an indirection, and its value should be another hash. The only keys allowed in thesethird-level hashes are terminus and cache . The value of each of these keys should be the name ofa valid terminus for the indirection.

Example:

---master:facts:terminus:puppetdbcache:yaml

autosign.conf

The autosign.conf le (located at /etc/puppet/autosign.conf by default, and congurable withthe autosign setting) is a list of certnames or certname globs (one per line) whose certicaterequests will automatically be signed.

rebuilt.example.com*.scratch.example.com*.local

Note that certname globs do not function as normal globs: an asterisk can only represent one ormore subdomains at the front of a certname that resembles a fully-qualied domain name. (That is,if your certnames dont look like FQDNs, you cant use autosign.conf to full eect.

As any host can provide any certname, autosigning should only be used with great care, and only insituations where you essentially trust any computer able to connect to the puppet master.

device.conf

Puppet device, added in Puppet 2.7, congures network hardware using a catalog downloadedfrom the puppet master; in order to function, it requires that the relevant devices be congured in

/etc/puppet/device.conf (congurable with the deviceconfig setting).

device.conf is organized in INI-like blocks, with one block per device:

[devicecertname]typeurl[router6.example.com]typeciscourlssh://admin:[email protected]


fileserver.conf

By default, fileserver.conf isnt necessary, provided that you only need to serve les frommodules. If you want to create additional leserver mount points, you can do so in

/etc/puppet/fileserver.conf (or whatever is set in the fileserverconfig setting).

fileserver.conf consists of a collection of mount-point stanzas, and looks like a hybrid ofpuppet.conf and auth.conf :

#Filesinthe/path/to/filesdirectorywillbeserved#atpuppet:///mount_point/.[mount_point]path/path/to/filesallow*.example.comdeny*.wireless.example.com

See the le serving documentation for more details.

Note that certname globs do not function as normal globs: an asterisk can only represent one ormore subdomains at the front of a certname that resembles a fully-qualied domain name. (That is,if your certnames dont look like FQDNs, you cant use autosign.conf to full eect.

tagmail.conf

Your puppet master server can send targeted emails to dierent admin users whenever certainresources are changed. This requires that you:

Set report=true on your agent nodesSet reports=tagmail on the puppet master (the reports setting accepts a list, so you canenable any number of reports)Set the reportfrom email address and either the smtpserver or sendmail setting on the puppetmasterCreate a tagmail.conf le at the location specied in the tagmap setting

More details are available at the tagmail report reference.

The tagmail.conf le (located at /etc/puppet/tagmail.conf by default, and congurable with thetagmap setting) is list of lines, each of which consists of:

A comma-separated list of tags and !negated tags; valid tags include:Explicit tagsClass namesallAny valid Puppet log level (debug , info , notice , warning , err , alert , emerg , crit , or

verbose )

A colonA comma-separated list of email addresses


The list of tags on a line builds the set of resources whose messages will be included in the mailing;each additional tag adds to the set, and each !negated tag subtracts from the set.

So, for example:

all:[email protected],!mailserver:[email protected],crit:[email protected],[email protected],[email protected]

This tagmail.conf le will mail any resource events tagged with webserver but not withmailserver to the httpadmins group; any emergency or critical events to to James, Zach, and Ben,and all events to the log-archive group.

Language Guide

The purpose of Puppets language is to make it easy to specify the resources you need to manageon the machines youre managing.

This guide will show you how the language works, going through some basic concepts.Understanding the Puppet language is key, as its the main driver of how you tell your Puppetmanaged machines what to do.

Ready To Dive In?Puppet language is really relatively simple compared to many programming languages. As you arereading over this guide, it may also be helpful to look over various Puppet modules people havealready written. Complete real world examples can serve as a great introduction to Puppet. See theModules page for more information and some links to list of community developed Puppet content.

Language Feature by ReleaseFeature 0.24.x 0.25.x 2.6.x 2.7.x 3.x

Plusignment operator (+>) X X X X X

Multiple Resource relationships X X X X X

Class Inheritance Overrides X X X X X

Appending to Variables (+=) X X X X X

Important NoteThis page has been superseded by the Puppet 2.7 reference manuals language reference.We hope you nd the new version more complete and easier to use! Find the new versionhere, and use the links in its left sidebar to navigate between pages. If you dont know whichlanguage feature you are looking for, use the visual language index.

Puppet Documentation Language Guide 39/434

Class names starting with 0-9 X X X X X

Multi-line C-style comments X X X X X

Node regular expressions X X X X

Expressions in Variables X X X X

RegExes in conditionals X X X X

Elsif in conditionals X X X

Chaining Resources X X X

Hashes X X X

Parameterised Class X X X

Run Stages X X X

The in syntax X X X

The unless syntax X

Acceptable Characters in NamesVariable names can include alphanumeric characters and underscores, and are case-sensitive.Hyphens are not allowed; although some Puppet versions permit them, this is now considered abug.

Class names, module names, and the names of dened and custom resource types should berestricted to lowercase alphanumeric characters and underscores, and should begin with alowercase letter; that is, they should match the expression [a-z][a-z0-9_]* . Although somenames that violate these restrictions currently work, using them is not recommended. Hyphens arevery strongly discouraged, and in most versions of Puppet will cause variables inside the class to beunavailable elsewhere.

Class and dened resource type names can use :: as a namespace separator, which is bothsemantically useful and a means of directing the behavior of the module autoloader. The nalsegment of a qualied variable name must obey the restrictions on variable names, and thepreceding segments must obey the restrictions on class names.

Parameters used in parameterized classes and dened resource types can include alphanumericcharacters and underscores, cannot begin with an underscore, and are case-sensitive. In practice,they should be treated as though they were under the same restrictions as class names in order tomaximize future compatibility.

There is no practical restriction on resource names.

Any word that the syntax uses for special meaning is a reserved word, meaning you cannot use itfor variable or type names. Words like true , define , inherits , and class are all reserved. If youever need to use a reserved word as a value, be sure to quote it.

ResourcesPuppet Documentation Language Guide 40/434

The fundamental unit of modelling in Puppet is a resource. Resources describe some aspect of asystem; it might be a le, a service, a package, or perhaps even a custom resource that you havedeveloped. Well show later how resources can be aggregated together with denes and classes,and even show how to organize things with modules, but resources are what we should start withrst.

Each resource has a type, a title, and a list of attributes each resource in Puppet can supportvarious attributes, though many of them will have reasonable defaults and you wont have tospecify all of them.

You can nd all of the supported resource types, their valid attributes, and documentation for all ofit in the References.

Lets get started. Heres a simple example of a resource in Puppet, where we are describing thepermissions and ownership of a le:

file{'/etc/passwd':owner=>'root',group=>'root',mode=>'0644',}

Any machine on which this snippet is executed will use it to verify that the passwd le is conguredas specied.

The eld before the colon is the resources title, which must be unique and can be used to refer tothe resource in other parts of the Puppet conguration. Following the title are a series of attributesand their values.

Most resources have an attribute (often called simply name ) whose value will default to the title ifyou dont specify it. (Internally, this is called the namevar.) For the file type, the path will defaultto the title. A resources namevar value almost always has to be unique. (The exec and notifytypes are the exceptions.)

For simple resources that dont vary much, leaving out the name or path and falling back to the titleis sucient. But for resources with long names, or in cases where lenames dier betweenoperating systems, it makes more sense to choose a symbolic title:

file{'sshdconfig':path=>$operatingsystem?{solaris=>'/usr/local/etc/ssh/sshd_config',default=>'/etc/ssh/sshd_config',},owner=>'root',group=>'root',mode=>'0644',}

This makes it easy to refer to the le resource elsewhere in our conguration, since the title isalways the same.


For instance, lets add a service that depends on the le:

service{'sshd':subscribe=>File['sshdconfig'],}

This will cause the sshd service to get restarted when the sshdconfig le changes. Youll noticethat when we reference a resource we capitalise the name of the resource, for example

File[sshdconfig] . When you see an uppercase resource type, thats always a reference. Alowercase version is a declaration. Since resources can only be declared once, repeating the samedeclaration twice will cause an error. This is an important feature of Puppet that makes sure yourconguration is well modelled.

What happens if our resource depends on multiple resources? From Puppet version 0.24.6 you canspecify multiple relationships like so:

service{'sshd':require=>File['sshdconfig','sshconfig','authorized_keys']}

MetaparametersIn addition to the attributes specic to each Resource Type Puppet also has global attributes calledmetaparameters. Metaparameters are parameters that work with any resource type.

In the examples in the section above we used two metaparameters, subscribe and require , bothof which build relationships between resources. You can see the full list of all metaparameters inthe Metaparameter Reference, though well point out additional ones we use as we continue theguide.

Resource DefaultsSometimes you will need to specify a default parameter value for a set of resources; Puppetprovides a syntax for doing this, using a capitalized resource specication that has no title. Forinstance, in the example below, well set the default path for all execution of commmands:

Exec{path=>'/usr/bin:/bin:/usr/sbin:/sbin'}exec{'echothisworks':}

The rst statement in this snippet provides a default value for exec resources; Exec resourcesrequire either fully qualied paths or a path in which to look for the executable. Individualresources can still override this path when needed, but this saves typing. This way you can specify asingle default path for your entire conguration, and then override that value as necessary.

Defaults work with any resource type in Puppet.

Defaults are not global they only aect the current scope and scopes below the current one. Ifyou want a default setting to aect your entire conguration, your only choice currently is to specifythem outside of any class. Well mention classes in the next section.Puppet Documentation Language Guide 42/434

Resource CollectionsAggregation is a powerful concept in Puppet. There are two ways to combine multiple resourcesinto one easier to use resource: Classes and dened resource types. Classes model fundamentalaspects of nodes, they say this node IS a webserver or this node is one of these. In programmingterminology classes are singletons they only ever get evaluated once per node.

Dened resource types, on the other hand, can be reused many times on the same node. Theyessentially work as if you created your own Puppet type just by using the language. They are meantto be evaluated multiple times, with dierent inputs each time. This means you can pass variablevalues into the denes.

Both classes and denes are very useful and you should make use of them when building out yourpuppet infrastructure.CLASSESClasses are introduced with the class keyword, and their contents are wrapped in curly braces. Thefollowing simple example creates a simple class that manages two separate les:

classunix{file{'/etc/passwd':owner=>'root',group=>'root',mode=>'0644';'/etc/shadow':owner=>'root',group=>'root',mode=>'0440';}}

Youll notice we introduced some shorthand here. This is the same as saying:

classunix{file{'/etc/passwd':owner=>'root',group=>'root',mode=>'0644',}file{'/etc/shadow':owner=>'root',group=>'root',mode=>'0440',}}

Classes also support a simple form of object inheritance. For those not acquainted withprogramming terms, this means that we can extend the functionality of the previous class withoutcopy/pasting the entire class. Inheritance allows subclasses to override resource settings declaredin parent classes. A class can only inherit from one other class, not more than one. In programmingterms, this is called single inheritance.


classfreebsdinheritsunix{File['/etc/passwd']{group=>'wheel'}File['/etc/shadow']{group=>'wheel'}}

If we needed to undo some logic specied in a parent class, we can use undef like so:

classfreebsdinheritsunix{File['/etc/passwd']{group=>undef}}

In the above example, nodes which include the unix class will have the password les group set toroot , while nodes including freebsd would have the password le group ownership leftunmodied.

In Puppet version 0.24.6 and higher, you can specify multiple overrides like so:

classfreebsdinheritsunix{File['/etc/passwd','/etc/shadow']{group=>'wheel'}}

There are other ways to use inheritance. In Puppet 0.23.1 and higher, its possible to add values toresource parameters using the +> (plusignment) operator:

classapache{service{'apache':require=>Package['httpd']}}

classapache-sslinheritsapache{#hostcertificateisrequiredforSSLtofunctionService['apache']{require+>File['apache.pem']}}

The above example makes the service resource in the second class require all the packages in therst, as well as the apache.pem le.

To append multiple requires, use array brackets and commas:

classapache{service{'apache':require=>Package['httpd']}}

classapache-sslinheritsapache{Service['apache']{require+>[File['apache.pem'],File['/etc/httpd/conf/httpd.conf']]}}

The above would make the require parameter in the apache-ssl class equal to


[Package['httpd'],File['apache.pem'],File['/etc/httpd/conf/httpd.conf']]

Like resources, you can also create relationships between classes with require, like so:

classapache{service{'apache':require=>Class['squid']}}

The above example uses the require metaparameter to make the apache class dependent on thesquid class.

In Puppet version 0.24.6 and higher, you can specify multiple relationships like so:

classapache{service{'apache':require=>Class['squid','xml','jakarta'],}}

The require metaparameter does not implicitly declare a class; this means it can be used multipletimes and is compatible with parameterized classes, but you must make sure you actually declarethe class youre requiring at some point.

Puppet also has a require function, which can be used inside class denitions and which doesimplicitly declare a class, in the same way that the include function does. This function doesnt playwell with parameterized classes. The require function is largely unnecessary, as class-leveldependencies can be managed in other ways.PARAMETERISED CLASSESIn Puppet release 2.6.0 and later, classes are extended to allow the passing of parameters intoclasses.

To create a class with parameters you can now specify:

classapache($version){...classcontents...}

Classes with parameters are not declared using the include function but with an alternate syntax

Date post:	27-Dec-2015
Category:	Documents
Upload:	pdog
View:	131 times
Download:	13 times