3rdparty/modules/concat/README.md

   1 # concat
   2
   3 #### Table of Contents
   4
   5 1. [Overview](#overview)
   6 2. [Module Description - What the module does and why it is useful](#module-description)
   7     * [Beginning with concat](#beginning-with-concat)
   8 4. [Usage - Configuration options and additional functionality](#usage)
   9 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
  10     * [Removed functionality](#removed-functionality)
  11 6. [Limitations - OS compatibility, etc.](#limitations)
  12 7. [Development - Guide for contributing to the module](#development)
  13
  14 <a id="overview"></a>
  15 ## Overview
  16
  17 The concat module lets you construct files from multiple ordered fragments of text.
  18
  19 <a id="module-description"></a>
  20 ## Module Description
  21
  22 The concat module lets you gather `concat::fragment` resources from your other modules and order them into a coherent file through a single `concat` resource.
  23
  24 <a id="beginning-with-concat"></a>
  25 ### Beginning with concat
  26
  27 To start using concat you need to create:
  28
  29 * A concat{} resource for the final file.
  30 * One or more concat::fragment{}s.
  31
  32 A minimal example might be:
  33
  34 ~~~
  35 concat { '/tmp/file':
  36   ensure => present,
  37 }
  38
  39 concat::fragment { 'tmpfile':
  40   target  => '/tmp/file',
  41   content => 'test contents',
  42   order   => '01'
  43 }
  44 ~~~
  45
  46 <a id="usage"></a>
  47 ## Usage
  48
  49 ### Maintain a list of the major modules on a node
  50
  51 To maintain an motd file that lists the modules on one of your nodes, first create a class to frame up the file:
  52
  53 ~~~
  54 class motd {
  55   $motd = '/etc/motd'
  56
  57   concat { $motd:
  58     owner => 'root',
  59     group => 'root',
  60     mode  => '0644'
  61   }
  62
  63   concat::fragment { 'motd_header':
  64     target  => $motd,
  65     content => "\nPuppet modules on this server:\n\n",
  66     order   => '01'
  67   }
  68
  69   # let local users add to the motd by creating a file called
  70   # /etc/motd.local
  71   concat::fragment { 'motd_local':
  72     target => $motd,
  73     source => '/etc/motd.local',
  74     order  => '15'
  75   }
  76 }
  77
  78 # let other modules register themselves in the motd
  79 define motd::register (
  80   $content = "",
  81   $order   = '10',
  82 ) {
  83   if $content == "" {
  84     $body = $name
  85   } else {
  86     $body = $content
  87   }
  88
  89   concat::fragment { "motd_fragment_$name":
  90     target  => '/etc/motd',
  91     order   => $order,
  92     content => "    -- $body\n"
  93   }
  94 }
  95 ~~~
  96
  97 Then, in the declarations for each module on the node, add `motd::register{ 'Apache': }` to register the module in the motd.
  98
  99 ~~~
 100 class apache {
 101   include apache::install, apache::config, apache::service
 102
 103   motd::register { 'Apache': }
 104 }
 105 ~~~
 106
 107 These two steps populate the /etc/motd file with a list of the installed and registered modules, which stays updated even if you just remove the registered modules' `include` lines. System administrators can append text to the list by writing to /etc/motd.local.
 108
 109 When you're finished, the motd file will look something like this:
 110
 111 ~~~
 112   Puppet modules on this server:
 113
 114     -- Apache
 115     -- MySQL
 116
 117   <contents of /etc/motd.local>
 118 ~~~
 119
 120 <a id="reference"></a>
 121 ## Reference
 122
 123 See [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-concat/blob/master/REFERENCE.md)
 124
 125 <a id="removed-functionality"></a>
 126 ### Removed functionality
 127
 128 The following functionality existed in previous versions of the concat module, but was removed in version 2.0.0:
 129
 130 Parameters removed from `concat::fragment`:
 131 * `gnu`
 132 * `backup`
 133 * `group`
 134 * `mode`
 135 * `owner`
 136
 137 The `concat::setup` class has also been removed.
 138
 139 Prior to concat version 2.0.0, if you set the `warn` parameter to a string value of `true`, `false`, 'yes', 'no', 'on', or 'off', the module translated the string to the corresponding boolean value. In concat version 2.0.0 and newer, the `warn_header` parameter treats those values the same as other strings and uses them as the content of your header message. To avoid that, pass the `true` and `false` values as booleans instead of strings.
 140
 141 <a id="limitations"></a>
 142 ## Limitations
 143
 144 This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified.
 145
 146 For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-concat/blob/master/metadata.json)
 147
 148 <a id="development"></a>
 149 ## Development
 150
 151 We are experimenting with a new tool for running acceptance tests. It's name is [puppet_litmus](https://github.com/puppetlabs/puppet_litmus) this replaces beaker as the test runner. To run the acceptance tests follow the instructions [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module).
 152
 153 Puppet 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.
 154
 155 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.
 156
 157 For more information, see our [module contribution guide](https://puppet.com/docs/puppet/latest/contributing.html).
 158
 159 ### Contributors
 160
 161 Richard Pijnenburg ([@Richardp82](http://twitter.com/richardp82))
 162
 163 Joshua Hoblitt ([@jhoblitt](http://twitter.com/jhoblitt))
 164
 165 [More contributors](https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors).