diff --git a/source/network_boot.rst b/source/network_boot.rst index 07fd4147..ee66e189 100644 --- a/source/network_boot.rst +++ b/source/network_boot.rst @@ -7,50 +7,49 @@ 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 `_. +`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. - 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 such as 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, +To retrieve data through other protocols such as HTTP, iSCSI, :abbr:`ATA over Ethernet +(AoE)`, or :abbr:`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 +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 OS for Intel Architecture, but the configuration options may apply elsewhere. Step 1 -------- +------ -Add the pxe-server bundle to your system which has all the bits to run a PXE +Add the ``pxe-server`` bundle to your system; this has all the bits to run a PXE server for Clear Linux. .. code-block:: console - # swupd bundle-add pxe-server + # swupd bundle-add pxe-server Step 2 -------- +------ -Configure the tftpd service using ``dnsmasq``. To do this, create the +Configure the ``tftpd`` service using ``dnsmasq``. To do this, populate the :file:`/etc/dnsmasq.conf` file with the following entries: .. code-block:: console - # cat << EOF > /etc/dnsmasq.conf - enable-tftp - tftp-root=/srv/tftp/ - EOF + # cat << EOF > /etc/dnsmasq.conf + enable-tftp + tftp-root=/srv/tftp/ + EOF Step 3 ------- @@ -60,13 +59,13 @@ Copy the :file:`/usr/share/ipxe/undionly.kpxe` (legacy) and directory. You can also download the ``undionly.kpxe`` (legacy) and ``ipxe.efi`` (EFI) -files from `the iPXE website `_. +files from the `iPXE website`_. .. code-block:: console - # mkdir /srv/tftp/ - # cp /usr/share/ipxe/undionly.kpxe /srv/tftp/undionly.kpxe - # cp /usr/share/ipxe/ipxe-x86_64.efi /srv/tftp/ipxe.efi + # mkdir /srv/tftp/ + # cp /usr/share/ipxe/undionly.kpxe /srv/tftp/undionly.kpxe + # cp /usr/share/ipxe/ipxe-x86_64.efi /srv/tftp/ipxe.efi Note. @@ -80,40 +79,40 @@ Start the dnsmasq service with: .. code-block:: console - # systemctl start dnsmasq.service + # systemctl start dnsmasq.service Step 5 ------- The kernel (linux), initramfs (initrd) and the iPXE scripts are transported via -HTTP. Download the Linux kernel and initrdfiles, and place them into the http +HTTP. Download the Linux kernel and initrd files, and put them in the http server root ``/var/www/pxe/``. .. code-block:: console - # mkdir -p /var/www/pxe/ - # version=$(cat /usr/share/clear/version) - # curl -o /var/www/pxe/clear-${version}-pxe.tar.xz https://download.clearlinux.org/current/clear-${version}-pxe.tar.xz - # tar -xJf /var/www/pxe/clear-${version}-pxe.tar.xz -C /var/www/pxe/ && rm /var/www/pxe/clear-${version}-pxe.tar.xz - # unset version + # mkdir -p /var/www/pxe/ + # version=$(cat /usr/share/clear/version) + # curl -o /var/www/pxe/clear-${version}-pxe.tar.xz https://download.clearlinux.org/current/clear-${version}-pxe.tar.xz + # tar -xJf /var/www/pxe/clear-${version}-pxe.tar.xz -C /var/www/pxe/ && rm /var/www/pxe/clear-${version}-pxe.tar.xz + # unset version Step 6 ------- -Create an iPXE script, and place it into the http server root -:file:`/var/www/pxe/ipxe_boot_script.txt`. +Create an iPXE script named ``ipxe_boot_script.txt`` under the http server root +:file:`/var/www/pxe/`. .. code-block:: console - # cat << EOF > /var/www/pxe/ipxe_boot_script.txt - #!ipxe + # cat << EOF > /var/www/pxe/ipxe_boot_script.txt + #!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 - EOF + kernel linux quiet rdinit=/usr/lib/systemd/systemd-bootchart initcall_debug tsc=reliable no_timer_check noreplace-smp rw initrd=initrd + initrd initrd + boot + EOF -If your kernel is not named linux, either rename the kernel or create a symlink. +If your kernel is not already named ``linux``, either rename the kernel or create a symlink. .. code-block:: console @@ -130,24 +129,24 @@ serve the kernel, initramfs, and ipxe_boot_script in .. code-block:: console - # mkdir /etc/nginx/ - # cat << EOF > /etc/nginx/nginx.conf - server { - listen 80; - server_name hostname; - server_name_in_redirect off; - location / { - root /var/www/pxe; - autoindex on; - index index.html index.htm; - } - } - EOF + # mkdir /etc/nginx/ + # cat << EOF > /etc/nginx/nginx.conf + server { + listen 80; + server_name hostname; + server_name_in_redirect off; + location / { + root /var/www/pxe; + autoindex on; + index index.html index.htm; + } + } + EOF Step 8 ------- -Start the nginx service with: +Start the nginx service: .. code-block:: console @@ -156,47 +155,47 @@ Start the nginx service with: Step 9 ------- -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 +To use PXE chainloading, set up ISC DHCPD to first assign ``undionly.kpxe`` to any +legacy PXE clients, and to then assign boot configuration to iPXE clients. Do this +by telling ISC DHCPD to make the assignments based on the DHCP user class. Here’s one way to do this using the :file:`/etc/dhcpd.conf` file: .. code-block:: console - allow booting; - allow bootp; - DHCPDARGS="interface"; + allow booting; + allow bootp; + DHCPDARGS="interface"; - # 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/ipxe_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"; - } - } + # Set up a class to assign an "IP only" to devices 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/ipxe_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; - } - } + # 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`` +or from a UEFI client, respectifully. 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. Note. @@ -210,58 +209,58 @@ Note. Step 10 ------- -There are several DHCP options specific to `iPXE `_ which are -not recognized by the standard ISC dhcpd installation. To add suport for these -options, place the following at the start of your :file:`/etc/dhcpd.conf`: +There are several DHCP options specific to `iPXE`_ which are +not recognized by the standard ISC DHCPD installation. To add suport for these +options, add the following to the top of your :file:`/etc/dhcpd.conf`: .. code-block:: console - ################################################### - # iPXE-specific options # - # Source: http://www.ipxe.org/howto/dhcpd # - ################################################### - option space ipxe; - option client-arch code 93 = unsigned integer 16; - 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; + ################################################### + # iPXE-specific options # + # Source: http://www.ipxe.org/howto/dhcpd # + ################################################### + option space ipxe; + option client-arch code 93 = unsigned integer 16; + 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; Step 11 ------- @@ -270,61 +269,62 @@ Create an empty :file:`/var/db/dhcpd.leases` file. .. code-block:: console - # mkdir /var/db/ - # touch /var/db/dhcpd.leases + # mkdir /var/db/ + # touch /var/db/dhcpd.leases Step 12 ------- -Start the dhcp service with: +Start the dhcp service: .. code-block:: console - # systemctl start dhcp4.service + # systemctl start dhcp4.service -PXE + grub -======================= +PXE + GRUB +========== -Another option for network booting Clear Linux OS for Intel Architecture 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 OS for Intel Architecture, -but the configuration options should apply elsewhere. +Another option for network booting Clear Linux* OS for Intel Architecture is to +use the GRUB bootloader to boot in UEFI mode. The bootloader will get its files +over TFTP; it 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 OS for Intel Architecture, but the configuration options should +apply elsewhere. -First add the pxe-server bundle to your system with: +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 ------------------------ +------------------ Add the following content to your :file:`/etc/dhcpd.conf` file: .. code-block:: console - allow booting; - allow bootp; + 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. - } + # 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; - } - } + # 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 @@ -337,98 +337,98 @@ 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"; - } + 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 + # mkdir -p /var/db + # touch /var/db/dhcp.leases + # systemctl start dhcp4.service GRUB configuration ------------------------ +------------------ Create the GRUB bootloader file (:file:`grubx64.efi`) with the following -command: +command; it will create the file in your current directory. + .. 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 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 xfs -This file will then 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 + set pager=1 - export menuentry_id_option + export menuentry_id_option - function load_video { - if [ x$feature_all_video_module = xy ]; then - insmod all_video + 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 - insmod efi_gop - insmod efi_uga - insmod ieee1275_fb - insmod vbe - insmod vga - insmod video_bochs - insmod video_cirrus + set timeout=5 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 - } + 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". TFTP configuration ------------------------ +------------------ Clear Linux OS for Intel Archiecture 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/ + enable-tftp + tftp-root=/srv/tftp/ The Linux kernel and initrd files can be downloaded from https://download.clearlinux.org/current/ (with a name clear-$version-pxe.tar.xz) as a compressed tar file containing two clearly-labeled @@ -440,4 +440,10 @@ Now start the tftp service with this command: .. code-block:: console - systemctl start dnsmasq.service + systemctl start dnsmasq.service + + + +.. _TFTP: http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf +.. _iPXE website: http://boot.ipxe.org/ +.. _iPXE: http://ipxe.org/ \ No newline at end of file