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 3. [Setup - The basics of getting started with concat](#setup)
   8     * [What concat affects](#what-concat-affects)
   9     * [Beginning with concat](#beginning-with-concat)
  10 4. [Usage - Configuration options and additional functionality](#usage)
  11 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
  12     * [Defines](#defines)
  13     * [Parameters](#parameters)
  14     * [Removed functionality](#removed-functionality)
  15 6. [Limitations - OS compatibility, etc.](#limitations)
  16 7. [Development - Guide for contributing to the module](#development)
  17
  18 ##Overview
  19
  20 The concat module lets you construct files from multiple ordered fragments of text.
  21
  22 ##Module Description
  23
  24 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.
  25
  26 ###Beginning with concat
  27
  28 To start using concat you need to create:
  29
  30 * A concat{} resource for the final file.
  31 * One or more concat::fragment{}s.
  32
  33 A minimal example might be:
  34
  35 ~~~
  36 concat { '/tmp/file':
  37   ensure => present,
  38 }
  39
  40 concat::fragment { 'tmpfile':
  41   target  => '/tmp/file',
  42   content => 'test contents',
  43   order   => '01'
  44 }
  45 ~~~
  46
  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($content="", $order='10') {
  80   if $content == "" {
  81     $body = $name
  82   } else {
  83     $body = $content
  84   }
  85
  86   concat::fragment{ "motd_fragment_$name":
  87     target  => '/etc/motd',
  88     order   => $order,
  89     content => "    -- $body\n"
  90   }
  91 }
  92 ~~~
  93
  94 Then, in the declarations for each module on the node, add `motd::register{ 'Apache': }` to register the module in the motd.
  95
  96 ~~~
  97 class apache {
  98   include apache::install, apache::config, apache::service
  99
 100   motd::register{ 'Apache': }
 101 }
 102 ~~~
 103
 104 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.
 105
 106 When you're finished, the motd file will look something like this:
 107
 108 ~~~
 109   Puppet modules on this server:
 110
 111     -- Apache
 112     -- MySQL
 113
 114   <contents of /etc/motd.local>
 115 ~~~
 116
 117 ##Reference
 118
 119 ###Defines
 120 * `concat`: Manages a file, compiled from one or more text fragments.
 121 * `concat::fragment`: Manages a fragment of text to be compiled into a file.
 122
 123 ###Types
 124 * `concat_file`: Generates a file with content from fragments sharing a common unique tag.
 125 * `concat_fragment`: Manages the fragment.
 126
 127 ###Parameters
 128
 129 ####Define: `concat`
 130
 131 All the parameters listed below are optional.
 132
 133 #####`backup`
 134
 135 Specifies whether (and how) to back up the destination file before overwriting it. Your value gets passed on to Puppet's [native `file` resource](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-backup) for execution. Valid options: 'true', 'false', or a string representing either a target filebucket or a filename extension beginning with ".". Default value: 'puppet'.
 136
 137 #####`ensure`
 138
 139 Specifies whether the destination file should exist. Setting to 'absent' tells Puppet to delete the destination file if it exists, and negates the effect of any other parameters. Valid options: 'present' and 'absent'. Default value: 'present'.
 140
 141 #####`ensure_newline`
 142
 143 Specifies whether to add a line break at the end of each fragment that doesn't already end in one. Valid options: 'true' and 'false'. Default value: 'false'.
 144
 145 #####`force`
 146
 147 Deprecated as of concat v2.0.0. Has no effect.
 148
 149 #####`group`
 150
 151 Specifies a permissions group for the destination file. Valid options: a string containing a group name. Default value: undefined.
 152
 153 #####`mode`
 154
 155 Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation. Default value: '0644'.
 156
 157 #####`order`
 158
 159 Specifies a method for sorting your fragments by name within the destination file. Valid options: 'alpha' (e.g., '1, 10, 2') or 'numeric' (e.g., '1, 2, 10'). Default value: 'alpha'.
 160
 161 You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.
 162
 163 #####`owner`
 164
 165 Specifies the owner of the destination file. Valid options: a string containing a username. Default value: undefined.
 166
 167 #####`path`
 168
 169 Specifies a destination file for the combined fragments. Valid options: a string containing an absolute path. Default value: the title of your declared resource.
 170
 171 #####`replace`
 172
 173 Specifies whether to overwrite the destination file if it already exists. Valid options: 'true' and 'false'. Default value: 'true'.
 174
 175 #####`validate_cmd`
 176
 177 Specifies a validation command to apply to the destination file. Requires Puppet version 3.5 or newer. Valid options: a string to be passed to a file resource. Default value: undefined.
 178
 179 #####`warn`
 180
 181 Specifies whether to add a header message at the top of the destination file. Valid options: the booleans 'true' and 'false', or a string to serve as the header. Default value: 'false'.
 182
 183 If you set 'warn' to 'true', `concat` adds the following message:
 184
 185 ~~~
 186 # This file is managed by Puppet. DO NOT EDIT.
 187 ~~~
 188
 189 ####Define: `concat::fragment`
 190
 191 Except where noted, all the below parameters are optional.
 192
 193 #####`content`
 194
 195 Supplies the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string. Default value: undef.
 196
 197 #####`ensure`
 198
 199 Deprecated as of concat v2.0.0. Has no effect.
 200
 201 #####`order`
 202
 203 Reorders your fragments within the destination file. Fragments that share the same order number are ordered by name. Valid options: a string (recommended) or an integer. Default value: '10'.
 204
 205 #####`source`
 206
 207 Specifies a file to read into the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string or an array, containing one or more Puppet URLs. Default value: undefined.
 208
 209 #####`target`
 210
 211 *Required.* Specifies the destination file of the fragment. Valid options: a string containing an absolute path.
 212
 213
 214 ####Type: `concat_file`
 215
 216 #####`backup`
 217
 218 Specifies whether (and how) to back up the destination file before overwriting it. Your value gets passed on to Puppet's [native `file` resource](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-backup) for execution. Valid options: 'true', 'false', or a string representing either a target filebucket or a filename extension beginning with ".". Default value: 'puppet'.
 219
 220 #####`ensure`
 221
 222 Specifies whether the destination file should exist. Setting to 'absent' tells Puppet to delete the destination file if it exists, and negates the effect of any other parameters. Valid options: 'present' and 'absent'. Default value: 'present'.
 223
 224 #####`ensure_newline`
 225
 226 Specifies whether to add a line break at the end of each fragment that doesn't already end in one. Valid options: 'true' and 'false'. Default value: 'false'.
 227
 228 #####`group`
 229
 230 Specifies a permissions group for the destination file. Valid options: a string containing a group name. Default value: undefined.
 231
 232 #####`mode`
 233
 234 Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation. Default value: '0644'.
 235
 236 #####`order`
 237
 238 Specifies a method for sorting your fragments by name within the destination file. Valid options: 'alpha' (e.g., '1, 10, 2') or 'numeric' (e.g., '1, 2, 10'). Default value: 'numeric'.
 239
 240 You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.
 241
 242 #####`owner`
 243
 244 Specifies the owner of the destination file. Valid options: a string containing a username. Default value: undefined.
 245
 246 #####`path`
 247
 248 Specifies a destination file for the combined fragments. Valid options: a string containing an absolute path. Default value: the title of your declared resource.
 249
 250 #####`replace`
 251
 252 Specifies whether to overwrite the destination file if it already exists. Valid options: 'true' and 'false'. Default value: 'true'.
 253
 254 ####`tag`
 255
 256 *Required.* Specifies a unique tag reference to collect all concat_fragments with the same tag.
 257
 258 #####`validate_cmd`
 259
 260 Specifies a validation command to apply to the destination file. Requires Puppet version 3.5 or newer. Valid options: a string to be passed to a file resource. Default value: undefined.
 261
 262 ####Type: `concat_fragment`
 263
 264 #####`content`
 265
 266 Supplies the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string. Default value: undef.
 267
 268 #####`order`
 269
 270 Reorders your fragments within the destination file. Fragments that share the same order number are ordered by name. Valid options: a string (recommended) or an integer. Default value: '10'.
 271
 272 #####`source`
 273
 274 Specifies a file to read into the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string or an array, containing one or more Puppet URLs. Default value: undefined.
 275
 276 #####`tag`
 277
 278 *Required.* Specifies a unique tag to be used by concat_file to reference and collect content.
 279
 280 #####`target`
 281
 282 *Required.* Specifies the destination file of the fragment. Valid options: a string containing an absolute path.
 283
 284 ###Removed functionality
 285
 286 The following functionality existed in previous versions of the concat module, but was removed in version 2.0.0:
 287
 288 Parameters removed from `concat::fragment`:
 289 * `gnu`
 290 * `backup`
 291 * `group`
 292 * `mode`
 293 * `owner`
 294
 295 The `concat::setup` class has also been removed.
 296
 297 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.
 298
 299 ##Limitations
 300
 301 This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified.
 302
 303 ##Development
 304
 305 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.
 306
 307 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.
 308
 309 For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html)
 310
 311 ###Contributors
 312
 313 Richard Pijnenburg ([@Richardp82](http://twitter.com/richardp82))
 314
 315 Joshua Hoblitt ([@jhoblitt](http://twitter.com/jhoblitt))
 316
 317 [More contributors.](https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors)