Installation on Red Hat OpenShift Virtualization and QEMU-KVM

1.0 Introduction

This article describes the steps to install Fortanix Data Security Manager (DSM) Red Hat OpenShift Virtualization and QEMU-KVM (Kernel-based Virtual Machine) using a QCOW2 (QEMU Copy-On-Write version 2) disk image.

2.0 Install Fortanix DSM on Red Hat OpenShift Virtualization

This section describes how to install Fortanix DSM on Red Hat OpenShift Virtualization using the QCOW2 image.

2.1 Prerequisites

Ensure the following:

Red Hat OpenShift Virtualization is configured and accessible.
virtctl CLI tool is installed on the client host.
The virt-viewer package is installed on the client host.
```
sudo apt install virt-viewer -y
```
NOTE
The client host is a Linux system with network access to the OpenShift cluster and the required CLI tools installed.
Minimum virtual machine requirements:
- CPU: 8 cores
- Memory: 32 GB RAM
- Storage: 512 GiB (persistent volume)
- Operating system: 64-bit Linux (Ubuntu)

2.2 Downloading the QCOW2 Image

Run the following command to download the Fortanix DSM QCOW2 image. Refer to Section 5.0: Support for the Fortanix DSM QCOW2 Installer Object URL.

wget <DSM Installer Object URL>

The QCOW2 artifact size is approximately 16 GB. The download time depends on the network speed.

2.3 Uploading the QCOW2 Image to OpenShift Virtualization

2.3.1 Authenticating to the OpenShift Cluster

Run the following command on the client host to authenticate to the OpenShift cluster:

oc login --token=<token> --server=<server-url>

To obtain the login command and token, navigate to the OpenShift web console, click your username in the top-right corner, and select Copy login command.

**Figure 1: Copy login command from the OpenShift web console**

2.3.2 Uploading the QCOW2 Image

Run the following command to upload the QCOW2 image to OpenShift Virtualization as a DataVolume (DV):

virtctl image-upload dv <dv-name> \
  --size=512Gi \
  --image-path=<qcow2-image-filename> \
  --access-mode=ReadWriteOnce \
  --insecure \
  --force-bind

Where,

<dv-name>: The name for the DV.
<qcow2-image-filename>: The filename of the downloaded QCOW2 image.

NOTE
The artifact size is approximately 16 GB and the upload may take a significant amount of time. The upload is complete when the following output is displayed:
Uploading data completed successfully, waiting for processing to complete, you can hit ctrl-c without interrupting the progress
Processing completed successfully
Uploading <qcow2-image-filename> completed successfully

2.3.3 Verifying the Persistent Volume Claim

After the upload is complete, OpenShift Virtualization creates a Persistent Volume Claim (PVC). Navigate to Storage → PersistentVolumeClaims in the OpenShift web console and verify that the PVC is in the Bound state.

**Figure 3: Create a virtual machine using YAML**

2.4 Creating the Virtual Machine

Perform the following steps to create a virtual machine from the uploaded QCOW2 image:

In the OpenShift web console, navigate to Virtualization → VirtualMachines.
Click Create and select With YAML.
Figure 4: Virtual machine YAML configuration

Paste the virtual machine YAML configuration provided by Fortanix.

fortanix-dsm-installation-on-red-hat-openshift-virtualization

1.59 KB

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  annotations:
    description: VM <any name>
  labels:
    os.template.kubevirt.io/ubuntu24.04: 'true'
    app: <any name>
  name: <any name>
spec:
  runStrategy: Halted
  template:
    metadata:
      annotations:
        vm.kubevirt.io/flavor: small
        vm.kubevirt.io/os: ubuntu24.04
        vm.kubevirt.io/workload: server
      labels:
        kubevirt.io/domain: <any name>
        kubevirt.io/size: small
    spec:
      domain:
        cpu:
          cores: 1
          sockets: 8
          threads: 1
        devices:
          disks:
            - disk:
                bus: virtio
              name: rootdisk
            - disk:
                bus: virtio
              name: cloudinitdisk
          interfaces:
            - masquerade: {}
              model: virtio
              name: default
          networkInterfaceMultiqueue: true
          rng: {}
        memory:
          guest: 32Gi
      hostname: <any name>
      networks:
        - name: default
          pod: {}
      terminationGracePeriodSeconds: 180
      volumes:
        - name: rootdisk
          persistentVolumeClaim:
            claimName: <package name>
        - name: cloudinitdisk
          cloudInitNoCloud:
            userData: |
              #cloud-config
              ssh_authorized_keys:
                - "<public keys>"
              users:
                - name: administrator
                  ssh_authorized_keys:
                    - "<public keys>"
                  sudo: ALL=(ALL) NOPASSWD:ALL

Replace the following placeholders in the YAML:

<public-key>: The SSH public key used to access the VM.
<vm-name>: The name you want to assign to the VM.
<dv-name>: The DV name used in Section 2.3.2: Uploading the QCOW2 Image.

Click Create to create the virtual machine.
Once the VM is created, locate it in the VirtualMachines list and click Start to power it on.

2.5 Connecting to the Virtual Machine

After the virtual machine is created and started, connect to the VM using VNC. Configure the VM network to obtain a private IP address and then connect to the VM using SSH.

2.5.1 Connecting Using VNC

Run the following command from the client host to open a VNC console connection to the VM:

virtctl vnc <vm-name> -n <namespace>

Where,

<vm-name>: The name of the VM created in Section 2.4: Creating the Virtual Machine.
<namespace>: The OpenShift namespace where the VM is running.

The VNC viewer opens the Fortanix DSM VM.

2.5.2 Connecting Using SSH

After the network is configured and the VM has an assigned IP address, run the following command to connect to the DSM node using SSH:

virtctl -n <namespace> ssh administrator@vm/<vm-name>

Where,

<namespace>: The OpenShift namespace where the VM is running.
<vm-name>: The name of the VM created in Section 2.4: Creating the Virtual Machine.

2.6 Configuring the Network

The QCOW2 image is pre-configured with the administrator user. However, the /etc/network/interfaces file does not include a Dynamic Host Configuration Protocol (DHCP) configuration, which prevents OpenShift from assigning a private IP address to the VM automatically.

Perform the following steps to configure the network:

Connect to the VM console using VNC. Refer to Section 2.5.1: Connecting Using VNC.
Edit the /etc/network/interfaces file to add DHCP configuration for the network interface:
```
auto <network-interface>
iface <network-interface> inet dhcp
```
Where, <network-interface> is the name of the network interface configured for the VM.
For example:
```
auto enp1s0
iface enp1s0 inet dhcp
```
Run the following command to restart the networking service:
```
sudo systemctl restart networking
```
After the networking service restarts, the VM receives a private IP address from OpenShift. For example, 10.0.2.2.

2.7 Installing Fortanix DSM

After connecting to the VM, perform the following steps:

Log in to one of the DSM nodes using the credentials and IP address obtained in Section 2.5: Connecting to the Virtual Machine. This node will be used to create the Fortanix DSM cluster.
Configure the deployment-specific configuration file during Fortanix DSM installation. For detailed instructions, refer to the Fortanix DSM Installation Guide - On-Prem.
Join the other nodes to the cluster. For detailed instructions, refer to Fortanix DSM Installation Guide – On-Prem.
Install and sign the certificate. For detailed instructions, refer to the Fortanix DSM Installation Guide – On-Prem.

NOTE
The QCOW2 image includes a fresh installation of Fortanix DSM. No cleanup or software reinstallation is required.

3.0 Install Fortanix DSM on QEMU-KVM

This section describes how to install Fortanix DSM on a QEMU-KVM hypervisor using the QCOW2 image.

NOTE
QEMU-KVM uses the same Fortanix DSM QCOW2 image provided for Red Hat OpenShift Virtualization. No separate QEMU-KVM image is provided. Configure the QCOW2 image to use DHCP before creating the VM, as described in Section 3.2: Configuring the QCOW2 Image to Use DHCP.

3.1 Prerequisites

Ensure that the following requirements are met:

QEMU-KVM is installed on the host node.
The libvirtd service is running on the host node.
The QCOW2 image is downloaded on the host node.

3.2 Configuring the QCOW2 Image to Use DHCP

The Fortanix DSM QCOW2 image uses a static IP configuration by default. When using the image with QEMU-KVM, configure the network interface to use Dynamic Host Configuration Protocol (DHCP) so that the VM can obtain an IP address from the QEMU-KVM default network.

Run the following command on the QEMU-KVM host:

sudo virt-customize -a <path-to-qcow2-image> \
  --install ifupdown \
  --write /etc/network/interfaces:"auto lo
iface lo inet loopback
auto enp1s0
iface enp1s0 inet dhcp" \
  --run-command "systemctl disable netplan-ovs-cleanup systemd-networkd 2>/dev/null || true" \
  --run-command "systemctl enable serial-getty@ttyS0.service || true"

Where, <path-to-qcow2-image> is the path to the Fortanix DSM QCOW2 image.

This configures the enp1s0 network interface to obtain an IP address using DHCP.

3.3 Creating the Virtual Machine

Perform the following steps to create a virtual machine using the QCOW2 image:

Run the following command on the host node to create the virtual machine:

sudo virt-install \
--name <vm-name> \
--vcpus 8 \
--ram 32768 \
--os-variant ubuntu24.04 \
--disk path=<qcow2-image-filename>,bus=virtio,format=qcow2 \
--import \
--network default,model=virtio \
--graphics vnc,listen=0.0.0.0,port=5900 \
--noautoconsole

Where,

<vm-name>: The name of the virtual machine.
<qcow2-image-filename>: The full path to the downloaded QCOW2 image.

After the virtual machine is created, run the following command to verify the IP address assigned to the virtual machine:

sudo virsh net-dhcp-leases default

The command displays the DHCP lease information, including the IP address assigned to the virtual machine.

Example output:

Expiry Time           MAC address         Protocol   IP address          Hostname     Client ID or DUID
-------------------------------------------------------------------------------------------------------------------------------------------------
 2026-09-01 14:19:36   52:54:00:3a:dd:5f   ipv4       192.168.122.58/24   dsm-server   ff:00:3a:dd:5f:00:01:00:01:32:29:83:81:52:54:00:3a:dd:5f

3.4 Accessing the VM from the Host Node

After the virtual machine is created and an IP address is assigned, you can access the virtual machine from the host node using SSH.

Run the following command to connect to the virtual machine:

ssh administrator@<vm-ip>

Where, <vm-ip> is the IP address assigned to the virtual machine. You can obtain the VM IP address using the command described in Step 2 in Section 3.3: Creating the Virtual Machine.

For example:

root@dsm-lab-56:/home/administrator# ssh administrator@192.168.122.141
The authenticity of host '192.168.122.141 (192.168.122.141)' can't be established.
ED25519 key fingerprint is SHA256:89wGoFnaSuZbohwRb2eztWTV2xn5cH/2PSYsGG0M+Lc.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '192.168.122.141' (ED25519) to the list of known hosts.
administrator@192.168.122.141's password:
Welcome to Ubuntu 24.04.4 LTS

3.5 Accessing the VM from Outside the Host Node

To access the virtual machine from a system outside the host node using the host node’s IP address, configure port forwarding on the host node.

The following example uses iptables to forward traffic to the virtual machine.

Run the following commands on the host node to configure port forwarding from the host node to the VM:

sudo iptables -t nat -A PREROUTING -i <host-interface> -p tcp --dport 2222 -j DNAT --to-destination <vm-ip>:22
sudo iptables -t nat -A PREROUTING -i <host-interface> -p tcp --dport 443 -j DNAT --to-destination <vm-ip>:443
sudo iptables -t nat -A PREROUTING -i <host-interface> -p tcp --dport 4445 -j DNAT --to-destination <vm-ip>:4445
sudo iptables -I FORWARD 1 -i <host-interface> -o virbr0 -d <vm-ip> -j ACCEPT
sudo iptables -I FORWARD 2 -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -t nat -A POSTROUTING -s 192.168.122.0/24 ! -d 192.168.122.0/24 -j MASQUERADE

Where,

<host-interface>: The network interface of the host node.
<vm-ip>: The IP address assigned to the virtual machine.

From the external system, run the following command to connect to the virtual machine through the host node:
```
ssh -p 2222 administrator@<host-node-ip>
```
Where, <host-node-ip> is the IP address of the QEMU-KVM host node on which the VM is running.

After a successful SSH connection, the VM command prompt is displayed.

For example:

Welcome to Ubuntu 24.04.4 LTS
(GNU/Linux 6.8.0-136-1.0-fortanix-legacy-appliance x86_64)
System information as of Tue Sep 1 01:25:11 PM UTC 2026
System load:  1.09
Processes:    324
Usage of /:   12.0% of 125.43GB
Users logged in: 1
Memory usage: 40%
IPv4 address for enp1s0: 192.168.122.58
Swap usage:   0%

3.6 Installing Fortanix DSM

Perform the following steps:

After connecting to the VM using SSH, modify the network configuration according to your environment, if required.
```
sudo nano /etc/network/interfaces
```
After modifying the network configuration, restart the networking service:
```
sudo systemctl restart networking
```
Configure the deployment-specific configuration file during Fortanix DSM installation. For detailed instructions, refer to the Fortanix DSM Installation Guide - On-Premises.
Run get_csrs to generate the certificate signing requests.
Run install_certs to install the certificates.
On the client system, add the following entry to the /etc/hosts file:
```
<host-node-ip> <domain-name-used-in-get_csrs>
```
Where,
- <host-node-ip>: The IP address of the QEMU-KVM host node.
- <domain-name-used-in-get_csrs>: The domain name configured when running get_csrs.

Access the Fortanix DSM dashboard using the domain name configured in the /etc/hosts file.

4.0 Backup and Restore Fortanix DSM

The backup and restore process for Fortanix DSM software deployments is similar to that for hardware-based deployments. The deployment key is generated and stored as a Kubernetes Secret and is not included in the Fortanix DSM backup for security reasons.

The deployment key is required to restore a Fortanix DSM backup after the cluster is reset or recreated. Therefore, export the deployment key and store it in a secure location before performing a backup. For information about configuring DSM backup and restore, refer to Fortanix DSM - Backup and Restore - Manual.

NOTE
The backup cannot be restored without the deployment key. Ensure that the exported deployment key is securely stored and available during the restoration process.

4.1 Exporting the Deployment Key

Before performing a backup, run the following command on a cluster node to export the deployment key to a YAML file:

kubectl get secrets sdkms-deployment-key-store -o yaml > sdkms-deployment-key-store.yaml

Save the sdkms-deployment-key-store.yaml file in a secure location. Do not store it with the backup.

4.2 Restoring the Deployment Key

When a new cluster is created, a new deployment key is automatically created. However, when restoring a cluster from a backup, the existing deployment key must be deleted, and the previously exported deployment key must be restored.

Ensure that the previously exported deployment key file is available before deleting the existing deployment key.

Perform the following steps:

Run the following command to delete the existing deployment key, which was created along with a fresh cluster:
```
kubectl delete secrets sdkms-deployment-key-store
```
Run the following command to restore the previously exported deployment key:
```
kubectl create -f sdkms-deployment-key-store.yaml
```

After completing these steps, start the restore process as described in the Fortanix DSM Restoration Guide - Automated.

5.0 Support

For production deployment of Fortanix DSM on Red Hat OpenShift Virtualization, download the QCOW2 image from the Fortanix Support Portal Downloads.