# Using PXE and Iguana
This document explains how to run Agama on PXE with the help of Iguana. The described setup
uses libvirt, but you can adapt the overall approach to other scenarios (like running your TFTP
server).
Additionally, it offers some helpful tips for debugging Agama problems.
## Set up
The process can be summarized in these steps:
1. Set up the TFTP tree, defining a boot option for Agama + Iguana.
2. Configure libvirt network to serve the tree.
3. Prepare the initial ramdisk image (initrd), based on Iguana.
4. Boot from PXE.
### Set up the TFTP tree
The TFTP tree should contain the SYSLINUX boot loader. You can copy the required files from the
`syslinux` package.
zypper in syslinux
mkdir /srv/tftpboot
cp /usr/share/syslinux/pxelinux.0 /srv/tftpboot
mkdir /srv/tftpboot/pxelinux.cfg
To define a boot option to run Agama, add a `/srv/tftpboot/pxelinux.cfg/default` file with the
following content:
```
default iguana
label iguana
ipappend 2
kernel vmlinuz-iguana
append initrd=initrd-iguana rd.iguana.control_url=tftp://192.168.122.1/agama.yaml rd.iguana.debug=1
display message
implicit 1
prompt 1
timeout 50
```
Do not worry about the kernel, the initrd or the `agama.yaml` file, we will jump into it
later.
### Configure libvirt to serve TFTP files
To instruct libvirt to serve the TFTP files, you must add the `tftp` and `bootp` elements to the
network configuration. Use the `virsh net-edit default` command to edit the configuration and adapt
it accordingly. Here is an example:
```xml
default
639e02a7-fcbd-4cf3-a563-6db083aef051
```
### Configure VirtualBox to serve TFTP files
If you want to use VirtualBox together with it's built-in TFTP support, you have to accept some limitations.
1. Built in TFTP support is available only for NAT network device.
Such device cannot be used for accessing the guest machine from host system later on. If you plan to access
the guest over network from host system, you have to use an additional network device - e.g. bridged one.
2. VirtualBox doesn't have particular configuration file / options for setting TFTP. Everything is done via
hardcoded setup. VirtualBox's internal TFTP server uses `~/.config/VirtualBox/TFTP` (on Linux) for serving
files. Moreover, to tight particular configuration to specific virtual machine (VM), you have to use VM's
name in file, subdirectory names. So if you have VM with name `PXE boot` then PXE kernel is expected to be
named `PXE boot.pxe`. Similarly, using same naming for kernel and initrd names as above, initrd-iguana is
expected to be named `PXE initrd-iguana` and kernel `PXE vmlinuz-iguana`. Last but not least the configuration
directory `pxelinux.0` should be named `PXE pxelinux.0`. To make it clear, machine name based prefix has to be
used only in the file names. In the configuration you refer to those files without the prefix - VirtualBox
adds it transparently for you.
3. VirtualBox's TFTP server is quite limited. You cannot use it for serving custom files like `agama.yaml`.
You can use another way how to serve Agama's configuration file. E.g. local http server by changing
boot option to `rd.iguana.control_url=http:///agama.yaml`
4. With this setup Agama listens on port 9090 (see also below in Booting from PXE chapter). To be able
to connect to it you need an additional network device as described in (1). You need to modify
kernel boot options one more time and add something like `ip=enp0s8:dhcp` where `enp0s8` is second network device.
So, to put everything together. You should have your PXE configuration stored in `~/.config/VirtualBox/TFTP`. You
can use sources and configuration as presented throughout this document with small modification to boot options in
the `default` configuration file. It should look e.g. like this (see point (4) above for details):
`append initrd=initrd-iguana rd.iguana.control_url=http:///agama.yaml rd.iguana.debug=1 ip=enp0s8:dhcp`
### initrd preparation
Iguana provides a universal initrd in which actual functionality is implemented in containers. This
ramdisk and its corresponding kernel are included in the [`iguana`
package](https://build.opensuse.org/package/show/home:oholecek:iguana/iguana).
Which containers to use and how to set them up is defined in a *workflow definition*. The [Iguana
repository](https://github.com/openSUSE/iguana) includes a [definition for
Agama](https://github.com/openSUSE/iguana/blob/main/iguana-workflow/examples/agama.yaml).
After installing the `iguana` package, copy the kernel (`/usr/share/iguana/vmlinuz-VERSION`), the
initrd (`/usr/share/iguana/iguana-initrd`) and the workflow definition to the TFTP tree[^1]. You must
use the same paths specified in the `ìguana` boot option (see [Set up the TFTP
tree](#set-up-the-tftp-tree) section).
[^1]: If you want to point always to the latest workflow definition, you can use a raw GitHub
link: `rd.iguana.control_url=https://raw.githubusercontent.com/openSUSE/iguana/main/iguana-workflow/examples/agama.yaml`
### Booting from PXE
To boot from PXE, you just need to set the network card as the first booting device. Alternatively,
you can enable the boot menu so you can decide how to boot your system manually.
Now your virtual machine should be ready to boot from PXE and start Iguana/Agama. Once the
system boots and the services are started, you should be able to access Agama with a browser
on port 9090.
:warning: 4GB RAM is the minimum memory for the virtual machine and using less could affect the
boot process.
## Tips
### Adding support for SSH
:warning: **Please, build the initrd on a virtual machine to avoid messing up your system.**
For debugging purposes, you might be interested in connecting to the system and running commands
like `podman` to inspect the situation. If that's the case, you can add SSH support to Iguana's
initrd following these steps:
1. Install [dracut-iguana](https://github.com/openSUSE/iguana/tree/main/dracut-iguana) from
[OBS](https://build.opensuse.org/package/show/home:oholecek:iguana/dracut-iguana).
2. Install the `dracut-sshd` package and place your public SSH key on `/root/.ssh/authorized_keys`.
3. Rebuild the image:
dracut --verbose --force --no-hostonly --no-hostonly-cmdline --no-hostonly-default-device --no-hostonly-i18n --reproducible --add iguana iguana-initrd
4. Copy the system's kernel (`/boot/vmlinuz-VERSION`) and the generated initrd to your TFTP tree.
### Accessing the serial console
In case of problems, you should inspect system messages. The best way is to enable the serial
console by adding `console=tty0 console=ttyS0,9600` to the `append` line. Then, you will be able to
connect using `sudo virsh console DOMAIN`.