Use shell scripts

Virtual machines can be easily started and managed using shell scripts. Scripted VM applications allow configurations to be saved persistently and reused after a restart. In combination with further instructions and shell scripts, any VM applications can be set up under TwinCAT/BSD.

The following sample script shows the basic structure of a scripted VM application:

# root permissions are required to run VMs
if test "$(id -u)" -ne 0; then
    printf "%s must be run as root\n" "${0##*/}"
    exit 1
fi

# Default values for VM configuration
vm_name="samplevm"

# Ensure that kernel modul vmm.ko is loaded
kldload -n vmm.ko

while true; do
    # destroy former VM instance to ensure we start
    # with a clean VM configuration
    if test -e "/dev/vmm/${vm_name}"; then
        bhyvectl --vm="${vm_name}" --destroy
    fi

    # start a simple UEFI based VM instance
    _bhyve_rc=0
    bhyve \
        -A -H -P \
        -c sockets=1,cores=1,threads=1 \
        -m 1G \
        -s 0:0,hostbridge \
        -l bootrom,/usr/local/share/uefi-firmware/BHYVE_BHF_UEFI.fd \
        -l com1,stdio \
        -s 31:0,lpc \
        "${vm_name}"
        _bhyve_rc=$?

    # according to bhyve man pages the return codes indicates
    # how the VM was terminated:
    # 0: rebooted
    # 1: powered off
    # ...
    # 4: exited due to an error
    if test "${_bhyve_rc}" -ne 0; then
        printf "bhyve exited with return code: %s\n" "${_bhyve_rc}"
        break
    fi
    printf "Restarting %s\n" "${vm_name}"

done

The sample script can be saved to a text file on the TwinCAT/BSD host and executed. Alternatively, the sample script can be downloaded from GitHub repository at https://github.com/Beckhoff/TCBSD_Hypervisor_Samples and copied to the TwinCAT/BSD host.

Proceed as follows:

1. Download the sample script at https://github.com/Beckhoff/TCBSD_Hypervisor_Samples.
2. Copy the entire folder on the TwinCAT/BSD host to the directory /home/Administrator by using the WinSCP program, for example.
Use shell scripts 1:
3. Alternatively, you can use the following command to load and unpack the sample script directly under TwinCAT/BSD:
fetch -o /home/Administrator/main.zip \
https://github.com/Beckhoff/TCBSD_Hypervisor_Samples/archive/refs/heads/main.zip \
&& unzip -d /home/Administrator main.zip
4. Navigate to the new directory with cd /home/Administrator/TCBSD_Hypervisor_Samples-main/basic_vm_script.
5. Enter the command doas make to install the sample script samplevm. In addition to the installation, the file permissions are set, making the sample script executable. Without the doas make command, file permissions must be set manually to run the sample script.
6. Finally, enter the command doas samplevm to run the sample script.
The virtual machine boots into the UEFI shell, which is output to the command line.
UEFI Interactive Shell v2.2
EDK II
UEFI v2.70 (BHYVE, 0x00010000)
map: No mapping found.
Press ESC in 1 seconds to skip startup.nsh or any other key to continue.
Shell>

You can return to the command line by shutting down the virtual machine with the reset -s command. To start virtual machines as a system service under TwinCAT/BSD, shell scripts can be used in combination with the rc framework and thus virtual machines can be managed as a system service or started automatically at system startup (see: Autostart shell scripts).