Skip to content

Commit d428281

Browse files
xbezdickxbezdick
committed
Update inifile to 57c68ba
57c68ba Merge pull request redhat-openstack#154 from psoloway/master 9789615 Updates README per DOC-1502
1 parent bec3ace commit d428281

2 files changed

Lines changed: 113 additions & 99 deletions

File tree

‎Puppetfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ mod 'horizon',
5959
:git => 'https://github.com/stackforge/puppet-horizon.git'
6060

6161
mod 'inifile',
62-
:commit => '606de6971d019fa9557d0866e90942a3d6e06a97',
62+
:commit => '57c68ba9ec6b5c255e89b28f91e56b2bfab50202',
6363
:git => 'https://github.com/puppetlabs/puppetlabs-inifile.git'
6464

6565
mod 'ipa',

‎inifile/README.markdown‎

Lines changed: 112 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
2-
3-
#INI file
1+
#inifile
42

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

@@ -9,74 +7,77 @@
97
1. [Overview](#overview)
108
2. [Module Description - What the module does and why it is useful](#module-description)
119
3. [Setup - The basics of getting started with inifile module](#setup)
12-
* [Setup requirements](#setup-requirements)
1310
* [Beginning with inifile](#beginning-with-inifile)
1411
4. [Usage - Configuration options and additional functionality](#usage)
1512
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
1613
5. [Limitations - OS compatibility, etc.](#limitations)
1714
6. [Development - Guide for contributing to the module](#development)
1815

19-
##Overview
16+
##Overview
2017

21-
This module adds resource types to manage settings in INI-style configuration files.
18+
The inifile module lets Puppet manage settings stored in INI-style configuration files.
2219

2320
##Module Description
2421

25-
The inifile module adds two resource types so that you can use Puppet to manage settings and subsettings in INI-style configuration files.
26-
27-
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.
28-
29-
###Noteworthy module features include:
30-
31-
* Supports comments starting with either '#' or ';'.
32-
* Supports either whitespace or no whitespace around '='.
33-
* Adds any missing sections to the INI file.
22+
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.
3423

3524
##Setup
3625

37-
##Beginning with inifile
26+
###Beginning with inifile
3827

39-
To manage an INI file, add the resource type `ini_setting` or `ini_subsetting` to a class.
4028

41-
##Usage
29+
To manage a single setting in an INI file, add the `ini_setting` type to a class:
4230

43-
Manage individual settings in INI files by adding the `ini_setting` resource type to a class. For example:
44-
45-
```
31+
~~~
4632
ini_setting { "sample setting":
4733
ensure => present,
4834
path => '/tmp/foo.ini',
49-
section => 'foo',
50-
setting => 'foosetting',
51-
value => 'FOO!',
35+
section => 'bar',
36+
setting => 'baz',
37+
value => 'quux',
5238
}
53-
```
39+
~~~
40+
41+
##Usage
42+
43+
44+
The inifile module tries hard not to manipulate your file any more than it needs to. In most cases, it doesn't affect the original whitespace, comments, ordering, etc.
5445

55-
To control multiple values in a setting, use `ini_subsetting`. For example:
5646

57-
```
47+
* Supports comments starting with either '#' or ';'.
48+
* Supports either whitespace or no whitespace around '='.
49+
* Adds any missing sections to the INI file.
50+
51+
###Manage multiple values in a setting
52+
53+
Use the `ini_subsetting` type:
54+
55+
~~~
5856
JAVA_ARGS="-Xmx192m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof "
5957
6058
ini_subsetting {'sample subsetting':
61-
ensure => present,
62-
section => '',
59+
ensure => present,
60+
section => '',
6361
key_val_separator => '=',
64-
path => '/etc/default/pe-puppetdb',
65-
setting => 'JAVA_ARGS',
66-
subsetting => '-Xmx',
67-
value => '512m',
62+
path => '/etc/default/pe-puppetdb',
63+
setting => 'JAVA_ARGS',
64+
subsetting => '-Xmx',
65+
value => '512m',
6866
}
69-
```
67+
~~~
68+
69+
###Implement child providers
7070

71-
###Implementing child providers:
7271

73-
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+
You might want to create child providers that inherit the `ini_setting` provider, for one or both of these purposes:
7473

75-
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+
* Make a custom resource to manage an application that stores its settings in INI files, without recreating the code to manage the files themselves.
7675

77-
For example:
76+
* [Purge all unmanaged settings](https://docs.puppetlabs.com/references/latest/type.html#resources-attribute-purge) from a managed INI file.
7877

79-
```
78+
To implement child providers, first specify a custom type. Have it implement a namevar called `name` and a property called `value`:
79+
80+
~~~
8081
#my_module/lib/puppet/type/glance_api_config.rb
8182
Puppet::Type.newtype(:glance_api_config) do
8283
ensurable
@@ -86,17 +87,17 @@ Puppet::Type.newtype(:glance_api_config) do
8687
newvalues(/\S+\/\S+/)
8788
end
8889
newproperty(:value) do
89-
desc 'The value of the setting to be defined.'
90+
desc 'The value of the setting to define'
9091
munge do |v|
9192
v.to_s.strip
9293
end
9394
end
9495
end
95-
```
96+
~~~
9697

97-
This type must also have a provider that uses the `ini_setting` provider as its parent. For example:
98+
Your type also needs a provider that uses the `ini_setting` provider as its parent:
9899

99-
```
100+
~~~
100101
# my_module/lib/puppet/provider/glance_api_config/ini_setting.rb
101102
Puppet::Type.type(:glance_api_config).provide(
102103
:ini_setting,
@@ -116,111 +117,124 @@ Puppet::Type.type(:glance_api_config).provide(
116117
'/etc/glance/glance-api.conf'
117118
end
118119
end
119-
```
120+
~~~
120121

121-
Now the individual settings of the /etc/glance/glance-api.conf file can be managed as individual resources:
122+
Now the settings in /etc/glance/glance-api.conf file can be managed as individual resources:
122123

123-
```
124+
~~~
124125
glance_api_config { 'HEADER/important_config':
125126
value => 'secret_value',
126127
}
127-
```
128+
~~~
128129

129-
If the self.file_path has been implemented, you can purge with the following Puppet syntax:
130+
If you've implemented self.file_path, you can have Puppet purge the file of all lines that aren't implemented as Puppet resources:
130131

131-
```
132+
~~~
132133
resources { 'glance_api_config'
133134
purge => true,
134135
}
135-
```
136-
137-
If the above code is added, the resulting configured file will contain only lines implemented as Puppet resources.
136+
~~~
138137

139138
##Reference
140139

141-
###Type: ini_setting
140+
###Public Types
141+
142+
* [`ini_setting`](#type-ini_setting)
143+
144+
* [`ini_subsetting`](#type-ini_subsetting)
145+
146+
### Type: ini_setting
147+
148+
Manages a setting within an INI file.
142149

143150
#### Parameters
144151

145-
* `ensure`: Ensures that the resource is present. Valid values are 'present', 'absent'.
152+
##### `ensure`
153+
154+
Determines whether the specified setting should exist. Valid options: 'present' and 'absent'. Default value: 'present'.
155+
156+
##### `key_val_separator`
157+
158+
*Optional.* Specifies a string to use between each setting name and value (e.g., to determine whether the separator includes whitespace). Valid options: a string. Default value: ' = '.
159+
160+
##### `name`
161+
162+
*Optional.* Specifies an arbitrary name to identify the resource. Valid options: a string. Default value: the title of your declared resource.
146163

147-
* `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).
164+
##### `path`
148165

149-
* `name`: An arbitrary name used as the identity of the resource.
166+
*Required.* Specifies an INI file containing the setting to manage. Valid options: a string containing an absolute path.
150167

151-
* `path`: The INI file in which Puppet ensures the specified setting.
168+
##### `section`
152169

153-
* `provider`: The specific backend to use for this `ini_setting` resource. You will seldom need to specify this --- Puppet usually discovers the appropriate provider for your platform. The only available provider for `ini_setting` is ruby.
170+
*Required.* 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.
154171

155-
* `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 "".
172+
##### `setting`
156173

157-
* `setting`: The name of the INI file setting to be defined.
174+
*Required.* Designates a setting to manage within the specified INI file and section. Valid options: a string.
158175

159-
* `value`: The value of the INI file setting to be defined.
176+
##### `value`
160177

161-
###Type: ini_subsetting
178+
*Optional.* Supplies a value for the specified setting. Valid options: a string. Default value: undefined.
179+
180+
### Type: ini_subsetting
181+
182+
183+
Manages multiple values within the same INI setting.
162184

163185
#### Parameters
164186

165-
* `ensure`: Ensures that the resource is present. Valid values are 'present', 'absent'.
187+
##### `ensure`
166188

167-
* `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).
189+
Specifies whether the subsetting should be present. Valid options: 'present' and 'absent'. Default value: 'present'.
168190

169-
* `name`: An arbitrary name used as the identity of the resource.
191+
##### `key_val_separator`
170192

171-
* `path`: The INI file in which Puppet ensures the specified setting.
193+
*Optional.* Specifies a string to use between subsetting name and value (e.g., to determine whether the separator includes whitespace). Valid options: a string. Default value: ' = '.
172194

173-
* `provider`: The specific backend to use for this `ini_subsetting` resource. You will seldom need to specify this --- Puppet usually discovers the appropriate provider for your platform. The only available provider for `ini_subsetting` is ruby.
195+
##### `path`
174196

175-
* `quote_char`: The character used to quote the entire value of the setting. Valid values are '', '"', and "'". Defaults to ''.
197+
*Required.* Specifies an INI file containing the subsetting to manage. Valid options: a string containing an absolute path.
176198

177-
* `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 "".
199+
##### `quote_char`
178200

179-
* `setting`: The name of the INI file setting to be defined.
201+
*Optional.* The character used to quote the entire value of the setting. Valid values are '', '"', and "'". Defaults to ''. Valid options: '', '"' and "'". Default value: ''.
180202

181-
* `subsetting`: The name of the INI file subsetting to be defined.
203+
##### `section`
182204

183-
* `subsetting_separator`: The separator string used between subsettings. Defaults to " ".
205+
*Required.* Designates a section of the specified INI file containing the subsetting to manage. To manage a global setting (at the beginning of the file, before any named sections) enter "". Valid options: a string, or "".
184206

185-
* `value`: The value of the INI file subsetting to be defined.
207+
##### `setting`
186208

187-
##Limitations
209+
*Required.* Designates a setting within the specified section containing the subsetting to manage. Valid options: a string.
188210

189-
This module is officially [supported](https://forge.puppetlabs.com/supported) on :
211+
##### `subsetting`
190212

191-
* Red Hat Enterprise Linux (RHEL) 5, 6, 7
192-
* CentOS 5, 6, 7
193-
* Oracle Linux 5, 6, 7
194-
* Scientific Linux 5, 6, 7
195-
* SLES 11 SP1 or greater
196-
* Debian 6, 7
197-
* Ubuntu 10.04 LTS, 12.04 LTS, 14.04 LTS
198-
* Solaris 10, 11
199-
* Windows Server 2003/2008 R2, 2012/2012 R2
200-
* AIX 5.3, 6.1, 7.1
213+
*Required.* Designates a subsetting to manage within the specified setting. Valid options: a string.
201214

202-
This module has also been tested, but is not officially supported, on:
203215

204-
* Red Hat Enterprise Linux (RHEL) 4
205-
* Windows 7
206-
* Mac OSX 10.9 (Mavericks)
216+
##### `subsetting_separator`
207217

208-
### Agent run failure with Puppet Enterprise
218+
*Optional.* Specifies a string to use between subsettings. Valid options: a string. Default value: " ".
209219

210-
As of Puppet Enterprise 3.3, agent runs on master fail if you are using an older, manually installed version of inifile. To solve this problem, upgrade your inifile module to version 1.1.0 or later.
220+
##### `value`
211221

212-
##Development
213-
214-
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.
222+
*Optional.* Supplies a value for the specified subsetting. Valid options: a string. Default value: undefined.
215223

216-
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.
224+
##Limitations
217225

218-
You can read the complete module contribution guide in [CONTRIBUTING.md](./CONTRIBUTING.md)
226+
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 and Mac OS X 10.9.
219227

220-
##Contributors
228+
##Development
221229

222-
The list of contributors can be found at: [https://github.com/puppetlabs/puppetlabs-inifile/graphs/contributors](https://github.com/puppetlabs/puppetlabs-inifile/graphs/contributors).
230+
#Development
223231

232+
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.
233+
234+
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.
224235

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

238+
###Contributors
226239

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

0 commit comments

Comments
 (0)