7.3 Full Upgrade Using a New VM

A full upgrade uses a new OCLM VMDK or QCOW2 image. Use this procedure when the release notes require a new image, when the base OS image changes, when the VM must be rebuilt, or when support directs a redeployment.

Perform the following recommended full upgrade procedure:

1. Back up customer-specific files from the old OCLM VM.
2. Deploy a new OCLM VM from the approved new image.
3. Restore only customer-specific configuration and certificate material.
4. Validate configuration, service startup, Operator CA connectivity, and API behavior.
5. Activate approved API clients on the new VM.
6. Retain the old VM powered off until customer acceptance is complete.

The following files must be backed up from the existing VM before a full upgrade:

Table 7-3 Full Upgrade Backup Set

Path	Required	Restore to New VM	Notes
/opt/oclm-service/issuerConfig.properties	Mandatory	Yes	Operator CA CMP configuration. Run configureIssuer.py after restore if endpoint, DN, TLS, or trust paths change.
/opt/oclm-service/operator-ca-root.pem	Mandatory	Yes	Operator CA trust anchor used by cmp.rootCACerts.
/opt/oclm-service/operator-ca-intermediate.pem	Conditional	Yes, if configured	Required only when the Operator CA chain uses an intermediate CA.
/opt/oclm-service/operator-ca-tls-root.pem	Conditional	Yes, if configured	Required only when cmp.enableTLS=true.
/opt/oclm-service/certs/initialIssuedCert.pem	Mandatory	Yes	Initial OCLM CMP client certificate trusted by Operator CA.
/opt/oclm-service/certs/initialIssuedKey.pem	Mandatory	Yes	Matching private key for the initial CMP client certificate. Protect this file as secret data.
/opt/oclm-service/bin/server.crt.pem	Conditional	Yes, if customer-specific	HTTPS certificate for the OCLM REST endpoint, when supplied by the site.
/opt/oclm-service/bin/server.key.pem	Conditional	Yes, if customer-specific	HTTPS private key for the OCLM REST endpoint. Protect this file as secret data.
/var/log/oclm.log	Optional	No	Retain only for audit or troubleshooting. Do not restore old logs over the new service log.

Do not restore the old VM application wheel, patch dependency files or OS packages into the new VM. Before taking the backup, stop the OCLM service.

sudo systemctl stop oclm-service
sudo systemctl status --no-pager oclm-service

Generated certificate files under /opt/oclm-service/certs are transient. If unretrieved generated material exists during activation, retrieve it through the API before decommissioning the old VM.

Create the full upgrade backup

Perform the following steps on the old OCLM VM after stopping the OCLM service:

1. Create the backup directory

   Create a timestamped backup directory under /home/admusr. The subdirectories keep configuration, CMP identity, HTTPS serving files, and logs separated so they are easy to review before restore.

   
   BACKUP_ROOT=/home/admusr/oclm-full-upgrade-backup-$(hostname)-$(date -u +%Y%m%d%H%M%S)
   sudo mkdir -p $BACKUP_ROOT/service $BACKUP_ROOT/certs $BACKUP_ROOT/bin $BACKUP_ROOT/logs

2. Back up Operator CA configuration and trust files

   Back up issuerConfig.properties and the Operator CA trust files. These files are required on the new VM so OCLM can continue to reach Operator CA and validate certificates issued by Operator CA. The intermediate and TLS trust files are copied only when they exist on the old VM.

   
   sudo cp -p /opt/oclm-service/issuerConfig.properties $BACKUP_ROOT/service/
   sudo cp -p /opt/oclm-service/operator-ca-root.pem $BACKUP_ROOT/service/
   [ -f /opt/oclm-service/operator-ca-intermediate.pem ] && sudo cp -p /opt/oclm-service/operator-ca-intermediate.pem $BACKUP_ROOT/service/
   [ -f /opt/oclm-service/operator-ca-tls-root.pem ] && sudo cp -p /opt/oclm-service/operator-ca-tls-root.pem $BACKUP_ROOT/service/

3. Back up the initial CMP client identity

   Back up the initial CMP client certificate and private key. These files are required because the new OCLM VM uses the same trusted CMP client identity when sending signature-protected CMP requests to Operator CA. Protect the private key file and any archive that contains it.

   
   sudo cp -p /opt/oclm-service/certs/initialIssuedCert.pem $BACKUP_ROOT/certs/
   sudo cp -p /opt/oclm-service/certs/initialIssuedKey.pem $BACKUP_ROOT/certs/

4. Back up optional HTTPS serving files and logs

   Back up the HTTPS serving certificate and private key only when they exist are customer-specific. Back up the current log only for audit or troubleshooting reference. Do not restore logs over the new VM log.

   
   [ -f /opt/oclm-service/bin/server.crt.pem ] && sudo cp -p /opt/oclm-service/bin/server.crt.pem $BACKUP_ROOT/bin/
   [ -f /opt/oclm-service/bin/server.key.pem ] && sudo cp -p /opt/oclm-service/bin/server.key.pem $BACKUP_ROOT/bin/
   [ -f /var/log/oclm.log ] && sudo cp -p /var/log/oclm.log $BACKUP_ROOT/logs/

5. Create and verify the backup archive

   Create a compressed archive under /home/admusr and verify that the archive was created. Copy this archive to customer-approved secure storage before decommissioning or powering off the old VM.

   
   sudo tar -C /home/admusr -czf $BACKUP_ROOT.tar.gz $(basename $BACKUP_ROOT)
   sudo ls -lh $BACKUP_ROOT.tar.gz

   The backup archive contains private key material. Restrict access to authorized deployment administrators only.

Deploy the new VM

Deploy the new OCLM VM from the approved image:

• Verify the new VM or VMDK artifact checksum.
• Create the VM using the approved CPU, memory, disk, and network settings.

Restore customer-specific files

Copy the backup archive to the new VM before running these commands. Extract it under /home/admusr, then restore only the customer-specific files from the backup.

1. Stage and extract the backup archive

   Set the backup archive path and extract it into a restore working directory. The --strip-components=1 option removes the top-level backup directory from the archive so the service, certs, bin, and logs directories are directly under $RESTORE_ROOT.

   
   BACKUP_ARCHIVE=/home/admusr/oclm-full-upgrade-backup-<old-host>-<timestamp>.tar.gz
   RESTORE_ROOT=/home/admusr/oclm-restore
   sudo mkdir -p $RESTORE_ROOT
   sudo tar -xzf $BACKUP_ARCHIVE -C $RESTORE_ROOT --strip-components=1

2. Restore Operator CA configuration and trust files

   Restore issuerConfig.properties and Operator CA trust files to /opt/oclm-service. The root CA file is mandatory. Intermediate CA and TLS trust files are restored only when they were present in the backup.

   
   sudo install -m 0640 $RESTORE_ROOT/service/issuerConfig.properties /opt/oclm-service/issuerConfig.properties
   sudo install -m 0644 $RESTORE_ROOT/service/operator-ca-root.pem /opt/oclm-service/operator-ca-root.pem
   [ -f $RESTORE_ROOT/service/operator-ca-intermediate.pem ] && sudo install -m 0644 $RESTORE_ROOT/service/operator-ca-intermediate.pem /opt/oclm-service/operator-ca-intermediate.pem
   [ -f $RESTORE_ROOT/service/operator-ca-tls-root.pem ] && sudo install -m 0644 $RESTORE_ROOT/service/operator-ca-tls-root.pem /opt/oclm-service/operator-ca-tls-root.pem

3. Restore the initial CMP client identity

   Restore the initial CMP client certificate and private key. These files allow the new OCLM VM to authenticate to Operator CA using the trusted CMP client identity from the old VM. The private key is installed with 0600 permissions.

   
   sudo install -d -m 0700 -o admusr -g admusr /opt/oclm-service/certs
   sudo install -m 0644 $RESTORE_ROOT/certs/initialIssuedCert.pem /opt/oclm-service/certs/initialIssuedCert.pem
   sudo install -m 0600 $RESTORE_ROOT/certs/initialIssuedKey.pem /opt/oclm-service/certs/initialIssuedKey.pem

4. Restore optional HTTPS serving files

   Restore the HTTPS serving certificate and private key only if they exist in the backup. These files are needed only when the site uses customer-specific HTTPS serving material for the OCLM REST endpoint.

   
   [ -f $RESTORE_ROOT/bin/server.crt.pem ] && sudo install -m 0640 $RESTORE_ROOT/bin/server.crt.pem /opt/oclm-service/bin/server.crt.pem
   [ -f $RESTORE_ROOT/bin/server.key.pem ] && sudo install -m 0600 $RESTORE_ROOT/bin/server.key.pem /opt/oclm-service/bin/server.key.pem

5. Set ownership on restored files

   Set ownership to admusr:admusr for the restored configuration, trust, identity, and optional HTTPS serving files so the OCLM service can read them with the intended permissions.

   
   sudo chown admusr:admusr /opt/oclm-service/issuerConfig.properties
   sudo chown admusr:admusr /opt/oclm-service/operator-ca-root.pem
   [ -f /opt/oclm-service/operator-ca-intermediate.pem ] && sudo chown admusr:admusr /opt/oclm-service/operator-ca-intermediate.pem
   [ -f /opt/oclm-service/operator-ca-tls-root.pem ] && sudo chown admusr:admusr /opt/oclm-service/operator-ca-tls-root.pem
   sudo chown admusr:admusr /opt/oclm-service/certs/initialIssuedCert.pem /opt/oclm-service/certs/initialIssuedKey.pem
   [ -f /opt/oclm-service/bin/server.crt.pem ] && sudo chown admusr:admusr /opt/oclm-service/bin/server.crt.pem
   [ -f /opt/oclm-service/bin/server.key.pem ] && sudo chown admusr:admusr /opt/oclm-service/bin/server.key.pem

   If the new VM uses a different Operator CA endpoint, IP address, TLS setting, or certificate path, run the configuration script after restore:

   
   cd /opt/oclm-service
   python3 configureIssuer.py
   sudo chown admusr:admusr /opt/oclm-service/issuerConfig.properties
   sudo chmod 640 /opt/oclm-service/issuerConfig.properties

Validate the new VM before acceptance

Validate configuration and files before exposing the new VM to production API clients.

sudo test -f /opt/oclm-service/issuerConfig.properties && echo "exists" || echo "missing"
sudo test -f /opt/oclm-service/operator-ca-root.pem && echo "exists" || echo "missing"
sudo test -f /opt/oclm-service/certs/initialIssuedCert.pem && echo "exists" || echo "missing"
sudo test -f /opt/oclm-service/certs/initialIssuedKey.pem && echo "exists" || echo "missing"
sudo systemctl daemon-reload
sudo systemctl start oclm-service
sudo systemctl status --no-pager oclm-service
sudo ss -ltnp | grep ':8989'
sudo tail -n 200 /var/log/oclm.log

Service activation and acceptance

After validation succeeds, activate the new OCLM VM as follows:

1. Enable the service for future boots

   Enable oclm-service only when the new VM is accepted as the active OCLM node.

   
   sudo systemctl enable oclm-service
   sudo systemctl status --no-pager oclm-service

2. Monitor OCLM during the acceptance window

   Monitor the service and recent logs after API clients or DSD/SDS integration are moved to the new VM. No repeated startup, TLS, CMP, or certificate validation errors should be present.

   
   sudo systemctl status --no-pager oclm-service
   sudo tail -n 200 /var/log/oclm.log
   sudo journalctl -u oclm-service --no-pager -n 100

3. Remove the old backups after approval

   Remove old backup material only after new OCLM VM service remains healthy.

   
   sudo rm -f /home/admusr/oclm-full-upgrade-backup-<old-host>-<timestamp>.tar.gz
   sudo rm -rf /home/admusr/oclm-full-upgrade-backup-<old-host>-<timestamp>