grub: type/provider for grub files for Puppet

This module provides a new type/provider for Puppet to read and modify grub 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.

WARNING Your system must be able to run the grub mkconfig scripts with BLS support if you are on a systen that uses BLS!

Installing

On Puppet 2.7.14+, the module can be installed easily (documentation):

puppet module install puppet/augeasproviders_grub

You may see an error similar to this on Puppet 2.x (#13858):

Error 400 on SERVER: Puppet::Parser::AST::Resource failed with error ArgumentError: Invalid resource type `kernel_parameter` at ...

Ensure the module is present in your puppetmaster's own environment (it doesn't have to use it) and that the master has pluginsync enabled. Run the agent on the puppetmaster to cause the custom types to be synced to its local libdir (puppet master --configprint libdir) and then restart the puppetmaster so it loads them.

Compatibility

Puppet versions

Minimum of Puppet 2.7.

Augeas versions

Note: grub_menuentry and grub_user for GRUB2 do not use Augeas at this time due to lack of available lenses.

Documentation and examples

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

kernel_parameter provider

This is a custom type and provider supplied by augeasproviders. It supports both GRUB Legacy (0.9x) and GRUB 2 configurations.

manage parameter without value

kernel_parameter { "quiet":
  ensure => present,
}

manage parameter with value

kernel_parameter { "elevator":
  ensure  => present,
  value   => "deadline",
}

manage parameter with multiple values

kernel_parameter { "rd_LVM_LV":
  ensure  => present,
  value   => ["vg/lvroot", "vg/lvvar"],
}

manage parameter on certain boot types

Bootmode defaults to "all", so settings are applied for all boot types usually.

Apply only to the default boot:

kernel_parameter { "quiet":
  ensure   => present,
  bootmode => "default",
}

Apply only to normal boots. In GRUB legacy, normal boots consist of the default boot plus non-recovery ones. In GRUB2, normal bootmode is just an alias for default.

kernel_parameter { "quiet":
  ensure   => present,
  bootmode => "normal",
}

Only recovery mode boots (unsupported with GRUB 2):

kernel_parameter { "quiet":
  ensure   => present,
  bootmode => "recovery",
}

delete entry

kernel_parameter { "rhgb":
  ensure => absent,
}

manage parameter in another config location

kernel_parameter { "elevator":
  ensure => present,
  value  => "deadline",
  target => "/mnt/boot/grub/menu.lst",
}

grub_config provider

This custom type manages GRUB Legacy and GRUB2 global configuration parameters.

In GRUB Legacy, the global items at the top of the grub.conf file are managed.

In GRUB2, the parameters in /etc/defaults/grub are managed.

When using GRUB2, take care that you aren't conflicting with an option later specified by grub_menuentry. Also, be aware that, in GRUB2, any global items here will not be referenced unless you reference them by variable name per Bash semantics.

change the default legacy GRUB timeout

This will set the timeout global value in the Legacy GRUB configuration.

grub_config { 'timeout':
  value => '1'
}

change the default GRUB2 timeout

This will set the GRUB_TIMEOUT global value in the GRUB2 configuration.

grub_config { 'GRUB_TIMEOUT':
  value => '1'
}

grub_menuentry provider

This is a custom type to manage GRUB Legacy and GRUB2 menu entries.

The GRUB Legacy provider utlizes Augeas under the hood but GRUB2 did not have an available Lens and was written in Ruby.

This will not allow for modifying dynamically generated system entries. You will need to remove some of the native GRUB2 configuration scripts to be fully independent of the default system values.

The GRUB2 output of this provider will be saved, by default, in /etc/grub.d/05_puppet_managed_<random_string> where the random_string is a hash of the resource name.

new entry preserving all existing values

This will create a new menu entry and copy over any default values if present. If the entry currently exists, it will preserve all values and not overwrite them with the default system values.

grub_menuentry { 'new_entry':
  root           => '(hd0,0)',
  kernel         => ':preserve:',
  initrd         => ':preserve:',
  kernel_options => [':preserve:']
}

kernel option lines

There are many methods for identifying and manipulating kernel option lines and so a method was developed for handling the most common scenarios. You can, of course, simply denote every option, but this is cumbersome and prone to error over time.

The following format is supported for the new options:

':defaults:'  => Copy defaults from the default GRUB entry
':preserve:'  => Preserve all existing options (if present)

Note: ':defaults:' and ':preserve:' are mutually exclusive.

All of the options below supersede any items affected by the above

'entry(=.*)?'   => Ensure that `entry` exists *as entered*; replaces all
                   other options with the same name
'!:entry(=.*)?' => Add this option to the end of the arguments
                   preserving any other options of the same name
'-:entry'       => Ensure that all instances of `entry` do not exist
'-:entry=foo'   => Ensure that only instances of `entry` with value `foo` do not exist

Note: Option removals and additions have higher precedence than preservation

grub_user provider

This type manages GRUB2 users and superusers.

The output of this provider is stored, by default, in /etc/grub.d/01_puppet_managed_users.

Any plain text passwords are automatically converted into the appropriate GRUB PBKDF2 format.

Note: If no users are defined as superusers, then GRUB2 will not enforce user restrictions on your entries.

user with a plain text password

grub_user { 'test_user':
  password => 'plain text password'
}

user with a pre-hashed password

grub_user { 'test_user':
  password => 'grub.pbkdf2.sha512.10000.REALLY_LONG_STRING'
}

user that is a superuser with a plain text password and 20000 rounds

grub_user { 'test_user':
  password  => 'plain text password',
  superuser => true,
  rounds    => '20000'
}

Issues

Please file any issues or suggestions on GitHub.

Reference

Table of Contents

Resource types

• grub_config: Manages global GRUB configuration parameters
• grub_menuentry: Manages menu entries in the GRUB and GRUB2 systems. NOTE: This may not cover all possible options and some options may apply to either
• grub_user: Manages GRUB2 Users - Does not apply to GRUB Legacy Note: This type compares against the active GRUB configuration. The contents of the ma
• kernel_parameter: Manages kernel parameters stored in bootloaders.

Resource types

grub_config

Manages global GRUB configuration parameters

Properties

The following properties are available in the grub_config type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

value

Value of the GRUB parameter.

Parameters

The following parameters are available in the grub_config type.

• name
• provider
• target

name

namevar

The parameter that you wish to set.

GRUB < 2

In the case of GRUB < 2, this will be something like 'default', 'timeout', etc...

See info grub for additional information.

GRUB >= 2

With GRUB >= 2, this will be 'GRUB_DEFAULT', 'GRUB_SAVEDEFAULT', etc..

See info grub2 for additional information.

provider

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

target

The bootloader configuration file, if in a non-default location for the provider.

grub_menuentry

Manages menu entries in the GRUB and GRUB2 systems.

NOTE: This may not cover all possible options and some options may apply to either GRUB or GRUB2!

Properties

The following properties are available in the grub_menuentry type.

bls

Valid values: true, false

Explicitly enable, or disable, BLS support for this resource.

Has on effect on systems that are not BLS enabled.

classes

Add this Array of classes to the menuentry.

default_entry

Valid values: true, false

If set, make this menu entry the default entry.

If more than one of these is set to true across all :menuentry resources, this is an error.

In GRUB2, there is no real guarantee that this will stick since entries further down the line may have custom scripts which alter the default.

NOTE: You should not use this in conjunction with using the :grub_config type to set the system default.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

initrd

Valid values: %r{^(/.*|:(default|preserve):)}

The path to the initrd image.

Set this to ':default:' to copy the default kernel initrd if one exists.

Set this to ':preserve:' to preserve the current entry. If a current entry does not exist, the default will be copied. If there is no default, this is an error.

kernel

Valid values: %r{^(/.*|:(default|preserve):)}

The path to the kernel that you wish to boot.

Set this to ':default:' to copy the default kernel if one exists.

Set this to ':preserve:' to preserve the current entry. If a current entry does not exist, the default will be copied. If there is no default, this is an error.

kernel_options

An array of kernel options to apply to the :kernel property.

The following format is supported for the new options: ':defaults:' => Copy defaults from the default GRUB entry ':preserve:' => Preserve all existing options (if present)

Note: ':defaults:' and ':preserve:' are mutually exclusive.

All of the options below supersede any items affected by the above

'entry(=.)?' => Ensure that entry exists as entered; replaces all other options with the same name '!:entry(=.)?' => Add this option to the end of the arguments preserving any other options of the same name '-:entry' => Ensure that all instances of entry do not exist '-:entry=foo' => Ensure that only instances of entry with value foo do not exist

Note: Option removals and additions have higher precedence than preservation

Default value: :preserve:

load_16bit

Valid values: true, false

If set, ensure that linux16 and initrd16 are used for the kernel entries.

Will default to true unless the entry is a BLS entry.

load_video

Valid values: true, false

If true, add the load_video command to the menuentry.

Will default to true unless the entry is a BLS entry.

makeactive

Valid values: true, false

In Legacy GRUB, having this set will add a 'makeactive' entry to the menuentry.

Default value: false

modules

An Array of module entry Arrays that apply to the given entry. Since each Multiboot format boot image is unique, you must know what you wish to pass to the module lines.

The one exception to this is that many of the linux multiboot settings require the kernel and initrd to be passed to them. If you set the ':defaults:' value anywhere in the options array, the default kernel options will be copied to that location in the output.

The following format is supported for the new options: ':defaults:' => Copy default options from the default kernel GRUB entry ':preserve:' => Preserve all existing options (if present)

Note: ':defaults:' and ':preserve:' are mutually exclusive.

All of the options below supersede any items affected by the above

'entry(=.*)?'   => Ensure that `entry` exists *as entered*; replaces all
                 other options with the same name
'!:entry(=.*)?' => Add this option to the end of the arguments
                 preserving any other options of the same name
'-:entry'       => Ensure that all instances of `entry` do not exist
'-:entry=foo'   => Ensure that only instances of `entry` with value `foo` do not exist

Note: Option removals and additions have higher precedence than preservation

Example: modules => [ ['/vmlinuz.1.2.3.4','ro'], ['/initrd.1.2.3.4'] ]

plugins

An Array of plugins that should be included in this menuentry.

Will default to ['gzio','part_msdos','xfs','ext2'] unless the entry is a BLS entry.

root

Valid values: %r{\(.*\)}

The filesystem root.

users

In GRUB2, having this set will add a requirement for the listed users to authenticate to the system in order to utilize the menu entry.

Default value: [:unrestricted]

Parameters

The following parameters are available in the grub_menuentry type.

• add_defaults_on_creation
• name
• provider
• target

add_defaults_on_creation

Valid values: true, false, yes, no

If set, when using the ':preserve:' option in kernel_options or modules will add the system defaults if the entry is being first created. This is the same technique that grub2-mkconfig uses when procesing entries.

Default value: true

name

namevar

The name of the menu entry.

provider

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

target

The bootloader configuration file, if in a non-default location for the provider.

grub_user

Manages GRUB2 Users - Does not apply to GRUB Legacy

Note: This type compares against the active GRUB configuration. The contents of the management file will not be updated unless the active configuration is out of sync with the expected configuration.

Properties

The following properties are available in the grub_user type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

password

The user's password. If the password is not already in a GRUB2 compatible form, it will be automatically converted.

purge

Valid values: true, false

Purge all unmanaged users.

This does not affect any users that are not defined by Puppet! There is no way to reliably eliminate the items from all other scripts without potentially severely damaging the GRUB2 build scripts.

Default value: false

Parameters

The following parameters are available in the grub_user type.

• name
• provider
• report_unmanaged
• rounds
• superuser
• target

name

namevar

The username of the GRUB2 user to be managed.

provider

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

report_unmanaged

Valid values: true, false

Report any unmanaged users as a warning during the Puppet run.

Default value: false

rounds

Valid values: %r{^\d+$}

The rounds to use when hashing the password.

Default value: 10_000

superuser

Valid values: true, false

If set, add this user to the 'superusers' list, if no superusers are set, but grub_user resources have been declared, a compile error will be raised.

Default value: false

target

The file to which to write the user information.

Must be an absolute path.

Default value: /etc/grub.d/02_puppet_managed_users

kernel_parameter

Manages kernel parameters stored in bootloaders.

Properties

The following properties are available in the kernel_parameter type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

value

Value of the parameter if applicable. Many parameters are just keywords so this must be left blank, while others (e.g. 'vga') will take a value.

Parameters

The following parameters are available in the kernel_parameter type.

• bootmode
• name
• provider
• target

bootmode

Valid values: all, default, normal, recovery

Boot mode(s) to apply the parameter to. Either 'all' (default) to use the parameter on all boots (normal and recovery mode), 'default' for just the default boot entry, 'normal' for just normal boots or 'recovery' for just recovery boots.

Default value: all

name

namevar

The parameter name, e.g. 'quiet' or 'vga'.

provider

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

target

The bootloader configuration file, if in a non-default location for the provider.

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v4.0.0 (2022-07-29)

Full Changelog

Breaking changes:

• Call grub2-mkconfig on all targets #57 (traylenator)

Fixed bugs:

• grub_menuentry resource fail if directory /boot/grub doe not exist #53
• grub.cfg isn't being properly updated on EFI systems running CentOS 7 #4
• Fix grub_menuentry issues #56 (trevor-vaughan)

Closed issues:

• The mkconfig update in #4 needs to be ported to the other providers #63
• kernel_parameters set incorrectly on CentOS 8 #58
• Typo in provider grub for custom type grub_menuentry #54
• Kernel_parameter subscribe executes on every run #41
• More informative error message for missing dependency #34
• Support for Puppet 4 #26
• Issue w/Puppet 2016.x #24

Merged pull requests:

• Update augeasproviders_core version #67 (sazzle2611)
• Fix mkconfig calls #64 (trevor-vaughan)
• error message improvement: specify that it's a missing module #61 (kenyon)
• Fix typo in grub_menuentry provider #55 (trevor-vaughan)

3.2.0 (2020-03-31)

Full Changelog

Fixed bugs:

• grub_menuentry is broken in EL8 and Fedora 30+ #49

Closed issues:

• grub_config values with spaces cause augeas errors #44
• Absent GRUB_CMDLINE_LINUX_DEFAULT can result in duplicated kernel parameters. #38
• The grub2 system should update both the EFI and non-EFI configurations when triggered #37

Merged pull requests:

• Add BLS support to grub_menuentry #50 (trevor-vaughan)
• Fixed the EFI code for grub_config and grub_menuentry #48 (tparkercbn)
• Fix String value issues in grub_config #46 (trevor-vaughan)
• Puppet6 #42 (raphink)

3.1.0 (2019-02-28)

Full Changelog

Closed issues:

• Hard dependency on grub2-tools on CentOS7 missing #20

Merged pull requests:

• Add back path for grub.cfg on Debian OS. #36 (olifre)

3.0.1 (2018-05-09)

Full Changelog

Closed issues:

• EFI support for all oses, not only fedora #27

Merged pull requests:

• Grub2 grub_user fix #32 (trevor-vaughan)
• Update grub2.rb for EFI systems #29 (cohdjn)

3.0.0 (2017-08-29)

Full Changelog

Closed issues:

• Unable to set/determine correct provider on Arch Linux #22

Merged pull requests:

• Add Global EFI support #28 (trevor-vaughan)
• Raise exception on missing augeasproviders_core #25 (igalic)

2.4.0 (2016-05-03)

Full Changelog

Implemented enhancements:

• Requesting support for grub 'module' statements #10
• Confine GRUB providers to presence of menus, prefer GRUB 2 #8 (ckoenig)

Closed issues:

• Fails on CentOS 6 #6

Merged pull requests:

• Update grub2.rb to add On UEFI Systems, grub.cfg #21 (stivesso)
• Updated the Changelog #19 (trevor-vaughan)
• Added support for global GRUB configuration #18 (trevor-vaughan)

2.3.0 (2016-02-18)

Full Changelog

Closed issues:

• wrong version of grub detection on Ubuntu Trusty #13
• Grub2 does not add the /files/etc/default/grub/GRUB_CMDLINE_LINUX_DEFAULT path if it is missing #11

Merged pull requests:

• adding 2 defaults for grub 2 #17 (wanix)
• add grub.cfg location for grub2 on UEFI systems #16 (tedwardia)
• Fix GRUB_CMDLINE_LINUX_DEFAULT #14 (trevor-vaughan)

2.2.0 (2016-01-04)

Full Changelog

2.1.0 (2015-11-17)

Full Changelog

Closed issues:

• undefined method `provider' for nil:NilClass #12
• Wrong provider selected in Centos7 #7

Merged pull requests:

• Set default to grub2 provider on el7 based systems #9 (vinzent)

2.0.1 (2014-12-10)

Full Changelog

Closed issues:

• Undefined method "provider" on Centos 6.5 #2

2.0.0 (2014-08-11)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator