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.