summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDan Callaghan <dcallagh@redhat.com>2014-06-12 16:32:08 +1000
committerGerrit Code Review <gerrit@beaker-project.org>2014-06-17 00:21:01 +0000
commit0d76be78b24e4eb09bb9a8ac57907d99a2e2e6a4 (patch)
treedbf4e14fb10d9f77f6f2d5746d652c7b24d8a8c2
parented0fcc2ab00f245ce277fdb449b80a780e78b08c (diff)
docs: describe the contents of the TFTP root directory
-rw-r--r--documentation/admin-guide/distro-import.rst2
-rw-r--r--documentation/admin-guide/index.rst1
-rw-r--r--documentation/admin-guide/tftp.rst133
-rw-r--r--documentation/user-guide/systems/adding.rst31
4 files changed, 138 insertions, 29 deletions
diff --git a/documentation/admin-guide/distro-import.rst b/documentation/admin-guide/distro-import.rst
index 4fd1ddc..bc8f5ac 100644
--- a/documentation/admin-guide/distro-import.rst
+++ b/documentation/admin-guide/distro-import.rst
@@ -47,6 +47,8 @@ more specific jobs that you might find useful.
.. note:: The ``updateDistro`` script assumes that the Beaker client is
correctly configured on the lab controller. See :ref:`installing-bkr-client`.
+.. _pxe-menu:
+
Generating a PXE menu
---------------------
diff --git a/documentation/admin-guide/index.rst b/documentation/admin-guide/index.rst
index ef3ef67..20fc8d8 100644
--- a/documentation/admin-guide/index.rst
+++ b/documentation/admin-guide/index.rst
@@ -30,6 +30,7 @@ Contents
installation
upgrading
config-files
+ tftp
distro-import
interface
kickstarts
diff --git a/documentation/admin-guide/tftp.rst b/documentation/admin-guide/tftp.rst
new file mode 100644
index 0000000..20c7230
--- /dev/null
+++ b/documentation/admin-guide/tftp.rst
@@ -0,0 +1,133 @@
+TFTP files and directories
+==========================
+
+As part of the :ref:`provisioning process <provisioning-process>`, test systems
+fetch boot loader images and configuration files over TFTP from the Beaker lab
+controller.
+This section describes all the files under the TFTP root directory that the
+:program:`beaker-provision` daemon either creates, or relies on indirectly,
+during the provisioning process.
+
+.. _boot-loader-images:
+
+Boot loader images
+------------------
+
+These images must be supplied by the Beaker administrator and copied into the
+TFTP root directory manually (with the exception of :file:`pxelinux.0`).
+The Cobbler project provides `pre-compiled binaries of common boot loaders
+<https://github.com/cobbler/cobbler.github.com/tree/master/loaders>`__. Many
+Linux distributions also package these boot loaders.
+
+Each test system should have a suitable DHCP option pointing at one of these
+boot loader images (see :ref:`adding-systems`).
+
+:file:`pxelinux.0`
+ Recommended location of the PXELINUX image, used for x86-based systems with
+ BIOS firmware. PXELINUX is a network boot loader developed as part of the
+ Syslinux_ project.
+
+ If this file does not exist, Beaker copies the PXELINUX image from the
+ Syslinux package to this location so that x86 BIOS systems can be
+ provisioned out of the box.
+
+ It is possible to use alternative names for this image (for example, to
+ have multiple parallel versions of PXELINUX for compatibility reasons),
+ assuming that the DHCP configuration is adjusted configured accordingly.
+
+:file:`grub/grub.efi`
+ Recommended location of the EFI GRUB_ image, used for x86-based systems
+ with UEFI firmware.
+
+ It is possible to use alternative names for this image, but the image must
+ be under the :file:`grub/` directory.
+
+:file:`yaboot`
+ Location of the Yaboot_ image, used for PowerPC systems.
+
+:file:`elilo-ia64.efi`
+ Location of the ELILO_ image, used for IA64 systems.
+
+:file:`pxelinux/bootaa64.efi`
+ Location of the boot loader image for 64-bit ARM systems.
+
+.. _Syslinux: http://www.syslinux.org/
+.. _GRUB: http://www.gnu.org/software/grub/
+.. _ELILO: http://elilo.sourceforge.net/
+.. _Yaboot: http://yaboot.ozlabs.org/
+
+Boot loader configuration files
+-------------------------------
+
+Beaker creates these files when a test system is being provisioned, and then
+removes them once the installation is complete.
+
+:file:`pxelinux.cfg/{0A010203}`
+ Configuration for PXELINUX. The filename is the IPv4 address of the test
+ system, represented as 8 hexadecimal digits (using uppercase letters).
+
+:file:`grub/images`
+ Symlink to the :file:`images` directory.
+
+:file:`grub/{0A010203}`
+ Configuration for EFI GRUB. The filename follows the PXELINUX naming
+ convention.
+
+:file:`ppc/{0a010203}`
+ Symbolic link to the Yaboot image. The filename is the IPv4 address of the
+ test system, represented as 8 hexadecimal digits (using lowercase letters).
+
+:file:`etc/{0a010203}`
+ Configuration for Yaboot. The filename matches the boot loader symlink
+ filename.
+
+:file:`{0A010203}.conf`
+ Configuration for ELILO. The filename follows the PXELINUX naming
+ convention.
+
+:file:`arm/empty`
+ An empty file.
+
+:file:`arm/pxelinux.cfg/{0A010203}`
+ Configuration for 32-bit ARM systems. The filename follows the PXELINUX
+ naming convention.
+
+:file:`pxelinux/{fqdn}.efi`
+ Symbolic link to :file:`bootaa64.efi`.
+
+:file:`pxelinux/grub.cfg-{0A010203}`
+ Configuration for 64-bit ARM systems.
+
+:file:`s390x/s_{fqdn}`; :file:`s390x/s_{fqdn}_parm`; :file:`s390x/s_{fqdn}_conf`
+ Configuration files for System/390 virtual machines using "zPXE" (Cobbler's
+ ``zpxe.rexx`` script).
+
+:file:`images/{fqdn}/`
+ Kernel and initrd images for the distro being provisioned. All the
+ generated boot loader configurations point at the images in this directory.
+
+
+Other files in the TFTP root directory
+--------------------------------------
+
+:file:`pxelinux.cfg/default`
+ Default configuration used by PXELINUX when no system-specific
+ configuration exists.
+
+ The Beaker administrator can customize this configuration, however it must
+ fall back to booting the local disk by default (perhaps after a timeout)
+ using the ``localboot 0`` command.
+
+ If this file does not exist, Beaker populates it with a simple default
+ configuration that immediately boots the local disk.
+
+:file:`pxelinux.cfg/beaker_menu`
+ Menu configuration generated by :program:`beaker-pxemenu` for the
+ ``menu.c32`` program (part of Syslinux). See :ref:`pxe-menu` for details.
+
+:file:`grub/efidefault`
+ Menu configuration generated by :program:`beaker-pxemenu` for EFI GRUB.
+
+:file:`distrotrees/`
+ Cached images for the generated menus. The contents of this directory are
+ managed by :program:`beaker-pxemenu`.
diff --git a/documentation/user-guide/systems/adding.rst b/documentation/user-guide/systems/adding.rst
index b3cbb48..94c08ae 100644
--- a/documentation/user-guide/systems/adding.rst
+++ b/documentation/user-guide/systems/adding.rst
@@ -30,35 +30,8 @@ available in your lab.
The DHCP configuration must also include suitable netboot options for the
system. Typically DHCP option 66 ("TFTP server") is set to the address of the
lab controller and option 67 ("bootfile") is set to ``pxelinux.0`` or some
-other boot loader image served by the lab controller.
-
-Boot loader image
------------------
-
-Some commonly used network boot loaders are listed below.
-
-==================================== ====================== =========
-System type Filename Project
-==================================== ====================== =========
-x86-based systems with BIOS firmware :file:`pxelinux.0` Syslinux_
-x86-based systems with EFI firmware :file:`grub/grub.efi` GRUB_
-IA64 systems :file:`elilo-ia64.efi` ELILO_
-PowerPC systems :file:`yaboot` Yaboot_
-==================================== ====================== =========
-
-.. _Syslinux: http://www.syslinux.org/
-.. _GRUB: http://www.gnu.org/software/grub/
-.. _ELILO: http://elilo.sourceforge.net/
-.. _Yaboot: http://yaboot.ozlabs.org/
-
-If Syslinux is installed on the lab controller, :program:`beaker-provision`
-will populate :file:`pxelinux.0` on startup by copying it from the system-wide
-installation. Otherwise, the Beaker administrator must manually add the
-necessary boot loader images to the TFTP root directory.
-
-The Cobbler project provides `pre-compiled binaries of common boot loaders
-<https://github.com/cobbler/cobbler.github.com/tree/master/loaders>`__. Many
-Linux distributions also package these boot loaders.
+other boot loader image served by the lab controller (see
+:ref:`boot-loader-images`).
Power control
-------------