diff --git a/source/_figures/ipxe/ipxe-install-1.png b/source/_figures/ipxe/ipxe-install-1.png new file mode 100644 index 00000000..52bab4b1 Binary files /dev/null and b/source/_figures/ipxe/ipxe-install-1.png differ diff --git a/source/_figures/ipxe/ipxe-install-2.png b/source/_figures/ipxe/ipxe-install-2.png new file mode 100644 index 00000000..cfa3f517 Binary files /dev/null and b/source/_figures/ipxe/ipxe-install-2.png differ diff --git a/source/get-started/index.rst b/source/get-started/index.rst index 02f4a15f..bab843b5 100644 --- a/source/get-started/index.rst +++ b/source/get-started/index.rst @@ -35,6 +35,7 @@ Install bare-metal-install-desktop bare-metal-install-server install-configfile + ipxe-install .. _virtual-machine-install: diff --git a/source/get-started/ipxe-install.rst b/source/get-started/ipxe-install.rst new file mode 100644 index 00000000..73e6105b --- /dev/null +++ b/source/get-started/ipxe-install.rst @@ -0,0 +1,580 @@ +.. _ipxe-install: + +Install |CL| Over the Network with iPXE +####################################### + +PXE :abbr:`PXE (Pre-boot Execution Environment)` is an industry standard +that describes client-server interaction with network-boot software and +uses the DHCP and TFTP protocols. iPXE, a fork of gPXE, is an open-source +version of PXE. It enables computers without built-in PXE capability to +network-boot using protocols such as HTTP, :abbr:`iSCSI (Internet Small +Computer Systems Interface)`, :abbr:`AoE (ATA over Ethernet\*)`, and +:abbr:`FCoE (Fiber Channel over Ethernet\*)`. + +This guide demonstrates how to setup an iPXE server to install |CL-ATTR| +over the network. + +Figure 1 depicts the flow of information between an iPXE server and a +PXE client. + +.. figure:: ../_figures/ipxe/ipxe-install-1.png + :alt: PXE information flow + + Figure 1: PXE information flow + +.. caution:: + + The |CL| PXE image that boots through the iPXE process automatically + erases all data and partitions on the PXE client system and performs + a fresh installation according to a clr-installer YAML configuration + file. + +Prerequisites +************* + +Your iPXE server must have: + +* Ethernet/LAN boot option +* At least two network adapters +* Connection to a public (WAN) network +* Secure Boot option disabled in BIOS + +Your clients must have: + +* Ethernet/LAN boot option +* One network adapter +* Secure Boot option disabled in BIOS +* The minimum requirements to run |CL|. Review the :ref:`compatibility-check`. + +Connect the iPXE server and clients to a network switch on a private +(LAN) network, as shown in Figure 2. + +.. figure:: ../_figures/ipxe/ipxe-install-2.png + :alt: Network topology + + Figure 2: Network topology + +Install |CL| on server +********************** + +#. Install |CL| on the system that will serve as the iPXE server. + We recommend using the `server` version. + +#. Open a terminal window. + +#. Add the :command:`pxe-server` bundle to your |CL| system. + The bundle contains all the necessary apps (web server, iPXE firmwares, + dnsmasq which provides TFTP, DNS, DHCP functionalities) to run an + iPXE server. + + .. code-block:: bash + + sudo swupd bundle-add pxe-server + +#. Define the following variables used for setting up the iPXE server. + Be sure to substitute the value for the WAN_INTERFACE and + LAN_INTERFACE variables with your LAN and WAN interfaces names. + Use :command:`ip a` to list your network devices and get their + names. + + .. code-block:: bash + + IPXE_APP_NAME=ipxe + IPXE_PORT=50000 + WEB_ROOT_DIR=/var/www + IPXE_ROOT_DIR=${WEB_ROOT_DIR}/${IPXE_APP_NAME} + TFTP_ROOT_DIR=/srv/tftp + CLR_INSTALLER_CONF_DIR=clr-installer-configs + WAN_INTERFACE=eno1 + LAN_INTERFACE=eno2 + IPXE_SUBNET=192.168.100 + IPXE_LAN_IP=${IPXE_SUBNET}.1 + IPXE_SUBNET_MASK_IP=255.255.255.0 + IPXE_SUBNET_BITMASK=16 + +Setup nginx web server to host iPXE +*********************************** + +#. Set up an nginx web server to serve the |CL| PXE image to clients + using these steps: + + .. code-block:: bash + + sudo mkdir -p /etc/nginx/conf.d + sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf + sudo tee -a /etc/nginx/conf.d/${IPXE_APP_NAME}.conf << EOF + server { + listen ${IPXE_PORT}; + server_name localhost; + # directory to store ipxe + location /${IPXE_APP_NAME}/ { + root ${WEB_ROOT_DIR}/${IPXE_APP_NAME}; + rewrite ^/${IPXE_APP_NAME}(/.*)$ \$1 break; + } + # directory to store clr-installer configs + location /${CLR_INSTALLER_CONF_DIR}/ { + root ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR}; + rewrite ^/${CLR_INSTALLER_CONF_DIR}(/.*)$ \$1 break; + } + } + EOF + +#. Set nginx to start automatically on boot and then start it. + + .. code-block:: bash + + sudo systemctl enable nginx + sudo systemctl start nginx + +Configure iPXE +************** + +#. Download the latest |CL| PXE image and extract the files into the iPXE root. + + .. code-block:: bash + + sudo curl -o /tmp/clear-pxe.tar.xz \ + https://cdn.download.clearlinux.org/current/clear-$(curl \ + https://cdn.download.clearlinux.org/latest)-pxe.tar.xz + sudo mkdir -p ${IPXE_ROOT_DIR} + sudo tar -xJf /tmp/clear-pxe.tar.xz -C ${IPXE_ROOT_DIR} + sudo ln -sf $(ls ${IPXE_ROOT_DIR} | grep 'org.clearlinux.*') ${IPXE_ROOT_DIR}/linux + + .. note:: + + Ensure that the initial ramdisk file is named :file:`initrd` and + the kernel file is named :file:`linux`, which is a symbolic link to the + actual kernel file. + +#. Create an iPXE boot script. The script presents a menu of bootable images to + download, boot, and install |CL|, according to a designated clr-installer + YAML configuration file. + + .. code-block:: bash + + sudo tee -a ${IPXE_ROOT_DIR}/ipxe_boot_script.ipxe << EOF + #!ipxe + + set menu-timeout 5000 + set submenu-timeout \${menu-timeout} + isset \${menu-default} || set menu-default clr-server + + :menu + menu Select a version of Clear Linux OS to install + item clr-desktop Clear Linux OS (Desktop) + item clr-server Clear Linux OS (Server) + item ipxe-shell iPXE Shell + item reboot Reboot + + choose --timeout \${menu-timeout} --default \${menu-default} selected || goto cancel + set menu-timeout 0 + goto \${selected} + + :clr-desktop + echo Booting and installing Clear Linux OS (Desktop)... + kernel linux quiet init=/usr/lib/systemd/systemd-bootchart initcall_debug \\ + tsc=reliable no_timer_check noreplace-smp rw initrd=initrd \\ + clri.descriptor=http://${IPXE_LAN_IP}:${IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/clr-desktop.yaml + initrd initrd + boot || goto failed + + :clr-server + echo Booting and installing Clear Linux OS (Server)... + kernel linux quiet init=/usr/lib/systemd/systemd-bootchart initcall_debug \\ + tsc=reliable no_timer_check noreplace-smp rw initrd=initrd \\ + clri.descriptor=http://${IPXE_LAN_IP}:${IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/clr-server.yaml + initrd initrd + boot || goto failed + + :cancel + echo Menu canceled, going to iPXE shell + + :ipxe-shell + echo Type 'exit' to return to the menu + shell + set menu-timeout 0 + set submenu-timeout 0 + goto menu + + echo Booting + :failed + echo Booting failed, going to iPXE shell + goto shell + + :reboot + echo Rebooting... + sleep 1 + reboot + EOF + + .. note:: + + The `clri.discriptor` option tells clr-installer where to download a YAML + configuration file to use. Without this option, the |CL| PXE image will + simply boot and not perform any installation. + +Add clr-installer YAML configuration files +****************************************** + +After the |CL| PXE image boot, clr-installer downloads the YAML configuration file +specified in the kernel command-line and installs accordingly. + +See `Installer YAML Syntax`_ for more information on clr-installer configuration +YAML syntax. + +#. Create the directory to store the configuration files. + + .. code-block:: bash + + sudo mkdir -p ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR} + +#. Create this sample `Desktop` configuration called :file:`clr-desktop.yaml`. + + .. code-block:: bash + + sudo tee -a ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR}/clr-desktop.yaml << EOF + #clear-linux-config + + # switch between aliases if you want to install to an actuall block device + # i.e /dev/sda + block-devices: [ + {name: "bdevice", file: "/dev/sda"} + ] + + targetMedia: + - name: \${bdevice} + type: disk + children: + - name: \${bdevice}1 + fstype: vfat + mountpoint: /boot + size: "150M" + type: part + - name: \${bdevice}2 + fstype: swap + size: "250M" + type: part + - name: \${bdevice}3 + fstype: ext4 + mountpoint: / + size: "0" # Use remaining disk space + type: part + + bundles: [ bootloader, os-core, os-core-update, desktop-autostart, libreoffice, + vlc, c-basic, git, openssh-server, vim ] + + autoUpdate: true + postArchive: false + postReboot: true + telemetry: false + hostname: clrlinux-desktop + keyboard: us + language: en_US.UTF-8 + kernel: kernel-native + + users: + - login: clrlinux + username: Clear Linux + # Password is "clear123" + password: \$6\$SJJMfnInWQg.CvMA\$m2F8dJGj71zvi9mSNMktHMsPH3qhBm8pgXDNdaBe2yFfgi479JXvEqWkvQ6OxIUgGNQ5YXFIF0tCn.hEXB90G/ + admin: true + - login: root + username: Root Root + # Password is "clear123" + password: \$6\$SJJMfnInWQg.CvMA\$m2F8dJGj71zvi9mSNMktHMsPH3qhBm8pgXDNdaBe2yFfgi479JXvEqWkvQ6OxIUgGNQ5YXFIF0tCn.hEXB90G/ + admin: true + + pre-install: [ + {cmd: "curl -o /tmp/add-issue.sh http://${IPXE_LAN_IP}:${IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/add-issue.sh"}, + {cmd: "chmod +x /tmp/add-issue.sh"} + ] + + post-install: [ + {cmd: "echo PermitRootLogin yes > \${chrootDir}/etc/ssh/sshd_config"}, + {cmd: "/tmp/add-issue.sh \${chrootDir}"} + ] + EOF + + +#. Create this sample `Server` configuration called :file:`clr-server.yaml`. + + .. code-block:: bash + + sudo tee -a ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR}/clr-server.yaml << EOF + #clear-linux-config + + # switch between aliases if you want to install to an actuall block device + # i.e /dev/sda + block-devices: [ + {name: "bdevice", file: "/dev/sda"} + ] + + targetMedia: + - name: \${bdevice} + type: disk + children: + - name: \${bdevice}1 + fstype: vfat + mountpoint: /boot + size: "150M" + type: part + - name: \${bdevice}2 + fstype: swap + size: "250M" + type: part + - name: \${bdevice}3 + fstype: ext4 + mountpoint: / + size: "0" # Use remaining disk space + type: part + + bundles: [ bootloader, os-core, os-core-update, vim ] + + autoUpdate: true + postArchive: false + postReboot: true + telemetry: false + hostname: clrlinux-server + keyboard: us + language: en_US.UTF-8 + kernel: kernel-native + + users: + - login: clrlinux + username: Clear Linux + # Password is "clear123" + password: \$6\$SJJMfnInWQg.CvMA\$m2F8dJGj71zvi9mSNMktHMsPH3qhBm8pgXDNdaBe2yFfgi479JXvEqWkvQ6OxIUgGNQ5YXFIF0tCn.hEXB90G/ + admin: true + - login: root + username: Root Root + # Password is "clear123" + password: \$6\$SJJMfnInWQg.CvMA\$m2F8dJGj71zvi9mSNMktHMsPH3qhBm8pgXDNdaBe2yFfgi479JXvEqWkvQ6OxIUgGNQ5YXFIF0tCn.hEXB90G/ + admin: true + + pre-install: [ + {cmd: "curl -o /tmp/add-issue.sh http://${IPXE_LAN_IP}:${IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/add-issue.sh"}, + {cmd: "chmod +x /tmp/add-issue.sh"} + ] + + post-install: [ + {cmd: "echo PermitRootLogin yes > \${chrootDir}/etc/ssh/sshd_config"}, + {cmd: "/tmp/add-issue.sh \${chrootDir}"} + ] + EOF + +#. Add following content to the :file:`add-issue.sh` script, which will be + used by the above two YAML configuration files: + + .. code-block:: bash + + sudo tee -a ${WEB_ROOT_DIR}/${CLR_INSTALLER_CONF_DIR}/add-issue.sh << EOF + #!/bin/bash + echo "Creating custom issue file for \$1" + + echo "Welcome to the Clear Linux* OS + + * Documentation: https://clearlinux.org/documentation + * Community Support: https://community.clearlinux.org + + " >> \$1/etc/issue + + exit 0 + EOF + +Configure network +***************** + +#. The DNS server, included with the `pxe-server` bundle, + conflicts with the DNS stub listener provided in `systemd-resolved`. + Disable the DNS stub listener and temporarily stop `systemd-resolved`. + + .. code-block:: bash + + sudo mkdir -p /etc/systemd + sudo tee -a /etc/systemd/resolved.conf << EOF + [Resolve] + DNSStubListener=no + EOF + + sudo systemctl stop systemd-resolved + +#. Disable NetworkManager. The base installation of |CL| comes with two + network managers, systemd-networkd and NetworkManager, with the latter + being the default. systemd-networkd is recommended for a server use case, + so we will disable NetworkManager. + + .. code-block:: bash + + sudo systemctl mask --now NetworkManager + +#. Assign a static IP address to the LAN side network adapter + and restart `systemd-networkd`. + + .. code-block:: bash + + sudo mkdir -p /etc/systemd/network + sudo tee -a /etc/systemd/network/70-internal-static.network << EOF + [Match] + Name=${LAN_INTERFACE} + [Network] + DHCP=no + Address=${IPXE_LAN_IP}/${IPXE_SUBNET_BITMASK} + EOF + + sudo systemctl enable systemd-networkd + sudo systemctl restart systemd-networkd + +Setup NAT +********* + +#. Configure :abbr:`NAT (Network Address Translation)` to route traffic from + the LAN to the WAN network so clients can download upstream bundles for + installation. And to make these changes persistent during reboots, save the + changes to the firewall. + + .. code-block:: bash + + sudo iptables -t nat -F POSTROUTING + sudo iptables -t nat -A POSTROUTING -o ${WAN_INTERFACE} -j MASQUERADE + sudo systemctl enable iptables-save.service + sudo systemctl restart iptables-save.service + sudo systemctl enable iptables-restore.service + sudo systemctl restart iptables-restore.service + +#. Configure the kernel to forward network packets to different interfaces. + Otherwise, NAT will not work. + + .. code-block:: bash + + sudo mkdir -p /etc/sysctl.d + sudo tee -a /etc/sysctl.d/80-nat-forwarding.conf << EOF + net.ipv4.ip_forward=1 + EOF + + sudo tee -a /proc/sys/net/ipv4/ip_forward << EOF + 1 + EOF + +Setup dnsmaq for DHCP, DNS, and TFTP functionalities +**************************************************** + +#. Create a configuration file for `dnsmasq` to listen on a dedicated IP address + for TFTP, DNS, and DHCP functions. PXE clients on the LAN network will talk to + this IP address. + + .. code-block:: bash + + sudo tee -a /etc/dnsmasq.conf << EOF + listen-address=${IPXE_LAN_IP} + EOF + +#. Add the options to serve iPXE firmware images to clients over TFTP to + the :file:`dnsmasq` configuration file. + + .. code-block:: bash + + sudo tee -a /etc/dnsmasq.conf << EOF + enable-tftp + tftp-root=${TFTP_ROOT_DIR} + EOF + +#. Add the options to host a DHCP server for clients to the :file:`dnsmasq` + configuration file. + + .. code-block:: bash + + sudo tee -a /etc/dnsmasq.conf << EOF + dhcp-leasefile=/var/db/dnsmasq.leases + + dhcp-authoritative + dhcp-option=option:router,${IPXE_LAN_IP} + dhcp-option=option:dns-server,${IPXE_LAN_IP} + + dhcp-match=set:ipxeclient,60,IPXEClient* + dhcp-range=tag:ipxeclient,${IPXE_SUBNET}.2,${IPXE_SUBNET}.253,${IPXE_SUBNET_MASK_IP},15m + dhcp-range=tag:!ipxeclient,${IPXE_SUBNET}.2,${IPXE_SUBNET}.253,${IPXE_SUBNET_MASK_IP},6h + + dhcp-match=set:ipxeboot,175 + dhcp-boot=tag:ipxeboot,http://${IPXE_LAN_IP}:${IPXE_PORT}/${IPXE_APP_NAME}/ipxe_boot_script.ipxe + dhcp-boot=tag:!ipxeboot,undionly.kpxe,${IPXE_LAN_IP} + EOF + + The configuration provides the following important functions: + + * Directs clients without an iPXE implementation to the TFTP server + to acquire architecture-specific iPXE firmware images that allow them + to perform an iPXE boot. + * Activates only on the network adapter that has an IP address on the + defined subnet. + * Directs clients to the DNS server. + * Directs clients to the iPXE server for routing via NAT. + * Divides the private network into two pools of IP addresses. One pool + is for network boot and one pool is used after boot. Each pool has + their own lease times. + +#. Create a file for `dnsmasq` to record the IP addresses it provides + to clients. + + .. code-block:: bash + + sudo mkdir -p /var/db + sudo touch /var/db/dnsmasq.leases + +#. Create a TFTP hosting directory and populate it with the iPXE firmware. + + .. code-block:: bash + + sudo mkdir -p ${TFTP_ROOT_DIR} + sudo ln -sf /usr/share/ipxe/undionly.kpxe ${TFTP_ROOT_DIR}/undionly.kpxe + +#. Start `dnsmasq` and enable startup on boot. + + .. code-block:: bash + + sudo systemctl daemon-reload + sudo systemctl enable dnsmasq + sudo systemctl restart dnsmasq + +#. Start `systemd-resolved`. + + .. code-block:: bash + + sudo systemctl start systemd-resolved + + .. note:: + + `systemd-resolved` dynamically updates the list of DNS servers for the + LAN network if you use the `dnsmasq` DNS server. The setup creates a + pass-through DNS server that relies on the DNS servers listed in + :file:`/etc/resolv.conf`. + +Verify setup +************ + +Verify you can access these URLs before deploying: + +* http://{$IPXE_LAN_IP}:{$IPXE_PORT}/${IPXE_APP_NAME}/ipxe_boot_script.ipxe +* http://{$IPXE_LAN_IP}:{$IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/clr-desktop.yaml +* http://{$IPXE_LAN_IP}:{$IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/clr-server.yaml +* http://{$IPXE_LAN_IP}:{$IPXE_PORT}/${CLR_INSTALLER_CONF_DIR}/add-issue.sh + +Deploy +****** + +#. Connect your client system to the LAN network. + +#. Power on the client. + +#. Set your client to network boot. It should get an IP address and download + the iPXE script. + +#. When presented with the iPXE menu, select one of the options. The client + will then download and boot the |CL| image. Once booted, clr-installer will + download the assigned YAML configuration file and begin to install |CL|. + After installation, the client will reboot to |CL|. + +.. _iPXE: + http://ipxe.org/ + +.. _Installer YAML Syntax: + https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md diff --git a/source/guides/clear/ister.rst b/source/guides/clear/ister.rst index b71aa8cc..21e2b6af 100644 --- a/source/guides/clear/ister.rst +++ b/source/guides/clear/ister.rst @@ -86,7 +86,6 @@ Related topics ************** * :ref:`mixer` -* :ref:`bulk-provision` .. _ister.py: https://github.com/bryteise/ister .. _Current release: https://cdn.download.clearlinux.org/current/ diff --git a/source/guides/maintenance/bulk-provision.rst b/source/guides/maintenance/bulk-provision.rst deleted file mode 100644 index a609fa6a..00000000 --- a/source/guides/maintenance/bulk-provision.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. _bulk-provision: - -Bulk provision -############## - -This guide explains how to perform a bulk provision of |CL-ATTR| using a -combination of the |CL| installer, Ister, and -:abbr:`ICIS (Ister Cloud Init Service)`. - -.. contents:: - :local: - :depth: 1 - -Overview -******** - -To configure a bulk provision: - -* Define Ister configuration files to customize the installation process -* Define cloud-init\* files to customize the installation instance -* Host the configuration files in ICIS to allow Ister to use them during - the installation - -Figure 1 depicts the flow of information between a PXE server and a PXE -client that needs to be set up to perform a bulk provision. - -.. figure:: ./figures/bulk-provision-flow.png - :alt: Bulk provision information flow - - Figure 1: Bulk provision information flow - -Prerequisites -************* - -Before performing a bulk provision, verify you have a PXE server capable -of performing network boots of |CL|. Please refer to our -:ref:`guide on how to perform an iPXE boot` using -:abbr:`NAT (network address translation)` for details. - -Because a bulk provision relies on a reboot, ensure the following -preparations have been made: - -* No existing disks are bootable. -* The network boot option must come immediately after the disk boot option - on any computer performing the installation. - -Configuration -************* - -#. Install ICIS by following the getting started guide on the - `ICIS`_ GitHub\* repository. - -#. Create an Ister installation file and save it to the - :file:`static/ister` directory within the web hosting directory for - ICIS. The installation file is a JSON block and provides Ister - with the steps it needs to perform an installation. The file outlines - what partitions, file systems, and mount points Ister should set - up. Lastly, the file outlines which bundles to install. See our - :ref:`bundles` document for the list of available bundles. The - following example shows the contents of an Ister installation file: - - .. code-block:: json - - { - "DestinationType":"physical", - "PartitionLayout":[ - {"disk":"sda", "partition":1, "size":"512M", "type":"EFI"}, - {"disk":"sda", "partition":2, "size":"512M", "type":"swap"}, - {"disk":"sda", "partition":3, "size":"rest", "type":"linux"} - ], - "FilesystemTypes":[ - {"disk":"sda", "partition":1, "type":"vfat"}, - {"disk":"sda", "partition":2, "type":"swap"}, - {"disk":"sda", "partition":3, "type":"ext4"} - ], - "PartitionMountPoints":[ - {"disk":"sda", "partition":1, "mount":"/boot"}, - {"disk":"sda", "partition":3, "mount":"/"} - ], - "Version":"latest", - "Bundles":[ - "kernel-native", - "os-core", - "os-core-update", - "os-cloudguest" - ], - "IsterCloudInitSvc":"http://192.168.1.1:60000/icis/" - } - - .. important:: - - Every Ister installation file hosted on ICIS must contain the - the `IsterCloudInitSvc` parameter as well as the :command:`os-cloudguest` - bundle. These entries allow Ister to customize an instance of of an - install. - -#. Create an Ister configuration file to define the location of the - Ister installation file. Save it to the :file:`static/ister` directory - within the web hosting directory of ICIS. The following example shows - an Ister configuration file: - - .. code-block:: none - - template=http://192.168.1.1:60000/icis/static/ister/ister.json - -#. Modify the iPXE boot script by adding a kernel parameter to the command line - for booting the network image. Add the kernel parameter `isterconf` with - the location of the Ister configuration file hosted on ICIS as the - kernel parameter value. The following example shows an iPXE boot script - with the `isterconf` parameter: - - .. code-block:: none - - #!ipxe - kernel linux quiet init=/usr/lib/systemd/systemd-bootchart initcall_debug tsc=reliable no_timer_check noreplace-smp rw initrd=initrd isterconf=http://192.168.1.1:60000/icis/static/ister/ister.conf - initrd initrd - boot - - .. note:: - - After the network image of |CL| boots, Ister inspects the - parameters used during boot in :file:`/proc/cmdline` to find the - location of the Ister configuration file. - -#. Write a cloud-init document to customize the instance of the installation - according to your requirements. The `cloud-init`_ documentation provides a - guide on how to write a cloud-init document. The guide covers the - customization options provided by cloud-init after an installation. - -#. Save the cloud-init document to the :file:`static/roles` directory within - the web hosting directory for ICIS with the name of a role you would - like to create. For example, a role may be "database", "web", or "ciao". - -#. After creating the roles, also known as cloud-init files, assign roles to - MAC addresses of PXE clients. To do so, modify the :file:`config.txt` file - in the :file:`static` directory within the web hosting directory of ICIS. - The following example shows an example assignment: - - .. code-block:: none - - # MAC address,role - 00:01:02:03:04:05,ciao - - If MAC addresses of PXE clients are not listed within the - :file:`config.txt` file, a default role for those MAC address may be - defined as follows: - - .. code-block:: none - - # MAC address,role - default,ciao - -#. Verify the following URLs are accessible on your local network: - - * \http://192.168.1.1:60000/icis/static/ister/ister.conf - * \http://192.168.1.1:60000/icis/static/ister/ister.json - * \http://192.168.1.1:60000/icis/get_config/ - * \http://192.168.1.1:60000/icis/get_role/ - * \http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt - -#. Power on the PXE client and watch it boot and install |CL|. - -#. Power-cycle the PXE client and watch it customize the |CL| installation. - -**Congratulations!** You have successfully performed a bulk provision of |CL|. - - -.. _ICIS: - https://github.com/clearlinux/ister-cloud-init-svc - -.. _cloud-init: - https://cloudinit.readthedocs.io diff --git a/source/guides/maintenance/deploy-at-scale.rst b/source/guides/maintenance/deploy-at-scale.rst index 3c5270c8..617b265e 100644 --- a/source/guides/maintenance/deploy-at-scale.rst +++ b/source/guides/maintenance/deploy-at-scale.rst @@ -221,7 +221,7 @@ through the *os-cloudguest* bundles which allow you to configure many Day 1 tasks such as setting hostname, creating users, or placing SSH keys in an automated way at boot. For more information on automating configuration during deployment of |CL| endpoints see the -:ref:`bulk-provision` guide. +:ref:`ipxe-install` guide. A configuration management tool is useful for maintaining consistent system and application-level configuration. Ansible\* is offered through the @@ -252,4 +252,4 @@ challenges your monitoring systems, and business continuity plans. server for this purpose, however implementation details are not in the scope of this document. In general, they should be close to your endpoints, highly available, and easy to scale with a load balancer when - necessary. \ No newline at end of file + necessary. diff --git a/source/guides/maintenance/figures/bulk-provision-flow.png b/source/guides/maintenance/figures/bulk-provision-flow.png deleted file mode 100644 index 036982f7..00000000 Binary files a/source/guides/maintenance/figures/bulk-provision-flow.png and /dev/null differ diff --git a/source/guides/network/figures/network-boot-flow.png b/source/guides/network/figures/network-boot-flow.png deleted file mode 100644 index 7ad68c76..00000000 Binary files a/source/guides/network/figures/network-boot-flow.png and /dev/null differ diff --git a/source/guides/network/figures/network-boot-setup.png b/source/guides/network/figures/network-boot-setup.png deleted file mode 100644 index dc9239db..00000000 Binary files a/source/guides/network/figures/network-boot-setup.png and /dev/null differ diff --git a/source/guides/network/ipxe-install.rst b/source/guides/network/ipxe-install.rst deleted file mode 100644 index 1c397072..00000000 --- a/source/guides/network/ipxe-install.rst +++ /dev/null @@ -1,342 +0,0 @@ -.. _ipxe-install: - -Install over the network with iPXE -################################## - -This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot -Execution Environment)` over the network. - -.. contents:: - :local: - :depth: 1 - -Overview -******** - -PXE is an industry standard that describes client-server interaction with -network-boot software and uses the DHCP and TFTP protocols. This guide shows one -method of using the PXE environment to install |CL|. - -The PXE extension called `iPXE`_ adds support for additional protocols such as -HTTP, :abbr:`iSCSI (Internet Small Computer Systems Interface)`, :abbr:`AoE -(ATA over Ethernet\*)`, and :abbr:`FCoE (Fiber Channel over Ethernet\*)`. iPXE -enables network booting on computers with no built-in PXE support. - -To install |CL| through iPXE, you must create a PXE client. Figure 1 depicts -the flow of information between a PXE server and a PXE client. - -.. figure:: ./figures/network-boot-flow.png - :alt: PXE information flow - - Figure 1: PXE information flow. - -.. caution:: - - The |CL| image that boots through the PXE process automatically erases all - data and partitions on the PXE client system and creates 3 new partitions - to install onto. - -Prerequisites -************* - -Before booting with iPXE, make the following preparations. - -Your PXE client system must meet the requirements to run |CL| and have a boot -order where the network boot option is prioritized before the disk boot -option. To determine if your PXE client system meets the minimum requirements -for |CL|, review the :ref:`compatibility-check`. - -Connect the PXE server and PXE clients to a switch on a private network, as -shown in figure 2. - -.. figure:: ./figures/network-boot-setup.png - :alt: Network topology - - Figure 2: Network topology. - -Your PXE server must have: - -* Ethernet/LAN boot option. -* At least two network adapters. -* Connection to a public network. -* Secure boot option disabled. - -.. note:: - - You must disable the secure boot option in the BIOS because the UEFI - binaries used to boot |CL| are not signed. - - -Configuration -************* - -To set up |CL| using iPXE automatically, use the :file:`configure-ipxe.sh` -script included with :abbr:`ICIS (Ister Cloud Init Service)`. For additional -instructions on the script, refer to the guide on the `ister-cloud-init-svc`_ -GitHub\* repository. - -To set up |CL| manually, perform the steps below. - -#. Define the variables used for iPXE boot configuration. - - .. code-block:: console - - ipxe_app_name=ipxe - ipxe_port=50000 - web_root=/var/www - ipxe_root=$web_root/$ipxe_app_name - tftp_root=/srv/tftp - external_iface=eno1 - internal_iface=eno2 - pxe_subnet=192.168.1 - pxe_internal_ip=$pxe_subnet.1 - pxe_subnet_mask_ip=255.255.255.0 - pxe_subnet_bitmask=16 - -#. Log in and get root privilege. - - .. code-block:: bash - - sudo -s - -#. Add the :command:`pxe-server` bundle to your |CL| system. The bundle contains all - files needed to run a PXE server. - - .. code-block:: bash - - sudo swupd bundle-add pxe-server - -#. Download the latest network-bootable release of |CL| and extract the - files. - - .. code-block:: bash - - sudo mkdir -p $ipxe_root - sudo curl -o /tmp/clear-pxe.tar.xz \ - https://cdn.download.clearlinux.org/current/clear-$(curl \ - https://cdn.download.clearlinux.org/latest)-pxe.tar.xz - sudo tar -xJf /tmp/clear-pxe.tar.xz -C $ipxe_root - sudo ln -sf $(ls $ipxe_root | grep 'org.clearlinux.*') $ipxe_root/linux - - .. note:: - - Ensure that the initial ramdisk file is named :file:`initrd` and - the kernel file is named :file:`linux`, which is a symbolic link to the - actual kernel file. - -#. Create an iPXE boot script with the following contents. During an iPXE - boot, the iPXE boot script directs the PXE client to download the files to - boot and install |CL|. Use the names previously given to the initial - ramdisk and kernel files. - - .. code-block:: console - - sudo cat > $ipxe_root/ipxe_boot_script.ipxe << EOF - #!ipxe - kernel linux quiet init=/usr/lib/systemd/systemd-bootchart \ - initcall_debug tsc=reliable no_timer_check noreplace-smp rw \ - initrd=initrd - initrd initrd - boot - EOF - -#. The :command:`pxe-server` bundle contains a lightweight web-server known as - nginx. Create a configuration file for nginx to serve |CL| to PXE - clients with the following contents: - - .. code-block:: console - - sudo mkdir -p /etc/nginx/conf.d - sudo cat > /etc/nginx/conf.d/$ipxe_app_name.conf << EOF - server { - listen $ipxe_port; - server_name localhost; - location /$ipxe_app_name/ { - root $web_root; - autoindex on; - } - } - EOF - - sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf - - .. note:: - - Create a separate nginx configuration file to serve network-bootable - images on a non-standard port number. This action saves existing nginx - configurations. - -#. Start nginx and enable the startup on boot option. - - .. code-block:: bash - - sudo systemctl start nginx - sudo systemctl enable nginx - -#. The :command:`pxe-server` bundle contains a lightweight DNS server which - conflicts with the DNS stub listener provided in `systemd-resolved`. - Disable the DNS stub listener and temporarily stop `systemd-resolved`. - - .. code-block:: console - - sudo mkdir -p /etc/systemd - sudo cat > /etc/systemd/resolved.conf << EOF - [Resolve] - DNSStubListener=no - EOF - - sudo systemctl stop systemd-resolved - -#. Assign a static IP address to the network adapter for the private network - and restart `systemd-networkd` with the following commands: - - .. code-block:: console - - sudo mkdir -p /etc/systemd/network - sudo cat > /etc/systemd/network/70-internal-static.network << EOF - [Match] - Name=$internal_iface - [Network] - DHCP=no - Address=$pxe_internal_ip/$pxe_subnet_bitmask - EOF - - sudo systemctl restart systemd-networkd - -#. Configure :abbr:`NAT (Network Address Translation)` to route traffic from - the private network to the public network. This action makes the PXE - server act as a router. To make these changes persistent during reboots, save the - changes to the firewall with the following commands: - - .. code-block:: bash - - sudo iptables -t nat -F POSTROUTING - sudo iptables -t nat -A POSTROUTING -o $external_iface -j MASQUERADE - sudo systemctl enable iptables-save.service - sudo systemctl restart iptables-save.service - sudo systemctl enable iptables-restore.service - sudo systemctl restart iptables-restore.service - - .. note:: - - The firewall masks packets to make them appear as coming from the PXE - server and hides PXE clients from the public network. - -#. Configure the kernel to forward network packets to different - interfaces. Otherwise, NAT will not work. - - .. code-block:: bash - - sudo mkdir -p /etc/sysctl.d - sudo echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf - sudo echo 1 > /proc/sys/net/ipv4/ip_forward - -#. The :command:`pxe-server` bundle contains iPXE firmware images that allow computers - without an iPXE implementation to perform an iPXE boot. Create a TFTP - hosting directory and populate the directory with the iPXE firmware images - with the following commands: - - .. code-block:: bash - - sudo mkdir -p $tftp_root - sudo ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe - -#. The :command:`pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP - server known as `dnsmasq`. Create a configuration file for `dnsmasq` - to listen on a dedicated IP address for those functions. PXE clients on - the private network will use this IP address. - - .. code-block:: console - - sudo cat > /etc/dnsmasq.conf << EOF - listen-address=$pxe_internal_ip - EOF - -#. Add the options to serve iPXE firmware images to PXE clients over TFTP to - the `dnsmasq` configuration file. - - .. code-block:: console - - sudo cat >> /etc/dnsmasq.conf << EOF - enable-tftp - tftp-root=$tftp_root - EOF - -#. Add the options to host a DHCP server for PXE clients to the :file:`dnsmasq` - configuration file. - - .. code-block:: console - - sudo cat >> /etc/dnsmasq.conf << EOF - dhcp-leasefile=/var/db/dnsmasq.leases - - dhcp-authoritative - dhcp-option=option:router,$pxe_internal_ip - dhcp-option=option:dns-server,$pxe_internal_ip - - dhcp-match=set:pxeclient,60,PXEClient* - dhcp-range=tag:pxeclient,$pxe_subnet.2,$pxe_subnet.253,$pxe_subnet_mask_ip,15m - dhcp-range=tag:!pxeclient,$pxe_subnet.2,$pxe_subnet.253,$pxe_subnet_mask_ip,6h - - dhcp-match=set:ipxeboot,175 - dhcp-boot=tag:ipxeboot,http://$pxe_internal_ip:$ipxe_port/$ipxe_app_name/ipxe_boot_script.ipxe - dhcp-boot=tag:!ipxeboot,undionly.kpxe,$pxe_internal_ip - EOF - - - The configuration provides the following important functions: - - * Directs PXE clients without an iPXE implementation to the TFTP server - to acquire architecture-specific iPXE firmware images that allow them - to perform an iPXE boot. - * Activates only on the network adapter that has an IP address on the - defined subnet. - * Directs PXE clients to the DNS server. - * Directs PXE clients to the PXE server for routing via NAT. - * Divides the private network into two pools of IP addresses. One pool - is for network boot and one pool is used after boot. Each pool has - their own lease times. - -#. Create a file for `dnsmasq` to record the IP addresses it provides - to PXE clients. - - .. code-block:: bash - - sudo mkdir -p /var/db - sudo touch /var/db/dnsmasq.leases - -#. Start `dnsmasq` and enable startup on boot. - - .. code-block:: bash - - sudo systemctl enable dnsmasq - sudo systemctl restart dnsmasq - -#. Start `systemd-resolved`. - - .. code-block:: bash - - sudo systemctl start systemd-resolved - - .. note:: - - `systemd-resolved` dynamically updates the list of DNS servers for the - private network if you use the `dnsmasq` DNS server. The setup creates a - pass-through DNS server that relies on the DNS servers listed in - :file:`/etc/resolv.conf`. - -#. Power on the PXE client and watch the client boot and install |CL|. - - After booting, |CL| automatically partitions the hard drive, - installs itself, updates to the latest version, and reboots. - - -**Congratulations!** You have successfully installed and configured a PXE -server that enables PXE clients to boot and install |CL| over the network. - - -.. _iPXE: - http://ipxe.org/ - -.. _ister-cloud-init-svc: - https://github.com/clearlinux/ister-cloud-init-svc