This article describes how to migrate an existing Smart ID Certificate Manager (CM) installation to Podman using Quadlet.

Prerequisites

• Certificate Manager (CM) is installed with version CM > 8.10.x.

  • Earlier CM versions are not supported for migration and must be updated the regular way before a migration can be performed.

• Podman version 4.9.4 or later is installed.

• A valid CM license file

Step-by-step instructions

Deployment directory setup

When deploying using quadlets the name of the directory in which the distributable deployment files are located will be dictated by the user running the container. It will map to the following directory:

$HOME/.config/containers/systemd/.

Load Podman images

The Podman images for CM are located in the images directory within the distributable package.

• Load the images using the following commands:
  podman image load -i images/cf-server-image-<version>.tar 
podman image load -i images/pgw-image-<version>.tar

Perquisition for CF and PGW deployments

• Copy the all the files and folders (*.container, volumes and network) under directory ‘certificate-manager-<Release_version>/deployment/podman-quadlets’ to $HOME/.config/containers/systemd the following location, assuming that the current user is the operator for the container deployment

  • Copy the license file into: $HOME/.config/containers/systemd/license

• If outgoing connectivity from the containers is required, edit the cmnet.network unit file and make sure the parameter Internal=no is set. Additional security hardening may be needed to restrict undesired outgoing connectivity from the container network with firewall rules or by other means.

CF in Podman container

Uninstall existing CF server

• Stop the services and make a backup of the following directories in <server_home> to be utilized later as volumes content for cf-server container:
  <server-home>/bin
  <server-home>/certs
  <server-home>/config

• Backup logs files

• Uninstall the current CF server. See Uninstall Certificate Manager server components and clients for more information.

Migrate CF server configuration

• Follow the commands with standard user (no sudo privilege)

• Start the following cf-server volumes:
  systemctl --user start cf-server-bin-volume
  systemctl --user start cf-server-certs-volume
  systemctl --user start cf-server-config-volume

• Start and stop the cf-service
  systemctl --user start cf-server
  verify starting the service has logged Applying runtime configuration
systemctl --user stop cf-server

• Copy the content of the backed-up folders you performed in step “Uninstall CF server“ to the volumes respectively (this assumes that your current installation is running CF with internal cis):
  cp <server-home-backup>/certs/* $HOME/.local/share/containers/storage/volumes/systemd-cf-server-certs/_data
cp -r <server-home-backup>/config/* $HOME/.local/share/containers/storage/volumes/systemd-cf-server-config/_data
  Note: Override the contents of systemd-cf-server-certs/_data and systemd-cf-server-config/_data

• Verify the database connection details under config volume $HOME/.local/share/containers/storage/volumes/systemd-cf-server-config/_data/cm.conf
  Database.name = jdbc:<db>://<DB_host_name>:<port>/<cmdb-name>

• Change the logging to podman console, edit cm.conf
  $HOME/.local/share/containers/storage/volumes/systemd-cf-server-config/_data/cm.conf
  for example, under Loggers configurations change to cm.agent.log.1.type = stdout
  

Configure HSM with cf-server container

• Copy HSM driver and config files to $HOME/.local/share/containers/storage/volumes/systemd-cf-server-bin/_data
  example Utimaco files (not limited to): libcs_pkcs11_R3.so cs_pkcs11_R3.cfg

• Provide the required environment variables via $HOME.config/containers/systemd/cf-server.container
  example of Utimaco driver configuration: Environment="CS_PKCS11_R3_CFG=/opt/cm/server/bin/cs_pkcs11_R3.cfg"

• Note: verify the connectivity details in HSM driver configuration file.

Start CF server container

• Start the CF server container using the following command:
  systemctl --user start cf-server

• Make sure cf-server is started and is logging:
  systemctl --user start cf-server; podman logs -f cf-server

PGW in Podman container

Uninstall existing PGW

• Make a backup of the following directories in <pgw_home>to be utilized later as volumes content for pgw container:
  Tomcat configuration which contains the TLS and server.xml: <tomcat_home>/conf
  PGW configuration which contains the conf and certdir: <pgw_home)/conf

• Uninstall Tomcat instance and remove Protocol Gateway (PGW) folders and files.

Migrate PGW configuration

• Start the following pgw volumes:
  systemctl --user start pgw-config-tomcat-volume
  systemctl --user start pgw-config-gw-volume

• Start and stop the pgw container
  systemctl --user start pgw
  verify that PGW service started successfully
  systemctl --user stop pgw

• Copy the content of the backed-up folders you performed in step “Uninstall PGW“

  • Note: exclude all logging.properties while coping required files into the volumes, override the contents of systemd-pgw-config-tomcat/_data and systemd-pgw-config-gw/_data.
    cp <tomcat-installation>/conf/<file> $HOME/.local/share/containers/storage/volumes/systemd-pgw-config-tomcat/_data
cp -r <cm-gateway>/conf/<file_dir> $HOME/.local/share/containers/storage/volumes/systemd-pgw-config-gw/_data

• Verify the connectivity details toward cf-server container is correct in: $HOME/.local/share/containers/storage/volumes/systemd-pgw-config-gw/_data/cm-gateway.properties
cmhost=<cf-server-host>, example cmhost=cf-server

Start PGW container

• Start the PGW container using the following command:
  systemctl --user start pgw

• Make sure PGW is running
  systemctl --user status pgw; podman logs pgw

Enable PGW container health check

• Follow the instructions in Enabling health check.

Configure HSM with PGW container

Configuring HSM with PGW can be performed in a manner similar to the approach outlined in CM-HSM setup

Recommendations

• Configuration files and libraries/addons (such as HSM) can be added as volumes to the containers.

• Removing volumes can lead to losing data and configurations. Therefor, we recommend keeping updated backup of the configuration.

• It is not recommended to run the database on the same machine of cf-server container, due to network issues.