1
========================================
2
Curthooks / New OS Support
3
========================================
4
Curtin has built-in support for installation of Ubuntu.
5
Other operating systems are supported through a mechanism called
6
'curthooks' or 'curtin-hooks'.
8
A curtin install runs through different stages. See the
10
documentation for function of each stage.
11
The stages communicate with each other via data in a working directory and
12
environment variables as described in
13
:ref:`Command Environment`.
15
Curtin handles partitioning, filesystem creation and target filesystem
16
population for all operating systems. Curthooks are the mechanism provided
17
so that the operating system can customize itself before reboot. This
18
customization typically would need to include:
20
- ensuring that appropriate device drivers are loaded on first boot
21
- consuming the network interfaces file and applying its declarations.
22
- ensuring that necessary packages are installed to utilize storage
23
configuration or networking configuration.
24
- making the system boot (running grub-install or equivalent).
26
Image provided curtin-hooks
27
---------------------------
28
An image provides curtin hooks support by containing a file
29
``/curtin/curtin-hooks``.
31
If an Ubuntu image image contains this path it will override the builtin
34
The ``curtin-hooks`` program should be executable in the filesystem and
35
will be executed without any arguments. It will be executed in the install
36
environment, *not* the target environment. A change of root to the
37
target environment can be done with ``curtin in-target``.
39
The hook is provided with some environment variables that can be used
40
to find more information. See the :ref:`Command Environment` doc for
41
details. Specifically interesting to this stage are:
43
- ``OUTPUT_NETWORK_CONFIG``: This is a path to the file created during
44
network discovery stage.
45
- ``OUTPUT_FSTAB``: This is a path to the file created during partitioning
47
- ``CONFIG``: This is a path to the curtin config file. It is provided so
48
that additional configuration could be provided through to the OS
51
.. **TODO**: We should add 'PYTHON' or 'CURTIN_PYTHON' to this environment
52
so that the hook can easily run a python program with the same python
53
that curtin ran with (ie, python2 or python3).
56
Networking configuration
57
------------------------
58
Access to the network configuration that is desired is inside the config
59
and is in the format described in :ref:`networking`.
61
.. TODO: We should guarantee that the presence
62
of network config v1 in the file OUTPUT_NETWORK_CONFIG.
64
The curtin-hooks program must read the configuration from the
65
path contained in ``OUTPUT_NETWORK_CONFIG`` and then set up
66
the installed system to use it.
68
If the installed system has cloud-init at version 17.1 or higher, it may
69
be possible to simply copy this section into the target in
70
``/etc/cloud/cloud.cfg.d/`` and let cloud-init render the correct
71
networking on first boot.
75
Access to the storage configuration that was set up is inside the config
76
and is in the format described in :ref:`storage`.
78
.. TODO: We should guarantee that the presence
79
of storage config v1 in the file OUTPUT_STORAGE_CONFIG.
80
This would mean the user would not have to pull it out
81
of CONFIG. We should guarantee its presence and format
82
even in the 'simple' path.
84
To apply this storage configuration, the curthooks may need to:
86
* update /etc/fstab to add the expected mounts entries. The environment
87
variable ``OUTPUT_FSTAB`` contains a path to a file that may be suitable
90
* install any packages that are not already installed that are required
91
to boot with the provided storage config. For example, if the storage
92
layout includes raid you may need to install the mdadm package.
94
* update or create an initramfs.
99
In Ubuntu, curtin will run 'grub-setup' and to install grub. This covers
100
putting the bootloader onto the disk(s) that are marked as
101
``grub_device``. The provided hook will need to do the equivalent
106
There is one other hook that curtin will invoke in an install, called
107
``finalize``. This program is invoked in the same environment as
108
``curtin-hooks`` above. It is intended to give the OS a final opportunity
109
make updates before reboot. It is called before ``late_commands``.
added
removed
doc/topics/curthooks.rst
