From 9a27456d3e3a257d8b31f5fd141c8494ad4e261e Mon Sep 17 00:00:00 2001 From: William Douglas Date: Mon, 14 Dec 2015 22:01:25 +0000 Subject: [PATCH] Revert "Removing network boot topic from Master branch. Not ready for public. Retained in Staging." This reverts commit ac5effa2259f6a2e4c4426ecb6524ee4eed06f6a. The removal merged into staging removing the file from staging so this is just adding the file back. --- source/network_boot.rst | 377 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 377 insertions(+) create mode 100644 source/network_boot.rst diff --git a/source/network_boot.rst b/source/network_boot.rst new file mode 100644 index 00000000..23581db5 --- /dev/null +++ b/source/network_boot.rst @@ -0,0 +1,377 @@ +.. _network_booting: + +Network Booting +=============== + +Network booting is an important feature that every data center should have; +it can be used, among other things, to install an operating system. To do this, +a :abbr:`Pre-boot eXecution Environment (PXE)` is defined upon a foundation of +industry-standard Internet protocols and services, namely TCP/IP, DHCP, and +`TFTP `_. + +.. tip:: + + Clear Linux Project for Intel Architecture uses UEFI to boot, so your target + machine should be UEFI capable. At present, the UEFI binary is not signed, so + be sure to disable secure boot. + +PXE + iPXE +---------- + +To retrieve data through other protocols like: HTTP, iSCSI, ATA over Ethernet +(AoE), and Fiber Channel over Ethernet (FCoE), an open source network boot +firmware called iPXE was created. iPXE provides a full PXE implementation, +enhanced with additional features. It can be used to enable network booting from +computers that lack built-in PXE support. + +Clear Linux Project for Intel Architecture can be configured to do network +booting via HTTP with the help of iPXE. The following sets up an iPXE +environment using Clear Linux, but the configuration options may apply +elsewhere. First, add the ``pxe-server`` bundle to your +system with: + +.. code-block:: console + + # swupd bundle-add pxe-server + + +DHCP configuration +~~~~~~~~~~~~~~~~~~ + +To use PXE chainloading, set up ISC DHCPD to hand out undionly.kpxe to legacy +PXE clients and then hand out boot configuration only to iPXE clients. Do +this by telling ISC DHCPD to use different configurations based on the DHCP user class. +Here's one way to do this: + +.. code-block:: console + + allow booting; + allow bootp; + + # Set up a class to assign an IP only to devices is attempting network boot. + class "pxeclients" { + match if substring(option vendor-class-identifier, 0, 9) = "PXEClient"; + next-server 192.168.1.1; + if exists user-class and option user-class = "iPXE" { + filename "http://my.web.server/real_boot_script.txt"; + } elsif exists client-arch and option client-arch = 9 { + # client-arch = 9 (64-bit EFI) + filename "ipxe.efi"; + } else { + # client-arch = 0 (Standard PC BIOS) + filename "undionly.kpxe"; + } + } + # Private subnet, in case you aren't able to run your own network wide DHCP service. + # Works when the machine you are network booting has two network interfaces, + # one connected to the private PXE boot network and the other connected to an external + # network. + subnet 192.168.1.0 netmask 255.255.255.0 { + pool { + allow members of "pxeclients"; + range 192.168.1.100 192.168.1.200; + } + } + +This ensures that either iPXE image (undionly.kpxe for BIOS or ipxe.efi for EFI) is handed +out only when the DHCP request comes from a legacy PXE client or from a UEFI client. Once +iPXE loads, the DHCP server will direct it to boot from options configured in your +``http://my.web.server/real_boot_script.txt`` file. + +Replace "http://my.web.server/real_boot_script.txt" with the address you want iPXE to boot from. + +The address ``192.168.1.1`` should be set to the address your TFTP server is using. + +The subnet being used in this example is private; if the DHCPD service you use applies to your +entire network, modify the configuration as needed. + +iPXE-specific options +~~~~~~~~~~~~~~~~~~~~~ + +There are several DHCP options specific to `iPXE `_ which are not recognized by the standard ISC +dhcpd installation. To add support for these options, place the following at the start of your +:file:`/etc/dhcpd.conf` : + +.. code-block:: console + + ################################################### + # iPXE-specific options # + # Source: http://www.ipxe.org/howto/dhcpd # + ################################################### + option space ipxe; + option ipxe-encap-opts code 175 = encapsulate ipxe; + option ipxe.priority code 1 = signed integer 8; + option ipxe.keep-san code 8 = unsigned integer 8; + option ipxe.skip-san-boot code 9 = unsigned integer 8; + option ipxe.syslogs code 85 = string; + option ipxe.cert code 91 = string; + option ipxe.privkey code 92 = string; + option ipxe.crosscert code 93 = string; + option ipxe.no-pxedhcp code 176 = unsigned integer 8; + option ipxe.bus-id code 177 = string; + option ipxe.bios-drive code 189 = unsigned integer 8; + option ipxe.username code 190 = string; + option ipxe.password code 191 = string; + option ipxe.reverse-username code 192 = string; + option ipxe.reverse-password code 193 = string; + option ipxe.version code 235 = string; + option iscsi-initiator-iqn code 203 = string; + # Feature indicators + option ipxe.pxeext code 16 = unsigned integer 8; + option ipxe.iscsi code 17 = unsigned integer 8; + option ipxe.aoe code 18 = unsigned integer 8; + option ipxe.http code 19 = unsigned integer 8; + option ipxe.https code 20 = unsigned integer 8; + option ipxe.tftp code 21 = unsigned integer 8; + option ipxe.ftp code 22 = unsigned integer 8; + option ipxe.dns code 23 = unsigned integer 8; + option ipxe.bzimage code 24 = unsigned integer 8; + option ipxe.multiboot code 25 = unsigned integer 8; + option ipxe.slam code 26 = unsigned integer 8; + option ipxe.srp code 27 = unsigned integer 8; + option ipxe.nbi code 32 = unsigned integer 8; + option ipxe.pxe code 33 = unsigned integer 8; + option ipxe.elf code 34 = unsigned integer 8; + option ipxe.comboot code 35 = unsigned integer 8; + option ipxe.efi code 36 = unsigned integer 8; + option ipxe.fcoe code 37 = unsigned integer 8; + option ipxe.vlan code 38 = unsigned integer 8; + option ipxe.menu code 39 = unsigned integer 8; + option ipxe.sdi code 40 = unsigned integer 8; + option ipxe.nfs code 41 = unsigned integer 8; + +Next, create an empty :file:`/var/db/dhcp.leases` file and start the dhcpd service with: + +.. code-block:: console + + # mkdir -p /var/db + # touch /var/db/dhcp.leases + # systemctl start dhcp4.service + +TFTP configuration +~~~~~~~~~~~~~~~~~~ + +Clear Linux uses ``dnsmasq`` to provide the tftpd service. Modify +:file:`/etc/dnsmasq.conf` with the following required entries: + +.. code-block:: console + + enable-tftp + tftp-root=/srv/tftp/ + +Download the undionly.kpxe (legacy) and ipxe.efi (EFI) files from +`the iPXE website `_ and place them in your TFTP +directory. Then you can start the service with + +.. code-block:: console + + # systemctl start dnsmasq.service + + +HTTP configuration +~~~~~~~~~~~~~~~~~~ + +The kernel (linux), initramfs (initrd) and the iPXE scripts are transported +via HTTP. The Linux kernel and initrd files can be downloaded from +https://download.clearlinux.org/image/ where clear-$version-pxe.tar.xz is a +compressed tar file containing two clearly-labeled files that should be moved +to the http server root /var/www/pxe/. + +Create a configuration file for the http service (nginx in this example) to +serve the kernel and initramfs in :file:`/etc/nginx/nginx.conf` with the +following: + +.. code-block:: console + + worker_processes 1; + http { + sendfile on; + keepalive_timeout 65; + server { + listen 80; + server_name hostname; + server_name_in_redirect off; + location / { + root /var/www/pxe; + autoindex on; + index index.html index.htm; + } + } + } + + And start the service with: + +.. code-block:: console + + # systemctl start nginx.service + + +iPXE script +~~~~~~~~~~~ + +The iPXE script used is + +.. code-block:: console + + #!ipxe + + kernel linux quiet rdinit=/usr/lib/systemd/systemd-bootchart initcall_debug + tsc=reliable no_timer_check noreplace-smp rw initrd=initrd initrd initrd + boot + +this should be located in ``/var/www/pxe`` with the kernel and initrd. + + +PXE + grub +---------- + +Another option for network booting Clear Linux is to use the GRUB bootloader +for booting in UEFI mode. The bootloader will get its files over TFTP and does +not require having another service to host the network boot artifacts. The +following sets up up a PXE using the GRUB bootloader environment and Clear Linux, +but the configuration options should apply elsewhere. + +The first thing to do is add the pxe-server bundle to your system with: + +.. code-block:: console + + # swupd bundle-add pxe-server + + +DHCP configuration +~~~~~~~~~~~~~~~~~~ + +Add the following content to your :file:`/etc/dhcpd.conf` file + +.. code-block:: console + + allow booting; + allow bootp; + + # Set up a class so you can give out an IP only for devices is attempting network boot. + { + match if substring(option vendor-class-identifier, 0, ; + next-server 192.168.1.1; + grubx64. + } + + # Private subnet, in case you are able to run your own network wide DHCP service. + # Works when the machine you are network booting has two network interfaces, + # one connected to the private PXE boot network and the other connected to an external + # network. + subnet 192.168.1.0 netmask 255.255.255.0 { + pool { + allow members + range 192.168.1.100 192.168.1.200; + } + } + + +Where 192.168.1.1 is set to the address your TFTP server is using, and grubx64.efi is set +to the name of your grub bootloader file. + +The subnet being used in this example is private; if the DHCPD service you use applies to your +entire network, modify the configuration as needed. Also, if multiple devices (including those +not using UEFI) are being supported by this DHCPD service, adding the following logic will allow +selection of the filename fetched from the client: + +.. code-block:: console + + if exists client-arch and option client-arch = 9 { + # client-arch = 9 (64-bit EFI) + filename "grubx64.efi"; + } elsif exists client-arch and option client-arch = 6 { + # client-arch = 6 (32-bit EFI) + filename "grubx32.efi"; + } else { + # client-arch = 0 (Standard PC BIOS) + filename "pxelinux.0"; + } + +Next create an empty :file:`/var/db/dhcp.leases` file and start the dhcpd service with: + +.. code-block:: console + + # mkdir -p /var/db + # touch /var/db/dhcp.leases + # systemctl start dhcp4.service + +TFTP configuration +~~~~~~~~~~~~~~~~~~ + +Clear Linux uses ``dnsmasq`` to provide the tftpd service. It requires +the following entries exist in :file:`/etc/dnsmasq.conf`: + +.. code-block:: console + + enable-tftp + tftp-root=/srv/tftp/ + +The Linux kernel and initrd files can be downloaded from https://download.clearlinux.org/image/ +(with a name clear-$version-pxe.tar.xz) as a compressed tar file containing two clearly-labeled +files that should be moved to the tftp root (``/srv/tftp/`` per the tftp server configuration), +as linux and initrd respectively. The bootloader :file:`grubx64.efi` and its configuration file +:file:`grub.cfg` should also be placed in the tftp root ``/srv/tftp/``. + +Now start the tftp service with :command:`systemctl start dnsmasq.service` + +GRUB configuration +~~~~~~~~~~~~~~~~~~ + +Create the GRUB bootloader file (:file:`grubx64.efi`) with the following +command: + +.. code-block:: console + + # grub-mkimage -O x86_64-efi -o grubx64.efi all_video boot btrfs cat + chain configfile echo efifwsetup efinet ext2 fat font gfxmenu gfxterm + gzio halt hfsplus iso9660 jpeg linuxefi loadenv loopback lvm mdraid09 + mdraid1x minicmd multiboot multiboot2 normal part_apple part_msdos + part_gpt password_pbkdf2 png reboot search search_fs_uuid search_fs_file + search_label serial sleep syslinuxcfg test tftp usbserial_pl2303 + usbserial_ftdi usbserial_usbdebugvideo xfs + +and it will be placed in your current directory. + +Next, a GRUB configuration file (:file:`grub.cfg`) should contain the +following content: + +.. code-block:: console + + set pager=1 + + export menuentry_id_option + + function load_video { + if [ x$feature_all_video_module = xy ]; then + insmod all_video + else + insmod efi_gop + insmod efi_uga + insmod ieee1275_fb + insmod vbe + insmod vga + insmod video_bochs + insmod video_cirrus + fi + } + + terminal_output console + if [ x$feature_timeout_style = xy ] ; then + set timeout_style=menu + set timeout=5 + else + set timeout=5 + fi + + menuentry 'Clear Linux Installation' --class gnu-linux --class gnu --class os { + load_video + set gfxpayload=keep + insmod gzio + insmod part_gpt + insmod ext2 + linuxefi /linux + initrdefi /initrd + } + +Where the Linux kernel is named "linux" and the initrd "initrd". \ No newline at end of file