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 Data type: Boolean, String.
 136
 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 ".".
 138
 139 Default value: 'puppet'.
 140
 141 ##### `ensure`
 142
 143 Data type: String.
 144
 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'.
 146
 147 Default value: 'present'.
 148
 149 ##### `ensure_newline`
 150
 151 Data type: Boolean.
 152
 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`.
 154
 155 Default value: `false`.
 156
 157 ##### `group`
 158
 159 Optional.
 160
 161 Data type: String, Integer.
 162
 163 Specifies a permissions group for the destination file. Valid options: a string containing a group name.
 164
 165 Default value: `undef`.
 166
 167 ##### `mode`
 168
 169 Data type: String.
 170
 171 Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation.
 172
 173 Default value: '0644'.
 174
 175 ##### `order`
 176
 177 Data type: String.
 178
 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').
 180
 181 You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.
 182
 183 Default value: 'alpha'.
 184
 185 ##### `owner`
 186
 187 Optional.
 188
 189 Data type: String, Integer.
 190
 191 Specifies the owner of the destination file. Valid options: a string containing a username.
 192
 193 Default value: `undef`.
 194
 195 ##### `path`
 196
 197 Data type: Stdlib::AbsolutePath.
 198
 199 Specifies a destination file for the combined fragments. Valid options: a string containing an absolute path.
 200
 201 Default value: `namevar`
 202
 203 ##### `replace`
 204
 205 Data type: Boolean.
 206
 207 Specifies whether to overwrite the destination file if it already exists. Valid options: `true` and `false`.
 208
 209 Default value: `true`.
 210
 211 ##### `show_diff`
 212
 213 Data type: Boolean.
 214
 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`.
 216
 217 Default value: `true`.
 218
 219 ##### `validate_cmd`
 220
 221 Optional.
 222
 223 Data type: String.
 224
 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.
 226
 227 Default value: `undef`.
 228
 229 ##### `warn`
 230
 231 Data type: Boolean, String.
 232
 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.
 234
 235 If you set 'warn' to `true`, `concat` adds the following line with an `order` of `0`:
 236
 237 Default value: `false`.
 238
 239 ~~~
 240 # This file is managed by Puppet. DO NOT EDIT.
 241 ~~~
 242
 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
 245 you need it.
 246
 247 ##### `selinux_ignore_defaults`
 248
 249 See the `file` type's
 250 [`selinux_ignore_defaults`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selinux_ignore_defaults)
 251 documentention.
 252
 253 ##### `selrange`
 254
 255 See the `file` type's
 256 [`selrange`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selrange)
 257 documentention.
 258
 259 ##### `selrole`
 260
 261 See the `file` type's
 262 [`selrole`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-selrole)
 263 documentention.
 264
 265 ##### `seltype`
 266
 267 See the `file` type's
 268 [`seltype`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-seltype)
 269 documentention.
 270
 271 ##### `seluser`
 272
 273 See the `file` type's
 274 [`seluser`](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-seluser)
 275 documentention.
 276
 277
 278 #### Define: `concat::fragment`
 279
 280 Except where noted, all the below parameters are optional.
 281
 282 ##### `content`
 283
 284 Data type: String.
 285
 286 Supplies the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string.
 287
 288 Default value: `undef`.
 289
 290 ##### `order`
 291
 292 Data type: String, Integer.
 293
 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.
 295
 296 Default value: '10'.
 297
 298 ##### `source`
 299
 300 Data type: String, Array.
 301
 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.
 303
 304 Default value: `undef`.
 305
 306 ##### `target`
 307
 308 *Required.*
 309
 310 Data type: String.
 311
 312 Specifies the destination file of the fragment. Valid options: a string containing the path or title of the parent `concat` resource.
 313
 314
 315 #### Type: `concat_file`
 316
 317 ##### `backup`
 318
 319 Data type: String, Boolean.
 320
 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 ".".
 322
 323 Default value: 'puppet'.
 324
 325 ##### `ensure`
 326
 327 Data type: String.
 328
 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'.
 330
 331 Default value: 'present'.
 332
 333 ##### `ensure_newline`
 334
 335 Data type: Boolean.
 336
 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`.
 338
 339 Default value: `false`.
 340
 341 ##### `group`
 342
 343 Data type: String, Integer.
 344
 345 Specifies a permissions group for the destination file. Valid options: a string containing a group name.
 346
 347 Default value: `undef`.
 348
 349 ##### `mode`
 350
 351 Data type: String.
 352
 353 Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation.
 354
 355 Default value: '0644'.
 356
 357 ##### `order`
 358
 359 Data type: String.
 360
 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').
 362
 363 You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.
 364
 365 Default value: 'numeric'.
 366
 367 ##### `owner`
 368
 369 Data type: String, Integer.
 370
 371 Specifies the owner of the destination file. Valid options: a string containing a username.
 372
 373 Default value: `undef`.
 374
 375 ##### `path`
 376
 377 Data type: String.
 378
 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.
 380
 381 Default value: `namevar`.
 382
 383 ##### `replace`
 384
 385 Data type: Boolean.
 386
 387 Specifies whether to overwrite the destination file if it already exists. Valid options: `true` and `false`.
 388
 389 Default value: `true`.
 390
 391 ##### `tag`
 392
 393 Data type: String.
 394
 395 *Required.* Specifies a unique tag reference to collect all concat_fragments with the same tag.
 396
 397 ##### `validate_cmd`
 398
 399 Data typeL String
 400
 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.
 402
 403 Default value: `undef`.
 404
 405 #### Type: `concat_fragment`
 406
 407 ##### `content`
 408
 409 Data type: String.
 410
 411 Supplies the content of the fragment. **Note**: You must supply either a `content` parameter or a `source` parameter. Valid options: a string.
 412
 413 Default value: `undef`.
 414
 415 ##### `order`
 416
 417 Data type: String, Integer.
 418
 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.
 420
 421 Default value: '10'.
 422
 423 ##### `source`
 424
 425 Data type: String.
 426
 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.
 428
 429 Default value: `undef`.
 430
 431 ##### `tag`
 432
 433 Data type: String.
 434
 435 *Required.* Specifies a unique tag to be used by concat_file to reference and collect content.
 436
 437 ##### `target`
 438
 439 Data type: String.
 440
 441 *Required.* Specifies the destination file of the fragment. Valid options: a string containing the path or title of the parent `concat_file` resource.
 442
 443 ### Removed functionality
 444
 445 The following functionality existed in previous versions of the concat module, but was removed in version 2.0.0:
 446
 447 Parameters removed from `concat::fragment`:
 448 * `gnu`
 449 * `backup`
 450 * `group`
 451 * `mode`
 452 * `owner`
 453
 454 The `concat::setup` class has also been removed.
 455
 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.
 457
 458 ## Limitations
 459
 460 This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified.
 461
 462 ## Development
 463
 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.
 465
 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.
 467
 468 For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html)
 469
 470 ### Contributors
 471
 472 Richard Pijnenburg ([@Richardp82](http://twitter.com/richardp82))
 473
 474 Joshua Hoblitt ([@jhoblitt](http://twitter.com/jhoblitt))
 475
 476 [More contributors.](https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors)