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)
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)
20 The concat module lets you construct files from multiple ordered fragments of text.
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.
26 ### Beginning with concat
28 To start using concat you need to create:
30 * A concat{} resource for the final file.
31 * One or more concat::fragment{}s.
33 A minimal example might be:
40 concat::fragment { 'tmpfile':
41 target => '/tmp/file',
42 content => 'test contents',
49 ### Maintain a list of the major modules on a node
51 To maintain an motd file that lists the modules on one of your nodes, first create a class to frame up the file:
63 concat::fragment{ 'motd_header':
65 content => "\nPuppet modules on this server:\n\n",
69 # let local users add to the motd by creating a file called
71 concat::fragment{ 'motd_local':
73 source => '/etc/motd.local',
78 # let other modules register themselves in the motd
79 define motd::register($content="", $order='10') {
86 concat::fragment{ "motd_fragment_$name":
87 target => '/etc/motd',
89 content => " -- $body\n"
94 Then, in the declarations for each module on the node, add `motd::register{ 'Apache': }` to register the module in the motd.
98 include apache::install, apache::config, apache::service
100 motd::register{ 'Apache': }
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.
106 When you're finished, the motd file will look something like this:
109 Puppet modules on this server:
114 <contents of /etc/motd.local>
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.
124 * `concat_file`: Generates a file with content from fragments sharing a common unique tag.
125 * `concat_fragment`: Manages the fragment.
129 #### Define: `concat`
131 All the parameters listed below are optional.
135 Data type: Boolean, String.
137 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 ".".
139 Default value: 'puppet'.
145 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'.
147 Default value: 'present'.
149 ##### `ensure_newline`
153 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`.
155 Default value: `false`.
161 Data type: String, Integer.
163 Specifies a permissions group for the destination file. Valid options: a string containing a group name.
165 Default value: `undef`.
171 Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation.
173 Default value: '0644'.
179 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').
181 You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.
183 Default value: 'alpha'.
189 Data type: String, Integer.
191 Specifies the owner of the destination file. Valid options: a string containing a username.
193 Default value: `undef`.
197 Data type: Stdlib::AbsolutePath.
199 Specifies a destination file for the combined fragments. Valid options: a string containing an absolute path.
201 Default value: `namevar`
207 Specifies whether to overwrite the destination file if it already exists. Valid options: `true` and `false`.
209 Default value: `true`.
215 Specifies whether to set the show_diff parameter for the file resource. Useful for hiding secrets stored in hiera from insecure reporting methods. Valid options: `true`.
217 Default value: `true`.
225 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.
227 Default value: `undef`.
231 Data type: Boolean, String.
233 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.
235 If you set 'warn' to `true`, `concat` adds the following line with an `order` of `0`:
237 Default value: `false`.
240 # This file is managed by Puppet. DO NOT EDIT.
243 Before 2.0.0, this parameter would add a newline at the end of the warn
244 message. To improve flexibilty, this was removed. Please add it explicitly if
247 ##### `selinux_ignore_defaults`
249 See the `file` type's
250 [`selinux_ignore_defaults`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selinux_ignore_defaults)
255 See the `file` type's
256 [`selrange`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selrange)
261 See the `file` type's
262 [`selrole`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selrole)
267 See the `file` type's
268 [`seltype`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-seltype)
273 See the `file` type's
274 [`seluser`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-seluser)
278 #### Define: `concat::fragment`
280 Except where noted, all the below parameters are optional.
286 Supplies the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string.
288 Default value: `undef`.
292 Data type: String, Integer.
294 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.
300 Data type: String, Array.
302 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.
304 Default value: `undef`.
312 Specifies the destination file of the fragment. Valid options: a string containing the path or title of the parent `concat` resource.
315 #### Type: `concat_file`
319 Data type: String, Boolean.
321 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 ".".
323 Default value: 'puppet'.
329 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'.
331 Default value: 'present'.
333 ##### `ensure_newline`
337 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`.
339 Default value: `false`.
343 Data type: String, Integer.
345 Specifies a permissions group for the destination file. Valid options: a string containing a group name.
347 Default value: `undef`.
353 Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation.
355 Default value: '0644'.
361 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').
363 You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.
365 Default value: 'numeric'.
369 Data type: String, Integer.
371 Specifies the owner of the destination file. Valid options: a string containing a username.
373 Default value: `undef`.
379 Specifies a destination file for the combined fragments. Valid options: a string containing an absolute path. Default value: the title of your declared resource.
381 Default value: `namevar`.
387 Specifies whether to overwrite the destination file if it already exists. Valid options: `true` and `false`.
389 Default value: `true`.
395 *Required.* Specifies a unique tag reference to collect all concat_fragments with the same tag.
401 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.
403 Default value: `undef`.
405 #### Type: `concat_fragment`
411 Supplies the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string.
413 Default value: `undef`.
417 Data type: String, Integer.
419 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.
427 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.
429 Default value: `undef`.
435 *Required.* Specifies a unique tag to be used by concat_file to reference and collect content.
441 *Required.* Specifies the destination file of the fragment. Valid options: a string containing the path or title of the parent `concat_file` resource.
443 ### Removed functionality
445 The following functionality existed in previous versions of the concat module, but was removed in version 2.0.0:
447 Parameters removed from `concat::fragment`:
454 The `concat::setup` class has also been removed.
456 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.
460 This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified.
464 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.
466 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.
468 For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html)
472 Richard Pijnenburg ([@Richardp82](http://twitter.com/richardp82))
474 Joshua Hoblitt ([@jhoblitt](http://twitter.com/jhoblitt))
476 [More contributors.](https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors)