README.md 5.47 KB
Newer Older
1
# concat
2

3
#### Table of Contents
4 5 6 7 8 9

1. [Overview](#overview)
2. [Module Description - What the module does and why it is useful](#module-description)
    * [Beginning with concat](#beginning-with-concat)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
10
    * [Removed functionality](#removed-functionality)
Pete Soloway's avatar
Pete Soloway committed
11 12
6. [Limitations - OS compatibility, etc.](#limitations)
7. [Development - Guide for contributing to the module](#development)
13

clairecadman's avatar
clairecadman committed
14
<a id="overview"></a>
15
## Overview
16

Pete Soloway's avatar
Pete Soloway committed
17
The concat module lets you construct files from multiple ordered fragments of text.
18

clairecadman's avatar
clairecadman committed
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

clairecadman's avatar
clairecadman committed
24
<a id="beginning-with-concat"></a>
25
### Beginning with concat
26 27 28 29

To start using concat you need to create:

* A concat{} resource for the final file.
Pete Soloway's avatar
Pete Soloway committed
30
* One or more concat::fragment{}s.
31

32
A minimal example might be:
33

Pete Soloway's avatar
Pete Soloway committed
34
~~~
35 36 37
concat { '/tmp/file':
  ensure => present,
}
38

39
concat::fragment { 'tmpfile':
40
  target  => '/tmp/file',
41 42 43
  content => 'test contents',
  order   => '01'
}
Pete Soloway's avatar
Pete Soloway committed
44
~~~
45

clairecadman's avatar
clairecadman committed
46
<a id="usage"></a>
47
## Usage
48

49
### Maintain a list of the major modules on a node
50

Pete Soloway's avatar
Pete Soloway committed
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

Pete Soloway's avatar
Pete Soloway committed
53
~~~
54
class motd {
55 56 57 58 59 60 61 62
  $motd = '/etc/motd'

  concat { $motd:
    owner => 'root',
    group => 'root',
    mode  => '0644'
  }

63
  concat::fragment { 'motd_header':
64 65 66 67 68
    target  => $motd,
    content => "\nPuppet modules on this server:\n\n",
    order   => '01'
  }

Pete Soloway's avatar
Pete Soloway committed
69
  # let local users add to the motd by creating a file called
70
  # /etc/motd.local
71
  concat::fragment { 'motd_local':
72 73 74 75
    target => $motd,
    source => '/etc/motd.local',
    order  => '15'
  }
76 77
}

Pete Soloway's avatar
Pete Soloway committed
78
# let other modules register themselves in the motd
79 80 81 82
define motd::register (
  $content = "",
  $order   = '10',
) {
83 84 85 86 87 88
  if $content == "" {
    $body = $name
  } else {
    $body = $content
  }

89
  concat::fragment { "motd_fragment_$name":
90
    target  => '/etc/motd',
Max Griffiths's avatar
Max Griffiths committed
91
    order   => $order,
92 93
    content => "    -- $body\n"
  }
94
}
Pete Soloway's avatar
Pete Soloway committed
95
~~~
96

Pete Soloway's avatar
Pete Soloway committed
97
Then, in the declarations for each module on the node, add `motd::register{ 'Apache': }` to register the module in the motd.
98

Pete Soloway's avatar
Pete Soloway committed
99
~~~
100
class apache {
101
  include apache::install, apache::config, apache::service
102

103
  motd::register { 'Apache': }
104
}
Pete Soloway's avatar
Pete Soloway committed
105
~~~
106

Pete Soloway's avatar
Pete Soloway committed
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

Pete Soloway's avatar
Pete Soloway committed
109
When you're finished, the motd file will look something like this:
110

Pete Soloway's avatar
Pete Soloway committed
111 112
~~~
  Puppet modules on this server:
113

Pete Soloway's avatar
Pete Soloway committed
114 115
    -- Apache
    -- MySQL
116

Pete Soloway's avatar
Pete Soloway committed
117 118
  <contents of /etc/motd.local>
~~~
119

clairecadman's avatar
clairecadman committed
120
<a id="reference"></a>
121
## Reference
122

123
See [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-concat/blob/main/REFERENCE.md)
124

clairecadman's avatar
clairecadman committed
125
<a id="removed-functionality"></a>
126
### Removed functionality
127 128 129 130 131 132 133 134 135 136 137 138

The following functionality existed in previous versions of the concat module, but was removed in version 2.0.0:

Parameters removed from `concat::fragment`:
* `gnu`
* `backup`
* `group`
* `mode`
* `owner`

The `concat::setup` class has also been removed.

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.
R.I.Pienaar's avatar
R.I.Pienaar committed
140

clairecadman's avatar
clairecadman committed
141
<a id="limitations"></a>
142
## Limitations
R.I.Pienaar's avatar
R.I.Pienaar committed
143

Pete Soloway's avatar
Pete Soloway committed
144
This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified.
R.I.Pienaar's avatar
R.I.Pienaar committed
145

146
For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-concat/blob/main/metadata.json)
147

148
## Development
R.I.Pienaar's avatar
R.I.Pienaar committed
149

150 151 152
Acceptance tests for this module leverage [puppet_litmus](https://github.com/puppetlabs/puppet_litmus).
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).
You can also find a tutorial and walkthrough of using Litmus and the PDK on [YouTube](https://www.youtube.com/watch?v=FYfR7ZEGHoE).
tphoney's avatar
tphoney committed
153

154 155
If you run into an issue with this module, or if you would like to request a feature, please [file a ticket](https://tickets.puppetlabs.com/browse/MODULES/).
Every Monday the Puppet IA Content Team has [office hours](https://puppet.com/community/office-hours) in the [Puppet Community Slack](http://slack.puppet.com/), alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).
R.I.Pienaar's avatar
R.I.Pienaar committed
156

157
If you have problems getting this module up and running, please [contact Support](http://puppetlabs.com/services/customer-support).
R.I.Pienaar's avatar
R.I.Pienaar committed
158

159 160 161 162 163
If you submit a change to this module, be sure to regenerate the reference documentation as follows:

```bash
puppet strings generate --format markdown --out REFERENCE.md
```
R.I.Pienaar's avatar
R.I.Pienaar committed
164

165
### Contributors
166

167 168 169 170
Richard Pijnenburg ([@Richardp82](http://twitter.com/richardp82))

Joshua Hoblitt ([@jhoblitt](http://twitter.com/jhoblitt))

171
[More contributors](https://github.com/puppetlabs/puppetlabs-concat/graphs/contributors).