Forge Home


Circus process and socket manager


9,934 latest version

3.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.1.5 (latest)
  • 0.1.4
  • 0.1.3
  • 0.1.2
  • 0.1.1
released Aug 7th 2014
This version is compatible with:
  • Puppet Enterprise >= 3.2.0 < 3.4.0
  • Puppet 3.x
  • , , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'daenney-circus', '0.1.5'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add daenney-circus
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install daenney-circus --version 0.1.5

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



daenney/circus — version 0.1.5 Aug 7th 2014


Build Status

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with circus
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module


Circus is a process and socket manager by Mozilla. Its goal is similar to other tools like Supervisord, runit, god etc. It is built on a much more modern and scalable foundation powered by ZeroMQ.

Module Description

This module will install Circus for you. This entails installing the necessary packages, creating the configuration directories and writing the main circusd.ini to get you started.

Because there currently aren't any packages to install Circus from we rely on pip to do the heavy lifting for us.

We also ship with Upstart, systemd and Sys-V startup scripts which are taken directly from Mozilla's source code repository. Any issues with the startup scripts should be raised with Mozilla.


What circus affects

  • Install circus from PyPi;
  • Create /etc/circus, /etc/circus/conf.d;
  • Create /etc/circus/circusd.ini;
  • Symlink /usr/local/bin/circusd into /usr/bin (only done if installed from pip to ensure the init-scripts can start the daemon).

Setup requirements

Python and Pip must be available for this module to be able to work.

Beginning with circus

To install circus:

include ::circus

In order to install Circus you'll need the Python development headers installed on your system and a few other things. If they aren't managed anywhere yet this module can do that for you.

class { 'circus':
  package_circus_dependencies => ['python-dev', 'build-essential'],

You can also use Hiera with databindings to do the same thing.

include ::circus
  - 'python-dev'
  - 'build-essential'


Because Circus is still relatively new and packages are bound to pop up at some point in time you might want to switch to those instead. To make this possible a few variables have been defined:

  • package_circus: defaults to circus;
  • package_circus_provider: defaults to pip, set to undef to let Puppet figure out which one to use on your platform;
  • package_circus_dependencies: List of dependent packages not available from PyPi;



Class circus

  • package_ensure: in what state we want Circus
    • default: installed
    • option: valid values for the package type's ensure attributed except for held and purged
    • type: string
  • package_circus: name of the Circus package
    • default: circus
    • option: whatever works for you
    • type: string
  • package_circus_provider: what provider to use to install Circus
    • default: pip
    • option: any valid provider for the package type, use undef to use your platforms default
    • type: string
  • package_circus_dependencies: additional dependencies to install
    • default: []
    • option: an array of package names
    • type: array of strings
  • service_circus_provider: init-system to configure
    • default: sysv
    • option: sysv, upstart, systemd`
    • type: string
  • conf_prefix: where to create the Circus configuration directory
    • default: /etc
    • option any absolute path
    • type: string that validates as an absolute path
  • log_prefix: where to create the Circus logging directory
    • default: /var/log
    • option: any aboslute path
    • type: string that validates as an absolute path
  • logrotate_dir: where to install the logrotate configuration
    • default: /etc/logrotate.d
    • option: any aboslute path
    • type: string that validates as an absolute path

Private Classes

Though you can call these classes individually they are considered private and depend on variables set in the main circus class.

  • circus::install: installs Circus;
  • circus::configure: writes configuration files for Circus;
  • circus::services: starts and manages the Circus daemon.


This module requires Puppet 3. We test on the full set of supported Rubies but only the latest Puppet version. Since this module does not rely on any fact we do not explicitly test against mutliple Facter versions.

It should work on most Linux platforms. BSD's are currently missing rc-scripts and probably a few other things but support should be trivial to add.

Windows is not supported.


This module is hosted on Github, that is where all development takes place. Feel free to fork the module and send pull requests for the enhancements you want to merge.

When you change something or add something new you are expected to:

  • provide a rationale for the change ('because it suits me better is not a good reason');
  • modify or add tests for the new behaviour.