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     * [Public Defines](#public-defines)
  13     * [Parameters](#parameters)
  14     * [Deprecations](#deprecations)
  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 through a single `concat` resource into a coherent file. It does this through a Ruby script and a temporary holding space for the fragments.
  25
  26 ##Setup
  27
  28 ###What concat affects
  29
  30 * Installs `concatfragments.rb`.
  31 * Adds a `concat/` directory into Puppet's `vardir`.
  32
  33 ###Beginning with concat
  34
  35 To start using concat you need to create:
  36
  37 * A concat{} resource for the final file.
  38 * One or more concat::fragment{}s.
  39
  40 A minimal example might be:
  41
  42 ~~~
  43 concat { '/tmp/file':
  44   ensure => present,
  45 }
  46
  47 concat::fragment { 'tmpfile':
  48   target  => '/tmp/file',
  49   content => 'test contents',
  50   order   => '01'
  51 }
  52 ~~~
  53
  54 ##Usage
  55
  56 ###Maintain a list of the major modules on a node
  57
  58 To maintain an motd file that lists the modules on one of your nodes, first create a class to frame up the file:
  59
  60 ~~~
  61 class motd {
  62   $motd = '/etc/motd'
  63
  64   concat { $motd:
  65     owner => 'root',
  66     group => 'root',
  67     mode  => '0644'
  68   }
  69
  70   concat::fragment{ 'motd_header':
  71     target  => $motd,
  72     content => "\nPuppet modules on this server:\n\n",
  73     order   => '01'
  74   }
  75
  76   # let local users add to the motd by creating a file called
  77   # /etc/motd.local
  78   concat::fragment{ 'motd_local':
  79     target => $motd,
  80     source => '/etc/motd.local',
  81     order  => '15'
  82   }
  83 }
  84
  85 # let other modules register themselves in the motd
  86 define motd::register($content="", $order='10') {
  87   if $content == "" {
  88     $body = $name
  89   } else {
  90     $body = $content
  91   }
  92
  93   concat::fragment{ "motd_fragment_$name":
  94     target  => '/etc/motd',
  95     order   => $order,
  96     content => "    -- $body\n"
  97   }
  98 }
  99 ~~~
 100
 101 Then, in the declarations for each module on the node, add `motd::register{ 'Apache': }` to register the module in the motd.
 102
 103 ~~~
 104 class apache {
 105   include apache::install, apache::config, apache::service
 106
 107   motd::register{ 'Apache': }
 108 }
 109 ~~~
 110
 111 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.
 112
 113 When you're finished, the motd file will look something like this:
 114
 115 ~~~
 116   Puppet modules on this server:
 117
 118     -- Apache
 119     -- MySQL
 120
 121   <contents of /etc/motd.local>
 122 ~~~
 123
 124 ##Reference
 125
 126 **Note**: Several of this module's parameters and features have been deprecated. See the [Deprecations](#deprecations) section below.
 127
 128 ###Public defines
 129 * `concat`: Manages a file, compiled from one or more text fragments.
 130 * `concat::fragment`: Manages a fragment of text to be compiled into a file.
 131
 132 ###Parameters
 133
 134 ####`concat`
 135
 136 All the parameters listed below are optional.
 137
 138 #####`backup`
 139
 140 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'.
 141
 142 #####`ensure`
 143
 144 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'.
 145
 146
 147 #####`ensure_newline`
 148
 149 Specifies whether to ensure there's a new line at the end of each fragment. Valid options: 'true' and 'false'. Default value: 'false'.
 150
 151 #####`force`
 152
 153 In case no fragments have been added, this parameter specifies whether to go ahead and create a potentially empty file. Valid options: 'true' and 'false'. Default value: 'false'.
 154
 155 #####`group`
 156
 157 Specifies a permissions group for the destination file. Valid options: a string containing a group name. Default value: undefined.
 158
 159 #####`mode`
 160
 161 Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation. Default value: '0644'.
 162
 163 #####`order`
 164
 165 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'.
 166
 167 You can override this setting for individual fragments by adjusting the `order` parameter in their `concat::fragment` declarations.
 168
 169 #####`owner`
 170
 171
 172 Specifies the owner of the destination file. Valid options: a string containing a username. Default value: undefined.
 173
 174 #####`path`
 175
 176
 177 Specifies a destination file for the combined fragments. Valid options: a string containing an absolute path. Default value: the title of your declared resource.
 178
 179 #####`replace`
 180
 181 Specifies whether to overwrite the destination file if it already exists. Valid options: 'true' and 'false'. Default value: 'true'.
 182
 183 #####`validate_cmd`
 184
 185 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.
 186
 187 #####`warn`
 188
 189 Specifies whether to add a warning message at the top of the destination file so users know it was autogenerated by Puppet. Valid options: 'true', 'false', or a string to be delivered as a warning message. Default value: 'false'.
 190
 191
 192 If you set this parameter to 'true', Puppet adds the following message:
 193
 194 ~~~
 195 # This file is managed by Puppet. DO NOT EDIT.
 196 ~~~
 197
 198 ####`concat::fragment`
 199
 200
 201 Except where noted, all the below parameters are optional.
 202
 203 #####`content`
 204
 205 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.
 206
 207 #####`ensure`
 208
 209 Specifies whether the fragment should be included in the destination file or discarded. Valid options: 'present' and 'absent'. Default value: 'present'.
 210
 211 #####`order`
 212
 213 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'.
 214
 215 #####`source`
 216
 217 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.
 218
 219 #####`target`
 220
 221 *Required.* Specifies the destination file of the fragment. Valid options: a string containing an absolute path.
 222
 223 ###Deprecations
 224
 225 **`concat` has the following deprecations**
 226
 227 #####`gnu`
 228
 229 Generates a catalog compile time warning and has no effect. This parameter was silently ignored in version `1.0.0` and will be removed in a future release.
 230
 231 #####stringified 'true'/'false' values deprecated in `warn`
 232
 233 Passing stringified boolean values (strings of 'true' and 'false') to the `warn` parameter of `concat` is deprecated. Generates a catalog compile time warning, and will be silently treated as the concatenated file header/warning message in a future release.
 234
 235 Please migrate to using the Puppet DSL's native [Boolean data
 236 type](http://docs.puppetlabs.com/puppet/3/reference/lang_datatypes.html#booleans).
 237
 238
 239 **`concat::fragment` has the following deprecations**
 240
 241 #####`backup`
 242
 243 Generates a catalog compile time warning and has no effect. In the `1.0.0` release this parameter controlled file bucketing of the file fragment. Bucketing the fragment(s) is redundant with bucketing the final concatenated file and this feature has been removed.
 244
 245
 246 #####`group`
 247
 248 Generates a catalog compile time warning and has no effect. Had no user-visible effect in version `1.0.0` and will be removed in a future release.
 249
 250 #####`mode`
 251
 252 Generates a catalog compile time warning and has no effect. Had no user-visible effect in version `1.0.0` and will be removed in a future release.
 253
 254
 255 #####`owner`
 256
 257 Generates a catalog compile time warning and has no effect. Had no user-visible effect in version `1.0.0` and will be removed in a future release.
 258
 259 #####file paths are deprecated in `ensure`
 260
 261 Passing a value other than 'present' or 'absent' in the `ensure` parameter of `concat::fragment` is **deprecated**, and generates a catalog compile time warning. The warning will become a catalog compilation failure in a future release.
 262
 263 If you want to use the content of a file as a fragment please use the [`source`](#source) parameter.
 264
 265 ####`concat::setup`
 266
 267 The `concat::setup` class should no longer be directly included in the manifest. It will be removed in a future release.
 268
 269 ##Limitations
 270
 271 This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified.
 272
 273 ##Development
 274
 275 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.
 276
 277 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.
 278
 279 For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html)
 280
 281 ###Contributors
 282
 283 To see who's already involved, see the [list of contributors.](https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors)