diff --git a/user-guide/howto/files/pxe/IPXE-100612_undionly.kpxe b/user-guide/howto/files/pxe/IPXE-100612_undionly.kpxe new file mode 100644 index 0000000..2a6bb89 Binary files /dev/null and b/user-guide/howto/files/pxe/IPXE-100612_undionly.kpxe differ diff --git a/user-guide/howto/files/pxe/dnsmasq.conf b/user-guide/howto/files/pxe/dnsmasq.conf new file mode 100644 index 0000000..03f0837 --- /dev/null +++ b/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 diff --git a/user-guide/howto/files/pxe/esdc-latest.ipxe b/user-guide/howto/files/pxe/esdc-latest.ipxe new file mode 100644 index 0000000..c680620 --- /dev/null +++ b/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 diff --git a/user-guide/howto/files/pxe/menu.ipxe b/user-guide/howto/files/pxe/menu.ipxe new file mode 100644 index 0000000..c8d90d3 --- /dev/null +++ b/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 diff --git a/user-guide/howto/files/pxe/netboot_install_script.sh b/user-guide/howto/files/pxe/netboot_install_script.sh new file mode 100644 index 0000000..6727b92 --- /dev/null +++ b/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 diff --git a/user-guide/howto/img/create_pxe_zone.png b/user-guide/howto/img/create_pxe_zone.png new file mode 100644 index 0000000..6f4a6d4 Binary files /dev/null and b/user-guide/howto/img/create_pxe_zone.png differ diff --git a/user-guide/howto/img/create_pxe_zone_admin_nic.png b/user-guide/howto/img/create_pxe_zone_admin_nic.png new file mode 100644 index 0000000..e426445 Binary files /dev/null and b/user-guide/howto/img/create_pxe_zone_admin_nic.png differ diff --git a/user-guide/howto/index.rst b/user-guide/howto/index.rst index 68eec8c..1347a6e 100644 --- a/user-guide/howto/index.rst +++ b/user-guide/howto/index.rst @@ -8,4 +8,5 @@ HOWTOs windows import access-zone + pxe-zone mdata diff --git a/user-guide/howto/pxe-zone.rst b/user-guide/howto/pxe-zone.rst new file mode 100644 index 0000000..b77fb45 --- /dev/null +++ b/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 `, 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 `: + + .. 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 ` + - iPXE scripts: :download:`menu.ipxe ` and/or :download:`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-.tgz + [root@pxe-boot erigonos] gtar -xzvf platform-.tgz + [root@pxe-boot erigonos] mv platform- + [root@pxe-boot erigonos] cd + [root@pxe-boot ] mkdir platform + [root@pxe-boot ] mv i86pc platform + + - After this operation the kernel should be in ``/data/tftpboot/erigonos//platform/i86pc/kernel/amd64/unix`` + - and the boot archive should be in ``/data/tftpboot/erigonos//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 + set install-host + + +Preparing HTTP Install Files +############################ + +* Download and unpack a *Danube Cloud* compute node :ref:`USB 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-.img.gz + [root@pxe-boot install] gzip -d esdc-ce-cn-.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:///esdc-ce-cn-.img" + + +.. note:: The network boot install script functionality is available from *Danube Cloud* version 2.6.