shellvar: type/provider for shell files for Puppet

This module provides a new type/provider for Puppet to read and modify shell config files using the Augeas configuration library.

The advantage of using Augeas over the default Puppet parsedfile implementations is that Augeas will go to great lengths to preserve file formatting and comments, while also failing safely when needed.

This provider will hide all of the Augeas commands etc., you don't need to know anything about Augeas to make use of it.

Requirements

Ensure both Augeas and ruby-augeas 0.3.0+ bindings are installed and working as normal.

See Puppet/Augeas pre-requisites.

Installing

The module can be installed easily (documentation):

puppet module install herculesteam/augeasproviders_shellvar

Documentation and examples

Type documentation can be generated with puppet doc -r type or viewed on the Puppet Forge page.

manage simple entry

shellvar { "HOSTNAME":
  ensure => present,
  target => "/etc/sysconfig/network",
  value  => "host.example.com",
}

shellvar { "disable rsyncd":
  ensure   => present,
  target   => "/etc/default/rsync",
  variable => "RSYNC_ENABLE",
  value    => "false",
}

shellvar { "ntpd options":
  ensure   => present,
  target   => "/etc/sysconfig/ntpd",
  variable => "OPTIONS",
  value    => "-g -x -c /etc/myntp.conf",
}

manage entry with comment

shellvar { "HOSTNAME":
  ensure  => present,
  target  => "/etc/sysconfig/network",
  comment => "My server's hostname",
  value   => "host.example.com",
}

export values

shellvar { "HOSTNAME":
  ensure  => exported,
  target  => "/etc/sysconfig/network",
  value   => "host.example.com",
}

unset values

shellvar { "HOSTNAME":
  ensure  => unset,
  target  => "/etc/sysconfig/network",
}

force quoting style

Values needing quotes will automatically get them, but they can also be explicitly enabled. Unfortunately the provider doesn't help with quoting the values themselves.

shellvar { "RSYNC_IONICE":
  ensure   => present,
  target   => "/etc/default/rsync",
  value    => "-c3",
  quoted   => "single",
}

delete entry

shellvar { "RSYNC_IONICE":
  ensure => absent,
  target => "/etc/default/rsync",
}

remove comment from entry

shellvar { "HOSTNAME":
  ensure  => present,
  target  => "/etc/sysconfig/network",
  comment => "",
}

replace commented value with entry

shellvar { "HOSTNAME":
  ensure    => present,
  target    => "/etc/sysconfig/network",
  value     => "host.example.com",
  uncomment => true,
}

uncomment a value

shellvar { "HOSTNAME":
  ensure    => present,
  target    => "/etc/sysconfig/network",
  uncomment => true,
}

array values

You can pass array values to the type.

There are two ways of rendering array values, and the behavior is set using the array_type parameter. array_type takes three possible values:

• auto (default): detects the type of the existing variable, defaults to string;
• string: renders the array as a string, with a space as element separator;
• array: renders the array as a shell array.

For example:

shellvar { "PORTS":
  ensure     => present,
  target     => "/etc/default/puppetmaster",
  value      => ["18140", "18141", "18142"],
  array_type => "auto",
}

will create PORTS="18140 18141 18142" by default, and will change PORTS=(123) to PORTS=("18140" "18141" "18142").

shellvar { "PORTS":
  ensure     => present,
  target     => "/etc/default/puppetmaster",
  value      => ["18140", "18141", "18142"],
  array_type => "string",
}

will create PORTS="18140 18141 18142" by default, and will change PORTS=(123) to PORTS="18140 18141 18142".

shellvar { "PORTS":
  ensure     => present,
  target     => "/etc/default/puppetmaster",
  value      => ["18140", "18141", "18142"],
  array_type => "array",
}

will create PORTS=("18140" "18141" "18142") by default, and will change PORTS=123 to PORTS=(18140 18141 18142).

Quoting is honored for arrays:

• When using the string behavior, quoting is global to the string;
• When using the array behavior, each value in the array is quoted as requested.

appending to arrays

shellvar { "GRUB_CMDLINE_LINUX":
  ensure       => present,
  target       => "/etc/default/grub",
  value        => "cgroup_enable=memory",
  array_append => true,
}

will change GRUB_CMDLINE_LINUX="quiet splash" to GRUB_CMDLINE_LINUX="quiet splash cgroup_enable=memory".

shellvar { "GRUB_CMDLINE_LINUX":
  ensure       => present,
  target       => "/etc/default/grub",
  value        => ["quiet", "cgroup_enable=memory"],
  array_append => true,
}

will also change GRUB_CMDLINE_LINUX="quiet splash" to GRUB_CMDLINE_LINUX="quiet splash cgroup_enable=memory".

removing from arrays

shellvar { "GRUB_CMDLINE_LINUX":
  ensure       => absent,
  target       => "/etc/default/grub",
  value        => "cgroup_enable=memory",
  array_append => true,
}

will change GRUB_CMDLINE_LINUX="quiet splash cgroup_enable=memory" to GRUB_CMDLINE_LINUX="quiet splash".

shellvar { "GRUB_CMDLINE_LINUX":
  ensure       => absent,
  target       => "/etc/default/grub",
  value        => ["quiet", "cgroup_enable=memory"],
  array_append => true,
}

will also change GRUB_CMDLINE_LINUX="splash cgroup_enable=memory" to GRUB_CMDLINE_LINUX="splash".

Issues

Please file any issues or suggestions on GitHub.

Reference

Table of Contents

Resource types

• shellvar: Manages variables in simple shell scripts.

Resource types

shellvar

Manages variables in simple shell scripts.

Properties

The following properties are available in the shellvar type.

comment

Text to be stored in a comment immediately above the entry. It will be automatically prepended with the name of the variable in order for the provider to know whether it controls the comment or not.

ensure

Valid values: present, absent, unset, exported

Create or remove the shellvar entry

Default value: present

value

Value to change the variable to.

Parameters

The following parameters are available in the shellvar type.

array_append

Valid values: false, true

Whether to add to existing array values or replace all values.

Default value: false

array_type

Valid values: auto, string, array

Type of array mapping to use, defaults to auto.

• auto will detect the current type, and default to string
• string will render the array as a string and use space-separated values
• array will render the array as a shell array

Default value: auto

name

The default namevar

provider

The specific backend to use for this shellvar resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

quoted

Valid values: auto, double, single, none, false, true

Quoting method to use, defaults to auto.

• auto will quote only if necessary, leaving existing quotes as-is
• double and single will always quotes
• none will remove quotes, which may result in save failures

Default value: auto

target

namevar

The file in which to store the variable.

uncomment

Valid values: true, false

Whether to remove commented value when found.

Default value: false

variable

namevar

The name of the variable, e.g. OPTIONS

Changelog

4.1.0

• Convert to PDK
• Add a check for nil when setting values for comments
• Allow augeasproviders_core 3.x

4.0.0

• Add array remove functionality (#36)
• Make uncomment work with array_append (fix #13)

3.1.0

• Add support for Puppet 6
• Deprecate support for Puppet < 5
• Update supported OSes in metadata.json

3.0.0

• Fix support for 'puppet generate types'

2.2.4

• Revert the 'puppet generate types' fix due to a discovery that it does not work properly prior to puppet 4.10.4 due to a bug in puppet.

2.2.3

• Fix support for 'puppet generate types'
• Added CentOS and OracleLinux to supported OS list

2.2.2

• Upped supported Puppet versions to include Puppet 5

2.2.1

• Only remove seq entries in array entries (GH #10)
• Resync value when exporting/unsetting (GH #10)

2.2.0

• Detect value in existing comment when uncommenting (GH #18)
• Improve README.md
• Use containerized Travis CI infrastructure
• Test on Puppet 4
• Update copyright

2.1.1

• Fix metadata.json

2.1.0

• Add multiline value support
• Depend on augeasproviders_core >= 2.1.0

2.0.4

• Fix Travis build

2.0.3

• Make sure :name is always fed by the composite namevar (GH #3)
• Always use resource[:variable] instead of resource[:name] in the provider

2.0.2

• Add target as namevar, activate composite namevars (GH #2)

2.0.1

• Fix exporting array values (GH #1)

2.0.0

• First release of split module.