freighthop 0.3.3 → 0.4.0

data/modules/concat/README.md

@@ -0,0 +1,440 @@
+#Concat
+
+[![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-concat.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-concat)
+
+####Table of Contents
+
+1. [Overview](#overview)
+2. [Module Description - What the module does and why it is useful](#module-description)
+3. [Setup - The basics of getting started with concat](#setup)
+    * [What concat affects](#what-concat-affects)
+    * [Setup requirements](#setup-requirements)
+    * [Beginning with concat](#beginning-with-concat)
+4. [Usage - Configuration options and additional functionality](#usage)
+    * [API _deprecations_](#api-deprecations)
+5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
+5. [Limitations - OS compatibility, etc.](#limitations)
+6. [Development - Guide for contributing to the module](#development)
+
+##Overview
+
+This module constructs files from multiple fragments in an ordered way.
+
+##Module Description
+
+This module lets you use many concat::fragment{} resources throughout
+your modules to construct a single file at the end.  It does this through
+a shell (or ruby) script and a temporary holding space for the fragments.
+
+##Setup
+
+###What concat affects
+
+* Installs concatfragments.[sh|rb] based on platform.
+* Adds a concat/ directory into Puppets `vardir`.
+
+###Beginning with concat
+
+To start using concat you need to create:
+
+* A concat{} resource for the final file.
+* One or more concat::fragment{}'s. 
+
+A minimal example might be:
+
+```puppet
+concat { '/tmp/file':
+  ensure => present,
+}
+
+concat::fragment { 'tmpfile':
+  target  => '/tmp/file'
+  content => 'test contents',
+  order   => '01'
+}
+```
+
+##Usage
+
+Please be aware that there have been a number of [API
+_deprecations_](#api-deprecations).
+
+If you wanted a /etc/motd file that listed all the major modules
+on the machine.  And that would be maintained automatically even
+if you just remove the include lines for other modules you could
+use code like below, a sample /etc/motd would be:
+
+<pre>
+Puppet modules on this server:
+
+    -- Apache
+    -- MySQL
+</pre>
+
+Local sysadmins can also append to the file by just editing /etc/motd.local
+their changes will be incorporated into the puppet managed motd.
+
+```puppet
+class motd {
+  $motd = '/etc/motd'
+
+  concat { $motd:
+    owner => 'root',
+    group => 'root',
+    mode  => '0644'
+  }
+
+  concat::fragment{ 'motd_header':
+    target  => $motd,
+    content => "\nPuppet modules on this server:\n\n",
+    order   => '01'
+  }
+
+  # local users on the machine can append to motd by just creating
+  # /etc/motd.local
+  concat::fragment{ 'motd_local':
+    target => $motd,
+    source => '/etc/motd.local',
+    order  => '15'
+  }
+}
+
+# used by other modules to register themselves in the motd
+define motd::register($content="", $order=10) {
+  if $content == "" {
+    $body = $name
+  } else {
+    $body = $content
+  }
+
+  concat::fragment{ "motd_fragment_$name":
+    target  => '/etc/motd',
+    content => "    -- $body\n"
+  }
+}
+```
+
+To use this you'd then do something like:
+
+```puppet
+class apache {
+  include apache::install, apache::config, apache::service
+
+  motd::register{ 'Apache': }
+}
+```
+
+##Reference
+
+###Classes
+
+####Public classes
+
+####Private classes
+* `concat::setup`: Sets up the concat script/directories.
+
+###Parameters
+
+###Defines
+
+####concat
+
+#####`ensure`
+Controls if the combined file is present or absent.
+
+######Example
+- ensure => present
+- ensure => absent
+
+#####`path`
+Controls the destination of the file to create.
+
+######Example
+- path => '/tmp/filename'
+
+#####`owner`
+Set the owner of the combined file.
+
+######Example
+- owner => 'root'
+
+#####`group`
+Set the group of the combined file.
+
+######Example
+- group => 'root'
+
+#####`mode`
+Set the mode of the combined file.
+
+######Example
+- mode => '0644'
+
+#####`warn`
+Determine if a warning message should be added at the top of the file to let
+users know it was autogenerated by Puppet.
+
+######Example
+- warn => true
+- warn => false
+
+#####`warn_message`
+Set the contents of the warning message.
+
+######Example
+- warn_message => 'This file is autogenerated!'
+
+#####`force`
+Determine if empty files are allowed when no fragments were added.
+
+######Example
+- force => true
+- force => false
+
+#####`backup`
+Controls the filebucket behavior used for the file.
+
+######Example
+- backup => 'puppet'
+
+#####`replace`
+Controls if Puppet should replace the destination file if it already exists.
+
+######Example
+- replace => true
+- replace => false
+
+#####`order`
+Controls the way in which the shell script chooses to sort the files.  It's
+rare you'll need to adjust this.
+
+######Allowed Values
+- order => 'alpha'
+- order => 'numeric'
+
+#####`ensure_newline`
+Ensure there's a newline at the end of the fragments.
+
+######Example
+- ensure_newline => true
+- ensure_newline => false
+
+####concat::fragment
+
+#####`target`
+Choose the destination file of the fragment.
+
+######Example
+- target => '/tmp/testfile'
+
+#####`content`
+Create the content of the fragment.
+
+######Example
+- content => 'test file contents'
+
+#####`source`
+Find the sources within Puppet of the fragment.
+
+######Example
+- source => 'puppet:///modules/test/testfile'
+- source => ['puppet:///modules/test/1', 'puppet:///modules/test/2']
+
+#####`order`
+Order the fragments.
+
+######Example
+- order => '01'
+
+#####`ensure`
+Control the file of fragment created.
+
+######Example
+- ensure => 'present'
+- ensure => 'absent'
+- ensure => 'file'
+- ensure => 'directory'
+
+#####`mode`
+Set the mode of the fragment.
+
+######Example
+- mode => '0644'
+
+#####`owner`
+Set the owner of the fragment.
+
+######Example
+- owner => 'root'
+
+#####`group`
+Set the group of the fragment.
+
+######Example
+- group => 'root'
+
+#####`backup`
+Control the filebucket behavior for the fragment.
+
+######Example
+- backup => 'puppet'
+
+### API _deprecations_
+
+#### Since version `1.0.0`
+
+##### `concat{}` `warn` parameter
+
+```puppet
+concat { '/tmp/file':
+  ensure => present,
+  warn   => 'true',  # generates stringified boolean value warning
+}
+```
+
+Using stringified Boolean values as the `warn` parameter to `concat` is
+deprecated, generates a catalog compile time warning, and will be silently
+treated as the concatenated file header/warning message in a future release.
+
+The following strings are considered a stringified Boolean value:
+
+ * `'true'`
+ * `'yes'`
+ * `'on'`
+ * `'false'`
+ * `'no'`
+ * `'off'`
+
+Please migrate to using the Puppet DSL's native [Boolean data
+type](http://docs.puppetlabs.com/puppet/3/reference/lang_datatypes.html#booleans).
+
+##### `concat{}` `gnu` parameter
+
+```puppet
+concat { '/tmp/file':
+  ensure => present,
+  gnu    => $foo,    # generates deprecation warning
+}
+```
+
+The `gnu` parameter to `concat` is deprecated, generates a catalog compile time
+warning, and has no effect.  This parameter will be removed in a future
+release.
+
+Note that this parameter was silently ignored in the `1.0.0` release.
+
+##### `concat::fragment{}` `ensure` parameter
+
+```puppet
+concat::fragment { 'cpuinfo':
+  ensure => '/proc/cpuinfo', # generates deprecation warning
+  target => '/tmp/file',
+}
+```
+
+Passing a value other than `'present'` or `'absent'` as the `ensure` parameter
+to `concat::fragment` is deprecated and generates a catalog compile time
+warning.  The warning will become a catalog compilation failure in a future
+release.
+
+This type emulates the Puppet core `file` type's disfavored [`ensure`
+semantics](http://docs.puppetlabs.com/references/latest/type.html#file-attribute-ensure)
+of treating a file path as a directive to create a symlink.  This feature is
+problematic in several ways.  It copies an API semantic of another type that is
+both frowned upon and not generally well known.  It's behavior may be
+surprising in that the target concatenated file will not be a symlink nor is
+there any common file system that has a concept of a section of a plain file
+being symbolically linked to another file.  Additionally, the behavior is
+generally inconsistent with most Puppet types in that a missing source file
+will be silently ignored.
+
+If you want to use the content of a file as a fragment please use the `source`
+parameter.
+
+##### `concat::fragment{}` `mode/owner/group` parameters
+
+```puppet
+concat::fragment { 'foo':
+  target  => '/tmp/file',
+  content => 'foo',
+  mode    => $mode,       # generates deprecation warning
+  owner   => $owner,      # generates deprecation warning
+  group   => $group,      # generates deprecation warning
+}
+```
+
+The `mode` parameter to `concat::fragment` is deprecated, generates a catalog compile time warning, and has no effect.
+
+The `owner` parameter to `concat::fragment` is deprecated, generates a catalog
+compile time warning, and has no effect.
+
+The `group` parameter to `concat::fragment` is deprecated, generates a catalog
+compile time warning, and has no effect.
+
+These parameters had no user visible effect in version `1.0.0` and will be
+removed in a future release.
+
+##### `concat::fragment{}` `backup` parameter
+
+```puppet
+concat::fragment { 'foo':
+  target  => '/tmp/file',
+  content => 'foo',
+  backup  => 'bar',       # generates deprecation warning
+}
+```
+
+The `backup` parameter to `concat::fragment` is deprecated, generates a catalog
+compile time warning, and has no effect.  It will be removed in a future
+release.
+
+In the `1.0.0` release this parameter controlled file bucketing of the file
+fragment.  Bucketting the fragment(s) is redundant with bucketting the final
+concatenated file and this feature has been removed.
+
+##### `class { 'concat::setup': }`
+
+```puppet
+include concat::setup     # generates deprecation warning
+
+class { 'concat::setup: } # generates deprecation warning
+```
+
+The `concat::setup` class is deprecated as a public API of this module and
+should no longer be directly included in the manifest.  This class may be
+removed in a future release.
+
+##### Parameter validation
+
+While not an API depreciation, users should be aware that all public parameters
+in this module are now validated for at least variable type.  This may cause
+validation errors in a manifest that was previously silently misbehaving.
+
+##Limitations
+
+This module has been tested on:
+
+* RedHat Enterprise Linux (and Centos) 5/6
+* Debian 6/7
+* Ubuntu 12.04
+
+Testing on other platforms has been light and cannot be guaranteed.
+
+#Development
+
+Puppet Labs modules on the Puppet Forge are open projects, and community
+contributions are essential for keeping them great. We can’t access the
+huge number of platforms and myriad of hardware, software, and deployment
+configurations that Puppet is intended to serve.
+
+We want to keep it as easy as possible to contribute changes so that our
+modules work in your environment. There are a few guidelines that we need
+contributors to follow so that we can have a chance of keeping on top of things.
+
+You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
+
+###Contributors
+
+The list of contributors can be found at:
+
+https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors

data/modules/concat/Rakefile

@@ -1,2 +1,6 @@
-require 'rubygems'
 require 'puppetlabs_spec_helper/rake_tasks'
+require 'rspec-system/rake_task'
+require 'puppet-lint/tasks/puppet-lint'
+
+PuppetLint.configuration.send('disable_80chars')
+PuppetLint.configuration.send('disable_quoted_booleans')

data/modules/concat/files/concatfragments.rb

@@ -0,0 +1,137 @@
+# Script to concat files to a config file.
+#
+# Given a directory like this:
+# /path/to/conf.d
+# |-- fragments
+# |   |-- 00_named.conf
+# |   |-- 10_domain.net
+# |   `-- zz_footer
+#
+# The script supports a test option that will build the concat file to a temp location and
+# use /usr/bin/cmp to verify if it should be run or not.  This would result in the concat happening
+# twice on each run but gives you the option to have an unless option in your execs to inhibit rebuilds.
+#
+# Without the test option and the unless combo your services that depend on the final file would end up
+# restarting on each run, or in other manifest models some changes might get missed.
+#
+# OPTIONS:
+#  -o	The file to create from the sources
+#  -d	The directory where the fragments are kept
+#  -t	Test to find out if a build is needed, basically concats the files to a temp
+#       location and compare with what's in the final location, return codes are designed
+#       for use with unless on an exec resource
+#  -w   Add a shell style comment at the top of the created file to warn users that it
+#       is generated by puppet
+#  -f   Enables the creation of empty output files when no fragments are found
+#  -n	Sort the output numerically rather than the default alpha sort
+#
+# the command:
+#
+#   concatfragments.rb -o /path/to/conffile.cfg -d /path/to/conf.d
+#
+# creates /path/to/conf.d/fragments.concat and copies the resulting
+# file to /path/to/conffile.cfg.  The files will be sorted alphabetically
+# pass the -n switch to sort numerically.
+#
+# The script does error checking on the various dirs and files to make
+# sure things don't fail.
+require 'optparse'
+require 'fileutils'
+
+settings = {
+  :outfile => "",
+  :workdir => "",
+  :test    => false,
+  :force   => false,
+  :warn    => "",
+  :sortarg => ""
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{$0} [options]"
+  opts.separator "Specific options:"
+
+  opts.on("-o", "--outfile OUTFILE", String, "The file to create from the sources") do |o|
+    settings[:outfile] = o
+  end
+
+  opts.on("-d", "--workdir WORKDIR", String, "The directory where the fragments are kept") do |d|
+    settings[:workdir] = d
+  end
+
+  opts.on("-t", "--test", "Test to find out if a build is needed") do
+    settings[:test] = true
+  end
+
+  opts.separator "Other options:"
+  opts.on("-w", "--warn WARNMSG", String,
+          "Add a shell style comment at the top of the created file to warn users that it is generated by puppet") do |w|
+    settings[:warn] = w
+  end
+
+  opts.on("-f", "--force", "Enables the creation of empty output files when no fragments are found") do
+    settings[:force] = true
+  end
+
+  opts.on("-n", "--sort", "Sort the output numerically rather than the default alpha sort") do
+    settings[:sortarg] = "-n"
+  end
+end.parse!
+
+# do we have -o?
+raise 'Please specify an output file with -o' unless !settings[:outfile].empty?
+
+# do we have -d?
+raise 'Please specify fragments directory with -d' unless !settings[:workdir].empty?
+
+# can we write to -o?
+if File.file?(settings[:outfile])
+  if !File.writable?(settings[:outfile])
+    raise "Cannot write to #{settings[:outfile]}"
+  end
+else
+  if !File.writable?(File.dirname(settings[:outfile]))
+    raise "Cannot write to dirname #{File.dirname(settings[:outfile])} to create #{settings[:outfile]}"
+  end
+end
+
+# do we have a fragments subdir inside the work dir?
+if !File.directory?(File.join(settings[:workdir], "fragments")) && !File.executable?(File.join(settings[:workdir], "fragments"))
+  raise "Cannot access the fragments directory"
+end
+
+# are there actually any fragments?
+if (Dir.entries(File.join(settings[:workdir], "fragments")) - %w{ . .. }).empty?
+  if !settings[:force]
+    raise "The fragments directory is empty, cowardly refusing to make empty config files"
+  end
+end
+
+Dir.chdir(settings[:workdir])
+
+if settings[:warn].empty?
+  File.open("fragments.concat", 'w') {|f| f.write("") }
+else
+  File.open("fragments.concat", 'w') {|f| f.write("#{settings[:warn]}\n") }
+end
+
+# find all the files in the fragments directory, sort them numerically and concat to fragments.concat in the working dir
+open('fragments.concat', 'a') do |f|
+  Dir.entries("fragments").sort.each{ |entry|
+    if File.file?(File.join("fragments", entry))
+	  f << File.read(File.join("fragments", entry))
+    end
+  }
+end
+
+if !settings[:test]
+  # This is a real run, copy the file to outfile
+  FileUtils.cp 'fragments.concat', settings[:outfile]
+else
+  # Just compare the result to outfile to help the exec decide
+  if FileUtils.cmp 'fragments.concat', settings[:outfile]
+    exit 0
+  else
+    exit 1
+  end
+end

data/modules/concat/files/concatfragments.sh

@@ -44,6 +44,7 @@ TEST=""
 FORCE=""
 WARN=""
 SORTARG=""
+ENSURE_NEWLINE=""
 
 PATH=/sbin:/usr/sbin:/bin:/usr/bin
 
@@ -51,7 +52,7 @@ PATH=/sbin:/usr/sbin:/bin:/usr/bin
 ## http://nexenta.org/projects/site/wiki/Personalities
 unset SUN_PERSONALITY
 
-while getopts "o:s:d:tnw:f" options; do
+while getopts "o:s:d:tnw:fl" options; do
 	case $options in
 		o ) OUTFILE=$OPTARG;;
 		d ) WORKDIR=$OPTARG;;
@@ -59,6 +60,7 @@ while getopts "o:s:d:tnw:f" options; do
 		w ) WARNMSG="$OPTARG";;
 		f ) FORCE="true";;
 		t ) TEST="true";;
+		l ) ENSURE_NEWLINE="true";;
 		* ) echo "Specify output file with -o and fragments directory with -d"
 		    exit 1;;
 	esac
@@ -105,16 +107,25 @@ fi
 
 cd ${WORKDIR}
 
-if [ x${WARNMSG} = "x" ]; then
+if [ "x${WARNMSG}" = "x" ]; then
 	: > "fragments.concat"
 else
 	printf '%s\n' "$WARNMSG" > "fragments.concat"
 fi
 
+if [ x${ENSURE_NEWLINE} != x ]; then
+	find fragments/ -type f -follow -print0 | xargs -0 -I '{}' sh -c 'if [ -n "$(tail -c 1 < {} )" ]; then echo >> {} ; fi'
+fi
+
 # find all the files in the fragments directory, sort them numerically and concat to fragments.concat in the working dir
-find fragments/ -type f -follow | sort ${SORTARG} | while read fragfile; do
-	cat "$fragfile" >> "fragments.concat"
+IFS_BACKUP=$IFS
+IFS='
+'
+for fragfile in `find fragments/ -type f -follow | LC_ALL=C sort ${SORTARG}`
+do
+    cat $fragfile >> "fragments.concat"
 done
+IFS=$IFS_BACKUP
 
 if [ x${TEST} = "x" ]; then
 	# This is a real run, copy the file to outfile

data/modules/concat/lib/facter/concat_basedir.rb

@@ -1,5 +1,11 @@
+# == 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")
-    end
+  setcode do
+    File.join(Puppet[:vardir],"concat")
+  end
 end