inifile

Table of Contents

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

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:

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:

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:

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

Use a non-standard section header

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

Results in:

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.

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:

[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 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:

#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:

# 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:

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:

resources { 'glance_api_config':
  purge => true,
}

Manage multiple ini_settings

To manage multiple ini_settings, use the inifile::create_ini_settings function.

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

Results in:

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

To include special parameters, use the following code:

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

Results in:

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

For the profile example:

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

Provide this in your Hiera data:

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

Results in:

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

See REFERENCE.md

Limitations

For an extensive list of supported operating systems, see metadata.json

Development

We are experimenting with a new tool for running acceptance tests. It's name is puppet_litmus this replaces beaker as the test runner. To run the acceptance tests follow the instructions here.

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.

Contributors

To see who's already involved, see the list of contributors.

Reference

Table of Contents

Resource types

• ini_setting: ini_settings is used to manage a single setting in an INI file
• ini_subsetting: ini_subsettings is used to manage multiple values in a setting in an INI file

Functions

• create_ini_settings: DEPRECATED. Use the namespaced function inifile::create_ini_settings instead.
• inifile::create_ini_settings: This function is used to create a set of ini_setting resources from a hash

Resource types

ini_setting

ini_settings is used to manage a single setting in an INI file

Properties

The following properties are available in the ini_setting type.

ensure

Valid values: present, absent

Ensurable method handles modeling creation. It creates an ensure property

Default value: present

value

The value of the setting to be defined.

Parameters

The following parameters are available in the ini_setting type.

name

namevar

An arbitrary name used as the identity of the resource.

section

The name of the section in the ini file in which the setting should be defined.

Default value: ''

setting

The name of the setting to be defined.

force_new_section_creation

Valid values: true, false, yes, no

Create setting only if the section exists

Default value: true

path

The ini file Puppet will ensure contains the specified setting.

show_diff

Valid values: true, md5, false

Whether to display differences when the setting changes.

Default value: true

key_val_separator

The separator string to use between each setting name and value.

Default value: =

section_prefix

The prefix to the section name\'s header.

Default value: [

section_suffix

The suffix to the section name\'s header.

Default value: ]

indent_char

The character to indent new settings with.

Default value:

indent_width

The number of indent_chars to use to indent a new setting.

refreshonly

Valid values: true, false, yes, no

A flag indicating whether or not the ini_setting should be updated only when called as part of a refresh event

Default value: false

ini_subsetting

ini_subsettings is used to manage multiple values in a setting in an INI file

Properties

The following properties are available in the ini_subsetting type.

ensure

Valid values: present, absent

Ensurable method handles modeling creation. It creates an ensure property

Default value: present

value

The value of the subsetting to be defined.

Parameters

The following parameters are available in the ini_subsetting type.

name

namevar

An arbitrary name used as the identity of the resource.

section

The name of the section in the ini file in which the setting should be defined.

Default value: ''

setting

The name of the setting to be defined.

subsetting

The name of the subsetting to be defined.

subsetting_separator

The separator string between subsettings. Defaults to the empty string.

Default value:

subsetting_key_val_separator

The separator string between the subsetting name and its value. Defaults to the empty string.

Default value: ''

path

The ini file Puppet will ensure contains the specified setting.

show_diff

Valid values: true, md5, false

Whether to display differences when the setting changes.

Default value: true

key_val_separator

The separator string to use between each setting name and value.

Default value: =

quote_char

The character used to quote the entire value of the setting. Valid values are '', '\"' and \"'\"

Default value: ''

use_exact_match

Valid values: true, false

Set to true if your subsettings don\'t have values and you want to use exact matches to determine if the subsetting exists.

Default value: false

insert_type

Valid values: start, end, before, after, index

Where the 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.

Default value: end

insert_value

The value for the insert types which require one.

Functions

create_ini_settings

Type: Ruby 4.x API

DEPRECATED. Use the namespaced function inifile::create_ini_settings instead.

create_ini_settings(Any *$args)

The create_ini_settings function.

Returns: Any

*args

Data type: Any

inifile::create_ini_settings

Type: Ruby 4.x API

This function is used to create a set of ini_setting resources from a hash

inifile::create_ini_settings(Hash $settings, Optional[Hash] $defaults)

The inifile::create_ini_settings function.

Returns: Any

settings

Data type: Hash

A hash of settings you want to create ini_setting resources from

defaults

Data type: Optional[Hash]

A hash of defaults you would like to use in the ini_setting resources

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v4.2.0 (2020-04-27)

Full Changelog

Added

• Finish API conversion of create\_ini\_settings #387 (alexjfisher)

v4.1.0 (2020-01-15)

Full Changelog

Added

• pdksync - (FM-8581) - Debian 10 added to travis and provision file refactored #374 (david22swan)
• Puppet 4 functions #373 (binford2k)
• pdksync - "MODULES-10242 Add ubuntu14 support back to the modules" #368 (sheenaajay)
• (FM-8689) - Addition of Support for CentOS 8 #366 (david22swan)

v4.0.0 (2019-11-11)

Full Changelog

Changed

• pdksync - FM-8499 - remove ubuntu14 support #363 (lionce)

Added

• FM-8402 add debian 10 support #352 (lionce)

v3.1.0 (2019-07-31)

Full Changelog

Added

• FM-8222 - Port Module inifile to Litmus #344 (lionce)
• (FM-8154) Add Windows Server 2019 support #340 (eimlav)
• (FM-8041) Add RedHat 8 support #339 (eimlav)

v3.0.0 (2019-04-22)

Full Changelog

Changed

• pdksync - (MODULES-8444) - Raise lower Puppet bound #335 (david22swan)

Fixed

• FM-7779 - Cleanup Inifile #328 (lionce)

2.5.0 (2018-12-28)

Full Changelog

2.4.0 (2018-09-27)

Full Changelog

Added

• (MODULES-8142) - Addition of support for SLES 15 #315 (david22swan)
• (MODULES-7560) - removed spaces from the beginning or from the end of the value #311 (lionce)
• pdksync - (FM-7392) - Puppet 6 Testing Changes #300 (pmcmaw)
• pdksync - (MODULES-7658) use beaker4 in puppet-module-gems #296 (tphoney)
• (MODULES-7552) - Addition of support for Ubuntu 18.04 to inifile #292 (david22swan)

Fixed

• pdksync - (FM-7655) Fix rubygems-update for ruby \< 2.3 #320 (tphoney)
• (MODULES-6714) - inifile: ensure absent not working with refreshonly = true #313 (Lavinia-Dan)
• (FM-7483) - update module to the latest version #310 (lionce)
• (FM-7331)-Fix japanese test #308 (lionce)
• (MODULES-7625) - Update README Limitations section #293 (eimlav)

2.3.0

Summary

This release uses the PDK convert functionality which in return makes the module PDK compliant. It also includes a feature for force_new_section_creation and a roll up of maintenance changes.

Added

• Added force_new_section_creation parameter.
• PDK convert and update to use pdk 1.5.0 (MODULES-6326).

Removed

• Support for Scientific Linux 5
• Support for Debian 7

Supported Release 2.2.2

Summary

This is a bug fix release that corrects type autoloading.

Fixed

• Correct type autoload (FM-6932).

Supported Release 2.2.1

Summary

This is a bug fix release for a problem with managing existing lines in Puppet > 5.4.0

Fixed

• issue with ini_setting's :refreshonly parameter validation (MODULES-6687)

Supported Release 2.2.0

Summary

This release uses the PDK convert functionality which in return makes the module PDK compliant. It also includes a roll up of maintenance changes.

Added

• PDK convert inifile (MODULES-6453).
• Modulesync updates.

Fixed

• Changes to address additional Rubocop failures.
• Addressing puppet-lint doc warnings.

Removed

• gem update bundler command in .travis.yml due to (MODULES-6339).

Supported Release 2.1.1

Summary

This release is in order to implement Rubocop within the module and includes a wide array of formatting changes throughout the code and the enabling of rubocop checks to be run against all pull requests against the module.

Changed

• Rubocop checks will now be run against any PRs made towards the module.
• The module has undergone a substantial reformatting in order to comply with the designated standards.

Supported Release 2.1.0

Summary

This is a clean release prior to the implementation of rubocop within the module.

Added

• Several Modulesync updates have been made.
• Indent Character can now be set.
• Support for Debian 9 has been added.

Removed

• Support for Ubuntu 1004 and 1204 has been removed.
• Support for SLES 10 SP4 has been removed.
• Support for Debian 6 has been removed.
• Support for Solaris 12 has been removed.
• Support for Windows Server 2003 R2 has been removed.

Supported Release 2.0.0

Summary

This is a major release that includes a few bugfixes as well as some general module updates.

This release drops Puppet 3 support

Changed

• Moved lower Puppet version requirement to 4.7.0, MODULES-4830

Fixed

• Fix path validation on windows MODULES-4170
• Fix headings in README
• Fix for mimicking commented settings MODULES-4932
• Fix for Backwards compatible ini_file.set_value MODULES-5172

Supported Release 1.6.0

Summary

This release expands functionality around sub-settings and adds the refreshonly parameter so the user can specify whether a resource should or should not respond to a refresh event.

Features

• refreshonly decide whether or not a value should be updated as part of a refresh
• insert_type choose where the sub-setting is placed in the final string
• subsetting_key_val_separator specify a key/value separator for sub-settings

Bugfixes

• MODULES-3145 Cast values to strings before passing to provider

Supported Release 1.5.0

Summary

This release adds the long-awaited show_diff parameter for diffing the complete file on changes (or can also just show the md5 sums).

Features

• Added show_diff parameter to show diffs on changes.
• Remove empty ini sections when the last line in the section is removed.

Bugfixes

• Workaround create_ini_settings() duplicate resources puppet bug PUP-4709

Supported Release 1.4.3

###Summary

Small release for support of newer PE versions. This increments the version of PE in the metadata.json file.

2015-09-01 - Supported Release 1.4.2

Summary

This release adds some bugfixes.

####Bugfixes

• MODULES-2212 Add use_exact_match parameter for subsettings
• MODULES-1908 Munge the setting to ensure we always strip the whitespace
• MODULES-2369 Support a space as a key_val_separator

2015-07-15 - Supported Release 1.4.1

Summary

This release bumps the metadata for PE up.

##2015-07-07 - Supported Releases 1.4.0 ###Summary

This is primarily a release which includes acceptance tests updates, but also includes some minor bug fixes and improvements

####Features

• Solaris 12 Support
• Acceptance testing improvements

####Bugfixes

• MODULES-1599 Match only on space and tab whitespace after k/v separator

##2015-06-09 - Supported Releases 1.3.0 ###Summary

This is primarily a feature release, but also includes test fixes, documentation updates and synchronization of files with modulesync.

####Features

• Synchronized files using modulesync
• Improved documentation
• Allow changing key value separator beyond indentation
• Adding the ability to change regex match for $section in inifile

####Bugfixes

• pin beaker-rspec for windows testing
• pin rspec gems for testing
• Adds default values for section
• Fixed names containing spaces

##2014-11-11 - Supported Releases 1.2.0 ###Summary

This is primarily a bugfix release, but also includes documentation updates and synchronization of files with modulesync.

####Features

• Synchronized files using modulesync
• Improved documentation with a warning about old, manually installed inifile with PE3.3+

####Bugfixes

• Fix issue where single character settings were not being saved

##2014-09-30 - Supported Releases 1.1.4 ###Summary

This release includes documentation and test updates.

##2014-07-15 - Supported Release 1.1.3 ###Summary

This release merely updates metadata.json so the module can be uninstalled and upgraded via the puppet module command.

##2014-07-10 - Supported Release 1.1.2 ###Summary

This is a re-packaging release.

##2014-07-07 - Release 1.1.1 ###Summary

This supported bugfix release corrects the inifile section header detection regex (so you can use more characters in your section titles).

####Bugfixes

• Correct section regex to allow anything other than ]
• Correct exists? to return a boolean
• Lots of test updates
• Add missing CONTRIBUTING.md

##2014-06-04 - Release 1.1.0 ###Summary

This is a compatibility and feature release. This release adds one new feature, the ability to control the quote character used. This allows you to do things like:

ini_subsetting { '-Xms':
    ensure     => present,
    path       => '/some/config/file',
    section    => '',
    setting    => 'JAVA_ARGS',
    quote_char => '"',
    subsetting => '-Xms'
    value      => '256m',
  }

Which builds:

JAVA_ARGS="-Xmx256m -Xms256m"

####Features

• Add quote_char parameter to the ini_subsetting resource type

####Bugfixes

####Known Bugs

• No known bugs

##2014-03-04 - Supported Release 1.0.3 ###Summary

This is a supported release. It has only test changes.

####Features

####Bugfixes

####Known Bugs

• No known bugs

##2014-02-26 - Version 1.0.2 ###Summary This release adds supported platforms to metadata.json and contains spec fixes

##2014-02-12 - Version 1.0.1 ###Summary This release is a bugfix for handling whitespace/[]'s better, and adding a bunch of tests.

####Bugfixes

• Handle whitespace in sections
• Handle square brances in values
• Add metadata.json
• Update some travis testing
• Tons of beaker-rspec tests

##2013-07-16 - Version 1.0.0 ####Features

• Handle empty values.
• Handle whitespace in settings names (aka: server role = something)
• Add mechanism for allowing ini_setting subclasses to override the formation of the namevar during .instances, to allow for ini_setting derived types that manage flat ini-file-like files and still purge them.

##2013-05-28 - Chris Price chris@puppetlabs.com - 0.10.3

• Fix bug in subsetting handling for new settings (cbea5dc)

##2013-05-22 - Chris Price chris@puppetlabs.com - 0.10.2

• Better handling of quotes for subsettings (1aa7e60)

##2013-05-21 - Chris Price chris@puppetlabs.com - 0.10.1

• Change constants to class variables to avoid ruby warnings (6b19864)

##2013-04-10 - Erik Dalén dalen@spotify.com - 0.10.1

• Style fixes (c4af8c3)

##2013-04-02 - Dan Bode dan@puppetlabs.com - 0.10.1

• Add travisfile and Gemfile (c2052b3)

##2013-04-02 - Chris Price chris@puppetlabs.com - 0.10.1

• Update README.markdown (ad38a08)

##2013-02-15 - Karel Brezina karel.brezina@gmail.com - 0.10.0

• Added 'ini_subsetting' custom resource type (4351d8b)

##2013-03-11 - Dan Bode dan@puppetlabs.com - 0.10.0

• guard against nil indentation values (5f71d7f)

##2013-01-07 - Dan Bode dan@puppetlabs.com - 0.10.0

• Add purging support to ini file (2f22483)

##2013-02-05 - James Sweeny james.sweeny@puppetlabs.com - 0.10.0

• Fix test to use correct key_val_parameter (b1aff63)

##2012-11-06 - Chris Price chris@puppetlabs.com - 0.10.0

• Added license file w/Apache 2.0 license (5e1d203)

##2012-11-02 - Chris Price chris@puppetlabs.com - 0.9.0

• Version 0.9.0 released

##2012-10-26 - Chris Price chris@puppetlabs.com - 0.9.0

• Add detection for commented versions of settings (a45ab65)

##2012-10-20 - Chris Price chris@puppetlabs.com - 0.9.0

• Refactor to clarify implementation of save (f0d443f)

##2012-10-20 - Chris Price chris@puppetlabs.com - 0.9.0

• Add example for ensure=absent (e517148)

##2012-10-20 - Chris Price chris@puppetlabs.com - 0.9.0

• Better handling of whitespace lines at ends of sections (845fa70)

##2012-10-20 - Chris Price chris@puppetlabs.com - 0.9.0

• Respect indentation / spacing for existing sections and settings (c2c26de)

##2012-10-17 - Chris Price chris@puppetlabs.com - 0.9.0

• Minor tweaks to handling of removing settings (cda30a6)

##2012-10-10 - Dan Bode dan@puppetlabs.com - 0.9.0

• Add support for removing lines (1106d70)

##2012-10-02 - Dan Bode dan@puppetlabs.com - 0.9.0

• Make value a property (cbc90d3)

##2012-10-02 - Dan Bode dan@puppetlabs.com - 0.9.0

• Make ruby provider a better parent. (1564c47)

##2012-09-29 - Reid Vandewiele reid@puppetlabs.com - 0.9.0

• Allow values with spaces to be parsed and set (3829e20)

##2012-09-24 - Chris Price chris@pupppetlabs.com - 0.0.3

• Version 0.0.3 released

##2012-09-20 - Chris Price chris@puppetlabs.com - 0.0.3

• Add validation for key_val_separator (e527908)

##2012-09-19 - Chris Price chris@puppetlabs.com - 0.0.3

• Allow overriding separator string between key/val pairs (8d1fdc5)

##2012-08-20 - Chris Price chris@pupppetlabs.com - 0.0.2

• Version 0.0.2 released

##2012-08-17 - Chris Price chris@pupppetlabs.com - 0.0.2

• Add support for "global" section at beginning of file (c57dab4)

* This Changelog was automatically generated by github_changelog_generator