File: README.markdown

package info (click to toggle)
puppet-module-puppetlabs-inifile 2.2.1-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 424 kB
  • sloc: ruby: 3,703; sh: 7; makefile: 5
file content (600 lines) | stat: -rw-r--r-- 16,170 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
# inifile

[![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-inifile.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-inifile)

#### Table of Contents

1. [Overview](#overview)
2. [Module Description - What the module does and why it is useful](#module-description)
3. [Setup - The basics of getting started with inifile module](#setup)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
5. [Limitations - OS compatibility, etc.](#limitations)
6. [Development - Guide for contributing to the module](#development)

## Overview

The inifile module lets Puppet manage settings stored in INI-style configuration files.

## Module Description

Many applications use INI-style configuration files to store their settings. This module supplies two custom resource types to let you manage those settings through Puppet.

## Setup

### Beginning with inifile

To manage a single setting in an INI file, add the `ini_setting` type to a class:

~~~puppet
ini_setting { "sample setting":
  ensure  => present,
  path    => '/tmp/foo.ini',
  section => 'bar',
  setting => 'baz',
  value   => 'quux',
}
~~~

## Usage


The inifile module is used to: 

 * Support comments starting with either '#' or ';'.
 * Support either whitespace or no whitespace around '='.
 * Add any missing sections to the INI file.
 
It does not manipulate your file any more than it needs to. In most cases, it doesn't affect the original whitespace, comments, or ordering. See the common usages below for examples.

### Manage multiple values in a setting

Use the `ini_subsetting` type:

~~~puppet
ini_subsetting {'sample subsetting':
  ensure            => present,
  section           => '',
  key_val_separator => '=',
  path              => '/etc/default/pe-puppetdb',
  setting           => 'JAVA_ARGS',
  subsetting        => '-Xmx',
  value             => '512m',
}
~~~

Results in managing this `-Xmx` subsetting:

~~~puppet
JAVA_ARGS="-Xmx512m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof"
~~~


### Use a non-standard section header

~~~puppet
ini_setting { 'default minage':
  ensure         => present,
  path           => '/etc/security/users',
  section        => 'default',
  setting        => 'minage',
  value          => '1',
  section_prefix => '',
  section_suffix => ':',
}
~~~

Results in:

~~~puppet
default:
   minage = 1
~~~

### Use a non-standard indent character

To use a non-standard indent character or string for added settings, set the `indent_char` and the `indent_width` parameters. The `indent_width` parameter controls how many `indent_char` appear in the indent.


~~~puppet
ini_setting { 'procedure cache size':
  ensure         => present,
  path           => '/var/lib/ase/config/ASE-16_0/SYBASE.cfg',
  section        => 'SQL Server Administration',
  setting        => 'procedure cache size',
  value          => '15000',
  indent_char    => "\t",
  indent_width   => 2,
}
~~~

Results in:

~~~puppet
[SQL Server Administration]
		procedure cache size = 15000
~~~

### Implement child providers

You might want to create child providers that inherit the `ini_setting` provider for one of the following reasons:

 * To make a custom resource to manage an application that stores its settings in INI files, without recreating the code to manage the files themselves.
 * To [purge all unmanaged settings](https://docs.puppetlabs.com/references/latest/type.html#resources-attribute-purge) from a managed INI file.

To implement child providers, first specify a custom type. Have it implement a namevar called `name` and a property called `value`:

~~~ruby
#my_module/lib/puppet/type/glance_api_config.rb
Puppet::Type.newtype(:glance_api_config) do
  ensurable
  newparam(:name, :namevar => true) do
    desc 'Section/setting name to manage from glance-api.conf'
    # namevar should be of the form section/setting
    newvalues(/\S+\/\S+/)
  end
  newproperty(:value) do
    desc 'The value of the setting to define'
    munge do |v|
      v.to_s.strip
    end
  end
end
~~~

Your type also needs a provider that uses the `ini_setting` provider as its parent:

~~~ruby
# my_module/lib/puppet/provider/glance_api_config/ini_setting.rb
Puppet::Type.type(:glance_api_config).provide(
  :ini_setting,
  # set ini_setting as the parent provider
  :parent => Puppet::Type.type(:ini_setting).provider(:ruby)
) do
  # implement section as the first part of the namevar
  def section
    resource[:name].split('/', 2).first
  end
  def setting
    # implement setting as the second part of the namevar
    resource[:name].split('/', 2).last
  end
  # hard code the file path (this allows purging)
  def self.file_path
    '/etc/glance/glance-api.conf'
  end
end
~~~

Now you can manage the settings in the `/etc/glance/glance-api.conf` file as individual resources:

~~~puppet
glance_api_config { 'HEADER/important_config':
  value => 'secret_value',
}
~~~

If you've implemented `self.file_path`, you can have Puppet purge the file of the all lines that aren't implemented as Puppet resources:

~~~puppet
resources { 'glance_api_config'
  purge => true,
}
~~~

### Manage multiple ini_settings

To manage multiple `ini_settings`, use the [`create_ini_settings`](#function-create_ini_settings) function.

~~~puppet
$defaults = { 'path' => '/tmp/foo.ini' }
$example = { 'section1' => { 'setting1' => 'value1' } }
create_ini_settings($example, $defaults)
~~~

Results in:

~~~puppet
ini_setting { '[section1] setting1':
  ensure  => present,
  section => 'section1',
  setting => 'setting1',
  value   => 'value1',
  path    => '/tmp/foo.ini',
}
~~~

To include special parameters, use the following code:

~~~puppet
$defaults = { 'path' => '/tmp/foo.ini' }
$example = {
  'section1' => {
    'setting1'  => 'value1',
    'settings2' => {
      'ensure' => 'absent'
    }
  }
}
create_ini_settings($example, $defaults)
~~~

Results in:

~~~puppet
ini_setting { '[section1] setting1':
  ensure  => present,
  section => 'section1',
  setting => 'setting1',
  value   => 'value1',
  path    => '/tmp/foo.ini',
}
ini_setting { '[section1] setting2':
  ensure  => absent,
  section => 'section1',
  setting => 'setting2',
  path    => '/tmp/foo.ini',
}
~~~

#### Manage multiple ini_settings with Hiera

This example requires Puppet 3.x/4.x, as it uses automatic retrieval of Hiera data for class parameters and `puppetlabs/stdlib`.

For the profile `example`:

~~~puppet
class profile::example (
  $settings,
) {
  validate_hash($settings)
  $defaults = { 'path' => '/tmp/foo.ini' }
  create_ini_settings($settings, $defaults)
}
~~~

Provide this in your Hiera data:

~~~puppet
profile::example::settings:
  section1:
    setting1: value1
    setting2: value2
    setting3:
      ensure: absent
~~~

Results in:

~~~puppet
ini_setting { '[section1] setting1':
  ensure  => present,
  section => 'section1',
  setting => 'setting1',
  value   => 'value1',
  path    => '/tmp/foo.ini',
}
ini_setting { '[section1] setting2':
  ensure  => present,
  section => 'section1',
  setting => 'setting2',
  value   => 'value2',
  path    => '/tmp/foo.ini',
}
ini_setting { '[section1] setting3':
  ensure  => absent,
  section => 'section1',
  setting => 'setting3',
  path    => '/tmp/foo.ini',
}
~~~


## Reference

### Public Types

 * [`ini_setting`](#type-ini_setting)

 * [`ini_subsetting`](#type-ini_subsetting)

### Public Functions

 * [`create_ini_settings`](#function-create_ini_settings)

### Type: ini_setting

Manages a setting within an INI file.

#### Parameters

All parameters are optional unless specified as required.

##### `ensure`

Determines whether the specified setting should exist. 

Valid options: 'present' and 'absent'. 

Default value: 'present'.

##### `key_val_separator`

Specifies a string to use between each setting name and value, for example, to determine whether the separator includes whitespace. 

Valid options: a string. 

Default value: ' = '.

##### `name`

Specifies an arbitrary name to identify the resource. 

Valid options: a string. 

Default value: the title of your declared resource.

##### `path`

*Required.* 

Specifies an INI file containing the setting to manage. 

Valid options: a string containing an absolute path.

##### `section`

Designates a section of the specified INI file containing the setting to manage. To manage a global setting (at the beginning of the file, before any named sections) enter "". 

Valid options: a string.

Default value: "". 

##### `setting`

*Required.* 

Designates a setting to manage within the specified INI file and section. 

Valid options: a string.

##### `show_diff`

Prevents outputting actual values to the logfile. This is useful for the handling of passwords and other sensitive information. Possible values are:
  * `true`: This allows all values to be passed to logfiles. (default)
  * `false`: The values in the logfiles will be replaced with `[redacted sensitive information]`.
  * `md5`: The values in the logfiles will be replaced with their md5 hash.

Global `show_diff` configuration takes priority over this one:
[https://docs.puppetlabs.com/references/latest/configuration.html#showdiff]([https://docs.puppetlabs.com/references/latest/configuration.html#showdiff].
). Default value: `true`.

##### `value`

Supplies a value for the specified setting. 

Valid options: a string. 

Default value: `undef`.

##### `section_prefix`

Designates the string to appear before the section's name.  

Default value: "["

##### `section_suffix`
  
Designates the string to appear after the section's name.  

Default value: "]".

##### `indent_char`

Designates the character (or string) to indent newly created settings. This does not affect settings that already exist in the file, even if they change. 

Default value: " ".

##### `indent_width`
 
Designates the number of `indent_char` with which to indent newly inserted settings. If this is not defined, the indentation is automatically computed from existing settings in the section, or if the section does not yet exist, no indent is made. This does not affect settings that already exist in the file, even if they change.

##### `refreshonly`

A Boolean to indicate whether the value associated with the setting should be updated, if this resource is only part of a refresh event.  

Default value: `false`.

For example, if we want a timestamp associated with the last time a setting's value was updated, we could do something like this:

~~~
ini_setting { 'foosetting':
  ensure  => present,
  path    => '/tmp/file.ini',
  section => 'foo',
  setting => 'foosetting',
  value   => 'bar',
  notify  => Ini_Setting['foosetting_timestamp'],
}

$now = strftime('%Y-%m-%d %H:%M:%S')
ini_setting {'foosetting_timestamp':
  ensure      => present,
  path        => '/tmp/file.ini',
  section     => 'foo',
  setting     => 'foosetting_timestamp',
  value       => $now,
  refreshonly => true,
}
~~~

**NOTE:** This type finds all sections in the file by looking for lines like `${section_prefix}${title}${section_suffix}`.

### Type: ini_subsetting

Manages multiple values within the same INI setting.

#### Parameters

All parameters are optional unless specified as required.

##### `ensure`

Specifies whether the subsetting should be present. 

Valid options: 'present' and 'absent'. 

Default value: 'present'.

##### `key_val_separator`

Specifies a string to use between setting name and value, for example, to determine whether the separator includes whitespace. 

Valid options: a string. 

Default value: ' = '.

##### `path`

*Required.* 

Specifies an INI file containing the subsetting to manage. 

Valid options: a string containing an absolute path.

##### `quote_char`

The character used to quote the entire value of the setting.

Valid options: '', '"' and "'". 

Default value: ''.

##### `section`

Designates a section of the specified INI file containing the setting to manage. You can manage a global setting by putting it at the beginning of the file, before any named sections, and entering "".  

Valid options: a string.

Default value: "".

##### `setting`

*Required.* 

Designates a setting within the specified section containing the subsetting to manage. 

Valid options: a string.

##### `show_diff`

Prevents outputting actual values to the logfile. This is useful for the handling of passwords and other sensitive information. Possible values are:
  * `true`: This allows all values to be passed to logfiles. (default)
  * `false`: The values in the logfiles will be replaced with `[redacted sensitive information]`.
  * `md5`: The values in the logfiles will be replaced with their md5 hash.

Global show_diff configuraton takes priority over this one -
[https://docs.puppetlabs.com/references/latest/configuration.html#showdiff]([https://docs.puppetlabs.com/references/latest/configuration.html#showdiff].
). Default value: 'true'.

##### `subsetting`

*Required.* 

Designates a subsetting to manage within the specified setting. 

Valid options: a string.

##### `subsetting_separator`

Specifies a string to use between subsettings. 

Valid options: a string. 

Default value: " ".

##### `subsetting_key_val_separator`

Specifies a string to use between the subsetting name and value (if there is a separator between the subsetting name and its value). 

Valid options: a string. 

Default value: empty string.

##### `use_exact_match`

Whether to use partial or exact matching for subsetting. This should be set to `true` if the subsettings do not have values. 

Valid options: `true`, `false`. 

Default value: `false`.

##### `value`

Supplies a value for the specified subsetting. 

Valid options: a string. 

Default value: `undef`.

##### `insert_type`

Selects where a new subsetting item should be inserted.

* *start*  - insert at the beginning of the line.
* *end*    - insert at the end of the line (default).
* *before* - insert before the specified element if possible.
* *after*  - insert after the specified element if possible.
* *index*  - insert at the specified index number.

##### `insert_value`

The value for the insert type, if the value is required.

### Function: `create_ini_settings`

Manages multiple `ini_setting` resources from a hash. Note that this cannot be used with ini_subsettings.

`create_ini_settings($settings, $defaults)`

#### Arguments

##### First argument: `settings`

*Required.* 

Specifies a hash representing the `ini_setting` resources you want to create.

##### Second argument: `defaults`

Accepts a hash to be used as the values for attributes not defined in the first argument.

~~~puppet
$example = {
  'section1' => {
    'setting1' => {
      'value' => 'value1', 'path' => '/tmp/foo.ini'
    }
  }
}
~~~

Default value: '{}'.

## Limitations

This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified. Additionally, it is tested (but not supported) on Windows 7, Mac OS X 10.9, and Solaris 12.

Due to (PUP-4709) the create_ini_settings function will cause errors when attempting to create multiple ini_settings in one go when using Puppet 4.0.x or 4.1.x. If needed, the temporary fix for this can be found here: https://github.com/puppetlabs/puppetlabs-inifile/pull/196.

## Development

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.

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.

For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html)

### Contributors

To see who's already involved, see the [list of contributors.](https://github.com/puppetlabs/puppetlabs-inifile/graphs/contributors)