Migrating PKI Server - dogtagpki/freeipa GitHub Wiki

Overview

Warning
This page is still under construction.

This page describes the manual process to migrate the PKI server in an IPA server to another machine. In the future this process can be automated.

This page assumes that the IPA server was already installed in ipa.example.com and the PKI server will be migrated to pki.example.com while the rest of IPA processes (e.g. DS, Kerberos) will continue to run on ipa.example.com.

The migration is done using backup and restore instead of cloning procedure to make sure all customization done by IPA is preserved.

Stopping PKI Server

Stop PKI server with the following command:

$ pki-server stop --wait

Backing Up PKI Server

Back up PKI server with the following command:

$ tar czvf pki-tomcat.tar.gz \
    -C / \
    etc/pki/pki-tomcat \
    etc/sysconfig/pki-tomcat \
    etc/sysconfig/pki/tomcat/pki-tomcat \
    etc/systemd/system/pki-tomcatd.target.wants/[email protected] \
    var/lib/pki/pki-tomcat \
    var/log/pki/pki-tomcat

See also Backing Up PKI Server.

Restoring PKI Server

Transfer the pki-tomcat.tar.gz to the new machine, then unpack the file:

$ tar xzvf pki-tomcat.tar.gz -C /

See also Restoring PKI Server.

Configuring HTTP Ports

Configure HTTP ports with the following commands:

$ pki-server http-connector-mod Unsecure --port 80
$ pki-server http-connector-mod Secure --port 443

Configuring HTTP Proxy Ports

Remove HTTP proxy ports with the following commands:

$ pki-server ca-config-unset proxy.securePort
$ pki-server ca-config-unset proxy.unsecurePort

Configuring Plain LDAP Port for Internal Database

Configure plain LDAP port with the following commands:

$ pki-server ca-config-set internaldb.ldapconn.host ipa.example.com
$ pki-server ca-config-set internaldb.ldapconn.port 389
$ pki-server ca-config-set internaldb.ldapconn.secureConn false

Configuring Basic Authentication for Internal Database

Configure basic authentication with the following commands:

$ pki-server ca-config-unset internaldb.ldapauth.clientCertNickname
$ pki-server ca-config-set internaldb.ldapauth.authtype BasicAuth
$ pki-server ca-config-set internaldb.ldapauth.bindDN "cn=Directory Manager"
$ pki-server ca-config-set internaldb.ldapauth.bindPWPrompt internaldb

Store the password with the following command:

$ pki-server password-add internaldb --password Secret.123

Configuring RSNv3 for Request ID Generator

Configure request ID generator with the following commands:

$ pki-server ca-config-unset dbs.beginRequestNumber
$ pki-server ca-config-unset dbs.endRequestNumber
$ pki-server ca-config-unset dbs.requestIncrement
$ pki-server ca-config-unset dbs.requestLowWaterMark
$ pki-server ca-config-unset dbs.requestCloneTransferNumber
$ pki-server ca-config-unset dbs.requestRangeDN
$ pki-server ca-config-set dbs.request.id.generator random
$ pki-server ca-config-set dbs.request.id.length 128

See also Configuring CA with Random Serial Numbers v3.

Configuring RSNv3 for Certificate ID Generator

Configure certificate ID generator with the following commands:

$ pki-server ca-config-unset dbs.beginSerialNumber
$ pki-server ca-config-unset dbs.endSerialNumber
$ pki-server ca-config-unset dbs.serialIncrement
$ pki-server ca-config-unset dbs.serialLowWaterMark
$ pki-server ca-config-unset dbs.serialCloneTransferNumber
$ pki-server ca-config-unset dbs.serialRangeDN
$ pki-server ca-config-unset dbs.enableRandomSerialNumbers
$ pki-server ca-config-unset dbs.randomSerialNumberCounter
$ pki-server ca-config-set dbs.cert.id.generator random
$ pki-server ca-config-set dbs.cert.id.length 128

See also Configuring CA with Random Serial Numbers v3.

Configuring Security Domain Connection

Configure security domain connection with the following commands:

$ pki-server ca-config-set securitydomain.host pki.example.com
$ pki-server ca-config-set service.securityDomainPort 443

Replacing SSL Server Certificate

Remove the old SSL server certificate with the following command:

$ certutil -D \
    -d /etc/pki/pki-tomcat/alias \
    -f /etc/pki/pki-tomcat/alias/pwdfile.txt \
    -n "Server-Cert cert-pki-ca"

Generate a new SSL server certificate with the following commands:

$ pki \
    -d /etc/pki/pki-tomcat/alias \
    -f /etc/pki/pki-tomcat/password.conf \
    nss-cert-request \
    --subject "CN=pki.example.com,OU=pki-tomcat,O=EXAMPLE" \
    --ext /usr/share/pki/server/certs/sslserver.conf \
    --csr sslserver.csr
$ pki \
    -d /etc/pki/pki-tomcat/alias \
    -f /etc/pki/pki-tomcat/password.conf \
    nss-cert-issue \
    --issuer "caSigningCert cert-pki-ca" \
    --csr sslserver.csr \
    --ext /usr/share/pki/server/certs/sslserver.conf \
    --cert sslserver.crt
$ pki \
    -d /etc/pki/pki-tomcat/alias \
    -f /etc/pki/pki-tomcat/password.conf \
    nss-cert-import \
    --cert sslserver.crt \
    "Server-Cert cert-pki-ca"

See also Generating SSL Server Certificate.

Updating SSL Server Certificate in CS.cfg

Update the certificate request with the following commands:

$ openssl req \
    -outform der \
    -in sslserver.csr \
    -out sslserver.csr.der
$ CSR=$(cat sslserver.csr.der | base64 -w 0)
$ pki-server ca-config-set ca.signing.certreq "$CSR"

Update the certificate with the following commands:

$ openssl x509 \
    -outform der \
    -in sslserver.crt \
    -out sslserver.crt.der
$ CERT=$(cat sslserver.crt.der | base64 -w 0)
$ pki-server ca-config-set ca.sslserver.cert "$CERT"

Importing SSL Server Certificate into CA Database

Import the certificate request with the following command:

$ pki-server ca-cert-request-import \
    --csr sslserver.csr \
    --profile serverCert.profile

Import the certificate with the following command:

$ pki-server ca-cert-import \
    --cert sslserver.crt \
    --profile serverCert.profile \
    --request <request ID>

Updating Security Domain Subsystem

Remove the old subsystem with the following command:

$ pki-server sd-subsystem-del "CA ipa.example.com 443"

Add the new subsystem with the following command:

$ pki-server sd-subsystem-add \
    --subsystem CA \
    --hostname pki.example.com \
    --unsecure-port 80 \
    --secure-port 443 \
    --domain-manager \
    "CA pki.example.com 443"

Updating Security Domain Subsystem User

Note:

  • Use port 8443 for the old PKI server since it is behind IPA HTTP proxy.

  • Use port 443 for the new PKI server since it is no longer behind IPA HTTP proxy.

Remove the old subsystem user from the Subsystem Group:

$ pki-server ca-group-member-del "Subsystem Group" CA-ipa.example.com-8443

Remove the old subsystem user with the following command:

$ pki-server ca-user-del CA-ipa.example.com-8443

Add the new subsystem user with the following command:

$ pki-server ca-user-add \
    --full-name "CA-pki.example.com-443" \
    --type agentType \
    --state 1 \
    CA-pki.example.com-443

Assign the subsystem certificate to the new subsystem user with the following command:

$ cat subsystem.crt | pki-server ca-user-cert-add CA-pki.example.com-443

Add the new subsystem user into the Subsystem Group:

$ pki-server ca-group-member-add "Subsystem Group" CA-pki.example.com-443

Starting PKI Server

Start PKI server on the new machine with the following command:

$ systemctl daemon-reload
$ pki-server start --wait

Updating IPA HTTP Proxy

Update IPA HTTP proxy with the following command:

$ sed \
    -i 's/localhost/pki\.example\.com/g' \
    /etc/httpd/conf.d/ipa-pki-proxy.conf

Updating IPA CA Service

Delete the old CA service with the following command:

$ ldapdelete \
    -H ldaps://ipa.example.com \
    -x \
    -D "cn=Directory Manager" \
    -w Secret.123 \
    "cn=CA,cn=ipa.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com"

Add the new CA service with the following command:

$ ldapadd \
    -H ldaps://ipa.example.com \
    -x \
    -D "cn=Directory Manager" \
    -w Secret.123 << EOF
dn: cn=pki.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com
objectClass: top
objectClass: nsContainer
objectClass: ipaReplTopoManagedServer
objectClass: ipaConfigObject
objectClass: ipaSupportedDomainLevelConfig
cn: pki.example.com
ipaReplTopoManagedSuffix: dc=example,dc=com
ipaReplTopoManagedSuffix: o=ipaca
ipaMinDomainLevel: 1
ipaMaxDomainLevel: 1

dn: cn=CA,cn=pki.example.com,cn=masters,cn=ipa,cn=etc,dc=example,dc=com
objectClass: nsContainer
objectClass: ipaConfigObject
objectClass: top
cn: CA
ipaConfigString: startOrder 50
ipaConfigString: caRenewalMaster
ipaConfigString: enabledService
EOF

Restarting IPA HTTPD Service

Finally, restart IPA HTTPD service with the following command:

$ systemctl restart httpd

Verification

Verify PKI server migration with the following command:

$ ipa cert-find

To Do

  • Add missing PKI CLIs

  • Do not hardcode PKI hostname and port

  • Replace AJP with HTTPS

  • Remove old PKI server

  • Support other IPA operations (e.g. enrollment, renewal, archival)

  • Support KRA migration

  • Support ACME migration

  • Support LWCA migration

  • Support DS migration

  • Support IPA installation/uninstallation with separate PKI server

⚠️ **GitHub.com Fallback** ⚠️