parabolaiso/docs/README.altbootmethods

INDEX
-----

* Alternative boot methods (configs/releng)
  * ISO in loopback mode
  * ISO in memdisk mode
  * Network booting (PXE) [first stage]
    * DHCP + TFTP
    * DHCP + HTTP
    * HTTP/NFS/NBD [second stage]


*** Alternative boot methods (configs/releng)

Release image filesystem labels consist of: PARA_<YYYY><MM>
Release image filenames consist of: parabola-<EDITION>-<ISO_TYPE>-<VERSION>.iso
  Where:
    <EDITION>  consist of either <INIT_SYSTEM>     or <INIT_SYSTEM>-<DESKTOP_ENVIRONMENT>
    <ISO_TYPE> consist of either <ARCH>-netinstall or <ARCH>-complete
    <VERSION>  consist of <YYYY>.<MM>.<DD>
    Where:
      <INIT_SYSTEM>         such as 'systend', 'openrc'
      <DESKTOP_ENVIRONMENT> such as 'cli', 'lxde'
      <ARCH>                such as 'i686', 'x86_64', or 'dual'
      <YYYY>                is the 4-digit year of the build date
      <MM>                  is the 2-digit month of the build date
      <DD>                  is the 2-digit day of the build date
  e.g. parabola-systemd-cli-i686-netinstall-2017-09-30.iso
       parabola-openrc-lxde-dual-complete-2017-09-30.iso


** ISO in loopback mode.

Note: Described method is for using with GRUB2.
      GRUB2 is installed on source media and parabola-<EDITION>-<ISO_TYPE>-<VERSION>.iso
      is at path <ISO_PATH> on disk <D> and partition <P>,
      where the ISO filesystem label is <ISO_FS_LABEL>
      and filesystem is labeled as <SOURCE_FS_LABEL>.
      <BOOT_DIRNAME> is the root directory of the kernel and initrd in the ISO,
      which corresponds to the $boot_dirname variable in build.sh (default: 'parabola').
Note: The 'dual' architecture ISOs can make use of both of the entries below.

menuentry "Parabola GNU/Linux-libre Live (x86_64)" {
    set boot_dirname="<BOOT_DIRNAME>"
    set iso_fs_label="<ISO_FS_LABEL>"
    set target_fs_label="<SOURCE_FS_LABEL>"
    set iso_file="/<ISO_PATH>/parabola-<EDITION>-<ISO_TYPE>-<VERSION>.iso"
    loopback loop (hd<D>,<P>)$iso_file
    linux (loop)/$boot_dirname/boot/x86_64/vmlinuz parabolaisolabel=$iso_fs_label img_label=$target_fs_label img_loop=$iso_file
    initrd (loop)/$boot_dirname/boot/x86_64/parabolaiso.img
}

menuentry "Parabola GNU/Linux-libre Live (i686)" {
    set boot_dirname="<BOOT_DIRNAME>"
    set iso_fs_label="<ISO_FS_LABEL>"
    set target_fs_label="<SOURCE_FS_LABEL>"
    set iso_file="/<ISO_PATH>/parabola-<EDITION>-<ISO_TYPE>-<VERSION>.iso"
    loopback loop (hd<D>,<P>)$iso_file
    linux (loop)/$boot_dirname/boot/i686/vmlinuz parabolaisolabel=$iso_fs_label img_label=$target_fs_label img_loop=$iso_file
    initrd (loop)/$boot_dirname/boot/i686/parabolaiso.img
}


** ISO in memdisk mode.

Note: Described method is for using with SYSLINUX. Anyway MEMDISK from SYSLINUX can work
      with other bootloaders.
      SYSLINUX is installed on target media and parabola-<EDITION>-<ISO_TYPE>-<VERSION>.iso
      is at path <ISO_PATH>.
      On 32-bit systems, is needed to pass vmalloc=nnM to the kernel, where nn is the size
      of the ISO image plus 64 MiB (or 128 MiB).
Note: The 'dual' architecture ISOs can make use of both of the entries below.

LABEL parabola_x64
   LINUX memdisk
   INITRD /<ISO_PATH>/parabola-<EDITION>-<ISO_TYPE>-<VERSION>.iso
   APPEND iso

LABEL parabola_x32
   LINUX memdisk
   INITRD /<ISO_PATH>/parabola-<EDITION>-<ISO_TYPE>-<VERSION>.iso
   APPEND iso


** Network booting (PXE).

All ISOs are ready to act as PXE server, some manual steps are needed
to setup the desired PXE boot mode.
Alternatively it is possible to use an existing PXE server following the same logic.
Note: Setup network first, adjust IP adresses, and respect all slashes "/".

First stage is for loading kernel and initramfs via PXE, two methods described here:

* DHCP + TFTP

Note: All NIC firmwares should support this.

# dnsmasq --port=0 \
          --enable-tftp \
          --tftp-root=/run/parabolaiso/bootmnt \
          --dhcp-range=192.168.0.2,192.168.0.254,86400 \
          --dhcp-boot=/parabola/boot/syslinux/gpxelinux.0 \
          --dhcp-option-force=209,boot/syslinux/parabolaiso.cfg \
          --dhcp-option-force=210,/parabola/

* DHCP + HTTP

Note: Not all NIC firmware supports HTTP and DNS (if domain name is used).
      At least this works with iPXE and gPXE.

# dnsmasq --port=0 \
          --dhcp-range=192.168.0.2,192.168.0.254,86400 \
          --dhcp-boot=http://192.168.0.7/parabola/boot/syslinux/gpxelinux.0 \
          --dhcp-option-force=209,boot/syslinux/parabolaiso.cfg \
          --dhcp-option-force=210,http://192.168.0.7/parabola/

Once the kernel is started from PXE, SquashFS files and other misc files
inside "parabola" directory must be loaded (second stage). One of the following
methods can be used to serve the rest of live-medium.

* HTTP

# darkhttpd /run/parabolaiso/bootmnt

* NFS

# echo "/run/parabolaiso/bootmnt 192.168.0.*(ro,no_subtree_check,no_root_squash)" >> /etc/exports
# systemctl start rpc-mountd.service

* NBD

Note: The ISO filesystem label is <ISO_FS_LABEL>. Get this with the following command:
      $ isoinfo -d -i path/to/the.iso | grep 'Volume id:'

# cat << EOF > /tmp/nbd-server.conf
[generic]
[parabolaiso]
    readonly = true
    exportname = /dev/disk/by-label/<ISO_FS_LABEL>
EOF
# nbd-server -C /tmp/nbd-server.conf