
                 Debian-Installer NetBoot Assistant
                ====================================

Overview
--------
    'di-netboot-assistant' is a tool to simplify the preparation of
    files for TFTP net booting: It downloads and extracts all the
    files needed and takes care of organizing them.
    In addition, it prepares a top level menu, which allows to choose
    from all installed netboot images.
    It supports completely automatic installations by preseeding the
    installer.  For details consult the 'README.preseed'.


QuickStart
----------
    1. Install the 'di-netboot-assistant' package and a TFTP
       server, for example 'dnsmasq' configured with
       'enable-tftp' [2].
    2. Run 'di-netboot-assistant install stable' or similar.
       'di-netboot-assistant install' returns a list of netboot images
       available for download and installation.
    3. Configure a DHCP server, as explained in [1]. For further
       information, read the 'architecture specific notes' below and
       the example configuration samples [2].

    For a more detailed example consult the 'README.installbox'.


Packaged Debian-Installer Images
--------------------------------
    You can also use the images provided by the
    debian-installer-*-netboot-* packages.

    1. Install the needed debian-installer-*-netboot-* packages.
    2. Bind mount (use 'ro' only if no firmware is needed) or copy
       '/usr/lib/debian-installer/' to your tftp root directory:

         mount -o bind,ro  /usr/lib/debian-installer/  $TFTP_ROOT/d-i/n-pkg/

       To make this persistent, add the following line to '/etc/fstab':

         /usr/lib/debian-installer/  $TFTP_ROOT/d-i/n-pkg/  none  bind,ro  0  0

    3. Add the corresponding menu entries to the boot menu by running:

         di-netboot-assistant -v rebuild-menu


Debian Live ISO Images
----------------------
    Finally, you can also provide Debian Live ISO images.

    1. Download the ISO image of interest.
    2. Mount the ISO image within your tftp root directory
       below '$TFTP_ROOT/d-i/n-live/':

         mount -o loop,ro  /PATH/TO/IMAGE.iso  $TFTP_ROOT/d-i/n-live/ISO_NAME

       To make this persistent, add the following line to '/etc/fstab':

         /PATH/TO/IMAGE.iso  $TFTP_ROOT/d-i/n-live/ISO_NAME  iso9660  loop,ro  0  0

    3. Add the corresponding menu entries to the boot menu by running:

         di-netboot-assistant -v rebuild-menu

    NOTE: In case you prefer to provide filesystem.squashfs by faster means
          than the TFTP server, use the variable $ISO_NAME in SQUASHIMG=…,
          c.f. '/etc/di-netboot-assistant/di-netboot-assistant.conf'.


TFTP server
-----------
    Depending on the TFTP server you use, adjust either 'TFTP_ROOT='
    in '/etc/di-netboot-assistant/di-netboot-assistant.conf' or the
    root directory of the TFTP server.


DHCP server
-----------
    There are two typical scenarios:
                                     ┌────────┐
         __                          │ Switch │  ┌───────────────────┐
      __/  \__                       └─┬──┬─┬─┘  │     This host     │
     /        \    ┌──────────────┐    │  │ │    │    is the only    │
    ( Internet )───┤ (DSL) Modem  ├────┘  │ └────┤    DHCP server    │
     \__    __/    │   or router  │       │      └───────────────────┘
        \__/       └──────────────┘       │    ┌───────────────────┐
                                          └────┤ A client computer │
                                               └───────────────────┘

    First case:  The TFTP server also provides DHCP for the local
                 network.  This is the most simple and recommended
                 configuration.  You simply have to add some options
                 to enable netbooting (typically, the filename to
                 boot, and the tftp server's address).  Read [1],
                 examples [2] and architecture specific notes.

                                      ┌────────┐
         __                           │ Switch │
      __/  \__     ┌───────────────┐  └─┬──┬─┬─┘
     /        \    │  (DSL) Modem  │    │  │ │    ┌───────────────────┐
    ( Internet )───┤      with     ├────┘  │ └────┤     This host     │
     \__    __/    │ build─in DHCP │       │      └───────────────────┘
        \__/       └───────────────┘       │    ┌───────────────────┐
                                           └────┤ A client computer │
                                                └───────────────────┘

    Second case: A DHCP already exists, but you can't/don't want to use it
                 for netbooting. This isn't the recommended configuration,
                 but it was successfully tested for netbooting PXE clients
                 (i386, amd64 and ia64) on network where the existing DHCP
                 server didn't provide netboot informations.
                 !!!! Do not setup rogue dhcp servers in your company !!!!

                 In this situation, you have to divide your DHCP subnet in
                 two ranges of IP address. The first range will still be
                 served by the existing DHCP server.
                 The second part will be served by "this host". It will only
                 reply to DHCP request sent during PXE netboot step. This is
                 possible because client computers (actually, their PXE agent
                 in the NIC's ROM) sends an option like this during PXE boot:
                    vendor-class-id= "PXEClient:Arch:00000:UNDI:002001"
                 Both dhcpd and dnsmasq can be instructed to provide answer
                 depending on such strings.

                 Note: For easy _home_ setup, you can choose not to reduce the
                 range of IP served by the existing DHCP server, and just
                 declare a *small* range of addresses on *both* DHCP (some
                 addresses that are unlikely to be used on the first one)
                 That's ugly, but it can work ! (as long your existing DHCP
                 don't allocate some of those IP ;-)


Using 'dnsmasq'
---------------
    'dnsmasq' is a simple all-in-one (DNS, DHCP and TFTP) server.

  QuickStart :
    Install the package 'dnsmasq':
        apt install dnsmasq

    Create the TFTP server's root directory:
	mkdir /var/lib/tftpboot

    Configure 'dnsmasq':
        cp /usr/share/doc/di-netboot-assistant/examples/dnsmasq.conf.simple \
                                               /etc/dnsmasq.d/netboot-installer
        systemctl restart dnsmasq

    Install the netboot images:
        di-netboot-assistant install stable


Running as non-root
-------------------
    It is possible to run di-netboot-assistant as non root. There are
    actually two ways to achieve that:

  • Delegate to a group (that manage the system wide netboot images)

        In this case, we want to delegate the management of netboot files
        to one or more people that don't have access to root account.

        Create a group and add those user to the group
            addgroup dina-admin
            adduser johndoe dina-admin

        Purge the package (and existing files that are owned by root !).
            # Note : you will loose existing configuration file!
            apt-get purge di-netboot-assistant

        Allow that group to modify the files
            # note: the four lines below are on single command.
            for dir in /var/cache/di-netboot-assistant \
                /var/lib/di-netboot-assistant \
                /var/lib/tftpboot/; do
                dpkg-statoverride --update --add root dina-admin 2775 $dir
            done

            # add the following line in di-netboot-assistant.conf, so
            # so new file are writable by other members of the group.
            umask 0002

            # Do not grant write permission on di-netboot-assistant.conf to
            # anybody but root. This would lead to privilege escalation since
            # the configuration file are executed (sourced) by the script.

        Reinstall the package
            apt-get install di-netboot-assistant

  • Per-user tftpboot
        It is possible to have per user configuration files and repositories.
        The user just have to create a configuration file in
           ~/.di-netboot-assistant/di-netboot-assistant.conf
        and configure it. A sample file is provided in
           /usr/share/doc/di-netboot-assistant/examples/peruser.di-netboot-assistant.conf

  • Sudo
        Do *NOT* expect the restriction of a sudo user to only run di-netboot-assistant
        to be a restriction at all:  It allows one to become root (because the sudoer
        can edit ~/.di-netboot-assistant/*).


Testing
-------
    qemu/kvm can emulate a TFTP server, so it's easy to test netboot:

        TFTP_ROOT="/var/lib/tftpboot/"

        qemu-system-x86_64 -enable-kvm -m 1024 -boot n -net nic \
                           -net user,tftp=$TFTP_ROOT,bootfile=/d-i/n-a/pxelinux.0

    or with 'Open Virtual Machine Firmware' (ovmf) installed:

        qemu-system-x86_64 -enable-kvm -m 1024 -boot n -net nic -bios /usr/share/OVMF/OVMF_CODE.fd \
                           -net user,tftp=$TFTP_ROOT,bootfile=/d-i/n-a/bootnetx64.efi

        qemu-system-x86_64 -enable-kvm -m 1024 -boot order=n \
          -net nic,netdev=net0 \
          -bios /usr/share/OVMF/OVMF_CODE.fd \
          -netdev user,id=net0,tftp=$TFTP_ROOT,bootfile=/d-i/n-a/bootnetx64.efi \
          -object filter-dump,id=net0,netdev=net0,file=/tmp/neboot.pcap

        qemu-system-aarch64 -machine virt -m 1024 -cpu cortex-a57 -boot order=n \
          -device virtio-net-device,netdev=net0 \
          -bios /usr/share/qemu-efi-aarch64/QEMU_EFI.fd \
          -netdev user,id=net0,tftp=$TFTP_ROOT,bootfile=/d-i/n-a/bootnetaa64.efi \
          -object filter-dump,id=net0,netdev=net0,file=/tmp/neboot.pcap

Mirrors
-------
    The file 'di-sources.list' contains the canonical URLs for
    repositories of netboot image.
    You can set the variable 'MIRROR_REGEXPS' to rewrite the URLs to
    your preferred mirror (you can specify multiple space-separated
    regexp).

    For example, if you want to search "://ftp.debian.org/" and
    replace it with "://ftp.fr.debian.org/debian/", then you declare
    MIRROR_REGEXPS="s=://ftp.debian.org/=://ftp.fr.debian.org/debian/="
    in '/etc/di-netboot-assistant/di-netboot-assistant.conf'.


Architecture specific notes
---------------------------
The notes in this section might not be up to date, as different Debian releases
support different architectures and systematic testing of 'di-netboot-assistant'
for exotic ones does not happen.  Do not hesitate to get in contact with the
maintainers if you would like to add additional support or further suggestions.

• i386 / amd64
    The Debian-Installer uses Syslinux's PXElinux[3] for BIOS
    platforms.  Syslinux is a boot-loader that provide a menu system
    to select the kernel you want to boot.
    For systems with EFI, grub-efi and the grub menu system is used.
    Make sure you have the grub-efi-amd64-bin package installed for
    building the grub-efi netboot image.  Secure boot is supported and
    available with 'grub-efi-amd64-signed' and 'shim-signed' installed.
    Run 'di-netboot-assistant rebuild-grub' to use the signed images.

    Absolute filenames in PXElinux:
      TFTP filenames inside PXElinux configuration files
      ('pxelinux.HEAD', 'default', …) must be prefixed with '::/'.
      PXElinux then treats them as absolute filenames (starting from
      the root of the TFTP server).  Paths starting with a slash ('/')
      are relative to the directory of 'pxelinux.0'.

    Configure DHCP:

        - In /etc/dhcp/dhcpd.conf (for isc-dhcp-server), configure the
          TFTP server's IP address:

           next-server 192.168.0.10;

        - Provide netboot/pxelinux information:

           filename "d-i/n-a/pxelinux.0";

        and/or:

           filename "d-i/n-a/bootnetx64.efi";

        for the grub EFI image.  Consult the examples [2] on how to
        configure the DHCP server to send the correct file automatically.

        If you prefer to boot a specific installer, make it the default
        in the top level menu and automatically boot it (perhaps after
        some timeout).

  The architectures below are rarely tested and the information might
  be out of date.  Help in providing support for them is highly
  appreciated.

• iPXE
    A iPXE script is provided to chainload 'pxelinux.0' or
    'bootnetx64.efi'.  Check the examples [2] on how to configure the
    DHCP server to send the boot.ipxe script to the client.

• ia64
    Support for ia64 was available in older versions of
    'di-netboot-assistant', but has been removed due to insufficient
    developer support.

• alpha
• hppa
• sparc
    Those  architectures  netboot using  BOOTP  (some  can use RARP or
    DHCP).  They don't have a boot-loader that would present a menu at
    boot-time.  This means that you must configure the DHCP server to
    provide one given kernel. (The DHCP server can of course provide
    different kernel images, based on the MAC and/or IP address).

    You can declare a kernel filename for all hosts in
    '/etc/dhcpd3/dhcpd.conf':

        subnet 192.168.0.0 netmask 255.255.255.0 {
            filename "d-i/n-a/stable/sparc/boot.img"
        }

    or declare a single host:

        host myhost1 {
            hardware ethernet 00:40:63:d8:02:2c;
            filename "d-i/n-a/stable/sparc/boot.img"
        }

• arm, armel, armhf, arm64
    Start u-boot, stop autoboot and enter at the prompt:
      => dhcp
      => pxe get
      => pxe boot
    Then choose an entry from the installer boot menu.

• mips,mipsel,mips64el
    Those architectures can do netbooting, but are not supported  by
    this tool at the moment (because there is no '.tar.gz' archive).

• m68k
• ppc64el
• s390, s390x


See also
--------
    http://wiki.debian.org/DebianInstaller/NetbootAssistant
    http://www.debian.org/releases/stable/debian-installer/

--------------------------------------------------------------------------
    [1] "Installation Guide", especially the sections
        "4.6 Preparing Files for TFTP Net Booting"
        and "5.1.5 Booting with TFTP"
        http://www.debian.org/releases/stable/installmanual

    [2] Sample DHCP configuration files:
        /usr/share/doc/di-netboot-assistant/examples/dnsmasq.conf.simple
        /usr/share/doc/di-netboot-assistant/examples/dnsmasq.conf.multiarch
        /usr/share/doc/di-netboot-assistant/examples/dhcpd.conf.simple
        /usr/share/doc/di-netboot-assistant/examples/dhcpd.conf.multiarch

    [3] PXElinux homepage.
        http://syslinux.zytor.com/wiki/index.php/PXELINUX

    [ ] Preboot Execution Environment (PXE) Specification
        http://www.intel.com/design/archives/wfm/downloads/pxespec.htm

    [ ] Extensible Firmware Interface (EFI)
        http://developer.intel.com/technology/efi/index.htm

 -- Franklin PIAT, Andreas B. Mundt
