diff --git a/README b/README new file mode 100644 index 0000000..81bdedb --- /dev/null +++ b/README @@ -0,0 +1,94 @@ +== 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 => '', + order => 01, + } + + concat::fragment {'apache-vhost-myvhost-close': + target => 'apache-vhost-myvhost', + content => '', + 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 +/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 /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/ripienaar/puppet-concat/ + +=== Contact: + +* R.I.Pienaar +* Volcane on freenode +* @ripienaar on twitter +* www.devco.net diff --git a/lib/facter/concat_basedir.rb b/lib/facter/concat_basedir.rb index 02e9c5b..ef5a689 100644 --- a/lib/facter/concat_basedir.rb +++ b/lib/facter/concat_basedir.rb @@ -1,3 +1,9 @@ +# == Fact: concat_basedir +# +# A custom fact that sets the default location for fragments +# +# "${::vardir}/concat/" +# Facter.add("concat_basedir") do setcode do File.join(Puppet[:vardir],"concat") diff --git a/manifests/fragment.pp b/manifests/fragment.pp index f289712..a6831f8 100644 --- a/manifests/fragment.pp +++ b/manifests/fragment.pp @@ -1,19 +1,40 @@ +# == Define: concat::fragment +# # Puts a file fragment into a directory previous setup using concat # -# OPTIONS: -# - target The file that these fragments belong to -# - content If present puts the content into the file -# - source If content was not specified, use the source -# - order By default all files gets a 10_ prefix in the directory -# you can set it to anything else using this to influence the -# order of the content in the file -# - ensure Present/Absent or destination to a file to include another file -# - mode Mode for the file -# - owner Owner of the file -# - group Owner of the file -# - backup Controls the filebucketing behavior of the final file and -# see File type reference for its use. Defaults to 'puppet' -define concat::fragment($target, $content=undef, $source=undef, $order=10, $ensure = 'present', $mode = '0644', $owner = $::id, $group = $concat::setup::root_group, $backup = 'puppet') { +# === Options: +# +# [*target*] +# The file that these fragments belong to +# [*content*] +# If present puts the content into the file +# [*source*] +# If content was not specified, use the source +# [*order*] +# By default all files gets a 10_ prefix in the directory you can set it to +# anything else using this to influence the order of the content in the file +# [*ensure*] +# Present/Absent or destination to a file to include another file +# [*mode*] +# Mode for the file +# [*owner*] +# Owner of the file +# [*group*] +# Owner of the file +# [*backup*] +# Controls the filebucketing behavior of the final file and see File type +# reference for its use. Defaults to 'puppet' +# +define concat::fragment( + $target, + $content=undef, + $source=undef, + $order=10, + $ensure = 'present', + $mode = '0644', + $owner = $::id, + $group = $concat::setup::root_group, + $backup = 'puppet') { $safe_name = regsubst($name, '[/\n]', '_', 'GM') $safe_target_name = regsubst($target, '[/\n]', '_', 'GM') $concatdir = $concat::setup::concatdir diff --git a/manifests/init.pp b/manifests/init.pp index b309059..cba8223 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,128 +1,50 @@ -# A system to construct files using fragments from other files or templates. +# == Define: concat # -# 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 => '', -# order => 01, -# } -# -# concat::fragment {'apache-vhost-myvhost-close': -# target => 'apache-vhost-myvhost', -# content => '', -# 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 -# /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 /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/ripienaar/puppet-concat/ -# -# CONTACT: -# R.I.Pienaar -# Volcane on freenode -# @ripienaar on twitter -# www.devco.net - - # Sets up so that you can use fragments to build a final config file, # -# OPTIONS: -# - path The path to the final file. Use this in case you want to -# differentiate between the name of a resource and the file path. -# Note: Use the name you provided in the target of your -# fragments. -# - mode The mode of the final file -# - owner Who will own the file -# - group Who will own the file -# - force Enables creating empty files if no fragments are present -# - warn Adds a normal shell style comment top of the file indicating -# that it is built by puppet -# - backup Controls the filebucketing behavior of the final file and -# see File type reference for its use. Defaults to 'puppet' -# - replace Whether to replace a file that already exists on the local -# system +# === Options: # -# ACTIONS: -# - Creates fragment directories if it didn't exist already -# - Executes the concatfragments.sh script to build the final file, this -# script will create directory/fragments.concat. Execution happens only -# when: -# * The directory changes -# * fragments.concat != final destination, this means rebuilds will happen -# whenever someone changes or deletes the final file. Checking is done -# using /usr/bin/cmp. -# * The Exec gets notified by something else - like the concat::fragment -# define -# - Copies the file over to the final destination using a file resource +# [*path*] +# The path to the final file. Use this in case you want to differentiate +# between the name of a resource and the file path. Note: Use the name you +# provided in the target of your fragments. +# [*mode*] +# The mode of the final file +# [*owner*] +# Who will own the file +# [*group*] +# Who will own the file +# [*force*] +# Enables creating empty files if no fragments are present +# [*warn*] +# Adds a normal shell style comment top of the file indicating that it is +# built by puppet +# [*backup*] +# Controls the filebucketing behavior of the final file and see File type +# reference for its use. Defaults to 'puppet' +# [*replace*] +# Whether to replace a file that already exists on the local system +# +# === Actions: +# * Creates fragment directories if it didn't exist already +# * Executes the concatfragments.sh script to build the final file, this +# script will create directory/fragments.concat. Execution happens only +# when: +# * The directory changes +# * fragments.concat != final destination, this means rebuilds will happen +# whenever someone changes or deletes the final file. Checking is done +# using /usr/bin/cmp. +# * The Exec gets notified by something else - like the concat::fragment +# define +# * Copies the file over to the final destination using a file resource +# +# === Aliases: +# +# * The exec can notified using Exec["concat_/path/to/file"] or +# Exec["concat_/path/to/directory"] +# * The final file can be referened as File["/path/to/file"] or +# File["concat_/path/to/file"] # -# ALIASES: -# - The exec can notified using Exec["concat_/path/to/file"] or -# Exec["concat_/path/to/directory"] -# - The final file can be referened as File["/path/to/file"] or -# File["concat_/path/to/file"] define concat( $path = $name, $owner = $::id, diff --git a/manifests/setup.pp b/manifests/setup.pp index 5e90bfa..2d29bf8 100644 --- a/manifests/setup.pp +++ b/manifests/setup.pp @@ -1,17 +1,22 @@ +# === Class: concat::setup +# # Sets up the concat system. # -# $concatdir is where the fragments live and is set on the fact concat_basedir. -# Since puppet should always manage files in $concatdir and they should -# not be deleted ever, /tmp is not an option. +# [$concatdir] +# is where the fragments live and is set on the fact concat_basedir. +# Since puppet should always manage files in $concatdir and they should +# not be deleted ever, /tmp is not an option. # -# $puppetversion should be either 24 or 25 to enable a 24 compatible -# mode, in 24 mode you might see phantom notifies this is a side effect -# of the method we use to clear the fragments directory. +# [$puppetversion] +# should be either 24 or 25 to enable a 24 compatible +# mode, in 24 mode you might see phantom notifies this is a side effect +# of the method we use to clear the fragments directory. # # The regular expression below will try to figure out your puppet version # but this code will only work in 0.24.8 and newer. # # It also copies out the concatfragments.sh file to ${concatdir}/bin +# class concat::setup { $id = $::id $root_group = $id ? {