Skip to content

Commit 9f9e1d4

Browse files
author
jbondpdx
committed
Docs: New inifile readme
1 parent d6335f5 commit 9f9e1d4

1 file changed

Lines changed: 193 additions & 80 deletions

File tree

‎README.markdown‎

Lines changed: 193 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,220 @@
11
[![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-inifile.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-inifile)
22

3-
# INI-file module #
3+
#INI file
44

5-
This module provides resource types for use in managing INI-style configuration
6-
files. The main resource type is `ini_setting`, which is used to manage an
7-
individual setting in an INI file. Here's an example usage:
5+
####Table of Contents
86

9-
ini_setting { "sample setting":
10-
ensure => present,
11-
path => '/tmp/foo.ini',
12-
section => 'foo',
13-
setting => 'foosetting',
14-
value => 'FOO!',
15-
}
7+
1. [Overview](#overview)
8+
2. [Module Description - What the module does and why it is useful](#module-description)
9+
3. [Setup - The basics of getting started with inifile module](#setup)
10+
* [Setup requirements](#setup-requirements)
11+
* [Beginning with inifile](#beginning-with-inifile)
12+
4. [Usage - Configuration options and additional functionality](#usage)
13+
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
14+
5. [Limitations - OS compatibility, etc.](#limitations)
15+
6. [Development - Guide for contributing to the module](#development)
1616

17-
A supplementary resource type is `ini_subsetting`, which is used to manage
18-
settings that consist of several arguments such as
17+
##Overview
1918

20-
JAVA_ARGS="-Xmx192m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof "
19+
This module adds resource types to manage settings in INI-style configuration files.
2120

22-
ini_subsetting {'sample subsetting':
23-
ensure => present,
24-
section => '',
25-
key_val_separator => '=',
26-
path => '/etc/default/pe-puppetdb',
27-
setting => 'JAVA_ARGS',
28-
subsetting => '-Xmx',
29-
value => '512m',
30-
}
21+
##Module Description
3122

32-
## implementing child providers:
23+
The inifile module adds two resource types so that you can use Puppet to manage settings and subsettings in INI-style configuration files.
3324

25+
This module tries hard not to manipulate your file any more than it needs to. In most cases, it should leave the original whitespace, comments, ordering, etc. intact.
3426

35-
The ini_setting class can be overridden by child providers in order to implement the management of ini settings for a specific configuration file.
27+
###Noteworthy module features include:
3628

37-
In order to implement this, you will need to specify your own Type (as shown below). This type needs to implement a namevar (name), and a property called value:
38-
39-
40-
example:
41-
42-
#my_module/lib/puppet/type/glance_api_config.rb
43-
Puppet::Type.newtype(:glance_api_config) do
44-
ensurable
45-
newparam(:name, :namevar => true) do
46-
desc 'Section/setting name to manage from glance-api.conf'
47-
# namevar should be of the form section/setting
48-
newvalues(/\S+\/\S+/)
49-
end
50-
newproperty(:value) do
51-
desc 'The value of the setting to be defined.'
52-
munge do |v|
53-
v.to_s.strip
29+
* Supports comments starting with either '#' or ';'.
30+
* Supports either whitespace or no whitespace around '='.
31+
* Adds any missing sections to the INI file.
32+
33+
##Setup
34+
35+
##Beginning with inifile
36+
37+
To manage an INI file, add the resource type `ini_setting` or `ini_subsetting` to a class.
38+
39+
##Usage
40+
41+
Manage individual settings in INI files by adding the `ini_setting` resource type to a class. For example:
42+
43+
```
44+
ini_setting { "sample setting":
45+
ensure => present,
46+
path => '/tmp/foo.ini',
47+
section => 'foo',
48+
setting => 'foosetting',
49+
value => 'FOO!',
50+
}
51+
```
52+
53+
To control multiple values in a setting, use `ini_subsetting`. For example:
54+
55+
```
56+
JAVA_ARGS="-Xmx192m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof "
57+
58+
ini_subsetting {'sample subsetting':
59+
ensure => present,
60+
section => '',
61+
key_val_separator => '=',
62+
path => '/etc/default/pe-puppetdb',
63+
setting => 'JAVA_ARGS',
64+
subsetting => '-Xmx',
65+
value => '512m',
66+
}
67+
```
68+
69+
###Implementing child providers:
70+
71+
You can set up custom child providers that inherit the `ini_setting` provider. This allows you to implement custom resources to manage INI settings for specific configuration files without copying all the code or writing your own code from scratch. This also allows resource purging to be used.
72+
73+
To implement child providers, you'll need to specify your own type. This type needs to implement a namevar (name) and a property called value:
74+
75+
For example:
76+
77+
```
78+
#my_module/lib/puppet/type/glance_api_config.rb
79+
Puppet::Type.newtype(:glance_api_config) do
80+
ensurable
81+
newparam(:name, :namevar => true) do
82+
desc 'Section/setting name to manage from glance-api.conf'
83+
# namevar should be of the form section/setting
84+
newvalues(/\S+\/\S+/)
85+
end
86+
newproperty(:value) do
87+
desc 'The value of the setting to be defined.'
88+
munge do |v|
89+
v.to_s.strip
5490
end
5591
end
5692
end
93+
```
5794

58-
This type also must have a provider that utilizes the ini_setting provider as its parent:
95+
This type must also have a provider that uses the `ini_setting` provider as its parent. For example:
5996

60-
example:
97+
```
98+
# my_module/lib/puppet/provider/glance_api_config/ini_setting.rb
99+
Puppet::Type.type(:glance_api_config).provide(
100+
:ini_setting,
101+
# set ini_setting as the parent provider
102+
:parent => Puppet::Type.type(:ini_setting).provider(:ruby)
103+
) do
104+
# implement section as the first part of the namevar
105+
def section
106+
resource[:name].split('/', 2).first
107+
end
108+
def setting
109+
# implement setting as the second part of the namevar
110+
resource[:name].split('/', 2).last
111+
end
112+
# hard code the file path (this allows purging)
113+
def self.file_path
114+
'/etc/glance/glance-api.conf'
115+
end
116+
end
117+
```
61118

62-
# my_module/lib/puppet/provider/glance_api_config/ini_setting.rb
63-
Puppet::Type.type(:glance_api_config).provide(
64-
:ini_setting,
65-
# set ini_setting as the parent provider
66-
:parent => Puppet::Type.type(:ini_setting).provider(:ruby)
67-
) do
68-
# implement section as the first part of the namevar
69-
def section
70-
resource[:name].split('/', 2).first
71-
end
72-
def setting
73-
# implement setting as the second part of the namevar
74-
resource[:name].split('/', 2).last
75-
end
76-
# hard code the file path (this allows purging)
77-
def self.file_path
78-
'/etc/glance/glance-api.conf'
79-
end
80-
end
119+
Now the individual settings of the /etc/glance/glance-api.conf file can be managed as individual resources:
81120

121+
```
122+
glance_api_config { 'HEADER/important_config':
123+
value => 'secret_value',
124+
}
125+
```
82126

83-
Now, the individual settings of the /etc/glance/glance-api.conf file can be managed as individual resources:
127+
If the self.file_path has been implemented, you can purge with the following Puppet syntax:
84128

85-
glance_api_config { 'HEADER/important_config':
86-
value => 'secret_value',
87-
}
129+
```
130+
resources { 'glance_api_config'
131+
purge => true,
132+
}
133+
```
88134

89-
Provided that self.file_path has been implemented, you can purge with the following puppet syntax:
135+
If the above code is added, the resulting configured file will contain only lines implemented as Puppet resources.
90136

91-
resources { 'glance_api_config'
92-
purge => true,
93-
}
137+
##Reference
94138

95-
If the above code is added, then the resulting configured file will only contain lines implemented as Puppet resources
139+
###Type: ini_setting
140+
141+
#### Parameters
142+
143+
* `ensure`: Ensures that the resource is present. Valid values are 'present', 'absent'.
144+
145+
* `key_val_separator`: The separator string to use between each setting name and value. Defaults to ' = ', but you could use this to override the default (e.g., whether or not the separator should include whitespace).
146+
147+
* `name`: An arbitrary name used as the identity of the resource.
148+
149+
* `path`: The INI file in which Puppet will ensure the specified setting.
150+
151+
* `provider`: The specific backend to use for this `ini_setting` resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform. The only available provider for `ini_setting` is ruby.
152+
153+
* `section`: The name of the INI file section in which the setting should be defined. Add a global section --- settings that appear at the beginning of the file, before any named sections --- by specifying a section name of "".
154+
155+
* `setting`: The name of the INI file setting to be defined.
156+
157+
* `value`: The value of the INI file setting to be defined.
158+
159+
###Type: ini_subsetting
160+
161+
#### Parameters
162+
163+
* `ensure`: Ensures that the resource is present. Valid values are 'present', 'absent'.
164+
165+
* `key_val_separator`: The separator string to use between each setting name and value. Defaults to ' = ', but you could use this to override the default (e.g., whether or not the separator should include whitespace).
166+
167+
* `name`: An arbitrary name used as the identity of the resource.
168+
169+
* `path`: The INI file in which Puppet will ensure the specified setting.
170+
171+
* `provider`: The specific backend to use for this `ini_subsetting` resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform. The only available provider for `ini_subsetting` is ruby.
172+
173+
* `quote_char`: The character used to quote the entire value of the setting. Valid values are '', '"', and "'". Defaults to ''.
174+
175+
* `section`: The name of the INI file section in which the setting should be defined. Add a global section --- settings that appear at the beginning of the file, before any named sections --- by specifying a section name of "".
176+
177+
* `setting`: The name of the INI file setting to be defined.
178+
179+
* `subsetting`: The name of the INI file subsetting to be defined.
180+
181+
* `subsetting_separator`: The separator string used between subsettings. Defaults to " ".
182+
183+
* `value`: The value of the INI file subsetting to be defined.
184+
185+
##Limitations
186+
187+
This module is officially [supported](https://forge.puppetlabs.com/supported) on :
188+
189+
* Red Hat Enterprise Linux (RHEL) 5, 6, 7
190+
* CentOS 5, 6, 7
191+
* Oracle Linux 5, 6, 7
192+
* Scientific Linux 5, 6, 7
193+
* SLES 11 SP1 or greater
194+
* Debian 6, 7
195+
* Ubuntu 10.04 LTS, 12.04 LTS, 14.04 LTS
196+
* Solaris 10, 11
197+
* Windows Server 2003/2008 R2, 2012/2012 R2
198+
* AIX 5.3, 6.1, 7.1
199+
200+
This module has also been tested, but is not officially supported, on:
201+
202+
* Red Hat Enterprise Linux (RHEL) 4
203+
* Windows 7
204+
* Mac OSX 10.9 (Mavericks)
205+
206+
##Development
207+
208+
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.
209+
210+
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.
211+
212+
You can read the complete module contribution guide on the [Puppet Labs wiki](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing).
213+
214+
##Contributors
215+
216+
The list of contributors can be found at: [https://github.com/puppetlabs/puppetlabs-inifile/graphs/contributors/contributors](https://github.com/puppetlabs/puppetlabs-inifile/graphs/contributors/contributors).
96217

97218

98-
## A few noteworthy features:
99219

100-
* The module tries *hard* not to manipulate your file any more than it needs to.
101-
In most cases, it should leave the original whitespace, comments, ordering,
102-
etc. perfectly intact.
103-
* Supports comments starting with either '#' or ';'.
104-
* Will add missing sections if they don't exist.
105-
* Supports a "global" section (settings that go at the beginning of the file,
106-
before any named sections) by specifying a section name of "".
107220

0 commit comments

Comments
 (0)
⚡