Curthooks / New OS Support¶
Curtin has built-in support for installation of:
- Ubuntu
- Centos
Other operating systems are supported through a mechanism called ‘curthooks’ or ‘curtin-hooks’.
A curtin install runs through different stages. See the Stages documentation for function of each stage. The stages communicate with each other via data in a working directory and environment variables as described in Command Environment.
Curtin handles partitioning, filesystem creation and target filesystem population for all operating systems. Curthooks are the mechanism provided so that the operating system can customize itself before reboot. This customization typically would need to include:
- ensuring that appropriate device drivers are loaded on first boot
- consuming the network interfaces file and applying its declarations.
- ensuring that necessary packages are installed to utilize storage configuration or networking configuration.
- making the system boot (running grub-install or equivalent).
Image provided curtin-hooks¶
An image provides curtin hooks support by containing a file
/curtin/curtin-hooks
.
If an Ubuntu image image contains this path it will override the builtin curtin support.
The curtin-hooks
program should be executable in the filesystem and
will be executed without any arguments. It will be executed in the install
environment, not the target environment. A change of root to the
target environment can be done with curtin in-target
.
The hook is provided with some environment variables that can be used to find more information. See the Command Environment doc for details. Specifically interesting to this stage are:
OUTPUT_NETWORK_CONFIG
: This is a path to the file created during network discovery stage.OUTPUT_FSTAB
: This is a path to the file created during partitioning stage.CONFIG
: This is a path to the curtin config file. It is provided so that additional configuration could be provided through to the OS customization.WORKING_DIR
: This is a path to a temporary directory where curtin stores state and configuration files.
Running built-in hooks¶
Curthooks may opt to run the built-in curthooks that are already provided in
curtin itself. To do so, an in-image curthook can import the curthooks
module and invoke the builtin_curthooks
function passing in the required
parameters: config, target, and state.
Networking configuration¶
Access to the network configuration that is desired is inside the config and is in the format described in Networking.
The curtin-hooks program must read the configuration from the
path contained in OUTPUT_NETWORK_CONFIG
and then set up
the installed system to use it.
If the installed system has cloud-init at version 17.1 or higher, it may
be possible to simply copy this section into the target in
/etc/cloud/cloud.cfg.d/
and let cloud-init render the correct
networking on first boot.
Storage configuration¶
Access to the storage configuration that was set up is inside the config and is in the format described in Storage.
To apply this storage configuration, the curthooks may need to:
- update /etc/fstab to add the expected mounts entries. The environment variable
OUTPUT_FSTAB
contains a path to a file that may be suitable for use.- install any packages that are not already installed that are required to boot with the provided storage config. For example, if the storage layout includes raid you may need to install the mdadm package.
- update or create an initramfs.
System boot¶
In Ubuntu, curtin will run ‘grub-setup’ and to install grub. This covers
putting the bootloader onto the disk(s) that are marked as
grub_device
. The provided hook will need to do the equivalent
operation.
finalize hook¶
There is one other hook that curtin will invoke in an install, called
finalize
. This program is invoked in the same environment as
curtin-hooks
above. It is intended to give the OS a final opportunity
make updates before reboot. It is called before late_commands
.