Puppet Dashboard Manual

(Generated on September 16, 2011, from git revision

8830f89918de137c687bd1616c0054e57ca66394)
Puppet Dashboard 1.2 Manual
This is the manual for Puppet Dashboard 1.2.

Overview
Puppet Dashboard is a web interface for Puppet. It can view and analyze Puppet reports, assign
Puppet classes and parameters to nodes, and view inventory data and backed-up file contents.

Chapters
Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

Bootstrapping Puppet Dashboard

This is a chapter of the Puppet Dashboard 1.2 manual.

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

Overview
Puppet Dashboard is a Ruby on Rails web app that interfaces with Puppet. It will run on most
modern Unix-like OSes (including Mac OS X and most Linux distributions), requires a certain
amount of supporting infrastructure, and can be deployed and served in a variety of ways.

In outline, getting Dashboard running is going to consist of:

Installing the external dependencies

Installing the Dashboard code
Configuring Dashboard

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 2/25

 Creating and configuring a MySQL database
Testing that Dashboard is working
Configuring Puppet
Starting the delayed job worker processes
Running Dashboard in a production-quality server

…after which you can configure Dashboard further and enable optional features, but the main
functionality will be on-line and working smoothly. If you are trying to upgrade Puppet Dashboard
instead of installing it from scratch, see the chapter of this manual on upgrading. If youʼre looking
for a vastly simplified install and maintenance process, download a free trial of Puppet Enterprise.

Installing Dependencies
Dashboard is distributed with the version of Rails it uses, as well as most of its other dependencies,
but youʼll have to ensure that the following software is installed:

Ruby or Ruby Enterprise Edition version 1.8.7 — Dashboard 1.2 no longer supports older
versions of Ruby, and Ruby 1.9.2 is not yet fully supported.
RubyGems
Rake version 0.8.3 or newer
MySQL database server version 5.x
Ruby-MySQL bindings version 2.7.x or 2.8.x

On most OSes, youʼll be able to install all of these easily with the OSʼs package tools.

INSTALLING DEPENDENCIES UNDER UBUNTU 10.04 LTS

Due to issues with Ubuntu 10.04 LTSʼs version of Ruby, you can install most dependencies from
packages but must manually build gem. Additionally, if you encounter performance issues, you may
wish to manually upgrade your version of Ruby to patch level 299 or higher.

These instructions assume a fresh install of the OS, and may differ depending on its current
configuration. The commands must be run from one of the standard shells, preferably bash, dash,
or zsh.

1. Install the operating system packages:

apt-get install -y build-essential irb libmysql-ruby libmysqlclient-dev \

libopenssl-ruby libreadline-ruby mysql-server rake rdoc ri ruby ruby-dev

2. Install the RubyGems package system, using the following shell script — do not use the rubygems
packaged with the operating system:

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 3/25

 URL="http://production.cf.rubygems.org/rubygems/rubygems-1.3.7.tgz"
PACKAGE=$(echo $URL | sed "s/\.[^\.]*$//; s/^.*\///")

cd $(mktemp -d /tmp/install_rubygems.XXXXXXXXXX) && \

wget -c -t10 -T20 -q $URL && \
tar xfz $PACKAGE.tgz && \
cd $PACKAGE && \
sudo ruby setup.rb
)

3. Create gem as an alternative name for the gem1.8 command:

update-alternatives --install /usr/bin/gem gem /usr/bin/gem1.8 1

INSTALLING DEPENDENCIES UNDER CENTOS OR RHEL 5.X OR EARLIER

As Dashboard no longer supports the version of Ruby used by version 5.x enterprise Linuxes,
installing Dashboard on a 5.x server requires that you maintain your own installation of Ruby,
which is beyond the scope of this manual. If you need to deploy on a pre-6.x version of enterprise
Linux and donʼt have the resources to maintain your own Ruby packages, you should consider
using Puppet Enterprise.

Installing Puppet Dashboard

Your three main options for installing Dashboard are to use deb or rpm packages, install the source
from Git, or download a tarball of the source. Whichever way, youʼll end up with a single directory —
as Rails apps are self-contained, all of Dashboardʼs code, configuration, and run data will be stored
in the same area. Any rake tasks mentioned later in this manual should be performed from a shell
in this main directory, and any relative paths will refer to locations within it.

Packages

The best way to install Dashboard is with the official Deb and RPM packages provided by Puppet
Labs. These packages are configured with the correct dependencies, and make for easier upgrades
when new versions are released.

Puppet Labs ships raw packages, and also maintains Yum and Apt repositories. With each of these
methods, Dashboard will be installed in /usr/share/puppet-dashboard, and the puppet-dashboard
user and group will own the files; this user will be created if it doesnʼt already exist.

INSTALLING PACKAGES FROM FILES

To install the RPM package, run:

# sudo rpm -Uvh puppet-dashboard-1.2.0.noarch.rpm

To install the Deb package, run:

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 4/25

 # sudo dpkg -i puppet-dashboard-1.2.0_all.deb

USING THE YUM REPO

Create a Yum repo entry for Puppet Labs in /etc/yum.repos.d/puppetlabs.repo:

# /etc/yum.repos.d/puppetlabs.repo
[puppetlabs]
name=Puppet Labs Packages
baseurl=http://yum.puppetlabs.com/base/
enabled=1
gpgcheck=1
gpgkey=http://yum.puppetlabs.com/RPM-GPG-KEY-puppetlabs

Install Puppet Dashboard via Yum:

sudo yum install puppet-dashboard

You will be prompted to install the Puppet Labs release key as part of the installation process.

USING THE APT REPO

Add the following to your /etc/apt/sources.list file:

# /etc/apt/sources.list
deb http://apt.puppetlabs.com/ubuntu lucid main
deb-src http://apt.puppetlabs.com/ubuntu lucid main

Add the Puppet Labs repository key to Apt by running:

gpg --recv-key 4BD6EC30

gpg -a --export 4BD6EC30 | sudo apt-key add -

Update Aptʼs package cache:

sudo apt-get update

Install the Puppet Dashboard package:

sudo apt-get install puppet-dashboard

Git

If youʼre unable to use the Dashboard packages on your system, the next best way to install

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 5/25

Dashboard is from the Puppet Labs Git repo. In the directory where you want Dashboard installed
(we suggest /opt/ or /usr/share/), run:

git clone git://github.com/puppetlabs/puppet-dashboard.git

cd puppet-dashboard
git checkout v1.2.0

The advantage of using Git is that you have an easier upgrade path: you donʼt have to manually
remember which files to preserve when upgrading, and the actual process of upgrading is much
simpler. The disadvantage is that it basically turns Git into another dependency. See upgrading for
more details.

If you havenʼt installed Dashboard from a package, you must create a user and group for
Dashboard and chown all its files to be owned by that user and group:

sudo chown -R puppet-dashboard:puppet-dashboard /opt/puppet-dashboard

Source Tarballs

If you prefer not to use Git, you can simply download the most recent release of Puppet Dashboard
and extract it into your install location:

wget http://puppetlabs.com/downloads/dashboard/puppet-dashboard-1.2.0.tar.gz
tar -xzvf puppet-dashboard-1.2.0.tar.gz
mv puppet-dashboard-1.1.1 /opt/puppet-dashboard

If you havenʼt installed Dashboard from a package, you must create a user and group for
Dashboard and chown all its files to be owned by that user and group.

sudo chown -R puppet-dashboard:puppet-dashboard /opt/puppet-dashboard

Configuring Dashboard
Dashboard needs a config/database.yml file and a config/settings.yml file. It ships with
functional examples of each, as config/database.yml.example and
config/settings.yml.example respectively.

database.yml

The database settings file is located at config/database.yml, and an example file can be found at
config/database.yml.example. This file should be a YAML hash with one key for each of the
standard Rails environments: production, development, and test.

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 6/25

 The “production” environment gives the best performance, and should be used most of the time
by most users. Rails does not consider production its default environment, and you must specify
it manually with the RAILS_ENV environment variable when running any rake tasks or starting a
WEBrick server.
The “development” environment gives worse performance, but yields better logging and error
reporting when something goes wrong.
The “test” environment is only used for running Dashboardʼs automated tests, and should never
be used by most users.

You will likely only ever be using the production environment. You may wish to use the same
database for the production and development environments, as this can remove the pain of having
to specify RAILS_ENV=production for every rake task and gives you the option of running a
temporary instance with the same data in the development environment (if you ever need to collect
detailed error messages, for example). You should not use the same database for the test
environment, as it gets destroyed every time the tests are run.

Each environment in the database.yml file should be a hash with keys for database, username,
password, encoding, and adapter. At the moment, adapter can only be mysql, and encoding should
always be utf8.

Do not give Dashboard the keys to MySQLʼs root user account — create a new database user for it
(preferably named “dashboard”) and choose a secure password.

Since the database.yml file has to contain Dashboardʼs database user and password in cleartext,
you should set its mode to 660 (or some other world-unreadable mode). If youʼve created the file
while logged in as a normal user, be sure to chown it to the Dashboard user.

settings.yml

The general settings file should be a YAML hash. When first configuring Dashboard, you should
simply make a copy of settings.yml.example, as itʼs unlikely that youʼll need to change any
settings yet. (Although you may wish to change date_format, custom_logo_url, or
no_longer_reporting_cutoff.)

Creating and Configuring a MySQL Database

Dashboard needs a user, a password, and at least one database. Create these using the names and
passwords you chose in your database.yml file.

This will require that you use some external MySQL administration utility;1 in the standard
command-line mysql client, the commands will look something like this:

CREATE DATABASE dashboard CHARACTER SET utf8;

CREATE USER 'dashboard'@'localhost' IDENTIFIED BY 'my_password';

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 7/25

 GRANT ALL PRIVILEGES ON dashboard.* TO 'dashboard'@'localhost';

(See the MySQL manual for more information.)

Tuning

After creating the database and user, youʼll need to configure MySQLʼs maximum packet size to
permit larger rows in the database. On rare occasions, Dashboard can send up to 17MB of data in a
single row, and to ensure that it will function under load, you should edit /etc/mysql/my.cnf to
increase the limit to at least 24MB (we recommend 32MB or more):

# Allowing 32MB allows an occasional 17MB row with plenty of spare room
max_allowed_packet = 32M

Either restart the MySQL server for this setting to take effect, or run the following command from
the mysql client:

mysql> set max_allowed_packet = 33554432;

Preparing Schema

Once Dashboard has its database, it can create its tables, but this has to be done manually with the
db:migrate rake task. For typical use with the production environment:

rake RAILS_ENV=production db:migrate

For developing the software using the development and test environments:

rake db:migrate db:test:prepare

The db:migrate task can be safely run multiple times.

Testing That Dashboard is Working

You can now run Dashboard using Rubyʼs built-in WEBrick server:

sudo -u puppet-dashboard ./script/server -e production

This will start a Dashboard instance on port 3000 using the “production” environment. Youʼll be
able to view Dashboardʼs UI in a web browser at http://dashboardserver:3000, and your puppet
master can now be configured to use it for reporting and node classification. Note that:

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 8/25

 You will need to have already created the puppet-dashboard user and group.
You must specify the environment manually if youʼre using anything other than “development”.

Running under WEBrick isnʼt feasible for production use, since it canʼt handle concurrent requests,
but it can be useful when first getting Dashboard and Puppet configured. If youʼd rather skip
straight to a production-ready deployment, see the relevant section below.

Configuring Puppet
Puppet Dashboard has two main functions: report viewer/analyzer, and node classifier. Puppet can
use either of these functions or both of them. Once you have puppet configured, youʼll need to
restart puppet master.

Using Dashboard for Reports

For Dashboard to receive reports, there are two requirements:

All agent nodes have to be configured to submit reports to the master.

The master has to be configured to send reports to Dashboard.

CONFIGURING REPORTS ON PUPPET 2.6.0 AND NEWER

Make sure that all agents have reporting turned on:

# puppet.conf (on each agent)

[agent]
report = true

Add the http report handler to your puppet masterʼs reports setting and set reporturl to your
Dashboard instanceʼs reports/upload URL:

# puppet.conf (on puppet master)

[master]
reports = store, http
reporturl = http://dashboard.puppetlabs.lan:3000/reports/upload

CONFIGURING REPORTS ON PUPPET 0.25.X

Puppet 0.25.x lacks the http report handler, so youʼll need to do a few extra steps.

Make sure that all agents have reporting turned on:

# puppet.conf (on each agent)

[puppetd]
report = true

Copy Dashboardʼs custom report handler into puppet masterʼs libdir:

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 9/25
 # mkdir -p $(puppetmasterd --configprint libdir)/puppet/reports
# cp ext/puppet/puppet_dashboard.rb $(puppetmasterd --configprint
libdir)/puppet/reports/

If the puppet master is a different machine, youʼll need to SCP the file to it first. Also note that
you may need to edit the report processor if youʼre running Dashboard on a different server or
port, as it assumes Dashboard is running on localhost:3000.

Add puppet_dashboard to your puppet masterʼs reports setting:

# puppet.conf (on puppet master)

[puppetmasterd]
reports = store, puppet_dashboard

If your puppet master server is also running puppetd AND it has pluginsync turned on, youʼll
also need to change the agentʼs libdir:

# puppet.conf (on puppet master)

[puppetd]
pluginsync = true
libdir = $vardir/agent_lib

Using Dashboard for Node Classification

You can use Dashboardʼs external node classifier (ENC) alongside traditional Puppet DSL node
definitions. However, if you use your own custom ENC (or LDAP nodes), you wonʼt be able to use
Dashboardʼs ENC.

To use Dashboardʼs ENC, youʼll need to set the puppet masterʼs node_terminus and
external_nodes settings, and make sure the master can access Dashboardʼs node classification
script, which is located at bin/external_nodes. This scriptʼs behavior can be overridden by setting
environment variables; unless youʼre serving Dashboard over HTTPS, the only one youʼll need to set
is PUPPET_DASHBOARD_URL.

# puppet.conf (on puppet master)

[master]
node_terminus = exec
external_nodes = /usr/bin/env PUPPET_DASHBOARD_URL=http://localhost:3000
/opt/puppet-dashboard/bin/external_node

Testing Puppetʼs Connection to Dashboard

After restarting puppet master, you can run one of your puppet agents with puppet agent --test

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 10/25

to check whether the configuration is correct. The agent should be able to retrieve its catalog and
complete its run, and when you reload the Dashboard UI in your web browser, you should see “1
pending task” under the “Background Tasks” heading in the upper left corner.

This means the report arrived as expected, and will be processed once the delayed job workers are
active.

Starting and Managing Delayed Job Workers

Dashboard uses a delayed_job queue to asynchronously process resource-intensive tasks.
Although Dashboard wonʼt lose any data sent by puppet masters if these jobs donʼt run, youʼll need
to be running at least one delayed job worker (and preferably one per CPU core) to get the full
benefit of Dashboardʼs UI.

A future version of Dashboard will ship with init scripts which will let you manage the workers with
Puppet or your platformʼs service tools, but in the meantime, you must either use the provided
monitor script or start non-daemonized workers individually with the provided rake task.

Using the monitor script

Dashboard ships a worker process manager, which can be found at script/delayed_job. This
toolʼs interface resembles an init script, but it can launch any number of worker processes as well
as a monitor process to babysit these workers; run it with --help for more details. delayed_job
requires that you specify RAILS_ENV as an environment variable. To start four worker processes and
the monitor process:

# env RAILS_ENV=production script/delayed_job -p dashboard -n 4 -m start

In most configurations, you should run exactly as many workers as the machine has CPU cores.

MONITORING THE MONITOR

For additional reliability, you might want to use a standard service monitoring tool like god, monit,
or runit to supervise the script/delayed_job monitor. You can also look into other ways to run
delayed_job workers, as itʼs becoming a fairly standard component in the Rails world.

Using the jobs:work Rake Task

We donʼt recommend using rake-started workers for production, but they can be useful when
testing or developing Dashboard. To start a single worker in the production environment:

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 11/25

 rake RAILS_ENV=production jobs:work

Running Dashboard in a Production-Quality Server

Although you may have tested Dashboard using the included WEBrick server script, youʼll need to
deploy in a production-quality server like Apache with Passenger or Nginx with Passenger, Thin, or
Unicorn before rolling out Dashboard to your entire site. Instructions follow for running Dashboard
under Apache with Passenger, but as Dashboard is a fairly standard Rails application, instructions
for using any popular backend should be easily adaptable.

Serving Dashboard With Passenger and Apache

First, youʼll need to ensure that Apache 2.2 and Phusion Passenger are installed. The Passenger
website has installation instructions, but itʼs quite possible that your OS vendor has already
packaged Passenger, which can make for a much easier install.

Once Passenger is enabled, copy Dashboardʼs example vhost from ext/dashboard-vhost.conf into
Apacheʼs sites-enabled directory and edit it to match your Dashboard installation. Passenger runs
Rails apps in the production environment by default, so you wonʼt need to explicitly set the
environment (with the RailsEnv directive in the vhost configuration) unless you plan to run it in
development mode. The parts of the file youʼll need to edit are:

The port on which to serve Dashboard. This defaults to 80, but if you want to serve it on Puppetʼs
preferred port of 3000, youʼll need to change the opening tag of the vhost definition block to
<VirtualHost *:3000> and insert a Listen 3000 directive above it.

The subdomain youʼll be serving Dashboard from, which is generally just the fully-qualified
domain name of this machine. Put this in the ServerName directive.

The location of Dashboardʼs public directory, which should go in both the DocumentRoot
directive and the <Directory> block opening tag.

Your preferred log file locations, which go in the ErrorLog and CustomLog directives.

The paths to Passenger, mod_passenger, and Ruby. But before you tweak these, scan the rest of
Apacheʼs config files: if you installed Passenger from a vendor package, it probably already
inserted a global config file to make sure itʼs loaded, in which case you can safely comment out
the first three lines of this vhost config. Otherwise, point the LoadModule, PassengerRoot, and
PassengerRuby directives at the top of the file to the correct files and directories.

If you prefer to roll your own vhost config, see the Passenger userʼs guide and note that:

The DocumentRoot should point to Dashboardʼs public directory, which needs to allow all access
and have the MultiViews option turned off.

Passenger will need either the per-server RailsAutoDetect directive set to On (which is its
default state), or a RailsBaseURI directive in the vhost definition.

Puppet Dashboard Manual • Puppet Dashboard 1.2 Manual 12/25

Once Dashboardʼs vhost config is properly configured, simply restart Apache and test that Puppet
can communicate with Dashboard, as described above.

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

1. Instead of creating a database manually, you can also use the db:create or db:create:all tasks, but these require that
Dashboardʼs MySQL user already exist and have the appropriate permissions on the requested database. Since youʼll likely
need to use raw SQL commands or another external tool to do that, you might as well just create the databases while youʼre
in there.↩

Upgrading Puppet Dashboard

This is a chapter of the Puppet Dashboard 1.2 manual.

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

Overview
Upgrading Dashboard from a previous version generally consists of the following:

Stopping the webserver

Upgrading the Dashboard code itself
Running any new database migrations
Restarting the webserver

In addition, there are several tasks you must take into account when upgrading from certain
versions.

Upgrading from pre-1.2 versions

Upgrading from pre-1.1 versions

Puppet Dashboard Manual • Upgrading Puppet Dashboard 13/25

Note that all rake tasks should be performed from a shell in the directory that contains Dashboardʼs
code. Any relative paths mentioned below refer to locations within this directory. If you are running
Dashboard in the recommended “production” environment, note that Rails does not consider
production its default environment, and you must specify it manually with the RAILS_ENV
environment variable when running any rake tasks.

Upgrading Code
From Packages

Dashboard installations that used Puppet Labsʼ packages are the easiest to upgrade. If you installed
Dashboard with Yum:

# sudo yum update puppet-dashboard

If you installed it with APT:

# sudo apt-get update

# sudo apt-get install puppet-dashboard

If you installed it from an RPM package file:

# sudo rpm -Uvh puppet-dashboard-1.2.0.noarch.rpm

If you installed it from a Deb package file:

# sudo dpkg -i puppet-dashboard-1.2.0_all.deb

From Git

Upgrading from Git is relatively straightforward, although you will have to re-chown all of
Dashboardʼs files after performing the upgrade.

First, fetch data from the remote repository:

# git fetch origin

Before checking out the new release, make sure that you havenʼt made any changes that would be
overwritten:

# git status

Puppet Dashboard Manual • Upgrading Puppet Dashboard 14/25

Dashboardʼs .gitignore file should ensure that your configuration files, certificates, temp files, and
logs will be untouched by the upgrade, but if the status command shows any new or modified files,
youʼll need to preserve them. You could just copy them outside the directory, but the easiest path is
to use git stash:

# git add {list of modified files}

# git stash save "Modified files prior to 1.2.0 upgrade"

After that, youʼre clear to upgrade:

# git checkout v1.2.0

(And if you had to stash any edits, you can now apply them:

# git stash apply

If they donʼt apply cleanly, you can abort the commit with git reset --hard HEAD, or read up on
how to resolve Git merge conflicts.)

Finally, re-chown all Dashboard files to the puppet-dashboard user:

# chown -R puppet-dashboard:puppet-dashboard ./*

From Tarballs

If you originally installed Dashboard from a source tarball, youʼll need to either pick out all of your
modified or created files and transplant them into the new installation, or convert your installation
to Git; either way, you should back up the entire installation first.

To convert an existing Dashboard installation to a Git repo, do something like the following,
replacing {version tag} with the version of Dashboard you originally installed:

git init
rm .gitignore
wget https://raw.github.com/puppetlabs/puppet-dashboard/{version
tag}/.gitignore
git add .
git commit -m "conversion commit"
git branch original
git remote add upstream git://github.com/puppetlabs/puppet-dashboard.git
git fetch upstream
git reset --hard tags/{version tag}
git merge --no-ff original
git reset --soft tags/{version tag}
git stash save "Non-ignored files which were changed after the original

Puppet Dashboard Manual • Upgrading Puppet Dashboard 15/25

 installation."
git checkout tags/v1.2.0
git stash apply

As with a standard Git upgrade, youʼll need to re-chown all Dashboard files to the puppet-
dashboard user:

# chown -R puppet-dashboard:puppet-dashboard ./*

Running Database Migrations

Puppet Dashboardʼs database schema changes as features are added and improved, and it needs to
be updated after an upgrade. You may want to backup your database before you do this — see the
database backups section of the maintaining chapter for further details.

DB migrations are done with a rake task, and should be simple and painless when upgrading
between any two official releases of Dashboard.

# rake db:migrate RAILS_ENV=production

Remember that Rails does not consider “production” its default environment, so you must specify it
manually for all rake tasks unless your RAILS_ENV environment variable is set or you are using the
same database in the production and development environments.

Youʼll need to run db:migrate once for each environment you use. The db:migrate task can be
safely run multiple times in the same environment.

After upgrading the code and the database, be sure to restart Dashboardʼs webserver.

Upgrading From Versions Prior to 1.2.0

For reasons of speed and scalability, Dashboard 1.2 introduced a delayed job processing system.
Dashboard wonʼt lose any data sent by puppet masters if you donʼt run these delayed jobs, but
theyʼre necessary for analyzing reports and keeping the web UI up-to-date. Youʼll need to
configure and run at least one worker process, and we recommend running exactly one process
per CPU core.

Currently, the best way to manage these processes is with the script/delayed_job command,
which can daemonize as a supervisor process and manage the requested number of workers. To
start four workers and the monitor process:

# env RAILS_ENV=production script/delayed_job -p dashboard -n 4 -m start

Puppet Dashboard Manual • Upgrading Puppet Dashboard 16/25

See the delayed jobs section of the bootstrapping chapter for more information.

Upgrading From Versions Prior to 1.1.0

In version 1.1.0, Dashboard changed the way it stores reports, and any reports from the 1.0.x series
will have to be converted before they can be displayed or analyzed by the new version.

Since this can potentially take a long time, depending on your installationʼs report history, it isnʼt
performed when running rake db:migrate. Instead, you should run:

# rake reports:schematize RAILS_ENV=production

This task will convert the most recent reports first, and if it is interrupted, it can be resumed by just
re-running the command.

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

Configuring Puppet Dashboard

This is a chapter of the Puppet Dashboard 1.2 manual.

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

Overview
Now that youʼve bootstrapped Dashboard for basic production-level use, you can configure it to:

Enable advanced features

Increase security
Improve performance

Puppet Dashboard Manual • Configuring Puppet Dashboard 17/25

 Install plugins

Note that all rake tasks should be performed from a shell in the directory that contains Dashboardʼs
code. Any relative paths mentioned below refer to locations within this directory. If you are running
Dashboard in the recommended “production” environment, note that Rails does not consider
production its default environment, and you must specify it manually with the RAILS_ENV
environment variable when running any rake tasks.

Advanced Features
By default, Dashboard only responds to requests from a user or a puppet master. However, if you
allow it to pull data from your puppet master, you can enable two extra features: the inventory
service, and the file viewer.

Generating Certs and Connecting to the Puppet Master

Puppet uses SSL certificates to control which entities can make which requests to the puppet
master, so Dashboard has to obtain a signed cert before asking for facts or files. To do this, edit
config/settings.yml to ensure that the ca_server and ca_port settings match the address and
port of your puppet master, then run the following commands:

# sudo -u puppet-dashboard rake cert:create_key_pair

# rake cert:request

Youʼll need to sign the certificate request on the master by running puppet cert sign dashboard.
Then, from Dashboardʼs directory again, run:

# sudo -u puppet-dashboard rake cert:retrieve

Enabling Inventory Support

With inventory support, Dashboard can display a complete list of facts on each nodeʼs detail page. It
also adds a new “Inventory Search” page which can search your entire site for nodes matching a
fact query.

Requirements: To use the inventory, you must be using Puppet 2.6.7 or later, configured to provide
the inventory service.

Once the puppet master is properly configured with a database-backed inventory, edit your puppet
masterʼs auth.conf file to grant Dashboard find and search access to /facts:

path /facts
auth yes
method find, search
allow dashboard

Puppet Dashboard Manual • Configuring Puppet Dashboard 18/25

Then, edit Dashboardʼs config/settings.yml to set enable_inventory_service to true and point
inventory_server and inventory_port to your puppet master. Restart Dashboard, and node
pages should now contain lists of facts.

Enabling the Filebucket Viewer

With the filebucket viewer, Dashboard can display the contents of different file versions when you
click on MD5 checksums in reports.

Requirements: To use the filebucket viewer, you must be using Puppet 2.6.5 or later and your agent
nodes must be configured to back up all files to a remote filebucket; this is done in your puppet
masterʼs site.pp manifest, where you must define a filebucket resource named “main”…

filebucket { "main":
server => "{your puppet master}",
path => false,
}

…and set a global resource default of…

File { backup => "main" }

If you are using inspect reports for a compliance workflow, you must also set archive_files =
true in each agentʼs puppet.conf.

Once the site manifest has been properly configured, edit Dashboardʼs config/settings.yml to set
use_file_bucket_diffs to true and point file_bucket_server and file_bucket_port to your
puppet master. Restart Dashboard, and you should be able to view the contents of any file
mentioned in a report by clicking on its MD5 checksum. Diffs are not currently enabled, but will
appear in a future version of Dashboard.

Security
As Dashboard provides access to sensitive information and can make changes to your Puppet-
managed infrastructure, youʼll need some way to restrict access to it. Dashboard does not yet
provide authentication or authorization, so youʼll need to use external tools to secure it. Some
options include:

Host firewalling — The Dashboard serverʼs firewall (e.g. iptables) can be used to limit which
hosts can access the port Dashboard runs on.
stunnel or ssh tunneling — You can use tunneling to provide an encrypted connection between
hosts, e.g. if the Puppet Master and Puppet Dashboard are running on separate hosts. It can also

Puppet Dashboard Manual • Configuring Puppet Dashboard 19/25

 allow you to access the web interface from a workstation once youʼve restricted access by IP.
HTTP Basic Authentication — When serving Dashboard via Apache, you can require a username
and password to access its URLs by setting authentication rules for / in Dashboardʼs vhost
configuration:

<Location "/">
Order allow,deny
Allow from 192.168.240.110 # your puppet master's IP
Satisfy any
AuthName "Puppet Dashboard"
AuthType Basic
AuthUserFile /etc/apache2/htpasswd
Require valid-user
</Location>

Notice that you need to leave an access exception for your puppet master(s). Although itʼs
possible to configure Puppet to use a password when connecting to Dashboard (by adding a
username and password to Puppetʼs reporturl and the URL used by the external_nodes script),
this currently requires patching Puppetʼs http report handler; see issue 7173 for more details.

HTTPS (SSL) Encryption — When serving Dashboard via Apache, you can encrypt traffic between
Puppet and the Dashboard. Using this requires a set of signed certificates from the puppet
master — see generating certs and connecting to the puppet master for how to obtain them. The
example configuration in ext/passenger/dashboard-vhost.conf includes a commented-out
vhost configured to use SSL. You may need to change the Apache directives
SSLCertificateFile, SSLCertificateKeyFile, SSLCACertificateFile, and
SSLCARevocationFile to the paths of the files created by the cert rake tasks.

If you have Dashboard set up to use HTTPS, youʼll need to add an https prefix to the
DASHBOARD_URL in the external_node script and potentially correct the port number (443, by
default). You may also need to change the CERT_PATH, PKEY_PATH, and CA_PATH variables if your
puppet masterʼs hostname is not puppet or if your ssldir is not /etc/puppet/ssl.

In order for reporting to work correctly via SSL, you will have to be running puppet master via
Passenger or some other app server/webserver combination that can handle SSL; reporting to an
SSL Dashboard is not supported when running puppet master under WEBrick. Youʼll also have to
change the reporturl setting in puppet.conf to start with “https” instead of “http”.

This information may be outdated, and is currently being checked for accuracy.

Performance
Puppet Dashboard slows down as it manages more data. Here are ways to make it run faster, from
easiest to hardest:

Puppet Dashboard Manual • Configuring Puppet Dashboard 20/25

 Run exactly one delayed_job worker per CPU core.

Make sure Dashboard is running in a production-quality web server, like Apache with Passenger.
Make sure Dashboard is running in the production environment. Although Passenger runs Rails
apps in production mode by default, other Rails tools may default to the much slower
development environment.
Optimize your database once a month; create a cron job that runs:

rake RAILS_ENV=production db:raw:optimize

…from your Puppet Dashboard directory. This will reorganize and reanalyze your database for
faster queries.

Tune the number of processes Dashboard uses to handle more concurrent requests. If youʼre
using Apache with Phusion Passenger to serve Dashboard (as covered in the bootstrapping
chapter), you can modify the appropriate settings in Dashboardʼs vhost file; in particular, pay
attention to the PassengerHighPerformance, PassengerMaxPoolSize, PassengerPoolIdleTime,
PassengerMaxRequests, and PassengerStatThrottleRate settings.

Regularly prune your old reports; see “cleaning old reports” in the maintenance chapter for more
details.
Run on a machine with a fast, local database.
Run on a machine with enough processing power and memory.
Run on a machine with fast backplane, controllers, and disks.

Installing Plugins
Puppet Labs plans to ship a variety of free and commercial plugins for Dashboard, which will add
new features to support specific workflows. If you are installing a plugin, it probably came with
official packages and its own installation instructions, but some general guidelines follow:

When installing a plugin from an official package, its files should be moved into the proper place
with the proper ownership. However, you will probably have to run the db:migrate rake task after
the installation is complete.

To install a plugin from source, rather than a package, youʼll have to know the hardcoded internal
name of the plugin. This should be listed in its documentation. Copy the pluginʼs directory to
vendor/plugins, rename it to its proper internal name, and chown the directory and its files to the
Dashboard user. Then, run the puppet:plugin:install task, passing the environment youʼre

using1 and the name of the plugin as variables:

# sudo -u puppet-dashboard rake puppet:plugin:install PLUGIN=name

RAILS_ENV=production

After this, the plugin should be available and functioning. If youʼve been using Git to install and
Puppet Dashboard Manual • Configuring Puppet Dashboard 21/25
upgrade Dashboard, it should leave all plugin files untouched the next time you upgrade.

Uninstalling Plugins

This section will be filled in at a later date.

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

1. Puppet:plugin:install runs db:migrate at the end. If you run in multiple environments regularly, youʼll need to run rake
db:migrate again for each additional one. ↩

Maintaining Puppet Dashboard

This is a chapter of the Puppet Dashboard 1.2 manual.

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

Overview
Puppet Dashboard exposes most of its functionality through its web UI, but it has a number of
routine tasks that have to be performed on the command line by an admin. This chapter is a brief
tour of some of these tasks.

Note that all rake tasks should be performed from a shell in the directory that contains Dashboardʼs
code. Any relative paths mentioned below refer to locations within this directory. If you are running
Dashboard in the recommended “production” environment, note that Rails does not consider
production its default environment, and you must specify it manually with the RAILS_ENV
environment variable when running any rake tasks.

Importing Pre-existing Reports

If your puppet master has stored a large number of reports from before your Dashboard came
Puppet Dashboard Manual • Maintaining Puppet Dashboard 22/25
online, you can import them into Dashboard to get a better view into your siteʼs history. If you are
running Dashboard on the same server as your puppet master and its reports are stored in
/var/puppet/lib/reports, you can simply run:

rake RAILS_ENV=production reports:import

Alternately, you can copy the reports to your Dashboard server and run:

rake RAILS_ENV=production reports:import REPORT_DIR=/path/to/your/reports

Note that this task can take a very long time, depending on the number of reports to be imported.
You can, however, safely interrupt and re-run the task, as the importer will automatically skip
reports that Dashboard has already imported.

Optimizing the Database

Since Dashboard turns over a lot of data, its MySQL database should be periodically optimized for
speed and disk space. Dashboard has a rake task for doing this:

rake RAILS_ENV=production db:raw:optimize

You should optimize Dashboardʼs database monthly, and we recommend creating a cron job to do
so.

Cleaning Old Reports

Reports will build up over time, which can slow Dashboard down. If you wish to delete the oldest
reports, for performance, storage, or policy reasons, you can use the reports:prune rake task.

For example, to delete reports older than 1 month:

rake RAILS_ENV=production reports:prune upto=1 unit=mon

Although this task should be run regularly as a cron job, the frequency with which it should be run
will depend on your siteʼs policies.

If you run ʻrake reports:pruneʼ without any arguments, it will display further usage instructions.

Reading Logs
Dashboard may fail to start or display warnings if it is misconfigured or encounters an error. Details
about these errors are recorded to log files that will help diagnose and resolve the problem.

Puppet Dashboard Manual • Maintaining Puppet Dashboard 23/25

You can find the logs in Dashboardʼs log/ directory. You can customize your log rotation in
config/environment.rb to devote more or less disk space to them.

If youʼre running Dashboard using Apache and Phusion Passenger, the Apache logs will contain
higher-level information, such as severe errors that prevent Passenger from starting the
application.

Database backups
Although you can back up and restore Dashboardʼs database with any tools, there are a pair of rake
tasks which simplify the process.

Dumping the Database

To dump the Puppet Dashboard production database to a file called production.sql:

rake RAILS_ENV=production db:raw:dump

Or dump it to a specific file:

rake RAILS_ENV=production FILE=/my/backup/file.sql db:raw:dump

Restoring the Database

To restore the Puppet Dashboard from a file called production.sql to your production
environment:

rake RAILS_ENV=production FILE=production.sql db:raw:restore

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

Using Puppet Dashboard

This is a chapter of the Puppet Dashboard 1.2 manual.

NAVIGATION

Puppet Dashboard Manual • Using Puppet Dashboard 24/25

 Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

This chapter has not yet been written.

NAVIGATION

Bootstrapping Dashboard
Upgrading Dashboard
Configuring Dashboard
Maintaining Dashboard
Using Dashboard

© 2010 Puppet Labs [email protected] 411 NW Park Street / Portland, OR 97209 1-877-575-
9775

Puppet Dashboard Manual • Using Puppet Dashboard 25/25