Collection of puppet modules for FreeBSD users and for reference/inspiration. Focuses on demonstrating best practices and language constructs to reduce complexity and code size.
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
manifests
modules
README.mkd
namespaceauth.conf
puppet.conf
tagmail.conf

README.mkd

Please README First!

This is a collection of Puppet 0.24.8 configuration files for FreeBSD. I make heavy use of defaults and defines to heavily reduce code weight. Hopefully this will be of instructive value to new users of Puppet and inspirational value to old users.

I am definitely willing to add additional documentation as necessary. Just email me.

List of Modules

TODO: Add link to each module.

  • core -- System files for hypervisor and child jails.
  • environment/project -- Baseline programming environments for projects to inherit and examples of some of those projects.
  • exim/mailman -- Configuration for baseline exim/mailman install. Extensive documentation available on how to move from one server to another. Less, but still documented, on how to install.
  • ezjail -- Jail manager for FreeBSD. Really useful for setting up/tearing down jails quickly.
  • mount -- Very simple module to control jailed fstabs for ezjail.
  • nginx -- Complete configuration to nginx, one of my specialties. It includes a copy of stationx, a configuration generation tool for nginx -- it makes managing nginx configuration files much easier!
  • mysql -- Simple mysql+sphinx module.
  • ports -- Controls installation of all software not covered above. (Basically, every port that requires installation but not configuration.) Includes simple ruby script to help automate this process.
  • puppet -- Meta module that maintains Puppet's files. Essential for any Puppet setup.
  • ssh -- Managed per-machine ssh keys.
  • thttpd -- Configured specifically for nginx/mailman.
  • user -- Shows how to setup the virtual/real user model advocated on Puppet's wiki. The examples there aren't as full, so this should be helpful to new users.

Infrastructure

My infrastructure consists of one physical machine separated into several jails for permission AND ease-of-use purposes.

  • rescue -- Hypervisor machine and fileserver.
  • hyper -- Jail, hosts puppetmasterd.
  • neko -- Jail, personal sites.
  • dso -- Jail, for DSO, a student org I founded.
  • lp -- Jail, for experimental use.

It was important for me to be able to quickly tear down a jail and put it up again with a preset environment already installed. In general, this is how I do it:

  1. Use ezjail-admin to drop the jail.
  2. Use Puppet (node.pp) to configure the environment of the new jail: which {users,ports,development environments,daemons/services,projects} are present/running.
  3. Use ezjail again to bring up the new jail. The ezjail module makes sure that puppetd is already running on the new jail.
  4. Login to the new jail and run Puppet to bring it fully online.

That is the main use case for my use of Puppet. Here are the secondary reasons:

  • DRY configuration files -- When I create a configuration file, I usually want to use it on all machines. I hate the process of making sure each copy of a file is identical.
  • Canonical location for files -- It was also nice to have one place to refer to for the "latest" copy of each file.
  • Canonical location for documentation -- For software I use often, I usually have some sort of "how-to-install" notes for myself. Puppet is a great place to keep and share such notes.
  • There are probably others, I'll put them up as I think of them.

Code Samples

TODO: Walk through a canonical module that demonstrates language constructs I use. TODO: Walk through confusing modules here. (user, environment?)

Would someone be kind enough to let me know which modules they find the most confusing or demonstrative/canonical of this repo?

Caveats

These configuration files are all working and in production on my own server. However, because I redacted several files for privacy reasons (SSH id_rsa's, for example), I don't guarantee that the complete configuration will work out of the box for you.

However, I still think they'll be of instructive value for those who think/code like me. I searched quite a while for a complete/simple/comprehensive Puppet public repository and failed to find one. There are several complete ones, but were slightly confusing for me to follow along.

My suggestion for you is try all of them and pick the author you find most lucid.


Files changed for privacy concerns:

  • tagmail.conf -- redacted email addresses.
  • modules/puppet/templates/tagmail.conf.erb -- redacted email addresses.
  • modules/exim/templates/aliases.erb -- redacted email addresses.
  • modules/user/manifests/virtual.pp -- removed users and changed to bogus password hashes.
  • modules/user/manifests/real/dso.pp -- changed real users to bogus ones.
  • modules/user/manifests/real/neko.pp -- changed real users to bogus ones.

Files blanked to size 0 for privacy concerns:

  • modules/nginx/files/passwords/personal.htaccess -- obvious reason.

Files removed for privacy concerns:

  • modules/nginx/files/enabled/* -- (5 files) -- unnecessary, as can generate it using included stationx.
  • modules/ssh/files/* -- (15 files) -- files of format: ssh_host_{dsa,rsa,}_key.

TODO

There is an embarassing amount TODO simply because I just open-sourced my modules. (Although the production version has been in development for a long time and represents years of experience.) Hints on how to prioritize would be nice. Again, hit up my email.

  • Logic behind the various files in /manifests and how they interact.
  • Document the use of defines and defaults within modules (through code samples?).
  • Make this TODO list comprehensive.