Update PXE building chapter
Redesign PXE building chapter to follow style guide. Thanks to Thomas Schraitle for review and additional contributions to this topic. This Fixes #323
This commit is contained in:
Marcus Schäfer
parent
543228fe0c
commit
367cf6070d
@ -1,79 +1,119 @@
|
||||
Build a PXE root File System Image
|
||||
.. _build_pxe:
|
||||
|
||||
Build a PXE Root File System Image
|
||||
==================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
.. _PXE: https://en.wikipedia.org/wiki/Preboot_Execution_Environment
|
||||
.. _TFTP: https://en.wikipedia.org/wiki/Trivial_File_Transfer_Protocol
|
||||
.. _NBD: https://en.wikipedia.org/wiki/Network_block_device
|
||||
.. _AoE: https://en.wikipedia.org/wiki/ATA_over_Ethernet
|
||||
|
||||
build_pxe_root_filesystem/setup_pxe_bootserver
|
||||
|
||||
.. hint::
|
||||
.. sidebar:: Abstract
|
||||
|
||||
Make sure you have checked out the example image descriptions
|
||||
For details see :ref:`example-descriptions`
|
||||
This page explains how to build a file system image for use with
|
||||
KIWI's PXE boot infrastructure. It contains:
|
||||
|
||||
PXE is a network boot protocol that is shipped with most BIOS
|
||||
* how to build a PXE file system image
|
||||
* how to setup the PXE file system image on the PXE server
|
||||
* how to run it with QEMU
|
||||
|
||||
`PXE`_ is a network boot protocol that is shipped with most BIOS
|
||||
implementations. The protocol sends a DHCP request to get an IP
|
||||
address. When an IP address is assigned, it uses the TFTP protocol to
|
||||
download a Kernel and boot instructions. Contrary to other images built
|
||||
with KIWI, a PXE image consists of separate boot and system images, since
|
||||
both images need to be made available in different locations on the network
|
||||
boot server.
|
||||
address. When an IP address is assigned, it uses the `TFTP`_ protocol
|
||||
to download a Kernel and boot instructions. Contrary to other images
|
||||
built with KIWI, a PXE image consists of separate boot, kernel and root
|
||||
filesystem images, since those images need to be made available in
|
||||
different locations on the PXE boot server.
|
||||
|
||||
The following example shows how to build one out of many possible
|
||||
network root filesystem flavours. The command below generates a squashfs
|
||||
root file system image which is designed to become deployed as an
|
||||
overlayfs-based union system. To use the image, all image parts need
|
||||
to be copied to a PXE boot server. If you have not set up such a server,
|
||||
refer to :ref:`pxe-boot-server` for instructions. The following
|
||||
example assumes you have created the PXE image on the boot server itself
|
||||
(if not, use **scp** to copy the files on the remote host)
|
||||
A root filesystem image which can be deployed via KIWI’s PXE
|
||||
netboot infrastructure represents the system rootfs in a linux
|
||||
filesystem. A user could loop mount the image and access the
|
||||
contents of the root filesystem. The image does not contain
|
||||
any information about the system disk its partitions or the
|
||||
bootloader setup. All of these information is provided by a
|
||||
client configuration file on the PXE server which controlls
|
||||
how the root filesystem image should be deployed.
|
||||
|
||||
.. code:: bash
|
||||
Many different deployment strategies are possible, e.g root over
|
||||
`NBD`_ (network block device), `AoE`_ (ATA over Ethernet), or
|
||||
NFS for diskless and diskfull clients. This particular
|
||||
example shows how to build an overlayfs-based union system based
|
||||
on openSUSE Leap for a diskless client which receives the squashfs
|
||||
compressed root file system image in a ramdisk overlayed via
|
||||
overlayfs and writes new data into another ramdisk on the same
|
||||
system. As diskless client, a QEMU virtual machine is used.
|
||||
|
||||
$ sudo kiwi-ng --profile netboot --type pxe system build \
|
||||
--description kiwi-descriptions/suse/x86_64/suse-leap-42.1-JeOS \
|
||||
--target-dir /tmp/mypxe-result
|
||||
.. compound:: **Things to know before**
|
||||
|
||||
1. Change into the build directory
|
||||
* To use the image, all image parts need to be copied to the PXE boot
|
||||
server. If you have not set up such a server, refer to
|
||||
:ref:`pxe-boot-server` for instructions.
|
||||
|
||||
.. code:: bash
|
||||
* The following example assumes you will create the PXE image
|
||||
on the PXE boot server itself (if not, use :command:`scp` to copy the files
|
||||
on the remote host).
|
||||
|
||||
$ cd /tmp/mypxe-result
|
||||
* To let QEMU connect to the network, we recommend to
|
||||
setup a network bridge on the host system and let QEMU connect
|
||||
to it via a custom :file:`/etc/qemu-ifup`. For details, see
|
||||
https://en.wikibooks.org/wiki/QEMU/Networking
|
||||
|
||||
2. Copy the initrd and the kernel to /srv/tftpboot/boot
|
||||
|
||||
.. code:: bash
|
||||
1. Make sure you have checked out the example image descriptions,
|
||||
see :ref:`example-descriptions`.
|
||||
|
||||
$ cp initrd-netboot-suse-*.gz /srv/tftpboot/boot/initrd
|
||||
$ cp initrd-netboot-suse-*.kernel /srv/tftpboot/boot/linux
|
||||
2. Build the image with KIWI:
|
||||
|
||||
3. Copy the system image and its md5 sum to /srv/tftpboot/image
|
||||
.. code:: bash
|
||||
|
||||
.. code:: bash
|
||||
$ sudo kiwi-ng --profile netboot --type pxe system build \
|
||||
--description kiwi-descriptions/suse/x86_64/suse-leap-42.1-JeOS \
|
||||
--target-dir /tmp/mypxe-result
|
||||
|
||||
$ cp LimeJeOS-Leap-42.1.x86_64-1.42.1 /srv/tftpboot/image
|
||||
$ cp LimeJeOS-Leap-42.1.x86_64-1.42.1.md5 /srv/tftpboot/image
|
||||
3. Change into the build directory:
|
||||
|
||||
4. Adjust the PXE configuration file. it controls which kernel and initrd is
|
||||
.. code:: bash
|
||||
|
||||
$ cd /tmp/mypxe-result
|
||||
|
||||
4. Copy the initrd and the kernel to :file:`/srv/tftpboot/boot`:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ cp initrd-netboot-suse-*.gz /srv/tftpboot/boot/initrd
|
||||
$ cp initrd-netboot-suse-*.kernel /srv/tftpboot/boot/linux
|
||||
|
||||
5. Copy the system image and its MD5 sum to :file:`/srv/tftpboot/image`:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ cp LimeJeOS-Leap-42.1.x86_64-1.42.1 /srv/tftpboot/image
|
||||
$ cp LimeJeOS-Leap-42.1.x86_64-1.42.1.md5 /srv/tftpboot/image
|
||||
|
||||
6. Adjust the PXE configuration file.
|
||||
The configuration file controls which kernel and initrd is
|
||||
loaded and which kernel parameters are set. A template has been installed
|
||||
at /srv/tftpboot/pxelinux.cfg/default with the kiwi-pxeboot package.
|
||||
at :file:`/srv/tftpboot/pxelinux.cfg/default` from the ``kiwi-pxeboot`` package.
|
||||
The minimal configuration required to boot the example image looks
|
||||
like to following:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: bash
|
||||
|
||||
DEFAULT KIWI-Boot
|
||||
DEFAULT KIWI-Boot
|
||||
|
||||
LABEL KIWI-Boot
|
||||
kernel boot/linux
|
||||
append initrd=boot/initrd
|
||||
IPAPPEND 2
|
||||
LABEL KIWI-Boot
|
||||
kernel boot/linux
|
||||
append initrd=boot/initrd
|
||||
IPAPPEND 2
|
||||
|
||||
5. Create the image client configuration file
|
||||
Additional configuration files can be found at :ref:`pxe_client_config`.
|
||||
|
||||
.. code:: bash
|
||||
7. Create the image client configuration file:
|
||||
|
||||
$ vi /srv/tftpboot/KIWI/config.default
|
||||
.. code:: bash
|
||||
|
||||
$ vi /srv/tftpboot/KIWI/config.default
|
||||
|
||||
IMAGE=/dev/ram1;LimeJeOS-Leap-42.1.x86_64;1.42.1;192.168.100.2;4096
|
||||
UNIONFS_CONFIG=/dev/ram2,/dev/ram1,overlay
|
||||
@ -84,251 +124,12 @@ example assumes you have created the PXE image on the boot server itself
|
||||
will be deployed into a ramdisk (ram1) and overlay mounted such
|
||||
that all write operations will land in another ramdisk (ram2).
|
||||
KIWI supports a variety of different deployment strategies based
|
||||
on the rootfs image created beforehand. For details please refer
|
||||
to :ref:`pxe-deployments`
|
||||
on the rootfs image created beforehand. For details, refer
|
||||
to :ref:`pxe_client_config`
|
||||
|
||||
6. Connect the client to the network and boot. This can also be done
|
||||
8. Connect the client to the network and boot. This can also be done
|
||||
in a virtualized environment using QEMU as follows:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: bash
|
||||
|
||||
$ qemu -boot n
|
||||
|
||||
.. note:: QEMU bridged networking
|
||||
|
||||
In order to let qemu connect to the network we recommend to
|
||||
setup a network bridge on the host system and let qemu connect
|
||||
to it via a custom /etc/qemu-ifup. For details see
|
||||
https://en.wikibooks.org/wiki/QEMU/Networking
|
||||
|
||||
.. _pxe-deployments:
|
||||
|
||||
PXE Client Configuration
|
||||
------------------------
|
||||
|
||||
All PXE boot based deployment methods are controlled by configuration files
|
||||
located in /srv/tftpboot/KIWI on the PXE server. Such a configuration
|
||||
file can either be client-specific (config.MAC_ADDRESS, for example
|
||||
config.00.AB.F3.11.73.C8), or generic (config.default). In an environment
|
||||
with heterogeneous clients, this allows to have a default configuration
|
||||
suitable for the majority of clients, to have configurations suitable
|
||||
for a group of clients (for example machines with similar or identical
|
||||
hardware) and individual configurations for selected machines.
|
||||
|
||||
The configuration file contains data about the image and about
|
||||
configuration, synchronization, and partition parameters.
|
||||
The configuration file has got the following general format:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
IMAGE="device;name;version;srvip;bsize;compressed,...,"
|
||||
|
||||
DISK="device"
|
||||
PART="size;id;Mount,...,size;id;Mount"
|
||||
RAID="raid-level;device1;device2;..."
|
||||
|
||||
AOEROOT=ro-device[,rw-device]
|
||||
NBDROOT="ip-address;export-name;device;swap-export-name;swap-device;write-export-name;write-device"
|
||||
NFSROOT="ip-address;path"
|
||||
|
||||
UNIONFS_CONFIGURATION="rw-partition,compressed-partition,overlayfs"
|
||||
|
||||
CONF="src;dest;srvip;bsize;[hash],...,src;dest;srvip;bsize;[hash]"
|
||||
|
||||
KIWI_BOOT_TIMEOUT="seconds"
|
||||
KIWI_KERNEL_OPTIONS="opt1 opt2 ..."
|
||||
|
||||
REBOOT_IMAGE=1
|
||||
RELOAD_CONFIG=1
|
||||
RELOAD_IMAGE=1
|
||||
|
||||
.. note:: Quoting the Values
|
||||
|
||||
The configuration file is sourced by the Bash, so the same quoting
|
||||
rules as for the Bash apply.
|
||||
|
||||
Not all configuration options needs to be specified. It depends on the
|
||||
setup of the client which configuration values are required. The
|
||||
following is a collection of client setup examples which covers all
|
||||
supported PXE client configurations:
|
||||
|
||||
Setup client with remote root
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to serve the image from a remote location and redirect all
|
||||
write operations on a tmpfs, the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
# When using AoE, see vblade toolchain for image export
|
||||
|
||||
AOEROOT=/dev/etherd/e0.1
|
||||
UNIONFS_CONFIG=tmpfs,aoe,overlay
|
||||
|
||||
# When using NFS, see exports manual page for image export
|
||||
|
||||
NFSROOT="192.168.100.2;/srv/tftpboot/image/root"
|
||||
UNIONFS_CONFIG=tmpfs,nfs,overlay
|
||||
|
||||
# When using NBD, see nbd-server manual page for image export
|
||||
|
||||
NBDROOT=192.168.100.2;root_export;/dev/nbd0
|
||||
UNIONFS_CONFIG=tmpfs,nbd,overlay
|
||||
|
||||
The above setup shows the most common use case where the image built
|
||||
with KIWI is populated over the network using either AoE, NBD or NFS
|
||||
in combination with overlayfs which redirects all write operations
|
||||
to be local to the client. In any case a setup of either AoE, NBD or
|
||||
NFS on the image server is required beforehand.
|
||||
|
||||
Setup client with system on local disk
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to deploy the image on a local disk the following setup
|
||||
is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
IMAGE="/dev/sda2;LimeJeOS-Leap-42.1.x86_64;1.42.1;192.168.100.2;4096"
|
||||
DISK="/dev/sda"
|
||||
PART="5;S;x,x;L;/"
|
||||
|
||||
The setup above will create a partition table on sda with a 5MB swap
|
||||
partition (no mountpoint) and the rest of the disk will be a Linux(L)
|
||||
partition with / as mountpoint. The (x) in the PART setup specifies
|
||||
a place holder to indicate the default behaviour.
|
||||
|
||||
Setup client with system on local MD RAID disk
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to deploy the image on a local disk with prior software raid
|
||||
configuration, the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
RAID='1;/dev/sda;/dev/sdb'
|
||||
IMAGE="/dev/md1;LimeJeOS-Leap-42.1.x86_64;1.42.1;192.168.100.2;4096"
|
||||
PART="5;S;x,x;L;/"
|
||||
|
||||
The first parameter of the RAID line is the raid level. So far only raid1
|
||||
(mirroring) is supported. The second and third parameter specifies the
|
||||
raid disk devices which make up the array. If a RAID line is present
|
||||
all partitions in PART will be created as raid partitions. The first
|
||||
raid is named md0 the second one md1 and so on. It is required to
|
||||
specify the correct raid partition in the IMAGE line according to the
|
||||
PART setup. In this case md0 is reserved for the swap space and md1
|
||||
is reserved for the system.
|
||||
|
||||
Setup loading of custom configuration file(s)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to load for example a custom /etc/hosts file on the client,
|
||||
the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
CONF="hosts;/etc/hosts;192.168.1.2;4096;ffffffff"
|
||||
|
||||
On boot of the client KIWI's boot code will fetch the `hosts` file
|
||||
from the root of the server (192.168.1.2) with 4k blocksize and deploy
|
||||
it as `/etc/hosts` on the client. The protocol is by default tftp
|
||||
but can be changed via the kiwiservertype kernel commandline option.
|
||||
For details see :ref:`custom-download-server`
|
||||
|
||||
Setup client to force reload image
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to force the reload of the system image even if the image on
|
||||
the disk is up-to-date, the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
RELOAD_IMAGE=1
|
||||
|
||||
The option only applies to configurations with a DISK/PART setup
|
||||
|
||||
Setup client to force reload configuration files
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to force the reload of all configuration files specified in
|
||||
CONF, the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
RELOAD_CONFIG=1
|
||||
|
||||
By default only configuration files which has changed according to
|
||||
their md5sum value will be reloaded. With the above setup all files
|
||||
will be reloaded from the PXE server. The option only applies to
|
||||
configurations with a DISK/PART setup
|
||||
|
||||
Setup client for reboot after deployment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to reboot the system after the initial deployment process is
|
||||
done the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
REBOOT_IMAGE=1
|
||||
|
||||
Setup custom kernel boot options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to for example deactivate the kernel mode setting on local
|
||||
boot of the client the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
KIWI_KERNEL_OPTIONS="nomodeset"
|
||||
|
||||
.. note::
|
||||
|
||||
This does not influence the kernel options passed to the client
|
||||
if it boots from the network. In order to setup those the pxe
|
||||
configuration on the PXE server needs to be changed
|
||||
|
||||
Setup a custom boot timeout
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to setup a 10sec custom timeout for the local boot of the client
|
||||
the following setup is required.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
KIWI_BOOT_TIMEOUT="10"
|
||||
|
||||
.. note::
|
||||
|
||||
This does not influence the boot timeout if the client boots off
|
||||
from the network.
|
||||
|
||||
.. _custom-download-server:
|
||||
|
||||
Setup a different download protocol and server
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By default all downloads controlled by the KIWI linuxrc code are
|
||||
performed by an atftp call using the TFTP protocol. With PXE the download
|
||||
protocol is fixed and thus you cannott change the way how the kernel and
|
||||
the boot image (initrd) is downloaded. As soon as Linux takes over, the
|
||||
download protocols http, https and ftp are supported too. KIWI uses
|
||||
the curl program to support the additional protocols.
|
||||
|
||||
To select one of the additional download protocols the following
|
||||
kernel parameters need to be specified
|
||||
|
||||
.. code:: bash
|
||||
|
||||
kiwiserver=192.168.1.1 kiwiservertype=ftp
|
||||
|
||||
To set up this parameters edit the file
|
||||
/srv/tftpboot/pxelinux.cfg/default on your PXE boot server and change
|
||||
the append line accordingly.
|
||||
|
||||
.. note::
|
||||
|
||||
Once configured all downloads except for kernel and initrd are
|
||||
now controlled by the given server and protocol. You need to make
|
||||
sure that this server provides the same directory and file structure
|
||||
as initially provided by the kiwi-pxeboot package
|
||||
$ qemu -boot n -m 4096
|
||||
|
||||
@ -5,8 +5,11 @@ These sections contains some "low level" topics which are useful for
|
||||
different image types.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
working_with_images/iso_to_usb_stick_deployment
|
||||
working_with_images/vmx_setup_for_ec2
|
||||
working_with_images/vmx_setup_for_azure
|
||||
working_with_images/vmx_setup_for_google
|
||||
working_with_images/setup_pxe_bootserver
|
||||
working_with_images/pxe_client_configuration
|
||||
|
||||
@ -0,0 +1,261 @@
|
||||
.. _pxe_client_config:
|
||||
|
||||
PXE Client Setup Configuration
|
||||
==============================
|
||||
|
||||
.. sidebar:: Abstract
|
||||
|
||||
This page provides further information for handling
|
||||
vmx images built with KIWI and references the following
|
||||
articles:
|
||||
|
||||
* :ref:`build_pxe`
|
||||
|
||||
All PXE boot based deployment methods are controlled by configuration files
|
||||
located in :file:`/srv/tftpboot/KIWI` on the PXE server. Such a configuration
|
||||
file can either be client-specific (config.MAC_ADDRESS, for example
|
||||
config.00.AB.F3.11.73.C8), or generic (config.default).
|
||||
|
||||
In an environment
|
||||
with heterogeneous clients, this allows to have a default configuration
|
||||
suitable for the majority of clients, to have configurations suitable
|
||||
for a group of clients (for example machines with similar or identical
|
||||
hardware), and individual configurations for selected machines.
|
||||
|
||||
The configuration file contains data about the image and about
|
||||
configuration, synchronization, and partition parameters.
|
||||
The configuration file has got the following general format:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
IMAGE="device;name;version;srvip;bsize;compressed,...,"
|
||||
|
||||
DISK="device"
|
||||
PART="size;id;Mount,...,size;id;Mount"
|
||||
RAID="raid-level;device1;device2;..."
|
||||
|
||||
AOEROOT=ro-device[,rw-device]
|
||||
NBDROOT="ip-address;export-name;device;swap-export-name;swap-device;write-export-name;write-device"
|
||||
NFSROOT="ip-address;path"
|
||||
|
||||
UNIONFS_CONFIGURATION="rw-partition,compressed-partition,overlayfs"
|
||||
|
||||
CONF="src;dest;srvip;bsize;[hash],...,src;dest;srvip;bsize;[hash]"
|
||||
|
||||
KIWI_BOOT_TIMEOUT="seconds"
|
||||
KIWI_KERNEL_OPTIONS="opt1 opt2 ..."
|
||||
|
||||
REBOOT_IMAGE=1
|
||||
RELOAD_CONFIG=1
|
||||
RELOAD_IMAGE=1
|
||||
|
||||
.. note:: Quoting the Values
|
||||
|
||||
The configuration file is sourced by Bash, so the same quoting
|
||||
rules as for Bash apply.
|
||||
|
||||
Not all configuration options needs to be specified. It depends on the
|
||||
setup of the client which configuration values are required. The
|
||||
following is a collection of client setup examples which covers all
|
||||
supported PXE client configurations.
|
||||
|
||||
Setup Client with Remote Root
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To serve the image from a remote location and redirect all
|
||||
write operations on a tmpfs, the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
# When using AoE, see vblade toolchain for image export
|
||||
|
||||
AOEROOT=/dev/etherd/e0.1
|
||||
UNIONFS_CONFIG=tmpfs,aoe,overlay
|
||||
|
||||
# When using NFS, see exports manual page for image export
|
||||
|
||||
NFSROOT="192.168.100.2;/srv/tftpboot/image/root"
|
||||
UNIONFS_CONFIG=tmpfs,nfs,overlay
|
||||
|
||||
# When using NBD, see nbd-server manual page for image export
|
||||
|
||||
NBDROOT=192.168.100.2;root_export;/dev/nbd0
|
||||
UNIONFS_CONFIG=tmpfs,nbd,overlay
|
||||
|
||||
The above setup shows the most common use case where the image built
|
||||
with KIWI is populated over the network using either AoE, NBD or NFS
|
||||
in combination with overlayfs which redirects all write operations
|
||||
to be local to the client. In any case a setup of either AoE, NBD or
|
||||
NFS on the image server is required beforehand.
|
||||
|
||||
Setup Client with System on Local Disk
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To deploy the image on a local disk the following setup
|
||||
is required:
|
||||
|
||||
.. note::
|
||||
|
||||
In the referenced :file:`suse-leap-42.1-JeOS` XML description the ``pxe``
|
||||
type must be changed as follows and the image needs to be
|
||||
rebuild:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<type image="pxe" filesystem="ext3" boot="netboot/suse-leap42.1"/>
|
||||
|
||||
.. code:: bash
|
||||
|
||||
IMAGE="/dev/sda2;LimeJeOS-Leap-42.1.x86_64;1.42.1;192.168.100.2;4096"
|
||||
DISK="/dev/sda"
|
||||
PART="5;S;X,X;L;/"
|
||||
|
||||
The setup above will create a partition table on sda with a 5MB swap
|
||||
partition (no mountpoint) and the rest of the disk will be a Linux(L)
|
||||
partition with :file:`/` as mountpoint. The (``X``) in the PART setup specifies
|
||||
a place holder to indicate the default behaviour.
|
||||
|
||||
Setup Client with System on Local MD RAID Disk
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To deploy the image on a local disk with prior software RAID
|
||||
configuration, the following setup is required:
|
||||
|
||||
.. note::
|
||||
|
||||
In the referenced :file:`suse-leap-42.1-JeOS` XML description the ``pxe``
|
||||
type must be changed as follows and the image needs to be
|
||||
rebuild:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<type image="pxe" filesystem="ext3" boot="netboot/suse-leap42.1"/>
|
||||
|
||||
.. code:: bash
|
||||
|
||||
RAID='1;/dev/sda;/dev/sdb'
|
||||
IMAGE="/dev/md1;LimeJeOS-Leap-42.1.x86_64;1.42.1;192.168.100.2;4096"
|
||||
PART="5;S;x,x;L;/"
|
||||
|
||||
The first parameter of the RAID line is the RAID level. So far only raid1
|
||||
(mirroring) is supported. The second and third parameter specifies the
|
||||
raid disk devices which make up the array. If a RAID line is present
|
||||
all partitions in ``PART`` will be created as RAID partitions. The first
|
||||
RAID is named ``md0``, the second one ``md1`` and so on. It is required to
|
||||
specify the correct RAID partition in the ``IMAGE`` line according to the
|
||||
``PART`` setup. In this case ``md0`` is reserved for the SWAP space and ``md1``
|
||||
is reserved for the system.
|
||||
|
||||
Setup Loading of Custom Configuration File(s)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to load for example a custom :file:`/etc/hosts` file on the client,
|
||||
the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
CONF="hosts;/etc/hosts;192.168.1.2;4096;ffffffff"
|
||||
|
||||
On boot of the client KIWI's boot code will fetch the :file:`hosts` file
|
||||
from the root of the server (192.168.1.2) with 4k blocksize and deploy
|
||||
it as :file:`/etc/hosts` on the client. The protocol is by default tftp
|
||||
but can be changed via the ``kiwiservertype`` kernel commandline option.
|
||||
For details, see :ref:`custom-download-server`
|
||||
|
||||
Setup Client to Force Reload Image
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To force the reload of the system image even if the image on
|
||||
the disk is up-to-date, the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
RELOAD_IMAGE=1
|
||||
|
||||
The option only applies to configurations with a DISK/PART setup
|
||||
|
||||
Setup Client to Force Reload Configuration Files
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To force the reload of all configuration files specified in
|
||||
CONF, the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
RELOAD_CONFIG=1
|
||||
|
||||
By default only configuration files which has changed according to
|
||||
their md5sum value will be reloaded. With the above setup all files
|
||||
will be reloaded from the PXE server. The option only applies to
|
||||
configurations with a DISK/PART setup
|
||||
|
||||
Setup Client for Reboot After Deployment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To reboot the system after the initial deployment process is
|
||||
done the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
REBOOT_IMAGE=1
|
||||
|
||||
Setup custom kernel boot options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To deactivate the kernel mode setting on local
|
||||
boot of the client the following setup is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
KIWI_KERNEL_OPTIONS="nomodeset"
|
||||
|
||||
.. note::
|
||||
|
||||
This does not influence the kernel options passed to the client
|
||||
if it boots from the network. In order to setup those the PXE
|
||||
configuration on the PXE server needs to be changed
|
||||
|
||||
Setup a Custom Boot Timeout
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To setup a 10sec custom timeout for the local boot of the client
|
||||
the following setup is required.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
KIWI_BOOT_TIMEOUT="10"
|
||||
|
||||
.. note::
|
||||
|
||||
This does not influence the boot timeout if the client boots off
|
||||
from the network.
|
||||
|
||||
.. _custom-download-server:
|
||||
|
||||
Setup a Different Download Protocol and Server
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By default all downloads controlled by the KIWI linuxrc code are
|
||||
performed by an atftp call using the TFTP protocol. With PXE the download
|
||||
protocol is fixed and thus you cannot change the way how the kernel and
|
||||
the boot image (:file:`initrd`) is downloaded. As soon as Linux takes over, the
|
||||
download protocols http, https and ftp are supported too. KIWI uses
|
||||
the curl program to support the additional protocols.
|
||||
|
||||
To select one of the additional download protocols the following
|
||||
kernel parameters need to be specified
|
||||
|
||||
.. code:: bash
|
||||
|
||||
kiwiserver=192.168.1.1 kiwiservertype=ftp
|
||||
|
||||
To set up this parameters edit the file
|
||||
:file:`/srv/tftpboot/pxelinux.cfg/default` on your PXE boot server and change
|
||||
the append line accordingly.
|
||||
|
||||
.. note::
|
||||
|
||||
Once configured all downloads except for kernel and initrd are
|
||||
now controlled by the given server and protocol. You need to make
|
||||
sure that this server provides the same directory and file structure
|
||||
as initially provided by the ``kiwi-pxeboot`` package
|
||||
@ -3,15 +3,23 @@
|
||||
Setting Up a Network Boot Server
|
||||
================================
|
||||
|
||||
.. sidebar:: Abstract
|
||||
|
||||
This page provides further information for handling
|
||||
PXE images built with KIWI and references the following
|
||||
articles:
|
||||
|
||||
* :ref:`build_pxe`
|
||||
|
||||
To be able to deploy PXE bot images created with KIWI, you need to
|
||||
set up a network boot server providing the services DHCP and atftp.
|
||||
|
||||
Installing and Configuring atftp
|
||||
--------------------------------
|
||||
|
||||
1. Install the packages atftp and kiwi-pxeboot
|
||||
1. Install the packages atftp and kiwi-pxeboot.
|
||||
|
||||
2. Edit the file /etc/sysconfig/atftpd. Set or modify the following variables:
|
||||
2. Edit the file :file:`/etc/sysconfig/atftpd`. Set or modify the following variables:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
@ -32,13 +40,13 @@ serve as an example. Depending on your network structure, the IP addresses,
|
||||
ranges and domain settings need to be adapted to allow the DHCP server to
|
||||
work within your network. If you already have a DHCP server running in your
|
||||
network, make sure that the filename and next-server are correctly set
|
||||
in /etc/dhcpd.conf on this server.
|
||||
in :file:`/etc/dhcpd.conf` on this server.
|
||||
|
||||
The following steps describe how to set up a new DHCP server instance:
|
||||
|
||||
1. Install the package dnsmasq
|
||||
|
||||
2. Create the file /etc/dnsmasq.conf and include the
|
||||
2. Create the file :file:`/etc/dnsmasq.conf` and include the
|
||||
following statements. Note that all **values** listed
|
||||
below are examples, make sure to replace them with data fitting your
|
||||
network setup.
|
||||
Loading…
Reference in New Issue
Block a user