Skip to content

Commit 1da623a

Browse files
committed
Update pxe docs
1 parent e535ace commit 1da623a

1 file changed

Lines changed: 22 additions & 18 deletions

File tree

  • docs/imagecustomizer/concepts

docs/imagecustomizer/concepts/pxe.md

Lines changed: 22 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@ hosts and also centralizes the deployment configuration to a single server.
1515
One way of enabling such setup is using the PXE (Preboot eXecution Environment)
1616
Boot protocol. The user can setup a server with all the OS artifacts, a DHCP
1717
endpoint, and a tftp connection endpoint. When a client machine is powered on,
18-
and its firmware will look for a DHCP server on the same network and find the
18+
its firmware will look for a DHCP server on the same network and will find the
1919
one configured by the user.
2020

2121
The DHCP server will serve information about the tftp endpoint to the client,
2222
and the client firmware can then proceed with retrieving the OS artifacts over
23-
tftp, then loading them into memory, and finally handing control over to the
23+
tftp, loading them into memory, and finally handing control over to the
2424
loaded OS.
2525

2626
The tftp protocol expects certain artifacts to be present on the server:
@@ -38,18 +38,27 @@ The initrd image is customized to perform the next set of tasks now that an
3838
OS is running. The tasks can range from just running some local scripts all
3939
the way to installing another OS.
4040

41-
## LiveOS ISOs and PXE Support
41+
## Live OS PXE Support
4242

43-
A [LiveOS ISO](./iso.md) image is a bootable ISO image that runs all the necessary
44-
components from memory (i.e. does not need to install anything to the host
45-
persistent storage).
43+
A Live OS is when a system is booted from an ISO or downloaded through something
44+
like the PXE boot process. In such flow, the OS is running, but nothing has been
45+
installed to the host.
4646

47-
The necessary components can be either embedded into the initrd image itself
48-
or embedded into a separate 'rootfs' image (to allow much smaller
49-
initrd images). If separate, then, the initrd image must be configured with an
50-
agent that will look for the rootfs image, and transition control over to the
51-
rootfs at boot time. Dracut provides the `dmsquash-live` module which managed this transition from
52-
the initrd image over to the rootfs image.
47+
The OS file system can be either embedded in the initrd image itself (`initramfsType=full-os`)
48+
or stored in a separate (bootstrap) image (`initramfsType=bootstrap`).
49+
50+
The main difference is the size of the generated initrd image:
51+
- When embedded, the initrd image size is larger and may not meet the memory
52+
restriction on certain hardware skus (leading to an "out of memory" grub
53+
error). However, this is much simpler to deploy to a PXE server since the
54+
full OS content will be served using the PXE protocol without any extra setup.
55+
- When bootstrapped, the initrd image size will be much smaller (~30MB) - which
56+
solves the memory restriction issue on affected hardware models. The downside
57+
is that extra PXE environment setup is necessary (like setting up a server to
58+
host the bootstrapped extra file and server it).
59+
60+
It is worth noting that the bootstrap support is implemented using Dracut's
61+
`dmsquash-live` module.
5362

5463
The **Image Customizer** produces such [LiveOS ISO](./iso.md) images. A typical
5564
image holds the following artifacts:
@@ -58,14 +67,9 @@ image holds the following artifacts:
5867
- the boot loader configuration
5968
- the kernel image
6069
- the initrd image
61-
- the rootfs image
70+
- the rootfs image (required only if `initramfsType=bootstrap`)
6271
- other user defined artifacts (optional)
6372

64-
Note that the first 4 artifacts are what is necessary to get an OS kernel up
65-
and running in a network boot scenario. What remains for a successful booting
66-
of a LiveOS over the network is to make the rootfs image available for the final
67-
transition (during the initrd phase).
68-
6973
Dracut enables that entire flow through the use of the `livenet` module - where
7074
it inspects the `root=live:liveos-iso-url` kernel parameter from the boot loader
7175
config file, and if it recognizes the `liveos-iso-url` protocol, it downloads

0 commit comments

Comments
 (0)