Installing Debian Linux as a guest operating system

In the following sample Debian is to be installed in a virtual machine under TwinCAT/BSD. The shell scripts from the GitHub repository https://github.com/Beckhoff/TCBSD_Hypervisor_Samples/tree/main/vm_autostart can be used as a template.

TCBSD_Hypervisor_Sampesl/vm_autostart
├── Makefile
├── rc.d
│   └── samplevm
└── samplevm

Requirements for the VM setup:

To run Debian as a guest operating system without a graphical desktop, the VM should provide two virtual cores and 2 GB RAM. The VM should be UEFI-based in order to boot guest operating systems. The Debian installation should be done via a "net installer" ISO-CDROM image. For Internet access, the VM is connected to the host's network via a Bridge network.
To interact with the Debian installer, a VNC connection to the VM should be enabled. The required scripts, the files for the UEFI and virtual data carriers (CDROM ISO and hard disk) should also be saved on a ZFS dataset so that the state can be backed up via a ZFS snapshot after the operating system has been installed and restored at a later date.

An overview of the configuration is shown in the following figure:

Installing Debian Linux as a guest operating system 1: — Debian Linux sample VM

Requirements:

Root rights are assumed for all the following commands. Switch to a root shell via doas sh.

Proceed as follows to set up the configuration:

1. Create a ZFS data sets as storage location for virtual machines configuration:

zfs create -p -o mountpoint=/vms/samplevm zroot/samplevm

2. Download and unzip the GitHub sample scripts to /vms/samplevm/scripts:

fetch -o /home/Administrator/main.zip \
https://github.com/Beckhoff/TCBSD_Hypervisor_Samples/archive/refs/heads/main.zip
unzip -d /vms/samplevm /home/Administrator/main.zip
mv /vms/samplevm/TCBSD_Hypervisor_Samples-main/vm_autostart /vms/samplevm/scripts 
rm -rf /vms/samplevm/TCBSD_Hypervisor_Samples-main /home/Administrator/main.zip

3. The next step is to adapt the bhyve call within /vms/sampelvm/vm_autostart/sample. The file can be opened and edited with ee:

ee /vms/samplevm/scripts/samplevm

4. Search for the bhyve call and adjust the parameters as follows:

bhyve \
-c sockets=1,cores=2,threads=1 \
-m 2G \
-l bootrom,/vms/samplevm/UEFI.fd,/vms/samplevm/EFI_VARS.fd,fwcfg=qemu \
-s 0,hostbridge \
-s 2,fbuf,rfb=0.0.0.0:5900,w=1280,h=1024 \
-s 3,xhci,tablet \
-s 10,nvme,/vms/samplevm/disk0.img \
-s 15,ahci-cd,/vms/samplevm/debian-installer.iso,ro \
-s 20,virtio-net,tap0 \
-s 31,lpc \
-A -H -P -w \
"${vm_name}"

5. Close the editor with ESC and save the changes to the file.

6. The adapted bhyve call references files in the program parameters that are not yet available on the TwinCAT/BSD host. The necessary files are therefore created in the next steps.

7. For the installation of the operating system the Debian "network install" CD-ISO should be used. The ISO file can be downloaded with fetch(8), as described in the chapter Use of installation media (ISO images), and later passed to the bhyve call as a disk of an ahci-hd device:

fetch -o /vms/samplevm/debian-installer.iso https://cdimage.debian.org/mirror/cdimage/archive/12.0.0/amd64/iso-cd/debian-12.0.0-amd64-netinst.iso

8. To install Debian on a virtual hard disk, the following command creates an empty disk image, which is used as a backend for the emulated nvme device in the bhyve call above:

truncate -s 20G /vms/samplevm/disk0.img

9. Debian uses EFI variables to store information about bootable disks. Therefore, a copy of the file /usr/local/share/uefi-firmware/BHYVE_BHF_UEFI_VARS.fd as well as the UEFI firmware itself should be stored in the ZFS dataset directory for the virtual machine:

cp /usr/local/share/uefi-firmware/BHYVE_BHF_UEFI.fd /vms/samplevm/UEFI.fd
cp /usr/local/share/uefi-firmware/BHYVE_BHF_UEFI_VARS.fd /vms/samplevm/EFI_VARS.fd

10. For the Debian installation, the virtual machine requires an Internet connection. For this purpose, a Bridged network is created on the TwinCAT/BSD host as shown in the figure above:

ifconfig bridge create name bridge0
ifconfig tap create name tap0
ifconfig bridge0 addm tap0 addm igb0 up

sysrc cloned_interfaces+="bridge0 tap0"
sysrc ifconfig_bridge0="addm tap0 addm igb0 up"

echo "net.link.bridge.pfil_bridge=0" >> /etc/sysctl.conf
echo "net.link.bridge.pfil_member=0" >> /etc/sysctl.conf
sysctl -f /etc/sysctl.conf

11. All files referenced in the program parameters of the bhyve call adapted above are now available on the TwinCAT/BSD host. Accordingly, the samplevm script can be started in the directory /vms/samplevm/scripts :

cd /vms/samplevm/scripts
sh -x samplevm start

12. The -x flag outputs the executed commands in the script on the command line. As soon as the bhyve(8) process is executed, the following output should appear on the command line:

+ _bhyve_rc=0
+ bhyve -c 'sockets=1,cores=2,threads=1' -m 2G -l 'bootrom,/vms/samplevm/UEFI.fd,/vms/samplevm/EFI_VARS.fd,fwcfg=qemu' -s 0,hostbridge -s '2,fbuf,rfb=0.0.0.0:5900,w=1280,h=1024' -s 3,xhci,tablet -s 10,nvme,/vms/samplevm/disk0.img -s 15,ahci-cd,/vms/samplevm/debian-installer.iso,ro -s 20,virtio-net,tap0 -s 31,lpc -A -H -P -w samplevm

fbuf frame buffer base: 0x12ec16e00000 [sz 16777216]

13. Now a VNC client, such as Ultra-VNC can be used to connect to the virtual machine:
Installing Debian Linux as a guest operating system 2:

14. After a successful connection via a VNC client, the installation menu is displayed. Start the installation of Debian:
Installing Debian Linux as a guest operating system 3:

Installing Debian Linux as a guest operating system 3:

15. Since Debian is to be installed without a graphical desktop, the options "Debian Desktop Environment" and "... Gnome" can be deselected. The "SSH server" option must be selected so that the Debian command line can later be accessed via an SSH client.
Installing Debian Linux as a guest operating system 4:

Installing Debian Linux as a guest operating system 4:

16. As soon as the installation of Debian is complete, the virtual machine is restarted. This will terminate the VNC connection. Once the connection is restored, you can use VNC to run the Debian operating system in the virtual machine.

17. The command ip –-brief address can be used to output the network address of the virtual machine in the network. The network address can be used, for example, to establish an SSH connection with an SSH client for remote access to the Debian operating system.

18. The VM should be shut down for the final steps.
Installing Debian Linux as a guest operating system 5:

19. If a connection to the VM can be established via SSH and the operating system is installed, the bhyve call can be adapted because neither the VNC connection nor the Debian installer are required for the next boot processes:

bhyve \
-c sockets=1,cores=2,threads=1 \
-m 2G \
-l bootrom,/vms/samplevm/UEFI.fd,/vms/samplevm/EFI_VARS.fd,fwcfg=qemu \
-s 0,hostbridge \
-s 10,nvme,/vms/samplevm/disk0.img \
-s 20,virtio-net,tap0 \
-s 31,lpc \
-A -H -P -w \
"${vm_name}"

20. To save the current state of the configuration, a ZFS snapshot of the dataset can be created with the following command. The current state of the autostart scripts, as well as the files for the virtual hard disks and the UEFI of the virtual machine, are backed up and can be restored to the current state:

zfs snapshot zroot/samplevm@os-installed

The VM configuration can be registered as a service via the Makefile. This allows the script to be stored in Autostart and managed via service(8):

cd /vms/samplevm/scripts
make install
service samplevm enable
service samplevm status
service samplevm start
service samplevm status
service samplevm stop