Skip to content


Subversion checkout URL

You can clone with
Download ZIP
JavaScript Ruby

This branch is 7 commits ahead, 1724 commits behind sodabrew:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Puppet Dashboard


The Puppet Dashboard is a web interface for Puppet, an open source system configuration management tool. The Puppet Dashboard displays reports with the detailed status and history of your Puppet-managed servers (nodes), and allows you to assign Puppet classes and parameters to them.

Source, community and support


The Puppet Dashboard will run on most Unix, Linux and Mac OS X systems if you install the following software from your operating system's repositories or these websites:

You may also want to install these tools:

  • Git revision control system to checkout the source code
  • Rubygems package manager to easily install Ruby libraries


  1. Download the Puppet Dashboard software:

    1. Checkout the latest source code using Git:

      git clone git://
    2. Or install the software using APT or RPM packages. See README_PACKAGES.markdown for instructions.

  2. Setup a MySQL database server, create a user and database for use with the Dashboard. For example, you might start a mysql session as root and run commands like:

    CREATE USER 'dashboard'@'localhost' IDENTIFIED BY 'my_password';
    GRANT ALL PRIVILEGES ON dashboard.* TO 'dashboard'@'localhost';
  3. Create a config/database.yml file to connect your Puppet Dashboard to this new database. Please see the config/database.yml.example file for further details about database configurations and environments. These files paths are relative to the path of the Puppet Dashboard software containing this README.markdown file.

  4. Populate the database with the tables for the Puppet Dashboard. You must cd into the directory with the Puppet Dashboard software containing this README.markdown file before running these commands:

    1. For typical use with the production environment:

       rake RAILS_ENV=production db:migrate
    2. For developing the software using the development and test environments:

       rake db:migrate db:test:prepare


There are many ways to run a Ruby web application like the Puppet Dashboard, we recommend:

  1. Built-in webserver: You can run a single instance of the application without any additional software. This is great for getting started quickly, but isn't recommended for production use because it's slow and can't handle multiple requests at the same time. You must cd into the directory with the Puppet Dashboard software containing this README.markdown file before running these commands:

    1. Start a production server on port 3000:

      ./script/server -e production

    2. Or start a development server on port 8080, where the development environment is used by default:

      ./script/server -p 8080

  2. Passenger: You can compile this plugin for Apache or Nginx to easily serve Ruby web apps quickly and with multiple instances -- it's great for production use. You can also use it with Ruby Enterprise Edition to reduce memory usage. For further information, please see Passenger/ and Ruby Enterprise Edition and the example apache configuration in ext/passenger/dashboard-vhost.conf.

  3. Thin: You can install this server, have it start multiple instances of your application as a cluster, and then put it behind a proxy like Apache or Nginx -- it's fast and reliable. For further information, please see Thin.


Import existing reports

To import Puppet reports stored in /var/puppet/lib/reports into your Puppet Dashboard's production environment:

rake RAILS_ENV=production reports:import

Or from another report directory:

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

You can re-run these commands, the importer will automatically skip existing reports and won't create duplicate entries.

Live report aggregation

The Puppet Dashboard can collect reports from your Puppet Master as they're created. To do this, you must modify your Puppet Master and all of your Puppet clients. The instructions for configuring this are different depending on what version of Puppet you are using:

Puppet 0.25.x and earlier

On your clients
  1. Make your clients send reports by setting report to true in the [puppetd] block of your puppet.conf, e.g.:

        report = true
On your Puppet Master
  1. Identify your Puppet Master's libdir by running the following command, it will probably be /var/lib/puppet:

    puppetmasterd --configprint libdir
  2. Create a directory for custom report libraries, e.g. run the following command, but replace LIBDIR with the path you found in step 1:

    mkdir -p LIBDIR/puppet/reports/
  3. Create a custom report processor file on your Puppet Master by copying the Puppet Dashboard's lib/puppet/puppet_dashboard.rb file to LIBDIR/puppet/reports. E.g.,

    cp lib/puppet/puppet_dashboard.rb LIBDIR/puppet/reports

    NOTE: This report processor will assume that your Puppet Dashboard server is running at localhost on port 3000, which is the default if it was started using script/server. If you need to specify different values, edit the lib/puppet/puppet_dashboard.rb file.

  4. Add a puppet_dashboard value to the reports setting in the [puppetmasterd] section of your puppet.conf file, e.g.:

        reports = puppet_dashboard
  5. Restart the puppetmasterd process.

Puppet 2.6.x

On your clients
  1. Make your clients send reports by setting report to true in the [agent] block of your puppet.conf, e.g.:

        report = true

    NOTE: The puppet.conf block name changed in 2.6.x from [puppetd] to [agent]

On your Puppet Master
  1. Modify your Puppet Master to send reports to the Puppet Dashboard. Do this by adding an http value to the reports setting in the master section of your puppet.conf file. For example, a puppet.conf for sending reports to a Puppet Dashboard server running at localhost on port 3000 may look like:

        reports = http, store

    If your Puppet Dashboard is at a different hostname or port, specify a reporturl setting with its URL, e.g.:

        reports = http, store
        reporturl = http://mydashboard.server:1234/reports

    NOTE: The /reports portion of the reporturl is required.

  2. Restart the puppetmasterd process.

External node classification

The Puppet Dashboard can act as an external node classification tool, which will allow you to manage Puppet classes and parameters for your nodes using a web interface:

  1. Modify your Puppet Master's puppet.conf file by adding lines like these:

      node_terminus  = exec
      external_nodes = /opt/dashboard/bin/external_node

    NOTE: Set the external_nodes value to the absolute path of the Puppet Dashboard's bin/external_node program. If the Puppet Dashboard is running on a different computer, you should copy this file to the Puppet Master to a local directory like /etc/pupppet and specify the path to it.

    NOTE: The bin/external_node program connects to the Puppet Dashboard at localhost on port 3000. If your Puppet Dashboard is running on a different host or node, please modify this file.


WARNING: The Puppet Dashboard provides access to sensitive information and can make changes to your Puppet-managed infrastructure. You must restrict access to it to protect it!

The Puppet Dashboard does not currently provide authentication, authorization or encryption -- although work on these is in progress.

Third-party tools that can help secure a Puppet Dashboard include:

  1. Host firewalling (e.g. iptables) can limit what hosts can access to the port that the Puppet Dashboard runs on, for example, only allowing the computer running the Puppet Master to connect.

  2. Tunneling (e.g. stunnel or ssh) can provide an encrypted connection between hosts, e.g. if the Puppet Master and Puppet Dashboard are running on separate hosts, or if you want to access the web interface from your workstation.

  3. HTTP Basic Authentication proxy (e.g. apache using .htaccess) can require that a username/password is provided when accessing URLs. However, if you use this, you must include the HTTP Basic Authentication username and password in the URLs in the puppet.conf's reporturl setting and in the bin/external_nodes file. A URL with HTTP Basic Authentication has the following format:


Database backups

The Puppet Dashboard database can be backed up and restored using your database vendor's tools, or using the included rake tasks which simplify the process. You must cd into the directory with the Puppet Dashboard software containing this README.markdown file before running these commands.


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


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


Something went wrong with that request. Please try again.