Clusterducks

Debian GNU/Linux netboot configuration

The following instructions will result in a working Debian image that boots from iSCSI with the custom clusterducks dracut module for vDisk support.

Create volumes for installation

  1. In your control panel, create a new volume of an appropriate size for your new Debian installation.

  2. Create a group based on the volume created in step one.

  3. Start a VM or physical device via PXE so that it shows up in the device list and is assigned to your new group. If using the "Exit to CDROM" menu item, any debian livedvd or usb environment that is next in the boot order will be loaded after the fresh PXE template fails to start. Try to use a recent live environment, based on Debian Wheezy or newer.

  4. In your live linux environment, configure networking using DHCP and install the open-iscsi utility set:

    $ sudo apt-get install open-iscsi

  5. Configure the live environment iSCSI initiator and target name for authentication:

    $ export IP_ADDRESS=$(ifconfig | awk '/inet addr/{print substr($2,6)}' | grep -v 127.0.0)

    # Systems with multiple IP addresses should just set IP_ADDRESS manually.

    $ export INITIATOR_NAME="iqn.2008.net.clusterducks:$(echo $IP_ADDRESS | md5sum | awk '{ print $1 }')"

    $ export TARGET_NAME="iqn.2008.net.clusterducks:$(cat /sys/class/net/eth0/address | sed 's/:/-/g')"

  6. Run a "discovery" against your master iSCSI server (replace 1.2.3.4 with your server IP):

    $ export SERVER_IP="1.2.3.4"

    $ iscsiadm -m discovery -t sendtargets -p "$SERVER_IP" | grep $TARGET_NAME

You should see an iSCSI target with the mac address of your netbooted device. If you do not, try booting the device via PXE again and make sure you see "Registered SAN 0x80".

  1. Connect to the device's iSCSI target.

    $ iscsiadm -m node --target "$TARGET_NAME" -p "$SERVER_IP" --login

    $ cd / ; readlink -e /dev/disk/by-path/iscsi-${SERVER_IP}:3260-iscsi-${TARGET_NAME}-lun-1 ; cd - 1>/dev/null 2>/dev/null

The second command will give you the name of the real udev path for the newly connected iSCSI device.

  1. At this point, your device now has access to its OS image and the installation can begin. To be sure your changes are saved, thaw/unlock the device via clusterducks - otherwise, the image will be erased on subsequent PXE boot.

  2. After Debian has been installed, do not yet reboot - some changes are required to allow native iSCSI boot because Debian's included initramfs facilities are problematic.

    • initramfs-tools must be replaced with dracut, a modular and flexible initramfs generator from Red Hat (used in CentOS, Fedora, SUSE) * A custom dracut module for clusterducks can be optionally installed for pre-rootfs vDisk support to allow the use of overlayfs as a root filesystem. Essentially, this module makes shared image architecture much more easily managed.
  3. To make the required changes, use ctrl+alt+f1, f2, f3 etc until you see the live environment's message "Press return to activate this console..":
  • $ df -h
    • Look for your mounted installation here. The path is typically /target for Debian install media.
  • $ chroot /target
    • This will pivot your terminal into the newly installed filesystem, so /target now becomes /. This means that all subsequent commands will be running in your new OS image.
  • $ apt-get install dracut dracut-network
    • (System will ask if you want to remove initramfs-tools - we do. That package is less than useful.)
  • $ git clone https://git.clusterducks.net/clusterducks/dracut-clusterducks.git /usr/lib/dracut/modules.d/99clusterducks
    • This will download an optional clusterducks module that sets up a handful of device configuration items automatically at boot
  • $ dracut -a 'iscsi clusterducks' -k $(uname -r) /boot/initrd-$(uname -r) --force
    • The initram image will be replaced once this is executed.
  • $ nano -w /etc/default/grub
    • Set GRUB_CMDLINE_LINUX="rd.netboot=iscsi rd.iscsi.firmware=1 ip=dhcp"
  • $ update-grub2
  • $ exit
    • Exit the chroot environment, back to the live filesystem
  • $ reboot
  1. During reboot, you should see the typical clusterducks netboot provisioning messages, GRUB2, and then Linux starts.

At this point, if you've created vDisks and assigned them to the device, they should be available by name in /dev/disk/by-path/