module-concat/README.md

#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)
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

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'

##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