DEBOPS.GRUB(5)

NAME
debops.grub - Manage GRUB configuration

SYNOPSIS

debops run service/grub [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

This Ansible role manages GRUB configuration. It detects kernel parameters which are currently set (probably during installation). Autodetected parameters can be merged or overwritten by Ansible variables. It can also enable both Linux kernel and GRUB serial console.

Parameter autodetection with values that contain spaces is not supported.

Additionally, this role allows you to configure password protection for GRUB.

GETTING STARTED

  Example inventory

To manage GRUB on a given host or a set of hosts, they need to be added to the [debops_service_grub] Ansible group in the inventory:

[debops_service_grub]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.grub role:

---
- name: Configure GRUB
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_grub' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: grub
      tags: [ 'role::grub', 'skip::grub' ]

  Password protection

To enable password protection, simply define a superuser like this:

grub__users:
  - name: 'su'
    password: 'NBLWAThUq5'
    superuser: True

The password will be hashed and salted on the Ansible controller and only the salted hash will be configured in the GRUB configuration.

With this change, GRUB will require authentication when attempting to change boot options or invoking a recovery shell. Booting menu entries will not require authentication so this configuration should be safe for normal operation.

DEFAULT VARIABLE DETAILS

Some of debops.grub default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  grub__configuration

The grub__*_configuration variables define the contents of the /etc/default/grub.d/ansible.cfg configuration file. The variables are lists of YAML dictionaries, the dictionaries with the same name parameter are merged together in an order specified by the grub__combined_configuration variable, which allows some of the configuration to be modified via Ansible inventory or other Ansible roles.

  Examples

Configure unattended filesystem check and repair on boot:

grub__configuration:
  - name: 'cmdline_linux_default'
    value:
      - 'fsck.mode=force'

Remove the quiet parameter from the default kernel command line:

grub__configuration:
  - name: 'cmdline_linux_default'
    value:
      - name: 'quiet'
        state: 'absent'

  Syntax

Each variable contains a list of YAML dictionaries, each dictionary defines a configuration file option using specific parameters:

name
    Required. Name of a GRUB option, it's also used as an anchor for merging multiple configuration entries together.

    The option name should be specified as lowercase, without the GRUB_ prefix. For example:

    GRUB_DEFAULT       -> 'default'
    GRUB_CMDLINE_LINUX -> 'cmdline_linux'

    You can specify the full names with uppercase, but they will not be automatically merged with existing configuration.

value
    The value which should be set for a given GRUB option. Values can be YAML booleans, numbers, strings or lists of strings. Additionally, in a list you can specify values in an extended format as a YAML dictionary with parameters:

name
    The value you want to manage, a string.

state
    If not specified or present, the value will be included in the configuration. If absent, the value will be removed from the configuration. If ignore, a given entry will not be evaluated by the role.

    The value parameters that contain YAML lists from multiple configuration entries are merged together.

state
    Optional. Specify the state of a given configuration entry. If not specified or present, the entry will be set in the GRUB configuration file. If absent, the entry will be removed from the configuration file. If ignore, this configuration entry will not be evaluated by the role.

comment
    Optional. String or a YAML text block with a comment added to a given configuration option in the GRUB config file.

quote
    Optional, boolean. If not specified or True, the value will be quoted. If False, the value will not be quoted.

original
    Optional, boolean. If True, the role will add $GRUB_<NAME> string to the given configuration option, based on the entry name. This allows to preserve existing GRUB options from the /etc/default/grub; this is useful only for specific options like kernel parameters.

export
    Optional, boolean. if True, the option will be exported in the GRUB environment by adding the export prefix in the configuration file. This is only needed in specific configuration scenarios.

AUTHOR
Patryk Ściborek, Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others