Edit language and markup.

Edited the language to increase readability and clarity.
Implemented the available substitutions and added markup for files and
abbreviations.

Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero
2017-03-14 10:02:43 -06:00
parent 065c8b0f3d
commit adc976db81
+254 -228
View File
@@ -3,299 +3,304 @@
Network Booting
###############
Clear Linux* Project for Intel® Architecture is bootable from a pre-boot
execution environment (PXE). PXE is an industry standard for describing the
client-server interaction to network boot software using DHCP and TFTP
protocols. One use of this environment is to automatically install an operating
system.
|CLOSIA| can boot from a :abbr:`PXE (pre-boot execution environment)`. PXE
is an industry standard which describes the client-server interaction to
network boot software using the DHCP and TFTP protocols. One possible use of
this environment is to automatically install an operating system.
Using an extension of PXE known as `iPXE`_ adds support for additional protocols
such as HTTP, iSCIS, ATA over Ethernet (AoE), and Fiber Channel over Ethernet
(FCoE). iPXE can also be used to enable network booting computers that lack
built-in PXE support.
The PXE extension known as `iPXE`_\* adds support for additional protocols
such as HTTP, iSCIS, :abbr:`AoE (ATA over Ethernet)`, and
:abbr:`FCoE (Fiber Channel over Ethernet)`. iPXE can also be used to enable
network-booting computers which lack built-in PXE support.
This guide covers how to perform an iPXE boot using network address translation
(NAT).
This guide covers how to boot |CL| with iPXE using
:abbr:`NAT (network address translation)`.
Prerequisites
=============
Before performing an iPXE boot, verify the following preparations have been
Before booting with iPXE, ensure the following preparations have been
made:
* Your PXE server has an ethernet/LAN boot option
* Your PXE server has at least two network adapters
* Your PXE server is connected to a public network
* Your PXE server and PXE clients are connected to a switch on a private network
* Your PXE server has secure boot disabled
* Your PXE server has an ethernet/LAN boot option.
* Your PXE server has at least two network adapters.
* Your PXE server is connected to a public network.
* Your PXE server and PXE clients are connected to a switch on a private
network.
* Your PXE server has the secure boot option disabled.
.. note::
Secure boot needs disabled because the UEFI binaries for booting the Clear
Linux* Project for Intel® Architecture are not signed.
The secure boot option must be disabled because the UEFI binaries used to
boot the |CLOSIA| are not signed.
Your computer and network setup should be the same as what is depicted in figure
1.
The required computer and network setup are depicted in figure 1.
.. figure:: _static/images/network-boot-setup.png
:alt: NAT network topology
:alt: NAT network topology
Figure 1: NAT network topology
Figure 1: NAT network topology
Configuration
=============
Configuration for performing an iPXE boot has been automated during the
installation of the `Ister Cloud Init Service`_ with ``configure-ipxe.sh`` to
quickly enable a bulk provisioning setup. Before running the configuration script, modify ``parameters.conf`` with your specific configurations.
Figure 2 depicts the information flow that the configuration script enables.
The configuration to boot using iPXE has been automated with the
:file:`configure-ipxe.sh` script which ran during the installation of the
`Ister Cloud Init Service`_, thus quickly enabling a bulk provisioning
setup. Before running the configuration script, modify
:file:`parameters.conf` with your specific configurations.
Figure 2 depicts the information flow enabled by the configuration script.
.. figure:: _static/images/network-boot-flow.png
:alt: PXE information flow
:alt: PXE information flow
Figure 2: PXE information flow
Figure 2: PXE information flow
#. Define variables that are used to parameterize the configuration of an iPXE boot.
#. Define the variables used to parameterize the configuration of an iPXE
boot.
.. code-block:: console
web_root=/var/www
ipxe_root=$web_root/ipxe
tftp_root=/srv/tftp
web_root=/var/www
ipxe_root=$web_root/ipxe
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=24
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=24
#. Add the ``pxe-server`` bundle to your system. This has all of the software
needed run a PXE server.
#. Add the ``pxe-server`` bundle to your system. This bundle has all the
packages needed run a PXE server.
.. code-block:: console
swupd bundle-add pxe-server
swupd bundle-add pxe-server
#. Create an iPXE hosting directory, download the latest network-bootable release
of the Clear Linux* Project for Intel® Architecture, and extract the files.
Ensure that the initial ramdisk file is named ``initrd`` and the kernel file is
named ``linux``, which is a symbolic link to the actual kernel file.
#. Create an iPXE hosting directory.
.. code-block:: console
rm -rf $ipxe_root
mkdir -p $ipxe_root
curl -o /tmp/clear-pxe.tar.xz https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-pxe.tar.xz
tar -xJf /tmp/clear-pxe.tar.xz -C $ipxe_root
ln -sf $(ls $ipxe_root | grep 'org.clearlinux.*') $ipxe_root/linux
#. Create an iPXE boot script. The iPXE boot script is used during an iPXE boot
to direct the PXE client to the files for network booting the latest
release. Use the same names you gave to the initial ramdisk and kernel files.
#. Download the latest network-bootable release of |CL|, and extract the
files.
.. code-block:: console
cat > $ipxe_root/ipxe_boot_script.txt << 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
curl -o /tmp/clear-pxe.tar.xz
https://download.clearlinux.org/current/clear-$(curl
https://download.clearlinux.org/latest)-pxe.tar.xz
tar -xJf /tmp/clear-pxe.tar.xz -C $ipxe_root
ln -sf $(ls $ipxe_root | grep 'org.clearlinux.*') $ipxe_root/linux
#. The ``pxe-server`` bundle comes with a lightweight web server known as
``nginx``. Create a configuration file for ``nginx`` to serve the latest release
to PXE clients.
.. important::
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. During an iPXE boot, the iPXE boot script
directs the PXE client to the files needed to network-boot the latest
release. Use the names given to the initial ramdisk and kernel
files.
.. code-block:: console
mkdir -p /etc/nginx
cat > /etc/nginx/nginx.conf << EOF
server {
listen 80;
server_name localhost;
location / {
root $ipxe_root;
autoindex on;
cat > $ipxe_root/ipxe_boot_script.txt << 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 ``pxe-server`` bundle contains a lightweight web-server known as
``nginx``. Create a configuration file for ``nginx`` to serve the latest
release to PXE clients.
.. code-block:: console
mkdir -p /etc/nginx
cat > /etc/nginx/nginx.conf << EOF
server {
listen 80;
server_name localhost;
location / {
root $ipxe_root;
autoindex on;
}
}
}
EOF
EOF
#. Start ``nginx`` and enable startup on boot.
.. code-block:: console
systemctl start nginx
systemctl enable nginx
systemctl start nginx
systemctl enable nginx
#. The ``pxe-server`` bundle comes with iPXE firmware images which allow computers
without an iPXE implementation to perform an iPXE boot. Create a TFTP hosting
directory and populate it with the iPXE firmware images.
#. The ``pxe-server`` bundle contains iPXE firmware images which allow
computers without an iPXE implementation to perform an iPXE boot. Create a
TFTP hosting directory and populate it with the iPXE firmware images.
.. code-block:: console
rm -rf $tftp_root
mkdir -p $tftp_root
ln -sf /usr/share/ipxe/ipxe-x86_64.efi $tftp_root/ipxe-x86_64.efi
ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe
rm -rf $tftp_root
mkdir -p $tftp_root
ln -sf /usr/share/ipxe/ipxe-x86_64.efi $tftp_root/ipxe-x86_64.efi
ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe
#. The ``pxe-server`` bundle comes with a lightweight TFTP server known as
``dnsmasq``. Create a configuration file for ``dnsmasq`` to serve iPXE firmware
images to PXE clients over TFTP.
#. The ``pxe-server`` bundle contains a lightweight TFTP server known as
``dnsmasq``. Create a configuration file for ``dnsmasq`` to serve iPXE
firmware images to PXE clients over TFTP.
.. code-block:: console
cat > /etc/dnsmasq.conf << EOF
enable-tftp
tftp-root=$tftp_root
EOF
cat > /etc/dnsmasq.conf << EOF
enable-tftp
tftp-root=$tftp_root
EOF
#. Enable ``dnsmasq`` to start automatically on boot.
.. code-block:: console
systemctl enable dnsmasq
systemctl enable dnsmasq
.. note::
At this point in the configuration process, ``dnsmasq`` is only
being enabled to start automatically on boot and not started because its DNS
server conflicts with the DNS stub listener offered by ``systemd-resolved``.
At this point in the configuration process, ``dnsmasq`` is only being
enabled to start automatically on boot but it is not started because
its DNS server conflicts with the DNS stub listener of
``systemd-resolved``.
#. The ``pxe-server`` bundle comes with a lightweight DNS server known as
``dnsmasq``. Set ``dnsmasq`` to listen on a dedicated IP address. PXE clients
on the private network will then use this IP address for DNS resolution.
Disable the DNS stub listener included with ``systemd-resolved`` to avoid a
conflict with the DNS server offered by ``dnsmasq``.
#. Set ``dnsmasq`` to listen on a dedicated IP address. PXE clients on the
private network will use this IP address for DNS resolution. Disable
the DNS stub listener included with ``systemd-resolved`` to avoid a
conflict with the ``dnsmasq`` DNS server.
.. code-block:: console
mkdir -p /etc/systemd
cat > /etc/systemd/resolved.conf << EOF
[Resolve]
DNSStubListener=no
EOF
mkdir -p /etc/systemd
cat > /etc/systemd/resolved.conf << EOF
[Resolve]
DNSStubListener=no
EOF
cat >> /etc/dnsmasq.conf << EOF
listen-address=$pxe_internal_ip
EOF
cat >> /etc/dnsmasq.conf << EOF
listen-address=$pxe_internal_ip
EOF
.. note::
``dnsmasq`` is a lightweight implementation of a DNS server, a DHCP server,
and a TFTP server. For the purposes of this guide, the DHCP server included
with ``dnsmasq`` is not being used.
``dnsmasq`` is a lightweight implementation of a DNS server, a DHCP
server, and a TFTP server. For the purposes of this guide, the DHCP
server included with ``dnsmasq`` is not being used.
.. note::
.. important::
Using DNS server provided by ``dnsmasq`` allows ``systemd-resolved`` to
dynamically update the list of DNS servers for the private network from the
public network. In effect, this creates a pass-through DNS server which
relies on DNS servers listed in ``/etc/resolv.conf``.
Using the ``dnsmasq`` DNS server allows ``systemd-resolved`` to
dynamically update the list of DNS servers for the private network from
the public network. This setup effectively creates a pass-through DNS
server which relies on the DNS servers listed in ``/etc/resolv.conf``.
#. Start ``dnsmasq`` and avoid conflicts with ``systemd-resolved``.
.. code-block:: console
systemctl stop systemd-resolved
systemctl restart dnsmasq
systemctl start systemd-resolved
systemctl stop systemd-resolved
systemctl restart dnsmasq
systemctl start systemd-resolved
#. Assign a static IP address to the network adapter for the private network.
.. code-block:: console
mkdir -p /etc/systemd/network
mkdir -p /etc/systemd/network
ln -sf /dev/null /etc/systemd/network/80-dhcp.network
ln -sf /dev/null /etc/systemd/network/80-dhcp.network
cat > /etc/systemd/network/80-external-dynamic.network << EOF
[Match]
Name=$external_iface
[Network]
DHCP=yes
EOF
cat > /etc/systemd/network/80-external-dynamic.network << EOF
[Match]
Name=$external_iface
[Network]
DHCP=yes
EOF
cat > /etc/systemd/network/80-internal-static.network << EOF
[Match]
Name=$internal_iface
[Network]
DHCP=no
Address=$pxe_internal_ip/$pxe_subnet_bitmask
EOF
cat > /etc/systemd/network/80-internal-static.network << EOF
[Match]
Name=$internal_iface
[Network]
DHCP=no
Address=$pxe_internal_ip/$pxe_subnet_bitmask
EOF
systemctl restart systemd-networkd
.. note::
By default, ``systemd-networkd`` uses DHCP for all network adapters. This
functionality needs disabled prior to assigning a static IP address. As a
consequence, this also disables DHCP functionality for the network adapter
connected to the public network. This network adapter needs to have this
functionality explicitly re-enabled.
By default, ``systemd-networkd`` uses DHCP for all network adapters.
This functionality must be disabled prior to assigning a static IP
address. Consequently, DHCP functionality for the network adapter
connected to the public network is also disabled. Thus, this functionality must be explicitly re-enabled for the network adapter.
#. The ``pxe-server`` bundle comes with a full implementation of a DHCP server
compliant to the specifications defined by the Internet Systems Consortium
(ISC), known as ``dhcpd``. Configure ``dhcpd`` to dynamically allocate IP
addresses to PXE clients on the private network. The following configuration
provides the following important functions:
* Enables ``dhcpd`` to be iPXE-aware with `iPXE-specific options`_
* Directs PXE clients without an iPXE implementation to the TFTP server for
acquiring architecture-specific iPXE firmware images to allow them to perform
an iPXE boot
* Is only active on the network adapter which 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 for network
booting and another for usage after boot; each with their own lease times
#. The ``pxe-server`` bundle contains a full DHCP server implementation
compliant with the specifications defined by the
:abbr:`ISC (Internet Systems Consortium)` known as ``dhcpd``. Configure
``dhcpd`` to dynamically allocate IP addresses to PXE clients on the
private network.
.. code-block:: console
cat > /etc/dhcpd.conf << EOF
option space ipxe;
option ipxe-encap-opts code 175 = encapsulate ipxe;
option ipxe.priority code 1 = signed integer 8;
option ipxe.keep-san code 8 = unsigned integer 8;
option ipxe.skip-san-boot code 9 = unsigned integer 8;
option ipxe.syslogs code 85 = string;
option ipxe.cert code 91 = string;
option ipxe.privkey code 92 = string;
option ipxe.crosscert code 93 = string;
option ipxe.no-pxedhcp code 176 = unsigned integer 8;
option ipxe.bus-id code 177 = string;
option ipxe.bios-drive code 189 = unsigned integer 8;
option ipxe.username code 190 = string;
option ipxe.password code 191 = string;
option ipxe.reverse-username code 192 = string;
option ipxe.reverse-password code 193 = string;
option ipxe.version code 235 = string;
option iscsi-initiator-iqn code 203 = string;
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;
cat > /etc/dhcpd.conf << EOF
option space ipxe;
option ipxe-encap-opts code 175 = encapsulate ipxe;
option ipxe.priority code 1 = signed integer 8;
option ipxe.keep-san code 8 = unsigned integer 8;
option ipxe.skip-san-boot code 9 = unsigned integer 8;
option ipxe.syslogs code 85 = string;
option ipxe.cert code 91 = string;
option ipxe.privkey code 92 = string;
option ipxe.crosscert code 93 = string;
option ipxe.no-pxedhcp code 176 = unsigned integer 8;
option ipxe.bus-id code 177 = string;
option ipxe.bios-drive code 189 = unsigned integer 8;
option ipxe.username code 190 = string;
option ipxe.password code 191 = string;
option ipxe.reverse-username code 192 = string;
option ipxe.reverse-password code 193 = string;
option ipxe.version code 235 = string;
option iscsi-initiator-iqn code 203 = string;
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;
class "PXE-Chainload" {
class "PXE-Chainload" {
match if substring(option vendor-class-identifier, 0, 9) = "PXEClient";
next-server $pxe_internal_ip;
@@ -308,9 +313,9 @@ Figure 2 depicts the information flow that the configuration script enables.
elsif substring(option vendor-class-identifier, 0, 20) = "PXEClient:Arch:00000" {
filename "undionly.kpxe";
}
}
}
subnet $pxe_subnet.0 netmask $pxe_subnet_mask_ip {
subnet $pxe_subnet.0 netmask $pxe_subnet_mask_ip {
authoritative;
option routers $pxe_internal_ip;
option domain-name-servers $pxe_internal_ip;
@@ -328,61 +333,82 @@ Figure 2 depicts the information flow that the configuration script enables.
default-lease-time 3600;
max-lease-time 21600;
}
}
EOF
}
EOF
.. note::
This configuration provides the following important functions:
There are three providers of a DHCP server on the system at this point:
``systemd-networkd``, ``dnsmasq``, and ``dhcpd``. ``dhcpd`` is used because it
is maintained by ISC and is more flexible for iPXE booting.
* Enables ``dhcpd`` to be iPXE-aware with `iPXE-specific options`_.
* Directs PXE clients without an iPXE implementation to the TFTP server
for acquiring architecture-specific iPXE firmware images to allow them
to perform an iPXE boot.
* Is only active on the network adapter which 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 for
network booting and another for usage after boot; each with their own
lease times.
#. Create a file where ``dhcpd`` can record the IP addresses that it hands out to
PXE clients.
.. important::
There are three providers of a DHCP server on the system at this point:
``systemd-networkd``, ``dnsmasq``, and ``dhcpd``. ``dhcpd`` is used
because it is maintained by ISC and is more flexible for iPXE booting.
#. Create a file where ``dhcpd`` can record the IP addresses it hands
out to PXE clients.
.. code-block:: console
mkdir -p /var/db
touch /var/db/dhcpd.leases
mkdir -p /var/db
touch /var/db/dhcpd.leases
#. Start ``dhcpd`` and enable startup on boot.
.. code-block:: console
systemctl enable dhcp4
systemctl restart dhcp4
systemctl enable dhcp4
systemctl restart dhcp4
#. Configure NAT so that traffic from the private network can be routed to the
public network. This effectively turns the PXE server into a router.
#. Configure NAT to route traffic from the private network to the public
network, effectively turning the PXE server into a router.
.. code-block:: console
iptables -t nat -F POSTROUTING
iptables -t nat -A POSTROUTING -o $external_iface -j MASQUERADE
systemctl enable iptables-save.service
systemctl restart iptables-save.service
systemctl enable iptables-restore.service
systemctl restart iptables-restore.service
iptables -t nat -F POSTROUTING
iptables -t nat -A POSTROUTING -o $external_iface -j MASQUERADE
systemctl enable iptables-save.service
systemctl restart iptables-save.service
systemctl enable iptables-restore.service
systemctl restart iptables-restore.service
.. note::
The firewall MASQUERADEs, or translates, packets to make them appear as if
they are coming from the PXE server. This hides the PXE clients from the
public network.
The firewall masquerades or translates packets to make them appear as
coming from the PXE server. Thus, it hides the PXE clients from the
public network.
#. Tell the Linux kernel to forward network packets on to different interfaces.
Otherwise, NAT will not work.
#. Tell the Linux kernel to forward network packets on to different
interfaces. Otherwise, NAT will not work.
.. code-block:: console
mkdir -p /etc/sysctl.d
echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf
echo 1 > /proc/sys/net/ipv4/ip_forward
mkdir -p /etc/sysctl.d
echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf
echo 1 > /proc/sys/net/ipv4/ip_forward
#. Power on the PXE client and watch it boot the latest release of the Clear Linux*
Project for Intel® Architecture.
#. Power on the PXE client and watch it boot the latest release of the
|CLOSIA|
Congratulations you have successfully installed and configured PXE network-booting for |CL|.
.. _iPXE: http://ipxe.org/
.. _Ister Cloud Init Service: https://github.com/clearlinux/ister-cloud-init-svc
.. _iPXE-specific options: http://www.ipxe.org/howto/dhcpd#ipxe-specific_options
.. _iPXE:
http://ipxe.org/
.. _Ister Cloud Init Service:
https://github.com/clearlinux/ister-cloud-init-svc
.. _iPXE-specific options:
http://www.ipxe.org/howto/dhcpd#ipxe-specific_options