puppetmanual.pdf

Puppet Documentation(Generated on July 18, 2012, from git revision cbae724238b675a49acc9024632376db3d15621e)

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

Part one: Serverless PuppetResources and the RAL Learn about the fundamental building blocks of system conguration.Manifests Start controlling your system by writing actual Puppet code.Ordering Learn about dependencies and refresh events, manage the relationships betweenresources, and discover the fundamental Puppet design pattern.Variables, Conditionals, and Facts Make your manifests versatile by reading systeminformation.Modules and Classes (Part One) Start building your manifests into self-contained modules.Templates Use ERB to make your cong les as exible as your Puppet manifests.Parameterized Classes (Modules, Part Two) Learn how to pass parameters to classes and makeyour modules more adaptable.Dened Types Model repeatable chunks of conguration by grouping basic resources intosuper-resources.

Part two: Master/Agent Puppet

Puppet Documentation Drive-Thru 2/391

Preparing an Agent VM Prepare your tools for the next few chapters with our step-by-stepwalkthrough.Basic Agent/Master Puppet Tour the agent/master workow: sign an agent nodes certicate,pick which classes a node will get, and pull and apply a catalog.More coming soon!

Reference ShelfCurated GuidesGet detailed information about cong les, APIs, and the Puppet language.

REST API reference of api accessible resourcesPuppet Language Guide all the language detailsPuppet 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 ConguringGet Puppet up and running at your site.Puppet Documentation Reference Shelf 3/391

An Introduction to PuppetSupported PlatformsInstalling Puppet from packages, source, or gemsConguring 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 Enterprise 2.5 andPuppet 2.7.

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 adding new puppet masters to a single-master siteScaling With Passenger for Puppet 0.24.6 and laterScaling With Mongrel for older versions of Puppet

Puppet Documentation Reference Shelf 4/391

Advanced FeaturesGo 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 INTERFACESREST 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)

Puppet Documentation Other Resources 5/391

ToolsThis guide covers the major tools that comprise Puppet.

Single binaryFrom version 2.6.0 and onwards all the Puppet functions are also available via a single Puppetbinary, in the style of git.

List of binary changes:

puppetmasterd puppet masterpuppetd puppet agentpuppet puppet applypuppetca puppet certralsh puppet resourcepuppetrun puppet kickpuppetqd puppet queuelebucket puppet lebucketpuppetdoc puppet docpi 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.

Puppet Documentation Tools 6/391

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

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 in

Puppet Documentation Tools 7/391

HTML, 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:

>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 Documentation Tools 8/391

Puppet 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 getPuppet Documentation Introduction to Puppet 9/391

done 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 [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:

Puppet Documentation Introduction to Puppet 10/391

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 initialinstallation, 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 BasedPuppet Documentation Introduction to Puppet 11/391

RESOURCE 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 needsto 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 Documentation Introduction to Puppet 12/391

Supported PlatformsFor information about Puppet Enterprises system requirements, see here.

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 and 2.7 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.4 (Tiger) and higherOracle Solaris, version 10 and higherAIX, 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 Documentation Supported Platforms 13/391

Puppet requires Ruby. Certain versions of Ruby work better with Puppet than others. Run ruby--version to check the version of Ruby on your system.

Ruby version Puppet 2.6 Puppet 2.7 Puppet 3.x

1.8.5* Supported Supported Supported

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

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; however:

Ruby 1.8.6 and 1.8.1 have occasionally been known to work for agent nodes, but should neverbe used on a puppet master server.Ruby 1.9.2 may work with Puppet 3.0, but there are several known issues, and Puppet Labs doesnot perform automated testing on it.Ruby 1.9.2 and 1.9.3 have major known issues with Puppet 2.7, and should be avoided. They willnot work at all with Puppet 2.6.Ruby 1.9.0 and 1.9.1 should always be avoided with all Puppet versions past and future.

PrerequisitesPuppet has a very small number of external dependencies, which are also developed by PuppetLabs:

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, Ruby 1.8.7 generally gives betterperformance and memory use.

Puppet Documentation Supported Platforms 14/391

Dependency Puppet 2.x Puppet 3.x

Facter Required Required

Hiera Optional Required

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

base64cgidigest/md5etcleutilsipaddropensslstrscansysloguriwebrickwebrick/httpsxmlrpc

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:

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

Puppet Documentation Installing Puppet 15/391

Agent/masterAgent nodes pull their congurations from a puppet master server. Admins must manage nodecerticates, 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 before installingon any agents. The master should be a dedicated machine with a fast processor, lots of RAM, anda fast disk.StandaloneEvery node compiles its own conguration from manifests. Admins must regularly sync Puppetmanifests 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 PuppetThe 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 6

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


Scientic 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 5 Lenny (previous stable release)Debian Wheezy (current testing distribution)


Debian Sid (current unstable distribution)Ubuntu 12.04 LTS Precise Pangolin (also supported by Puppet Enterprise)Ubuntu 11.10 Oneiric OcelotUbuntu 11.04 Natty NarwhalUbuntu 10.10 Maverick MeerkatUbuntu 10.04 LTS Lucid Lynx (also supported by Puppet Enterprise)Ubuntu 8.04 LTS Hardy Heron

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-capacityPuppet Documentation Installing Puppet 18/391

web 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 16Fedora 15

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 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 NODES


On 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 Puppet package

2. INSTALL FACTERMount the Facter disk image, and run the installer package it contains.3. INSTALL PUPPETMount the Puppet disk image, and run the installer package it contains.4. 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, usingthese as 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. To ndexamples to modify, see the conf/ directory in the Puppet source.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.

2. DOWNLOAD PUPPET AND FACTERDownload 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. To ndexamples to modify, see the conf/ directory in the Puppet source.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 .Puppet Documentation Installing Puppet 22/391

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

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.


WITH CRONStandalone 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'

Sign Node CerticatesIn an agent/master deployment, an admin must approve a certicate request for each agent nodebefore 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 thePuppet Documentation Installing Puppet 24/391

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

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.

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.

Puppet Documentation Setting Up Puppet 25/391

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 ifdoing 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 tutorials listed in the GettingStarted section.

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 InstallationTo 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.domain.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 conguration


catalog (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.domain.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 Puppetsauxiliary cong les.

Puppets SettingsPuppet is able to automatically generate a reference of all its cong settings (puppetdoc--

Puppet Documentation Conguring Puppet 28/391

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.confPuppets 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 in versions prior to 2.7.3, due to a known bug.

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:

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


[main]#setting=valuepairs:server=master.example.comcertname=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.

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 noenvironment.)

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 REST 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/authanyenvironmentoverrideallowmagpie.example.com

path/certificate_statusauthanyenvironmentproductionallowmagpie.example.com

path/factsmethodsaveauthanyallowmagpie.example.com

path/factsauthyesmethodfind,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*.domain.comdeny*.wireless.domain.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 ([reports ] accepts a list, so you can enable anynumber of reports)Set the reportfrom email address and either the smtpserver or sendmail setting on the puppet


masterCreate 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 GuideThe 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 Documentation Language Guide 36/391

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 Upcoming

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

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.Puppet Documentation Language Guide 37/391

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.

ResourcesThe 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 attributes

Puppet Documentation Language Guide 38/391

and 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']}

Metaparameters


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

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 leftPuppet Documentation Language Guide 41/391

unmodied.

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 the


squid 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 syntaxsimilar to a resource declaration:

nodewebserver{class{'apache':version=>'1.3.13'}}

You can also specify default parameter values in your class like so:

classapache($version='1.3.13',$home='/var/www'){...classcontents...}

RUN STAGESRun stage were added in Puppet version 2.6.0, you now have the ability to specify any number ofstages which provide another method to control the ordering of resource management in puppet. IfPuppet Documentation Language Guide 43/391

stages which provide another method to control the ordering of resource management in puppet. Ifyou have a large number of resources in your catalog it may become tedious and cumbersome toexplicitly manage every relationship between the resources where order is important. In thissituation, run-stages provides you the ability to associate a class to a single stage. Puppet willguarantee stages run in a specic predictable order every catalog run.

In order to use run-stages, you must rst declare additional stages beyond the already presentmain stage. You can then congure puppet to manage each stage in a specic order using thesame resource relationship syntax, before, require, -> and Stage['main']}stage{'last':require=>Stage['main']}

All classes associated with the rst stage are to be managed before the classes associated with themain stage. All classes associated with the last stage are to be managed after the classes associatedwith the main stage.

Once stages have been declared, a class may be associated with a stage other than main using thestage class parameter.

class{'apt-keys':stage=>first;'sendmail':stage=>main;'apache':stage=>last;}

Associate all resources in the class apt-keys with the rst run stage, all resources in the classsendmail with the main stage, and all resources in the apache class with the last stage.

This short declaration guarantees resources in the apt-keys class are managed before resources inthe sendmail class, which in turn is managed before resources in the apache class.

Please note that stage is not a metaparameter. The run stage must be specied as a class parameterand as such classes must use the resource declaration syntax as shown rather than the includestatement.DEFINED RESOURCE TYPES


Dened resource types follow the same basic form as classes, but they are introduced with thedefine keyword (not class ) and they support arguments but no inheritance. As mentionedpreviously, dened resource types take parameters and can be reused multiple times on the samesystem. Suppose we want to create a resource collection that creates source control repositories.We probably would want to create multiple repositories on the same system, so we would use adened type, not a class. Heres an example:

definesvn_repo($path){exec{"/usr/bin/svnadmincreate${path}/${title}":unless=>"/bin/test-d${path}",}}

svn_repo{'puppet_repo':path=>'/var/svn_puppet'}svn_repo{'other_repo':path=>'/var/svn_other'}

Note how parameters specied in the denition (definesvn_repo($path) ) must appear asresource attributes (path=>'/var/svn_puppet' ) whenever a resource of the new type is declaredand are available as variables (unless=>"/bin/test-d${path}" ) within the denition. Multiplevariables (separated by commas) can be specied. Default values can also be specied for anyparameter with = , and any parameter which has a default becomes non-mandatory when aresource of the new type is declared.

Dened types have a number of built-in variables available, including $name and $title , which areset to the title of the resource when it is declared. (The reasons for having two identical variableswith this information are outside the scope of this document, and these two special variablescannot be used the same way in classes or other resources.) As of Puppet 2.6.5, the $name and

$title variables can also be used as default values for parameters:

definesvn_repo($path="/var/${name}"){...}

Any metaparameters used when a dened resource is declared are also made available in thedenition as variables:

definesvn_repo($path){exec{"create_repo_${name}":command=>"/usr/bin/svnadmincreate${path}/${title}",unless=>"/bin/test-d${path}",}if$require{Exec["create_repo_${name}"]{require+>$require,}}}


svn_repo{'puppet':path=>'/var/svn',require=>Package['subversion'],}

The above is perhaps not a perfect example, as most likely we would know that subversion wasalways required for svn checkouts, but it illustrates how require and other metaparameters can beused in dened types.

Dened resource types can have namespace separators (:: ) in their names, just like classes. Whenmaking a resource reference (e.g. File['/etc/motd'] ) to an instance of a dened type, you mustcapitalize all segments of the types name (e.g. Apache::Vhost['wordpress'] ).

CLASSES VS. DEFINED RESOURCE TYPESClasses and dened types are created similarly, but they are used very dierently.

Dened types are used to dene reusable objects which will have multiple instances on a givenhost, so they cannot include any resources that will only have one instance. For instance, multipleuses of the same dene cannot create the same le.

Classes, on the other hand, are guaranteed to be singletons you can include them as many timesas you want and youll only ever get one copy of the resources.

Most often, services will be dened in a class, where the services package, conguration les, andrunning service will all be gathered, because there will normally be one copy of each on a givenhost. (This idiom is sometimes referred to as service-package-le).

Dened types would be used to manage resources like virtual hosts, of which you can have many,or to encode some simple information in a reusable wrapper to save typing.MODULESYou can (and should!) combine collections of classes, dened types, and resources into modules.Modules are portable collections of conguration, for example a module might contain all theresources required to congure Postx or Apache. You can nd out more on the Modules Page

Chaining resourcesAs of puppet version 2.6.0, resources may be chained together to declare relationships betweenand among them.

You can now specify relationships directly as statements in addition to the before and requireresource metaparameters of previous versions:

File['/etc/ntp.conf']->Service['ntpd']

Manage the ntp conguration le before the ntpd servicePuppet Documentation Language Guide 46/391

You can specify a notify relationship by employing the tilde instead of the hyphen:

File['/etc/ntp.conf']~>Service['ntpd']

This manages the ntp conguration le before the ntpd service and noties the service of changesto the ntp conguration le.

You can also do relationship chaining, specifying multiple relationships on a single line:

Package['ntp']->File['/etc/ntp.conf']->Service['ntpd']

Here we rst manage the ntp package, second manage the ntp conguration le, and third managethe ntpd service.

Note that while its confusing, you dont have to have all of the arrows be the same direction:

File['/etc/ntp.conf']->Service['ntpd']file{'/etc/ntp.conf':}

Here we manage the ntp package before the ntp conguration le.

But wait! Theres more! You can also specify a collection on either side of the relationship marker:

yumrepo{'localyumrepo':....}package{'ntp':provider=>yum,...}Yumrepo->Package

This manages all yum repository resources before managing all package resources that explicitlyspecify the yum provider. (Note that it will not work for package resources that dont specify aprovider but end up using Yum since this relationship is created during catalog compilation, itPuppet Documentation Language Guide 47/391

can only act on attributes visible to the parser, not properties that must be read from the targetsystem.)

This, nally, provides easy many to many relationships in Puppet, but it also opens the door tomassive dependency cycles. This last feature is a very powerful stick, and you can considerably hurtyourself with it. In particular, watch out when using virtual resources, as the collection operatorrealizes resources as a side-eect.

NodesHaving knowledge of resources, classes, denes, and modules gets you to understanding of mostof Puppet. Nodes are a very simple remaining step, which are how we map the what we dene (thisis what a webserver looks like) to what machines are chosen to fulll those instructions.

Node denitions look just like classes, including supporting inheritance, but they are special in thatwhen a node (a managed computer running the Puppet client) connects to the Puppet masterdaemon, its name will be looked for in the list of dened nodes. The information found for thenode will then be evaluated for that node, and then node will be sent that conguration.

Node names can be the short host name, or the fully qualied domain name (FQDN). Some names,especially fully qualied ones, need to be quoted, so it is a best practice to quote all of them. Heresan example:

node'www.testing.com'{includecommonincludeapache,squid}

The previous node denition creates a node called www.testing.com and includes the common ,apache and squid classes.

You can also specify that multiple nodes receive an identical conguration by separating each witha comma:

node'www.testing.com','www2.testing.com','www3.testing.com'{includecommonincludeapache,squid}

The previous examples creates three identical nodes: www.testing.com , www2.testing.com , andwww3.testing.com .

MATCHING NODES WITH REGULAR EXPRESSIONSIn Puppet 0.25.0 and later, nodes can also be matched by regular expressions, which is much moreconvenient than listing them individually, one-by-one:


node/^www\d+$/{includecommon}

The above would match any host called www and ending with one or more digits. Heres anotherexample:

node/^(foo|bar)\.testing\.com$/{includecommon}

The above example would match either host foo or bar in the testing.com domain.

What happens if there are multiple regular expressions or node denitions set in the same le?

If there is a node without a regular expression that matches the current client connecting, thatwill be used rst.Otherwise the rst matching regular expression wins.

NODE INHERITANCENodes support a limited inheritance model. Like classes, nodes can only inherit from one othernode:

node'www2.testing.com'inherits'www.testing.com'{includeloadbalancer}

In this node denition the www2.testing.com inherits any conguration specied for thewww.testing.com node in addition to including the loadbalancer class. In other words, it doeseverything www.testing.com does, but also takes on some additional functionality.DEFAULT NODESIf you create a node named default , the node conguration for default will be used if no othernode matches are found.EXTERNAL NODESIn some cases you may already have an external list of machines and what roles they perform. Thismay be in LDAP, version control, or a database. You may also need to pass some variables to thosenodes (more on variables later).

In these cases, writing an External Nodes script can help, and that can take the place of your nodedenitions. See that section for more information.

Additional Language FeaturesPuppet Documentation Language Guide 49/391

Weve already gone over features such as ordering and grouping, though theres still a few morethings to learn.

Puppet is not a programming language, it is a way of describing your IT infrastructure as a model.This is usually quite sucient to get the job done, and prevents you from having to write a lot ofprogramming code.

QuotingMost of the time, you dont have to quote strings in Puppet. Any alphanumeric string starting with aletter (hyphens are also allowed), can leave out the quotes, though its a best practice to quotestrings for any non-native value.

Variable Interpolation With QuotesSo far, weve mentioned variables in terms of denes. If you need to use those variables within astring, use double quotes, not single quotes. Single-quoted strings will not do any variableinterpolation, double-quoted strings will. Variables in strings can also be bracketed with {} whichmakes them easier to use together, and also a bit cleaner to read:

$value="${one}${two}"

To put a quote character or $ in a double-quoted string where it would normally have a specialmeaning, precede it with an escaping \ . For an actual \ , use \\ .

In single-quoted strings only two escape sequences are supported, \' for single quote and \\ forsingle backslash. Except for these two escape sequences, everything else between single quotes istreated literally.

We recommend using single quotes for all strings that do not require variable interpolation. Usedouble quotes for those strings that require variable interpolation. The Style Guide also discussesthis with examples.

CapitalizationCapitalization of resources is used in three major ways:

Referencing: when you want to reference an already declared resource, usually for dependencypurposes, you have to capitalize the name of the resource, for example

require=>File['sshdconfig']

Inheritance. When overwriting the resource settings of a parent class from a subclass, use theuppercase versions of the resource names. Using the lowercase versions will result in an error.See the inheritance section above for an example of this.


Setting default attribute values: Resource Defaults. As mentioned previously, using a capitalizedres

Date post:	27-Nov-2015
Category:	Documents
Upload:	nightwingsbr
View:	125 times
Download:	7 times