Webconf: Restore and Migration

Prerequisites

The Next Generation Hardware Appliance needs to be in Alarm State or Factory Reset State.

For u.trust HSM

A Backup with its DMS and the corresponding Backup Protection Smart Cards.
A connected PIN Pad to interact with the HSM restore.
SCA Cards (if backup setup has SCA enabled slots).
To activate FIPS mode by restoring a backup from a non-FIPS installation, the appliance backup must be created on an appliance running at least u.trust HSM firmware 6.0.0.0.
The FIPS activation option is not available when restoring backups from version 4.0.0 or 5.0.0. The same applies to all backup files that are to be migrated from Legacy Hardware appliance to a Next Generation Hardware Appliance.
The restore must be carried out without FIPS.
In the next step, update the HSM firmware (if an update is available).
Then create a backup on the newly restored/migrated appliance.
Now it is possible to restore this new backup with FIPS activated.

For Luna HSM

A Backup with its DMS and the corresponding Backup Keys.
Storage Information is displayed in a table and Restore Parameters can be set here. Activating a checkbox allows the HSM to run in FIPS mode.
A locally or externally connected Backup Device to interact with the HSM restore.

The selection of the target drive is independent of the prerequisites for creating a backup.
Regardless of whether NFS or a USB driver has been selected, all prerequisites must be met (DMS, no OTP, etc.).

Network File System (NFS):
To restore, archives have to be uploaded to a Network File System (NFS) located in your network and reachable for the Next Generation Hardware Appliance.
On the Next Generation Hardware Appliance the following NFS versions are supported:

NFS Version 4
NFS Version 4.1
NFS Version 4.2

If you experience long loading times or even timeouts when opening the restore file browser when accessing NFS, this could be due to a blocked port 111/TCP.
For more information, see Ports and Protocols.

Do not restart or shut down the appliance while the Restore is running.

Restore a Backup

To restore the Next Generation Hardware Appliance from an existing backup, perform the following steps:

Log in to the Next Generation Hardware Appliance.
Open the Restore page.
In the Restore Settings section, select the Storage Type for the backup you want to restore. Select Network File Setting (NFS) or the USB drive from the drop down menu.
After making the selection, another line appears to further define the path to the directory.
Enter the NFS or USB URL and click Browse Storage:
Using the Filter allows to narrow down search results.
- navigate to the path where the backup is located
- click Directories to navigate one level down or
  click One level up to return to the previous level
Select the Backup to be restored.
The Storage Information is displayed on the right side of the window.
- Backup Details displayed in a table
- Restore Parameter
  Select Keep current Network configuration if you want to preserve the current network configuration and not restore the network configuration from the backup
- Domain Master Secret
  Enter the Domain Master Secret (DMS). This entry is required.
Click Use this Backup.
The Appliance Guided Restore - Summary window opens.
A summary of the backup information and the steps for the restore are displayed.
Click Restore to start the process.
Run HSM in FIPS Mode
The FIPS check box is optional for deciding whether FIPS should be enabled or disabled during restore.
Choose PIN Pad
- choose the PIN Pad from the drop down menu
Follow the instructions in the Restore Guide.
The Restore Guide/Wizard appears in Webconf and guides through the next steps.
It shows the overall progress and indicates the part, that is currently restored.
The Restore is successful.
Once the restore has been successfully completed, the Appliance Login appears in Webconf. Enter your credentials to log into the Hardware Appliance.

On the Overview page in Webconf in Recent Activities an entry shows Backup was restored.

Backup Details

If the Keep current network configuration option is selected, the TLS certificate of the Default interface is used for all interfaces.
The TLS certificate of the interfaces can be changed later, see Transport Layer Security Configuration.

The issue that restoring a backup with Keep current network configuration will overwrite the TLS configuration of all NICs and selects the management certificate from the backup instead is resolved with the Intermediate Release 5.2.2.

For u.trust HSM

Be aware, that you will need to perform PIN Pad interactions in several steps during HSM restore.

It is possible that a restore fails in a certain step.

In this case, a Retry button is displayed. Click on this button to repeat the failed restore step.

For Luna HSM

This restore process does not restore internal HSM data.
After restore is complete, the internal HSM should be initialized and each slot should be restored separately.

Open the Security page. The HSM is restored in two steps:

The HSM must be initialized and some parameters are locked based on the restored configuration.
The next step is to initialize each slot individually and restore them one after the other.
See HSM Slot Restore for more information.

Restore a Migration Export from a Legacy Hardware Appliance

There are certain aspects to consider when restoring a migration backup.

Prerequisites

Make sure that the existing PKCS#11 slot authentication codes contain only allowed characters!
If there are any invalid characters, change the slot authentication codes before performing the migration export.
To avoid problems, please make sure in advance that you use only supported characters.
Allowed characters for PKCS#11 slot authentication codes in Webconf are:

lowercase letters: a-z
uppercase letters: A-Z
digits: 0-9
underscore: _
hyphen: -

min. length: 8
max. length: 64

Routing of Network Traffic

Network traffic routing behaves differently on Next Generation Hardware Appliance compared to Legacy Hardware Appliance.
All outgoing traffic is sent over the network interface connected to the target subnet.
If the destination is a hostname or IP address that must be routed, it is routed via the Default interface. See Network Interfaces Configuration for further information.

By default, a configuration with all incoming services is activated on the Network Interface and set as the default. It is possible to activate the other NIC and set it as the default via Webconf.

Net File System (NFS)

on the Next Generation Hardware Appliance the following NFS versions are supported:

NFS Version 4
NFS Version 4.1
NFS Version 4.2

Soft Keys

Installations with soft keys used for backup protection cannot be migrated using the migration procedure described in this document. Further preparations would be necessary on the Legacy Hardware Appliance. For more information, please contact Keyfactor Support.

SSH

SSH access to the Next Generation Hardware Appliance is no longer available. All configuration options are now accessible through Webconf.

Protocol and Port Changes

The Next Generation Hardware Appliance has undergone changes in its cluster communication protocol and ports. Consequently, existing firewall rules and network configurations may require updates to accommodate these changes. For detailed information on the current requirements for ports and protocols, see Ports and Protocols.

Cluster

When migrating a cluster configuration from the Legacy Hardware Appliance to the Next Generation Hardware Appliance, it is not advised to migrate the entire cluster.

only Node1 should be migrated
there, it will become Node1 again
then completely rebuild the cluster on the Next Generation Hardware Appliance, using Node1 as the basis.

The same applies to the restore of a cluster on the Next Generation Hardware Appliance:

only restore Node1 using the backup created on Node1
then completely rebuild the cluster using Node1 as the basis.

Cluster Traffic

Cluster traffic is forwarded via the network interface connected to the cluster network.
If the node's IP address is not on the same network, traffic is forwarded via the Default interface.

Migrating a Peer-Connected Legacy RA/VA Configuration

When migrating a peer-connected legacy RA/VA configuration to a Next Generation Hardware Appliance, in rare cases issues have been encountered with long RA web interface load times and authentication problems. Reconfiguring the peer connection roles in accordance with the EJBCA documentation should resolve these issues. For more information, refer to the Peer Systems Operations section in the EJBCA documentation.

Restore Migration Export

To restore a Migration Backup from the Legacy Hardware Appliance, proceed as for Restore.
Navigate to the path where the Migration Export from the Legacy Hardware Appliance is located.
Select the migration backup you want to restore.
Once the restore process is complete, Webconf prompts you to enter your user credentials.

OTP authentication is not possible.

The credentials are migration as a user, and the DMS set on the Legacy Hardware Appliance is used as the password.

If the restore is carried out while retaining the current network, an error may occur in the Transport Layer Security (TLS) interface, which can be rectified manually.
In the TLS display, the active interface may only be displayed in one domain. This can be corrected manually. The page Transport Layer Security (TLS) shows you how to manage TLS certificates in Webconf.

After the migration, old SCA Cards will continue to work with all slots on which SCA was activated.
If the SCA configuration of a slot is adjusted, new, individual SCA Cards are generated for this slot. These new SCA Cards will only work on the new slot, not on the already existing slots on which SCA was activated.

Known Issue Resolved in Version 5.2.2:

Fixed a bug affecting large-scale exports where the restore process became unresponsive. Previously, users attempting to migrate large databases would encounter a permanent hang at the "Prepare HSM" step; this is now resolved, ensuring stable restoration for high-volume environments.