Puppet Documentation

Table of Contents

1. Introduction to Puppet
2. Command Line Executables
3. Type and Language Reference
4. API Documentation
5. Configuration
6. Cookbook
7. Additional Documentation

Introduction to Puppet

Puppet is a declarative language for expressing system configuration, a client and server for distributing it, and a library for realizing the configuration.

The Puppet Introduction covers the basic architecture and design goals, including whether and why you should be using Puppet on your network. The Big Picture is an unfinished narrative on the design and philosophy of Puppet meant to supplement the introduction.

There is an Installation Guide meant for installation of Puppet across a network.

There is also a guide for using Puppet from source, and one for testing Puppet, to get an idea of what you can do without making a full deployment.

Command Line Executables

This section will eventually have links to full man-pages for each executable, but for now the man pages can be found by running the respective executable with the --help flag (this requires the Rdoc::usage module, which is often missing).

However, most arguments for the executables are in the form of configuration parameters used internally in the library. All of the executables are written to accept any of these configuration parameters, and they are all defined in the Configuration Reference.

• puppet. Stand alone Puppet Site Manifest Script evaluator. Parses, evaluates, and implements a Site Manifest locally.
• puppetmasterd. Puppet Site Manifest Server Daemon. Runs on each host serving/providing configurations to Puppet client hosts.
• puppetd. Puppet Client Host Configuration Daemon. Runs on each host whose configuration is managed by Puppet. Requests a Host Specific Manifest from a Puppet Manifest Server and implements it locally.
• puppetca. SSL Certificate Authority Server used for receiving cerification requests from puppet clients. Puppet Client Hosts are required to have their SSL certs signed by their Puppet Manifest Server's Authority before they can be authenticated and authorized to recieve configurations.
• puppetdoc. Command line tool for printing Puppet Default and Local Type Library reference documentation. This is really only used internally.

Type and Language Reference

The Puppet reference is split into two pieces:

• Language Structures. An overview of language structures available for site configurations.
• Language Reference. A reference to all available language structures within Puppet. This reference presents the limits of and options for expressibility within Puppet.
• Function Reference
• Type Reference. A reference of all available Puppet Types. The types defined in this reference represent the total ability of Puppet to manage your system -- if an object is not in this reference, then Puppet cannot currently manage it.
• Glossary OfTerms

API Documentation

Until I have time to write tutorials on how to extend Puppet, you might find some benefit in perusing the API docs. They're woefully incomplete as of the middle of 2006, but I'll be updating them over time. Configuration

Configuration

Puppet configuration can be done through per-process configuration files (e.g., puppetd.conf) or on the command-line via switches. Much of the documentation is available via --help switches on each executable, but most of the useful switches are common to all executables and are thus documented in the Configuration Reference.

There are some guides already, though:

• Resources And Relationships are the building blocks of the puppet configuration language.
• Language Tutorial. A simple description of how the Puppet language functions, with multiple examples.
• File Serving Configuration
• Certificates And Security
• Puppet Templating with ERB
• Reports And Reporting
• Using Tags
• Ldap Nodes explains how to store node information in LDAP
• Virtual Resources (advanced)
• Runtime Configuration Reference

Cookbook

The Cookbook is a repository of 'recipes', puppet and facter configuration snippets for achieving common tasks.

• Recipe Requests - a wishlist
• Recipes for configuring Puppet
• Recipes for configuring Facter

Additional Documentation

While the above links represent the standard, recommended documentation, there is additional information available for those who are interested:

• Frequently Asked Questions
• Puppet Internals describes how manifests are processed and used
• Transitioning From Cfengine using the Cfengine module
• How Cfengine compares to Puppet
• Master Config Layout describes how to organize manifests and config files on the puppetmaster
• Creating Custom Types
• Writing Your Own Functions -- extending the Puppet language with your own server-side functions
• Puppet With Launchd -- A tutorial for starting puppet with Apple's new launchd.
• Documenting Manifests -- A proposal for a standard for manifest documentation.
• A detailed example of using Puppet and how the way it modularizes configurations can be used for sharing 'system recipes'
• If you're considering contributing documentation, please take a look at the Documentation Standards.
• Puppet Scalability describes common issues and solutions related to scaling a puppet deployment.
• PuppetMacOSX descibes recommendations when running Puppet on a Mac OS X node.
• Puppet Presentations: Luke Kanies about Puppet at BayLISA