diff --git a/source/network_boot.rst b/source/network_boot.rst index 46ccc510..23581db5 100644 --- a/source/network_boot.rst +++ b/source/network_boot.rst @@ -1,38 +1,54 @@ +.. _network_booting: + Network Booting =============== -Booting from network is an important feature that every data center should have, and is used among other things to install an operating system. To do this task, a Pre-boot eXecution Environment (PXE) is defined on a foundation of industry-standard Internet protocols and services that are widely deployed in the industry, namely TCP/IP, DHCP, and TFTP [1]_. - -.. [1] Preboot Execution Environment (PXE) Specification Version 2.1, http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf +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 is an OS that uses UEFI to boot, then your target machine should be a UEFI capable. Also, so far, the UEFI binary is not signed, so you must disable secure boot. + 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 Fibre Channel over Ethernet (FCoE), an open source network boot firmware was created: iPXE. iPXE provides a full PXE implementation enhanced with additional features [2]_, and It can be used to enable computers without built-in PXE support to boot from the network. +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. -.. [2] iPXE home page, http://ipxe.org/ - -Clear Linux* Project for Intel Architecture can do network booting via HTTP with the help of iPXE. The following sets up a iPXE environment using Clear Linux but the configuration options should apply elsewhere. The first thing to do is add the pxe-server bundle to your system with: +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 + # swupd bundle-add pxe-server + DHCP configuration ~~~~~~~~~~~~~~~~~~ -To use PXE chainloading, you need to set up ISC dhcpd to hand out undionly.kpxe to legacy PXE clients, and then hand out boot configuration only to iPXE clients. You can do this by telling ISC dhcpd to use different configurations based on the DHCP user class with the following configuration file options: +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; + allow booting; + allow bootp; - # Setup a class so you can give out an IP only for devices is attempting network boot. + # 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; @@ -57,16 +73,24 @@ allow bootp; } } -This will ensure that the iPXE image (undionly.kpxe for BIOS and ipxe.efi for EFI) is handed out only when the DHCP request comes from a legacy PXE client or a UEFI client. Once iPXE has been loaded, the DHCP server will direct it to boot from http://my.web.server/real_boot_script.txt. You should replace filename "http://my.web.server/real_boot_script.txt" with the address you want iPXE to boot from. +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. -The address 192.168.1.1 should be set to the address your TFTP server is using. +Replace "http://my.web.server/real_boot_script.txt" with the address you want iPXE to boot from. -The subnet being used in this case is private, if the dhcpd service is for your entire network the configuration should be modified according to your s configuration needs. +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 that are specific to iPXE [2]_ and that are not recognised by the standard ISC dhcpd installation. To add support for these options, place the following at the start of your /etc/dhcpd.conf: +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 @@ -116,34 +140,46 @@ There are several DHCP options that are specific to iPXE [2]_ and that are not r option ipxe.sdi code 40 = unsigned integer 8; option ipxe.nfs code 41 = unsigned integer 8; -Next create an empty /var/db/dhcp.leases file and start the dhcpd service with: +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 + + # mkdir -p /var/db + # touch /var/db/dhcp.leases + # systemctl start dhcp4.service TFTP configuration ~~~~~~~~~~~~~~~~~~ -Clear Linux uses dnsmasq to provide the tftpd service. Its configuration file is /etc/dnsmasq.conf and requires the following entries: +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/ -You should place: undionly.kpxe (legacy) and ipxe.efi (EFI) files in your TFTP directory. You can download them from: http://boot.ipxe.org/. Then you can start the service with: +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 + # systemctl start dnsmasq.service + HTTP configuration ~~~~~~~~~~~~~~~~~~ -The kernel (linux), initramfs (initrd) and the iPXE script are transported via HTTP. 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 http root (/var/www/pxe/ per the http server configuration) as linux and initrd respectively. +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 case) to serve the kernel and initramfs in /etc/nginx/nginx.conf with the following: +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 @@ -163,54 +199,63 @@ Create a configuration file for the http service (nginx in this case) to serve t } } -Then start the service with: + And start the service with: .. code-block:: console - systemctl start nginx.service + # systemctl start nginx.service + iPXE script ~~~~~~~~~~~ -The iPXE script used is: +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 + 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. +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 built for booting in UEFI mode. The bootloader will get its files over TFTP and so does not require having another service to host the network boot artifacts. The following setups up a PXE using the grub bootloader environment using Clear Linux but the configuration options should apply elsewhere. The first thing to do is add the pxe-server bundle to your system with: +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 + # swupd bundle-add pxe-server + DHCP configuration ~~~~~~~~~~~~~~~~~~ -Add the following content to your /etc/dhcpd.conf file: +Add the following content to your :file:`/etc/dhcpd.conf` file .. code-block:: console allow booting; allow bootp; - # Setup a class so you can give out an IP only for devices is attempting network boot. + # 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 t able to run your own network wide DHCP service. + # 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. @@ -221,9 +266,14 @@ Add the following content to your /etc/dhcpd.conf file: } } -Where the address 192.168.1.1 should be set to the address your TFTP server is using and grubx64.efi should be set to the name of your grub bootloader file. -The subnet being used in this case is private, if the dhcpd service is for your entire network the configuration should be modified according to your s configuration needs. In addition if multiple devices (including those not using UEFI) are being supported by this dhcpd service, adding the following logic will allow selecting which filename is given back the client: +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 @@ -238,43 +288,53 @@ The subnet being used in this case is private, if the dhcpd service is for your filename "pxelinux.0"; } -Next create an empty /var/db/dhcp.leases file and start the dhcpd service with: +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 + # mkdir -p /var/db + # touch /var/db/dhcp.leases + # systemctl start dhcp4.service TFTP configuration ~~~~~~~~~~~~~~~~~~ -Clear Linux uses dnsmasq to provide the tftpd service. Its configuration file is /etc/dnsmasq.conf and requires the following entries: +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 (grubx64.efi) and its configuration file (grub.cfg) should also be placed in the tftp-root (/srv/tftp/). -Now start the tftp service with: +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/``. -.. code-block:: console +Now start the tftp service with :command:`systemctl start dnsmasq.service` - systemctl start dnsmasq.service - -Grub configuration +GRUB configuration ~~~~~~~~~~~~~~~~~~ -The grub bootloader file must be created with the following command: +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 + # 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 -The result of this command will be a grubx64.efi file created in your current directory. +and it will be placed in your current directory. -Next a grub configuration file (grub.cfg) should contain the following content: +Next, a GRUB configuration file (:file:`grub.cfg`) should contain the +following content: .. code-block:: console @@ -314,4 +374,4 @@ Next a grub configuration file (grub.cfg) should contain the following content: initrdefi /initrd } -Where the Linux kernel is named "linux" and the initrd "initrd". +Where the Linux kernel is named "linux" and the initrd "initrd". \ No newline at end of file