From 367cf6070db3d2e1b48a0e0e834530cb08daba6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcus=20Sch=C3=A4fer?= Date: Thu, 8 Jun 2017 16:01:05 +0200 Subject: [PATCH] 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 --- .../building/build_pxe_root_filesystem.rst | 383 +++++------------- doc/source/building/working_with_images.rst | 3 + .../pxe_client_configuration.rst | 261 ++++++++++++ .../setup_pxe_bootserver.rst | 16 +- 4 files changed, 368 insertions(+), 295 deletions(-) create mode 100644 doc/source/building/working_with_images/pxe_client_configuration.rst rename doc/source/building/{build_pxe_root_filesystem => working_with_images}/setup_pxe_bootserver.rst (80%) diff --git a/doc/source/building/build_pxe_root_filesystem.rst b/doc/source/building/build_pxe_root_filesystem.rst index 25815e44..52101bac 100644 --- a/doc/source/building/build_pxe_root_filesystem.rst +++ b/doc/source/building/build_pxe_root_filesystem.rst @@ -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 diff --git a/doc/source/building/working_with_images.rst b/doc/source/building/working_with_images.rst index ce365782..a8a78ed1 100644 --- a/doc/source/building/working_with_images.rst +++ b/doc/source/building/working_with_images.rst @@ -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 diff --git a/doc/source/building/working_with_images/pxe_client_configuration.rst b/doc/source/building/working_with_images/pxe_client_configuration.rst new file mode 100644 index 00000000..d309037d --- /dev/null +++ b/doc/source/building/working_with_images/pxe_client_configuration.rst @@ -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 + + + +.. 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 + + + +.. 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 diff --git a/doc/source/building/build_pxe_root_filesystem/setup_pxe_bootserver.rst b/doc/source/building/working_with_images/setup_pxe_bootserver.rst similarity index 80% rename from doc/source/building/build_pxe_root_filesystem/setup_pxe_bootserver.rst rename to doc/source/building/working_with_images/setup_pxe_bootserver.rst index da5b8678..c10c01af 100644 --- a/doc/source/building/build_pxe_root_filesystem/setup_pxe_bootserver.rst +++ b/doc/source/building/working_with_images/setup_pxe_bootserver.rst @@ -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.