Skip to main content
Welcome to Virtru's support portal. As we work to make this page more accessible to screen readers, please contact us at support@virtru.com for technical support.

Virtru Private Keystore (VPK): Upgrading on RHEL 8 / Podman

  • Updated

Overview

This guide walks you through upgrading the Virtru Private Keystore (VPK) container on Red Hat Enterprise Linux 8 (RHEL 8) using Podman. It covers the complete upgrade process and addresses two platform-specific requirements that must be met for the v2.x image to run correctly in this environment.

Before you begin: If you are upgrading from v1.x, back up your key material before proceeding. There is no automated rollback path from v2.x to v1.x.

 

Prerequisites

Before starting the upgrade, confirm the following are in place:

  • Root or sudo access to the RHEL 8 host
  • Existing VPK running in CKS-only mode
  • Key material present at /var/virtru/cks/keys/
  • SSL certificates present at /var/virtru/cks/ssl/
  • Environment file present at /var/virtru/cks/env/cks.env
  • Network access to pull images from containers.virtru.com
  • SELinux mode confirmed — run getenforce and verify the output is Enforcing

Upgrade Steps

Step 1 — Apply the Kernel Setting on the Host

This setting must be applied before starting the v2.x container. It allows Caddy's HTTP listener to bind to port 80 on the host.

Apply the setting for the current session:

sysctl -w net.ipv4.ip_unprivileged_port_start=80

Make the setting persistent across reboots:

echo "net.ipv4.ip_unprivileged_port_start=80" >> /etc/sysctl.conf

Verify the setting is active:

sysctl net.ipv4.ip_unprivileged_port_start

Expected output: net.ipv4.ip_unprivileged_port_start = 80

Important: If this setting is not active when the container starts, Caddy will crash-loop. If that happens, stop the container, apply the setting, verify it, and restart.

 

Step 2 — Set Correct File Permissions

Ensure your key material and SSL certificates are readable after SELinux relabeling:

chmod 644 /var/virtru/cks/keys/rsa*
chmod 644 /var/virtru/cks/ssl/*

 

Step 3 — Pull the New Image

Pull the target version from the Virtru container registry:

podman pull containers.virtru.com/cks:v2.4.0

Verify the image was pulled successfully:

podman images | grep cks

Step 4 — Stop and Remove the Existing Container

podman stop Virtru_CKS && podman rm Virtru_CKS

Step 5 — Update Your Run Command and Start the Container

Update your run.sh or systemd service file to use the following command exactly. Pay close attention to the -v mount syntax and the addition of -p 80:80.

podman run --name Virtru_CKS \
  --interactive --tty --detach \
  --restart unless-stopped \
  --env-file /var/virtru/cks/env/cks.env \
  -p 443:9000 \
  -p 80:80 \
  -v /var/virtru/cks/keys:/app/keys:Z \
  -v /var/virtru/cks/ssl:/app/ssl:Z \
  containers.virtru.com/cks:v2.4.0

Key changes from v1.x run commands:

  • Image tag updated to v2.4.0 (or your target v2.x version)
  • -p 80:80 added to expose the HTTP redirect port required by Caddy
  • Bind mounts changed from --mount syntax to -v syntax with :Z for SELinux compatibility

If you are using a systemd service file, apply the same changes to the ExecStart line, then run:

systemctl daemon-reload
systemctl restart Virtru_CKS

Step 6 — Verify Startup in the Container Logs

podman logs -f Virtru_CKS

All four of the following lines should appear in the log output, confirming a healthy startup:

"success to start program  program=caddy"

"success to start program  program=cks"

"The organization keys refreshing procedure completed"

"listening on port 3000"

If Caddy is still failing with the port 80 bind error, confirm the kernel setting from Step 1 is active (sysctl net.ipv4.ip_unprivileged_port_start), stop the container, re-apply the setting, and restart.

Support

If you encounter an issue not covered by this guide, contact your Virtru Solutions Architect or open a support ticket at support.virtru.com.

When submitting a ticket, please include:

  • Output of podman logs Virtru_CKS (last 100 lines minimum)
  • Output of getenforce
  • Output of sysctl net.ipv4.ip_unprivileged_port_start
  • Your current run command or systemd unit file (redact any secrets)

Related articles