Deploying AIMS in KVM

This topic explains how to deploy the AI Media Server (AIMS) software in KVM using an OVA image file.

KVM deployments are currently tech preview. Please contact your Pexip authorized support representative for more information.

For information regarding manual customization or maintenance tasks such as re-running the installation wizard or replacing the AIMS's default certificate, see Configuration and maintenance of the AI Media Server.

Prerequisites

Pexip Infinity

AIMS requires Pexip Infinity v36 or later. See Pexip Infinity versions for information about which versions of Pexip Infinity are required to support the features available in each version of AIMS.

NVIDIA GPU

The AIMS VM requires complete control of all GPUs assigned to it — the GPUs cannot be shared with any other VM.

The following NVIDIA GPU models are supported:

  • NVIDIA L4
  • NVIDIA A100 40GB SXM4 *
  • NVIDIA H100 80GB HBM3 *

* See notes in Resilience / redundancy / scaling

If you are unsure about compatibility with a given GPU, please contact your Pexip authorized support representative.

Host hardware requirements

For on-premises deployments, host hardware must meet the following minimum specifications for each card:

GPU CPU RAM Storage
L4 8 cores 32 GB 75 GB SSD (200 GB recommended)
A100 12 cores 32 GB 75 GB SSD (200 GB recommended)
H100 24 cores 64 GB 75 GB SSD (200 GB recommended)

These requirements may change in future versions.

For all other on-premises deployments, please contact your Pexip authorized support representative for guidance.

KVM versions

AIMS supports the following KVM versions:

  • Linux: 5.15.0 or later
  • QEMU: 6.2.0 or later

Firewall and DNS requirements

You must configure DNS for your deployment as follows:

  • There must be a DNS A record for the AIMS server.
  • The AIMS server must have a DNS name that is resolvable by Conferencing Nodes.
  • On Pexip Infinity, you must enter the AIMS server's host address (as per the DNS record) as the Live captions service API gateway (under Platform > Global settings > Live captions).

When requesting/generating certificates for your AIMS server:

  • The AIMS server requires TLS certificates with SHA256 or later signature algorithms. Certificates using legacy algorithms such as SHA1 and MD5 are not supported.
  • The AIMS server must have a certificate with either a CN or SAN that matches the AIMS server's host address (as per the DNS record), and this certificate must be trusted by Pexip Infinity.
  • We recommend using a 4096 bit public key (2048 bit minimum).

The following table lists the ports/protocols used to carry traffic between the AIMS server and Conferencing Nodes, DNS servers and NTP servers:

Source address Source port Destination address Destination port Protocol Notes
AIMS 123, 55000–65535 NTP server 123 UDP Required for correct log timestamps.
AIMS 55000–65535 DNS server 53 TCP/UDP Required to resolve NTP and other addresses.
Conferencing Node <any> AIMS 443 TCP (HTTPS)

Access live captions service.

Web proxies are not supported for this traffic flow.

Installing AIMS in KVM

Installing the AIMS Virtual Machine (VM) on the host hardware involves the following steps:

Download the AIMS .ova image and convert it for use with KVM

You must download the AIMS OVA image file and then, to use it with KVM, you must convert it from VMDK to raw format.

From within your KVM environment:

  1. Download the latest version of the AIMS OVA template from https://dl.pexip.com/aims/index.html.

  2. Unpack the .ova image, using the command:

    tar xf aims-<build>.ova

    This unpacks a set of files including aims-disk01.vmdk.

  3. If required, you can verify the aims.mf manifest file, using the command:

    sha256sum -c aims.mf

  4. Convert the disk image from VMDK to raw, using the command:

    qemu-img convert -O raw aims-disk01.vmdk aims-disk01.raw

    (This conversion process can take several seconds.)

Create a new volume and upload the disk image

Next, you create a new volume on your KVM server and upload the converted disk image. From within your KVM environment:

  1. Use virsh to create a new volume on your KVM server:

    virsh vol-create-as <poolname> <volume_name> 200G --format raw

    where:

    • <poolname> is the name of the storage pool in which to create the volume; typically you would use default. (To determine the storage pools available on the target system, use virsh pool-list.)
    • <volume_name> is the name of your new volume.
    • 200G is the virtual size of the volume; for AIMS we recommend a disk size of 200 GB as a starting point but the minimum disk size required depends on which models you wish to install.

    For example:

    virsh vol-create-as default aims-01 200G --format raw

    This example creates a volume named aims-01 of size 200 GB and format raw in the storage pool named default.

  2. Upload the converted disk image to the newly created volume:

    virsh vol-upload <volume_name> pexip-disk01.raw --pool <poolname>

    For example:

    virsh vol-upload aims-01 pexip-disk01.raw --pool default

    This example uploads the pexip-disk01.raw image to the newly created volume, aims-01, in the storage pool named default.

Create the virtual machine

After the disk image has been uploaded, you can create the virtual machine to use it.

Note that we use the libvirt command line tools to perform the import as they provide greater control than Virtual Machine Manager.

  1. Identify the filesystem path of the newly uploaded disk image:

    virsh vol-path <volume_name> --pool <poolname>

    For example:

    virsh vol-path aims-01 --pool default

    This prints out the absolute path to the disk image file, for example:

    /var/lib/libvirt/images/aims-01

    This path is used in the disk path parameter in the virt-install command below.

  2. Ensure that the GPU is available to be passed through on the host machine.

    These commands are for generic Debian-based systems.

    Use lspci -nn to determine the PCI bus ID of the card.

    For example, for a specific L4 device this could return:

    0b:00.0 3D controller [0302]: NVIDIA Corporation AD104GL [L4] [10de:27b8] (rev a1)

    where the PCI bus ID is 0b:00.0 (and the PCI ID is 10de:27b8).

    This PCI bus ID is used in the hostdev parameter in the virt-install command below.

  3. Use the virt-install command line tool to create the virtual machine:

    virt-install \
  --import \
  --hvm \
  --name=<vm_name> \
  --arch=x86_64 \
  --vcpus=8 \
  --ram=32768 \
  --cpu host \
  --osinfo=linux2024 \
  --connect=qemu://<hostname>/system \
  --virt-type kvm \
  --disk path=<image_file_path>,bus=virtio,format=raw,cache=none,io=native \
  --network bridge=br0,model=virtio \
  --graphics vnc,listen=0.0.0.0,password=<password>
  --hostdev <pci_bus_id>

    This creates a new VM (KVM domain) from the converted disk image.

    The command options are described below (items in bold may be changed as necessary):

    Option Description
    --import Build guest domain around pre-installed disk image; do not attempt to install a new OS.
    --hvm Create a fully virtualized (i.e. not paravirtualized) VM.
    --name=<vm_name> Name of the new VM, where <vm_name> is, for example, aims-01-vm.
    --arch=x86_64 CPU architecture of new VM (must be x84_64).
    --vcpus=8 Number of CPUs allocated to new VM. This should be at least 8 for AIMS.
    --ram=32768 Memory allocated to new VM (in megabytes).
    --cpu host Expose all host CPU capabilities to new VM (CPUID).
    --osinfo=linux2024

    The guest OS is Linux. Valid year values are 2018 or later.

    For older osinfo databases, you may need to use
    --osinfo=$(virt-install --osinfo list | grep '^linux' | sort -r | head -n 1)
    --connect=qemu://<hostname>/system Connect to KVM on the target system, where <hostname> is the hostname of your KVM server.
    --virt-type kvm Use KVM to host the new VM.
    --disk path=<image_file_path>,
    bus=virtio,format=raw,cache=none,io=native
    • Define the location of the disk image file, where <image_file_path> is as determined in the previous step, for example /var/lib/libvirt/images/aims-01.
    • Expose it to the guest on the virtio paravirtualized bus (as opposed to IDE/SCSI).
    • Define the image file as being in raw format.
    • Instruct the host system not to cache the disk contents in memory.
    • Use the native IO backend to access the disk device.
    --network bridge=br0,model=virtio
    • Create a network interface connected to the br0 bridge interface on the host.
    • Expose it to the guest as a virtio paravirtualized NIC.
    --graphics vnc,listen=0.0.0.0,
    password=<password>    		 Expose the graphical console over VNC, listening on 0.0.0.0 (i.e. all addresses on the target system) and with an access password of <password>.
    --hostdev <pci_bus_id> Attach the physical GPU with this ID on the host, to the new guest VM.

    You may receive a warning "Unable to connect to graphical console: virt-viewer not installed"; if so, this message can be safely ignored.

    After the VM has been created, it may be managed using the Virtual Machine Manager desktop interface (virt-manager application) or via the command line interface (virsh).

    The new node should start automatically. If it does not you can use the Virtual Machine Manager to start the node, or the CLI command:

    virsh start <vm_name>

    Note that you can list existing VMs by using:

    virsh list

NUMA pinning

Our guidance provided here for NUMA pinning with AIMS assumes you have a single GPU or multiple GPUs all on the same NUMA domain. If you have multiple GPUs on different NUMA domains then please contact your Pexip authorized support representative for guidance.

You can follow our general KVM and NUMA guidance provided in KVM NUMA affinity and hyperthreading. That guidance is directed at Pexip Infinity Conferencing Nodes but the same principles apply to your AIMS VM with the following additional guidelines:

  • You must NUMA pin your AIMS instance to the same NUMA domain that your GPU(s) are attached to.
  • If you only have a single NUMA domain then no further action is required.

To check the NUMA domain of the GPU, use the PCI bus ID obtained previously, and on the host run:

cat /sys/bus/pci/devices/<pci_bus_id>/numa_node

If this returns -1, there is only a single NUMA domain, so you do not need to do anything further.

If this returns 0 or 1, you should NUMA pin your AIMS VM to that NUMA domain.

Enabling automatic startup

After deploying a new AIMS server in KVM, you should enable automatic startup of that virtual machine (VM). In KVM, automatic startup is disabled by default for every new VM. This means that if the host server is powered down for any reason, when it restarts the VM will not restart and must be started manually.

You can only enable automatic startup after the AIMS server has been deployed.

To enable automatic startup using Virtual Machine Manager:

  1. Connect to the Virtual Machine Manager (virt-manager) that is managing the node's VM.

  2. Select the node's VM and then, from the toolbar, select the Show the virtual machine console and details icon .

    A new window for that VM is opened.

  3. If necessary, select View > Details to display the VM information.
  4. From the sidebar menu, select Boot Options.
  5. Select the Start virtual machine on host boot up check box.
  6. Select Apply.

Running the installation wizard

To run the installation wizard, which configures the AIMS server, you must open a console window on the AIMS VM.

Opening a console window

  1. Connect to Virtual Machine Manager (virt-manager) that is managing the AIMS VM.
  2. Ensure that the AIMS VM is Running.

  3. Select the new AIMS VM and then, from the toolbar, select the Show the virtual machine console and details icon .

    A new window for that VM is opened.

  4. If necessary, select View > Console to display the console.

Completing the installation wizard

Follow the prompts to set the following configuration for the AIMS VM.

If you subsequently rerun the installation wizard, the default values for the questions use the answers from the previous run (if they are still valid).

If you select Enter, the default value is applied:

Setting Default value Multiple entries allowed?
IP address As assigned by DHCP, otherwise 192.168.0.100 * No
Network mask As assigned by DHCP, otherwise 255.255.255.0 * No
Gateway As assigned by DHCP, otherwise 192.168.0.1 * No
Hostname As assigned by DHCP, otherwise pexaims No
Domain suffix As assigned by DHCP, otherwise <no default> No
DNS servers As assigned by DHCP, otherwise 8.8.8.8 Yes, if separated by a space or comma
NTP servers†

As assigned by DHCP, otherwise:

  • 0.pexip.pool.ntp.org
  • 1.pexip.pool.ntp.org
 Yes, if separated by a space or comma
Enable incident reporting (yes/no) <no default>  
Contact email address ** <no default> No
Send deployment and usage statistics to Pexip (yes/no) <no default>  

* The addresses entered here are assigned as static IP addresses. When deploying in a cloud service, these values are replaced with the IP address and network settings for your instance.

** Shown and required if incident reporting is enabled.

† The NTP server must be accessible by the AIMS server at the time the startup wizard is run. Installation will fail if the AIMS server is unable to synchronize its time with an NTP server.

When all of the installation wizard steps have been completed, the AIMS VM will automatically reboot.

Next steps