Puppet: System Administration Automated

Support

Using Stored Configurations

Puppet uses a technique called stored configuration, enabled with the storeconfigs configuration option, to store data in a database. This technique make use of the Ruby on Rails framework and one of three database back-ends: SQLite (the default), MySQL or PostgreSQL. Currently stored configurations are principally used by exported resources.

It is important to note that once a node is in the stored configuration database it will not be automatically purged - even if you remove the corresponding node from your configuration. If you wish to purge nodes from your database you will need to do this manually. There is a script attached to this page that allows you to remove a node by name from the database.

Contents

Installing Prerequisites

To make use of stored configuration you will need to install some prerequisites principally the database back-end you wish to use and the Rails framework.

At present (2008-01-17) Puppet requires rails 1.x. If 2.x is used you will see the following warning:

err: Could not store configs: You cannot call create unless the parent is saved

with 1.x you will get some deprecation warnings (let us know that 2.x won't work for us) these can be safely ignored:

DEPRECATION WARNING: Calling .create on a has_many association without saving its
owner will not work in rails 2.0, you probably want .build instead
See http://www.rubyonrails.org/deprecation for details. (called from create at
/usr/lib/gems/1.8/gems/activerecord-1.15.6/lib/active_record/associations/association_collection.rb:95)

We start by installing the rails Ruby Gem, either with the distribution's package management (e.g. Debian/Ubuntu have a 'rails' package) or as a ruby gem:

gem install rails -v 1.2.6

MySQL

For MySQL you will need to install a number of packages. For Red Hat/Fedora the typical packages required would be:

mysql
mysql-devel
mysql-server

Or for Debian/Ubuntu you would need the following packages. libmysql-ruby provides the mysql gem, so installing via gems is unneccesary:

mysql-server
libmysql-ruby

You may also need to install the mysql Ruby Gem (not required on Debian/Ubuntu). You may need to specify the --with-mysql-config option to tell Gems where to find your MySQL libraries and headers:

# gem install mysql -- --with-mysql-config=/usr/bin/mysql_config

You may require the ruby-devel package in order to install this gem.

A word of warning - it is possible to be using stored configurations with MySQL without installing the mysql gem. This is because rails includes with it a simple Ruby based MySQL connector. Relying on this connector is strongly discouraged, as it has been observed to leak filehandles, leave open network and database connections, and eventually cause puppetmasterd to become completely unresponsive.

In order to check if you are using the unreliable Ruby based connector, examine the rails.log file produced by puppetmasterd. If you are using the Ruby one, you will find a message like this:

WARNING: You're using the Ruby-based MySQL library that ships with Rails.
This library is not suited for production. Please install the C-based MySQL
library instead (gem install mysql).

If you find that warning, make sure you install the mysql gem, which is based on the native MySQL libraries, before you begin using stored configurations in production.

SQLite3

For SQLite you will need to install the database package. For Red Hat/Fedora the package required would be:

sqlite

For Ubuntu/Debian, the packages required are (libsqlite3-ruby contains the appropriate gem):

sqlite3
libsqlite3-ruby

You may also need to install the sqlite3-ruby Ruby Gem (not required on Debian/Ubuntu):

# gem install sqlite3-ruby

PostgreSQL

For PostgreSQL you will need to install a number of packages. For Red Hat/Fedora the typical packages required would be:

postgresql
postgresql-server
postgresql-devel

You will also need to install the postgres Ruby Gem:

# gem install postgres

For PostgreSQL you will also need to create setup the database and create an appropriate role and password.

Configuring basic storeconfigs

Now we need to configure stored configuration in Puppet itself. There are three types of database adapters available for us, the default sqlite3, MySQL and PostgreSQL. For the latter backends we also have available a number of options that let us specify a particular user, password and the location of a database socket. Let's walk through the steps required to configure the most basic SQLite backend.

  • Configure puppet.conf:

    [puppetmasterd]
storeconfigs = true
dbadapter = sqlite3
dblocation = /var/lib/puppet/storeconfigs.sqlite

  • Start the puppetmasterd daemon

  • Start the puppetd client

Now storeconfigs should be enabled and running.

Note that if you intend to use PuppetShow, you may need to include a dblocation setting under puppetmasterd, pointing to the default location. Also note that SQLite is not very happy with high volume usage (more than 5 or 10 hosts), and will report locking failures during operation.

Configuring storeconfigs for MySQL

  • Create a puppet database, and grant privileges. Replace password below with an appropriate password:

    # mysql -u root -p
mysql> create database puppet;
mysql> grant all privileges on puppet.* to puppet@localhost identified by 'password';

  • Configure your [puppetmasterd] section to reflect these settings:

    [puppetmasterd]
storeconfigs = true
dbadapter = mysql
dbuser = puppet
dbpassword = password
dbserver = localhost
dbsocket = /var/run/mysqld/mysqld.sock

  • Start the puppetmasterd daemon

  • Start the puppetd client

You can also find some information on configuring MySQL stored configurations in a Puppet manifest.

Configuring storeconfigs for PostgreSQL

By default (on RHEL/CentOS, other distros unknown), you will have to su - to the postgres user to do any administrative work such as database creation.

  • Set up the database:

    # su - postgres
$ psql template1
template1=# create database puppet;
CREATE DATABASE
create user puppetuser with unencrypted password 'password';
CREATE ROLE
template1=# grant create on database puppet to puppetuser;

Note that Puppet requires the CREATE right to do automatic table creation to initialize the database.

  • Configure your [puppetmasterd] section to reflect these settings:

    [puppetmasterd]
storeconfigs = true
dbadapter = postgresql
dbuser = puppet
dbpassword = password
dbserver = localhost
dbname = puppet

  • Start the puppetmasterd daemon

  • Start the puppetd client

  • Check /var/log/messages (or wherever you have Puppet set to log) for the message for an ''Initialized database'' message when the first client checks in.

Attachments