module-concat/README

== Module: concat

A system to construct files using fragments from other files or templates.

This requires at least puppet 0.25 to work correctly as we use some
enhancements in recursive directory management and regular expressions
to do the work here.

=== Usage:

The basic use case is as below:

 concat{"/etc/named.conf":
   notify => Service["named"]
 }

 concat::fragment{"foo.com_config":
   target  => "/etc/named.conf",
   order   => 10,
   content => template("named_conf_zone.erb")
 }

 # add a fragment not managed by puppet so local users
 # can add content to managed file
 concat::fragment{"foo.com_user_config":
   target  => "/etc/named.conf",
   order   => 12,
   ensure  => "/etc/named.conf.local"
 }

This will use the template named_conf_zone.erb to build a single
bit of config up and put it into the fragments dir.  The file
will have an number prefix of 10, you can use the order option
to control that and thus control the order the final file gets built in.

You can also specify a path and use a different name for your resources:

 # You can make this something dynamic, based on whatever parameters your
 # module/class for example.
 $vhost_file = '/etc/httpd/vhosts/01-my-vhost.conf'

 concat{'apache-vhost-myvhost':
  path => $vhost_file,
 }

 # We don't care where the file is located, just what to put in it.
 concat::fragment {'apache-vhost-myvhost-main':
  target  => 'apache-vhost-myvhost',
  content => '<virtualhost *:80>',
  order   => 01,
 }

 concat::fragment {'apache-vhost-myvhost-close':
  target  => 'apache-vhost-myvhost',
  content => '</virtualhost>',
  order   => 99,
 }

=== Setup:

The class concat::setup uses the fact concat_basedir to define the variable
$concatdir, where all the temporary files and fragments will be
durably stored. The fact concat_basedir will be set up on the client to
<Puppet[:vardir]>/concat, so you will be able to run different setup/flavours
of puppet clients.
However, since this requires the file lib/facter/concat_basedir.rb to be
deployed on the clients, so you will have to set "pluginsync = true" on
both the master and client, at least for the first run.

There's some regular expression magic to figure out the puppet version but
if you're on an older 0.24 version just set $puppetversion = 24

=== Detail:

We use a helper shell script called concatfragments.sh that gets placed
in <Puppet[:vardir]>/concat/bin to do the concatenation.  While this might
seem more complex than some of the one-liner alternatives you might find on
the net we do a lot of error checking and safety checks in the script to avoid
problems that might be caused by complex escaping errors etc.

=== License:

Apache Version 2

=== Latest:

http://github.com/puppetlabs/puppetlabs-concat/

=== Contact:

Puppetlabs, via our puppet-users@ mailing list.