Added PXE zone howto - closes erigones/esdc-factory#37

user-guide/howto/files/pxe/dnsmasq.conf

@@ -0,0 +1,55 @@
+# Configuration file for dnsmasq.
+# Disable DNS
+port=0
+
+# Set the domain for dnsmasq. this is optional, but if it is set, it
+# does the following things.
+# 1) Allows DHCP hosts to have fully qualified domain names, as long
+#     as the domain part matches this setting.
+# 2) Sets the "domain" DHCP option thereby potentially setting the
+#    domain of all systems configured by DHCP
+# 3) Provides the domain part for "expand-hosts"
+domain=test.example.com
+
+# Uncomment this to enable the integrated DHCP server, you need
+# to supply the range of addresses available for lease and optionally
+# a lease time. If you have more than one network, you will need to
+# repeat this for each network on which you want to supply DHCP
+# service.
+dhcp-range=set:nodes,10.10.0.50,10.10.0.100,255.255.255.0,12h
+
+# Always give the host with Ethernet address 11:22:33:44:55:66
+# the name node99 and tag node99 and IP address 10.0.60.60
+#dhcp-host=set:node99,11:22:33:44:55:66,node99,10.10.0.200,24h
+
+# Override the default route supplied by dnsmasq, which assumes the
+# router is the same machine as the one running dnsmasq.
+dhcp-option=option:router,10.10.0.1
+
+# Set the DNS server address
+dhcp-option=option:dns-server,10.10.0.4
+
+# Boot for Etherboot gPXE. The idea is to send two different
+# filenames, the first loads gPXE, and the second tells gPXE what to
+# load. The dhcp-match sets the gpxe tag for requests from gPXE.
+dhcp-match=set:gpxe,175 # gPXE sends a 175 option.
+dhcp-boot=tag:!gpxe,undionly.kpxe
+dhcp-boot=menu.ipxe
+#dhcp-boot=tag:nodes,menu.ipxe
+
+# Run custom iPXE script on specific server with tag "node99"
+#dhcp-boot=tag:node99,esdc-latest.ipxe
+
+# Enable dnsmasq's built-in TFTP server
+enable-tftp
+
+# Set the root directory for files available via FTP.
+tftp-root=/data/tftpboot
+
+# The DHCP server needs somewhere on disk to keep its lease database.
+# This defaults to a sane location, but if you want to change it, use
+# the line below.
+dhcp-leasefile=/var/lib/dnsmasq.leases
+
+# Log lots of extra information about DHCP transactions.
+log-dhcp

user-guide/howto/files/pxe/esdc-latest.ipxe

@@ -0,0 +1,9 @@
+#!ipxe
+
+set platform-version 20170624T192838Z
+set install-host 10.10.0.33
+
+kernel /erigonos/${platform-version}/platform/i86pc/kernel/amd64/unix -B smartos=true,computenode=true,netboot=true,netboot_install_script=http://${install-host}/netboot_install_script.sh
+initrd /erigonos/${platform-version}/platform/i86pc/amd64/boot_archive
+
+boot

user-guide/howto/files/pxe/menu.ipxe

@@ -0,0 +1,46 @@
+#!ipxe
+
+set platform-version 20170624T192838Z
+set install-host 10.10.0.33
+
+######## MAIN MENU ###################
+:start
+menu Welcome to iPXE's Boot Menu
+item
+item --gap -- ------------------------- Operating systems ------------------------------
+item esdc_b1    Danube Cloud Compute Node (${platform-version})
+item esdc_r1    Danube Cloud Compute Node (${platform-version}) Rescue (l/p: root/root)
+item
+item --gap -- ------------------------------ Utilities ---------------------------------
+item shell      Enter iPXE shell
+item reboot     Reboot
+item
+item exit       Exit (boot local disk)
+choose --default esdc_b1 --timeout 30000 target && goto ${target}
+
+
+########## UTILITY ITEMS ####################
+:shell
+echo Type exit to get the back to the menu
+shell
+set menu-timeout 0
+goto start
+
+:reboot
+reboot
+
+:exit
+exit
+
+########## MENU ITEMS #######################
+:esdc_b1
+kernel /erigonos/${platform-version}/platform/i86pc/kernel/amd64/unix -B computenode=true,smartos=true,netboot=true,netboot_install_script=http://${install-host}/netboot_install_script.sh
+initrd /erigonos/${platform-version}/platform/i86pc/amd64/boot_archive
+boot
+goto start
+
+:esdc_r1
+kernel /erigonos/${platform-version}/platform/i86pc/kernel/amd64/unix -B computenode=true,smartos=true,netboot=true,root_shadow='$5$2HOHRnK3$NvLlm.1KQBbB0WjoP7xcIwGnllhzp2HnT.mDO7DpxYA'
+initrd /erigonos/${platform-version}/platform/i86pc/amd64/boot_archive
+boot
+goto start

user-guide/howto/files/pxe/netboot_install_script.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/bash
+#
+# The logic is simple:
+#  1. Download and extract USB image into /tmp/usbkey
+#  2. Run prompt-config.sh, which will create /usbkey on the zones pool
+#  3. Copy contents of /tmp/usbkey into /usbkey
+#
+# There is one little problem:
+#   The original prompt-config.sh does a reboot before it finishes =>
+#   => we need to change that before running the script.
+# 
+
+# Adjust this: download URL of the compute node USB image
+USB_URL="http://10.10.0.33/esdc-ce-cn-2.6.0.img"
+###########################################################
+
+export PATH="/usr/sbin:/sbin:/usr/bin:/bin"
+
+# Active network interface
+NIC_UP="$1"
+# /usbkey
+USB_PATH="/$(svcprop -p "joyentfs/usb_copy_path" svc:/system/filesystem/smartdc:default)"
+# /mnt/usbkey
+USBMOUNT="/mnt/$(svcprop -p "joyentfs/usb_mountpoint" svc:/system/filesystem/smartdc:default)"
+# Download USB image into /tmp
+USBIMAGE="/tmp/usbkey.iso"
+# Custom prompt-config.sh
+PROMPT_CONFIG="/tmp/prompt-config.sh"
+
+echo "=> Running netboot_install_script"
+
+if [[ -f "${USB_PATH}/.joyliveusb" ]]; then
+	echo "${USB_PATH} is already in place" >&2
+	exit 0
+fi
+
+echo "=> Preparing ${USBMOUNT}"
+mkdir -p "${USBMOUNT}"
+
+echo "=> Downloading compute node USB image into ${USBIMAGE}"
+if ! curl -m 30 -f -k -L --progress-bar -o "${USBIMAGE}" "${USB_URL}"; then
+	echo "ERROR: Failed to download \"${USB_URL}\"" >&2
+	exit 1
+fi
+
+echo "=> Mounting USB image"
+LOFIDEV=$(lofiadm -a "${USBIMAGE}")
+mount -F pcfs -o noclamptime,noatime "${LOFIDEV}:c" "${USBMOUNT}"
+
+if [[ ! -f "${USBMOUNT}/scripts/prompt-config.sh" ]]; then
+	echo "ERROR: \"${USBMOUNT}/scripts/prompt-config.sh\" does not exist" >&2
+	exit 2
+fi
+
+# FIXME: It might be better to distribute a custom prompt-config.sh along with this script
+# Remove last 5 lines from prompt-config.sh
+x=$(($(wc -l < "${USBMOUNT}/scripts/prompt-config.sh" )-5))
+sed "$x,\$d" "${USBMOUNT}/scripts/prompt-config.sh" > "${PROMPT_CONFIG}"
+chmod +x "${PROMPT_CONFIG}"
+
+echo "=> Shutting down network (${NIC_UP})"
+[[ -n "${NIC_UP}" ]] && /sbin/ifconfig "${NIC_UP}" unplumb
+
+echo "=> Running prompt-config.sh"
+/smartdc/lib/sdc-on-tty -d /dev/console "${PROMPT_CONFIG}" "${USBMOUNT}"
+
+echo "=> Copying files from USB image onto disk storage"
+echo "=> Please wait..."
+rsync -a --exclude private --exclude os "${USBMOUNT}/" "${USB_PATH}/"
+
+echo "=> The system will now reboot"
+reboot 2> /dev/null

user-guide/howto/index.rst

@@ -8,4 +8,5 @@ HOWTOs
    windows
    import
    access-zone
+   pxe-zone
    mdata

user-guide/howto/pxe-zone.rst

@@ -0,0 +1,147 @@
+.. _pxe_zone:
+
+PXE Zone providing Network Booting for Compute Nodes
+****************************************************
+
+The PXE zone is a SunOS Zone :ref:`server <vm>`, which acts as a DHCP and TFTP server and is used for booting and installing compute nodes on the *admin* network.
+
+
+Creating a Zone with admin NIC
+##############################
+
+* Create an PXE zone. The disk should be large enough for storing one or two *Danube Cloud* USB images.
+
+    .. image:: img/create_pxe_zone.png
+
+* Add a NIC with the *admin* network and **DHCP spoofing enabled**.
+
+    .. image:: img/create_pxe_zone_admin_nic.png
+
+* Deploy your PXE zone.
+
+
+Install and Configure Required Services
+#######################################
+
+* Install dnsmasq (for DHCP and TFTP) and nginx (for HTTP).
+
+    .. code-block:: bash
+
+        [root@pxe-boot ~] pkgin install dnsmasq nginx
+
+* Configure dnsmasq (DHCP and TFTP).
+
+    - Download a semi-prepared :download:`dnsmasq.conf <files/pxe/dnsmasq.conf>`:
+
+        .. code-block:: bash
+
+            [root@pxe-boot ~] curl https://docs.danubecloud.org/user-guide/_downloads/dnsmasq.conf > /opt/local/etc/dnsmasq.conf
+
+    - Change at least the following configure options in ``/opt/local/etc/dnsmasq.conf`` according to your *admin* network:
+
+        - ``dhcp-range=``
+        - ``dhcp-option=option:router``
+        - ``dhcp-option=option:dns-server``
+
+    - Create the TFTP root directory.
+
+        .. code-block:: bash
+
+            [root@pxe-boot ~] mkdir /data/tftpboot
+
+* Configure nginx (HTTP).
+
+    - The defaults are fine, just change the document root for ``location /`` to something else.
+
+        .. code-block:: bash
+
+            [root@pxe-boot ~] vim /opt/local/etc/nginx/nginx.conf
+
+                location / {
+                    root   /data/tftpboot/install;
+                    index  index.html index.htm;
+                    autoindex on;
+                }
+
+    - Create the document root directory.
+
+        .. code-block:: bash
+
+            [root@pxe-boot ~] mkdir /data/tftpboot/install
+
+* Enable both services.
+
+    .. code-block:: bash
+
+        [root@pxe-boot ~] svcadm enable dnsmasq
+        [root@pxe-boot ~] svcadm enable nginx
+
+
+Preparing TFTP and iPXE Boot Files
+##################################
+
+* The following files iPXE files should be placed into the TFTP root directory:
+
+    - iPXE client: :download:`undionly.kpxe <files/pxe/IPXE-100612_undionly.kpxe>`
+    - iPXE scripts: :download:`menu.ipxe <files/pxe/menu.ipxe>` and/or :download:`esdc-latest.ipxe<files/pxe/esdc-latest.ipxe>`
+
+    .. code-block:: bash
+
+        [root@pxe-boot ~] cd /data/tftpboot
+        [root@pxe-boot tftpboot] curl -o undionly.kpxe https://docs.danubecloud.org/user-guide/_downloads/IPXE-100612_undionly.kpxe
+        [root@pxe-boot tftpboot] curl -O https://docs.danubecloud.org/user-guide/_downloads/menu.ipxe
+        [root@pxe-boot tftpboot] curl -O https://docs.danubecloud.org/user-guide/_downloads/esdc-latest.ipxe
+
+* Download and unpack a *Danube Cloud* ErigonOS (SmartOS) platform archive.
+
+    .. code-block:: bash
+
+        [root@pxe-boot ~] mkdir /data/tftpboot/erigonos
+        [root@pxe-boot ~] cd /data/tftpboot/erigonos
+        [root@pxe-boot erigonos] curl -O https://download.erigones.org/esdc/factory/platform/platform-<version>.tgz
+        [root@pxe-boot erigonos] gtar -xzvf platform-<version>.tgz
+        [root@pxe-boot erigonos] mv platform-<version> <version>
+        [root@pxe-boot erigonos] cd <version>
+        [root@pxe-boot <version>] mkdir platform
+        [root@pxe-boot <version>] mv i86pc platform
+
+    - After this operation the kernel should be in ``/data/tftpboot/erigonos/<version>/platform/i86pc/kernel/amd64/unix``
+    - and the boot archive should be in ``/data/tftpboot/erigonos/<version>/platform/i86pc/amd64/boot_archive``.
+
+* Configure the iPXE script. The default is to use the ``menu.ipxe``, but you can also boot a compute node directly by using the example ``esdc-latest.ipxe`` script. In any case, the ``platform-version`` and ``install-host`` variables at the beginning of the *.ipxe* script should be adjusted to your reality:
+
+    .. code-block:: bash
+
+        [root@pxe-boot tftpboot] vim menu.ipxe
+
+            set platform-version <platform-version>
+            set install-host <pxe-boot-host-IP-address>
+
+
+Preparing HTTP Install Files
+############################
+
+* Download and unpack a *Danube Cloud* compute node :ref:`USB image <cn_image>`.
+
+    .. code-block:: bash
+
+        [root@pxe-boot ~] cd /data/tftpboot/install
+        [root@pxe-boot install] curl -O https://download.erigones.org/esdc/usb/stable/esdc-ce-cn-<version>.img.gz 
+        [root@pxe-boot install] gzip -d esdc-ce-cn-<version>.img.gz 
+
+* Download a sample install script.
+
+    .. code-block:: bash
+
+        [root@pxe-boot install] curl -O https://docs.danubecloud.org/user-guide/_downloads/netboot_install_script.sh
+
+* Change the USB image download URL in the ``netboot_install_script.sh`` to the desired *Danube Cloud* compute node image.
+
+    .. code-block:: bash
+
+        [root@pxe-boot install] vim netboot_install_script.sh
+
+            USB_URL="http://<pxe-boot-host-IP-address>/esdc-ce-cn-<esdc-version>.img"
+
+
+.. note:: The network boot install script functionality is available from *Danube Cloud* version 2.6.