clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-08-26 18:36:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

iPXE updated to use clr-installer. (#932)

Browse Source 
ister and icis deprecated.

See also: https://github.com/clearlinux/clr-bundles/issues/171
Signed-off-by: Bun K Tan <bun.k.tan@intel.com>
This commit is contained in:
bktan8
2019-11-21 15:39:14 -08:00
committed by michael vincerra
parent 112ec79c56
commit 8ca656b901
11 changed files with 583 additions and 517 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/_figures/ipxe/ipxe-install-1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

source/_figures/ipxe/ipxe-install-2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

source/get-started/index.rst
+1
View File
@@ -35,6 +35,7 @@ Install
bare-metal-install-desktop
bare-metal-install-server
install-configfile
ipxe-install
.. _virtual-machine-install:
source/get-started/ipxe-install.rst
+580
View File
@@ -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
source/guides/clear/ister.rst
-1
View File
@@ -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/
source/guides/maintenance/bulk-provision.rst
-172
View File
@@ -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<ipxe-install>` 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/<MAC address>
* \http://192.168.1.1:60000/icis/get_role/<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
source/guides/maintenance/deploy-at-scale.rst
+2 -2
View File
@@ -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.
necessary.
source/guides/maintenance/figures/bulk-provision-flow.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 36 KiB

source/guides/network/figures/network-boot-flow.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 30 KiB

source/guides/network/figures/network-boot-setup.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

source/guides/network/ipxe-install.rst
-342
View File
@@ -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