-
The
bootloaderrole manages GRUB2 boot loader settings: kernel command line parameters, the boot loader timeout, and the boot loader password. -
Considerations: Fedora 42 (
grubby-8.40-82.fc42.x86_64) introduced a bug, BZ#2361624, that changes the default kernel to a newly added kernel. To keep a specific kernel as the default, setdefault: truefor that kernel in thebootloader_settingsvariable. -
Collection requirements: To manage
rpm-ostreeor SUSE systems, the role needs extra modules from external collections, such ascommunity.generalforzypperon SUSE. Install them withansible-galaxy collection install -vv -r meta/collection-requirements.yml. Systems that are neitherrpm-ostreenor SUSE need no extra collections. -
For
rpm-ostreesystems, see theREADME-ostree.mdfile in the role. -
For SUSE systems, see the
README-suse.mdfile in the role.
| Parameter | Comments |
|---|---|
| bootloader_gather_facts boolean | Whether to gather bootloader facts containing boot information for all kernels. The role returns the facts in the bootloader_facts variable. Choices: false (default), true |
| bootloader_password any | The password to protect boot parameters. When set to null or left unset, the role leaves the current password unchanged. The boot loader username is always root. Store this value in Ansible Vault. Changing the password is not idempotent; use bootloader_password_hash for idempotent password configuration. On SUSE, setting the same password again changes nothing; see the README-suse.md file. You cannot set this variable together with bootloader_password_hash. |
| bootloader_password_hash any | Precomputed GRUB PBKDF2 SHA512 password hash for the root boot loader user. Generate the hash with grub2-mkpasswd-pbkdf2 and store it in Ansible Vault. Supply only the resulting grub.pbkdf2.sha512... hash, without the command's explanatory text or a trailing newline. The hash must have a positive iteration count, a nonempty hexadecimal salt consisting of whole bytes, and a 64-byte hexadecimal digest. Setting the same hash repeatedly is idempotent. When null or unset, the role writes no hash. An empty string is invalid; to remove a password set bootloader_remove_password=true with this variable unset or null. You cannot combine it with bootloader_password or bootloader_remove_password=true. |
| bootloader_reboot_ok boolean | Whether the role is allowed to reboot the managed host when changes require a reboot to take effect. If false, the role sets bootloader_reboot_required to true instead. Choices: false (default), true |
| bootloader_remove_password boolean | Whether to remove the boot loader password configuration. Choices: false (default), true |
| bootloader_secure_logging boolean | Whether to suppress potentially sensitive output from tasks that handle credentials by setting no_log to true on those tasks. Choices: false, true (default) |
| bootloader_settings list / elements=dictionary | List of kernel entries and their command line parameters to configure. Each entry specifies a kernel and the boot loader settings to apply. Default: [] |
| - default boolean | Whether to make this kernel the default boot entry. Choices: false (default), true |
| - kernel any / required | The kernel to update settings for. Accepts the string DEFAULT or ALL to target the default or all kernels, or a dictionary with keys path, index, title, and initrd to identify a specific kernel. To modify or remove a kernel, one of path, index, or title is required to identify it; to add a kernel, specify path, title, and initrd. |
| - options list / elements=dictionary | List of boot loader arguments to apply to the specified kernel. |
| - - copy_default boolean | Whether to copy the default arguments to the created kernel. Choices: false (default), true |
| - - name string | The name of the boot loader setting. Not required when using previous: replaced. |
| - - previous string | Whether to replace all previous settings with the given settings. The only supported value is replaced. Choices: "replaced" |
| - - state string | Whether the setting is present or absent. absent removes the setting with the given name. Choices: "present" (default), "absent" |
| - - value any | The value for the setting. Not required when the setting has no value, for example quiet. The value must not be a YAML bool type; quote values such as value: on as value: "on", or otherwise pass them as str. The value must also not be null; value:, value: ~, and value: null raise an error. |
| - state string | Whether to keep the kernel entry (present) or remove it (absent). Choices: "present" (default), "absent" |
| bootloader_timeout any | The GRUB boot loader timeout in seconds. When set to null or left unset, the role does not change the timeout setting. |
| Attribute | Support | Description |
|---|---|---|
| architectures | partial x86-64 - supported ARMv8.0 - supported POWER9 - supported s390x - not supported |
CPU architectures the role can run on. |
| check_mode | none The role does not support check mode. | Can run in check_mode and return a changed-status prediction without modifying the target. |
| idempotent | partial Kernel command line parameters, the boot loader timeout, and bootloader_password_hash are applied idempotently. bootloader_password is not idempotent; each run regenerates and rewrites the password. Use bootloader_password_hash for idempotent password configuration. |
When run twice in a row outside check mode with the same arguments, the second run reports no change. This assumes the managed host has not changed in a relevant way between runs. |
| platforms | full Fedora RHEL and compatible Enterprise Linux 7, 8, 9, and 10 SLES 16 and openSUSE Leap 16 |
Target operating systems. |
- name: Manage kernels by path, index, and title, and add, remove, and copy defaults
hosts: all
vars:
bootloader_settings:
# Update an existing kernel using path and replacing previous settings
- kernel:
path: /boot/vmlinuz-6.5.7-100.fc37.x86_64
options:
- name: console
value: tty0
state: present
- previous: replaced
default: false
# Update an existing kernel using index
- kernel:
index: 1
options:
- name: print-fatal-signals
value: 1
default: true
# Update an existing kernel using title
- kernel:
title: Red Hat Enterprise Linux (4.1.1.1.el8.x86_64) 8
options:
- name: no_timer_check
state: present
# Add a kernel with arguments
- kernel:
path: /boot/vmlinuz-6.5.7-100.fc37.x86_64
initrd: /boot/initramfs-6.5.7-100.fc37.x86_64.img
title: My kernel
options:
- name: console
value: tty0
- name: print-fatal-signals
value: 1
- name: no_timer_check
state: present
state: present
# Add a kernel with arguments and copying default arguments
- kernel:
path: /boot/vmlinuz-6.5.7-100.fc37.x86_64
initrd: /boot/initramfs-6.5.7-100.fc37.x86_64.img
title: My kernel
options:
- name: console
value: tty0
- copy_default: true
state: present
# Remove a kernel
- kernel:
title: My kernel
state: absent
# Update all kernels
- kernel: ALL
options:
- name: debug
state: present
# Update the default kernel
- kernel: DEFAULT
options:
- name: quiet
state: present
bootloader_timeout: 5
bootloader_reboot_ok: true
roles:
- linux-system-roles.bootloader
- name: Gather bootloader facts for all kernels without making changes
hosts: all
vars:
bootloader_gather_facts: true
roles:
- linux-system-roles.bootloader
- name: Set a bootloader password (pull the value from Ansible Vault)
hosts: all
vars:
bootloader_password: "{{ vault_bootloader_password }}"
bootloader_secure_logging: true
roles:
- linux-system-roles.bootloader
- name: Set an idempotent password hash from grub2-mkpasswd-pbkdf2
hosts: all
vars:
bootloader_password_hash: "{{ vault_bootloader_password_hash }}"
bootloader_secure_logging: true
roles:
- linux-system-roles.bootloader
- name: Remove the bootloader password
hosts: all
vars:
bootloader_remove_password: true
roles:
- linux-system-roles.bootloader
- name: Allow the role to reboot the host automatically
hosts: all
vars:
bootloader_reboot_ok: true
bootloader_settings:
- kernel: DEFAULT
options:
- name: crashkernel
value: 512M
roles:
- linux-system-roles.bootloaderThe following variables are set by this role:
| Key | Description |
|---|---|
| bootloader_facts list / elements=dictionary | Boot information for all kernels, as gathered by the bootloader_facts module. The role sets this in ansible_facts and also copies it to the bootloader_facts variable. Returned: When bootloader_gather_facts is true. Sample: [{"args": "ro rootflags=subvol=root console=tty0 quiet", "default": true, "id": "890cea0fd7b140cf890eb0145b3caa72-6.6.4-100.fc38.x86_64", "index": "1", "initrd": "/boot/initramfs-6.6.4-100.fc38.x86_64.img", "kernel": "/boot/vmlinuz-6.6.4-100.fc38.x86_64", "root": "UUID=2b95a97a-3f73-4566-b0a3-a11b4e9c3663", "title": "Fedora Linux (6.6.4-100.fc38.x86_64) 38 (Cloud Edition)"}] |
| - args string | Command line arguments passed to the kernel. Returned: success |
| - default boolean | Whether this kernel is the default boot entry. Returned: success |
| - id string | The kernel ID. Returned: success |
| - index string | The kernel index. Returned: success |
| - initrd string | Path to the kernel initrd image. Returned: success |
| - kernel string | Path to the kernel image. Returned: success |
| - root string | The root device for this kernel. Returned: success |
| - title string | The boot entry title. Returned: success |
| bootloader_reboot_required boolean | true means the host must reboot to apply the role's changes. Set to true when changes require a reboot and bootloader_reboot_ok is false; when bootloader_reboot_ok is true the role reboots and sets it to false. Unset when no change requires a reboot. Returned: When the role makes changes that require a reboot. Sample: true |
- Sergei Petrosian (@spetrosi)