3rdparty/modules/inifile/README.markdown

   1 #inifile
   2
   3 [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-inifile.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-inifile)
   4
   5 ####Table of Contents
   6
   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     * [Beginning with inifile](#beginning-with-inifile)
  11 4. [Usage - Configuration options and additional functionality](#usage)
  12 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
  13 5. [Limitations - OS compatibility, etc.](#limitations)
  14 6. [Development - Guide for contributing to the module](#development)
  15
  16 ##Overview
  17
  18 The inifile module lets Puppet manage settings stored in INI-style configuration files.
  19
  20 ##Module Description
  21
  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.
  23
  24 ##Setup
  25
  26 ###Beginning with inifile
  27
  28
  29 To manage a single setting in an INI file, add the `ini_setting` type to a class:
  30
  31 ~~~
  32 ini_setting { "sample setting":
  33   ensure  => present,
  34   path    => '/tmp/foo.ini',
  35   section => 'bar',
  36   setting => 'baz',
  37   value   => 'quux',
  38 }
  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.
  45
  46  * Supports comments starting with either '#' or ';'.
  47  * Supports either whitespace or no whitespace around '='.
  48  * Adds any missing sections to the INI file.
  49
  50 ###Manage multiple values in a setting
  51
  52 Use the `ini_subsetting` type:
  53
  54 ~~~
  55 JAVA_ARGS="-Xmx192m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof "
  56
  57 ini_subsetting {'sample subsetting':
  58   ensure            => present,
  59   section           => '',
  60   key_val_separator => '=',
  61   path              => '/etc/default/pe-puppetdb',
  62   setting           => 'JAVA_ARGS',
  63   subsetting        => '-Xmx',
  64   value             => '512m',
  65 }
  66 ~~~
  67
  68 ###Use a non-standard section header
  69
  70 ~~~
  71 default:
  72    minage = 1
  73    maxage = 13
  74
  75 ini_setting { 'default minage':
  76   ensure         => present,
  77   path           => '/etc/security/users',
  78   section        => 'default',
  79   setting        => 'minage',
  80   value          => '1',
  81   section_prefix => '',
  82   section_suffix => ':',
  83 }
  84 ~~~
  85
  86 ###Implement child providers
  87
  88
  89 You might want to create child providers that inherit the `ini_setting` provider, for one or both of these purposes:
  90
  91  * Make a custom resource to manage an application that stores its settings in INI files, without recreating the code to manage the files themselves.
  92
  93  * [Purge all unmanaged settings](https://docs.puppetlabs.com/references/latest/type.html#resources-attribute-purge) from a managed INI file.
  94
  95 To implement child providers, first specify a custom type. Have it implement a namevar called `name` and a property called `value`:
  96
  97 ~~~
  98 #my_module/lib/puppet/type/glance_api_config.rb
  99 Puppet::Type.newtype(:glance_api_config) do
 100   ensurable
 101   newparam(:name, :namevar => true) do
 102     desc 'Section/setting name to manage from glance-api.conf'
 103     # namevar should be of the form section/setting
 104     newvalues(/\S+\/\S+/)
 105   end
 106   newproperty(:value) do
 107     desc 'The value of the setting to define'
 108     munge do |v|
 109       v.to_s.strip
 110     end
 111   end
 112 end
 113 ~~~
 114
 115 Your type also needs a provider that uses the `ini_setting` provider as its parent:
 116
 117 ~~~
 118 # my_module/lib/puppet/provider/glance_api_config/ini_setting.rb
 119 Puppet::Type.type(:glance_api_config).provide(
 120   :ini_setting,
 121   # set ini_setting as the parent provider
 122   :parent => Puppet::Type.type(:ini_setting).provider(:ruby)
 123 ) do
 124   # implement section as the first part of the namevar
 125   def section
 126     resource[:name].split('/', 2).first
 127   end
 128   def setting
 129     # implement setting as the second part of the namevar
 130     resource[:name].split('/', 2).last
 131   end
 132   # hard code the file path (this allows purging)
 133   def self.file_path
 134     '/etc/glance/glance-api.conf'
 135   end
 136 end
 137 ~~~
 138
 139 Now the settings in /etc/glance/glance-api.conf file can be managed as individual resources:
 140
 141 ~~~
 142 glance_api_config { 'HEADER/important_config':
 143   value => 'secret_value',
 144 }
 145 ~~~
 146
 147 If you've implemented self.file_path, you can have Puppet purge the file of all lines that aren't implemented as Puppet resources:
 148
 149 ~~~
 150 resources { 'glance_api_config'
 151   purge => true,
 152 }
 153 ~~~
 154
 155 ##Reference
 156
 157 ###Public Types
 158
 159  * [`ini_setting`](#type-ini_setting)
 160
 161  * [`ini_subsetting`](#type-ini_subsetting)
 162
 163 ### Type: ini_setting
 164
 165 Manages a setting within an INI file.
 166
 167 #### Parameters
 168
 169 ##### `ensure`
 170
 171 Determines whether the specified setting should exist. Valid options: 'present' and 'absent'. Default value: 'present'.
 172
 173 ##### `key_val_separator`
 174
 175 *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: ' = '.
 176
 177 ##### `name`
 178
 179 *Optional.* Specifies an arbitrary name to identify the resource. Valid options: a string. Default value: the title of your declared resource.
 180
 181 ##### `path`
 182
 183 *Required.* Specifies an INI file containing the setting to manage. Valid options: a string containing an absolute path.
 184
 185 ##### `section`
 186
 187 *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.
 188
 189 ##### `setting`
 190
 191 *Optional.* 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 "". Defaults to "". Valid options: a string.
 192
 193 ##### `value`
 194
 195 *Optional.* Supplies a value for the specified setting. Valid options: a string. Default value: undefined.
 196
 197 ##### `section_prefix`
 198
 199 *Optional.*  Designates the string that will appear before the section's name.  Default value: "["
 200
 201 ##### `section_suffix`
 202
 203 *Optional.*  Designates the string that will appear after the section's name.  Default value: "]"
 204
 205 **NOTE:** The way this type finds all sections in the file is by looking for lines like `${section_prefix}${title}${section_suffix}`
 206
 207 ### Type: ini_subsetting
 208
 209
 210 Manages multiple values within the same INI setting.
 211
 212 #### Parameters
 213
 214 ##### `ensure`
 215
 216 Specifies whether the subsetting should be present. Valid options: 'present' and 'absent'. Default value: 'present'.
 217
 218 ##### `key_val_separator`
 219
 220 *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: ' = '.
 221
 222 ##### `path`
 223
 224 *Required.* Specifies an INI file containing the subsetting to manage. Valid options: a string containing an absolute path.
 225
 226 ##### `quote_char`
 227
 228 *Optional.* The character used to quote the entire value of the setting. Valid values are '', '"', and "'". Defaults to ''. Valid options: '', '"' and "'". Default value: ''.
 229
 230 ##### `section`
 231
 232 *Optional.* 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 "". Defaults to "". Valid options: a string.
 233
 234 ##### `setting`
 235
 236 *Required.* Designates a setting within the specified section containing the subsetting to manage. Valid options: a string.
 237
 238 ##### `subsetting`
 239
 240 *Required.* Designates a subsetting to manage within the specified setting. Valid options: a string.
 241
 242
 243 ##### `subsetting_separator`
 244
 245 *Optional.* Specifies a string to use between subsettings. Valid options: a string. Default value: " ".
 246
 247 ##### `value`
 248
 249 *Optional.* Supplies a value for the specified subsetting. Valid options: a string. Default value: undefined.
 250
 251 ##Limitations
 252
 253 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.
 254
 255 ##Development
 256
 257 #Development
 258
 259 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.
 260
 261 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.
 262
 263 For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html)
 264
 265 ###Contributors
 266
 267 To see who's already involved, see the [list of contributors.](https://github.com/puppetlabs/puppetlabs-inifile/graphs/contributors)