Deployment using Quadlets

This article applies for CM version 8.10.x and later versions.

This article describes how to install Smart ID Certificate Manager (CM) server components using quadlets.

Prerequisites

A supported database server must be installed/available
License file must be available
Podman version 4.9.4 or later
Administrator's Workbench, Registration Authority, and Certificate Controller clients from CM distributable package.

CM and PGW installation steps

CM image archive files

The Podman images of Certificate Manager are stored in the images directory under the distributable. These image files may be uploaded to a local private container registry with controlled and limited access, but shall not be distributed to any public container registry.

For local use, the images can be read with below commands:

CODE

podman image load --input images/cf-server-image-<version>.tar
podman image load --input images/pgw-image-<version>.tar

CM license file

Create a license directory in the cm deployment directory and place the CM license files inside it. In this article, the license directory will be mounted as
a read-only bind file system volume for the cf-server container, which runs the certificate factory server.

Deployment directory

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/

Initialize the CM deployment

To handle CM on Podman in a production system, it is recommended to create quadlets for each container. Example quadlets can be found in the quadlets directory inside the distributable cm directory.

For rootless deployment, the .container, .volume and .network files from the quadlets directory need to be copied to the following location, assuming that the current user is the operator for the container deployment:

$HOME/.config/containers/systemd

If the directory does not exist it can be created.

The license directory containing the CM license files must also be copied to the above directory.

CM containers are by default configured with an internal bridged network. This implies that CM will not be able to access anything outside its network. This can be an issue with for example cloud HSM's, or an external CMDB database.

To enable outgoing external connectivity from this network, the parameter in the cmnet.network file should be changed as below:

CODE

Internal=no

In case the above setting is used, hardening security for the outgoing connectivity from the containers in this network should be done with additional firewall rules outside the containers.

Once the .container, .volume, .network and license files are in place they can be loaded into systemd using:

systemctl --user daemon-reload

This will create a systemd service for each container and volume and can be started up accordingly.

The deployment procedure for CM with quadlets is that the containers are managed by using systemd. Volumes only need to be started once, but may be restarted if the volumes are removed for any reason.

Examples (for rootless deployment):

CODE

systemctl --user start cf-server-bin-volume
systemctl --user start cf-server-certs-volume
systemctl --user start cf-server-config-volume

The container images should be pulled or loaded manually before starting any of the containers using systemd. Due to lack of TTY (a virtual text console) it might cause startup problems with the containers, the systemctl command will appear to time out due to halting and waiting for console user input. Pulling the images manually with "podman pull" is preferable, which will permit user input in case an option needs to be selected.

Any changes to files in the systemd .container, .volume, .network files or even local bind volumes in the systemd directory require a daemon reload:
systemctl --user daemon-reload

Containers running from quadlets/systemd will be removed when the systemd service is stopped. Any data on the container not stored on volumes will be lost.

CM database installation

Before continuing with the CM deployment on quadlets, follow the steps for the corresponding database from one of the following pages:

Add the CM database connection

To add the CMDB connection to the CM configuration, a JDBC connection must be added. This can be done in two ways, either by updating the cf-server.container file, or by editing cm.conf file in the systemd-cf-server-config volume. See the steps for the two alternatives below.

Containers should not be running , while doing changes in conf files

Connection string examples for the supported databases:

Database.name = jdbc:oracle:thin:@//<host>:<port/CMDB
Database.name = jdbc:postgresql://<host>:<port>/cmdb
Database.name = jdbc:sqlserver://<host>:<port>;databaseName=CMDB;encrypt=false;trustServerCertificate=true
Database.name = jdbc:mysql://<host>:<port>/CMDB?permitMysqlScheme=true&allowPublicKeyRetrieval=true&sessionVariables=transaction_isolation='READ-COMMITTED'
Database.name = jdbc:mariadb://<host>:<port/CMDB?sessionVariables=tx_isolation='READ-COMMITTED'

The following parameters needs to be updated:

Database.name
Database.user
Database.password
Database.connections

Edit cf-server.container

Add the following --cm-param flags to the /quadlets/cf-server.container Exec property to make the CF container start with a correctly configured JDBC connection:

CODE

Exec=5009 combo --cm-param Database.name=<jdbc-connection-string>\
 --cm-param Database.user=<user> --cm-param Database.password=<password> --cm-param Database.connections=20

OR:

Edit cm.conf

The CF container needs to be started to initialize the volumes with the configuration files, this start of CF will fail because no JDBC connection is yet configured.

systemctl --user start cf-server

The cm.conf can then be configured with the JDBC connection at the following path:

$HOME/.local/share/containers/storage/volumes/systemd-cf-server-config/_data/

Then restart the CF container by running the below command again:

systemctl --user restart cf-server

Connecting to services running on the Podman host

There might be situations where a connection from a container to the Podman host machine is needed. As Podman uses the slirp4netns driver by default for rootless containers, there is no directly available routing configured to reach the Podman localhost/127.0.0.1 address. To achieve this, a special IP address 10.0.2.2 can be configured in the CM configuration files to reach the Podman machine localhost. Enable this by adding the following configuration to the container-files:

Location	Configuration
In the [Container] section	`Network=slirp4netns:allow_host_loopback=true`

Post-configuration

Accessing the CM containers using the CM clients

At this point the CF is ready to accept connections on the exposed CF container port, so it is now possible to connect using Administrator's Workbench and Registration Agent clients. These clients can be installed from the CM distributable zip package.

There might be firewall rules blocking the exposed container ports in the Podman host.

At this point the deployment will have configuration, certificates, and other persistent data on volumes mounted in the CF containers. To make changes in any of the configuration files or just copy files, the volumes needs to be accessed either inside the containers or mounting the volumes elsewhere.

For example, to edit configuration in CM from inside the container:

podman exec -ti cf-server bash

This will start a new shell inside the cf-server container, which allows editing of the cm.conf, and other files. The base directory where the tools and configuration can be found is /opt/cm/server/. It is also possible to mount a named volume to the host in case the container cannot start properly for some reason. For more details please consult the podman documentation.

The volumes can also be reached from the local file system in most cases by viewing the container volume mount list using the below command:

podman inspect cf-server

Initializing the Protocol Gateway container

The Protocol Gateway container, here named pgw, is based on an Apache Tomcat version 10 image and contains a configuration for a minimal deployment. The Protocol Gateway servlets are deployed but none of them are started.

For HTTPS in Tomcat, there is a default PKCS#12 TLS server token file name and password in the server.xml, "protocol-gateway-tls.p12", but the token file is not included. It needs to be issued and then it can be uploaded to the Tomcat configuration directory, (or a different volume backed path configured in server.xml.)

To initialize the volumes from the Protocol Gateway image data, the pgw container should be started up, and once Tomcat has started, the container should be stopped again:

PGW image deployment

CODE

podman image load --input images/pgw-image-<version>.tar

CODE

systemctl --user start pgw
podman logs -f pgw
systemctl --user stop pgw

Configuring the Protocol Gateway container

The pgw container has two volumes by default:

CODE

systemd_pgw-config-gw
systemd-pgw-config-tomcat

The systemd_pgw-config-gw volume contains configuration related to PGW, this includes configuration of the different certificate issuance protocols that PGW supports.

The systemd-pgw-config-tomcat volume contains configuration related to Tomcat, this includes configuration of the different connectors that tomcat should listen on.

It should be configured in a stopped state, and in order to modify the configuration in these volumes one method is to access the container's file system from the Podman host. The volumes can be found in the following directories:

CODE

$HOME/.local/share/containers/storage/volumes/systemd-pgw-config-gw/_data/
$HOME/.local/share/containers/storage/volumes/systemd-pgw-config-tomcat/_data/

It is possible to edit the files from within the pgw container. However, this is not recommended due to the limit amount of utility tools available inside the container.

For more information on how to configure pgw: Initial configuration of Protocol Gateway.

The template file that includes standard configurations of Protocol Gateway can be found in cm_clients_<version>.zip provided with the client installation zip.

Enabling the pgw container health check

For the health check to pass successfully, the Ping servlet requires a valid virtual registration officer token from the previous step, and the ping servlet should also have a ping procedure configured in CM.

Once the token is configured and the ping procedure is available, the Ping servlet must be started by setting the "start=true" parameter in the ping.properties file in the systemd-pgw-config-gw volume.

Warnings will be logged in the Protocol Gateway if the Ping servlet does not refer to a Ping procedure in CM. See the Technical Description document for configuring this.

Starting the pgw container

Once the configuration has been edited the pgw container can be started:

systemctl --user start pgw

This is the required minimum configuration for setting up the Protocol Gateway. Additional volumes for possible output directories or HSM/other libraries, additional configuration, or web applications may be added if so required.