Backing Up and Restoring the Appliance Configuration

TIP   This page concerns authentication and management of roles that govern network administrative access to the appliance.

That is, access, management, and use of the cryptographic module and its application partitions, are distinct from access to the physical platform (and operating system) in which the HSM resides. This is true:

>for Luna PCIe HSM 7 installed in a workstation that you provide, and

>for the same cryptographic module inside a Luna Network HSM 7 appliance with hardened operating system and administrative access restricted to the limited Luna shell command set.

On the appliance, the cryptographic module has its own separate and distinct authentication roles and requirements; see hsm init , hsm login, and partition init, partition init co, partition init cu, partition createChallenge, partition changePw, partition activate, and audit changePwd, audit login among the various other administrative operations on the SSH-accessible appliance command path, or via the equivalent REST APIs, as well as the client-side equivalent commands (in LunaCM) partition init, partition login, partition logout, and all the partition role commands.

The appliance admin can create a backup of configuration settings for various services running on the Luna Network HSM 7 appliance, and save it to the appliance file system. This allows you to easily restore the configuration after a factory reset, ensuring that existing clients can connect to the restored appliance with all services functioning correctly. You can create multiple backup files and provide a description for each, to store different configurations. You can store your configuration backup files on the appliance filesystem, save them to the internal HSM, or export them to an external backup HSM.

>Backing Up the Appliance Configuration (pre-7.8.5)

>Restoring the Appliance Configuration

>Managing Configuration Backup Files

The backup file includes configuration data for the following modules and services:

Network Network configuration
NTLS NTLS configuration
NTP Network Time Protocol configuration
SNMP SNMP configuration
SSH SSH configuration
Syslog Syslog configuration
System System configuration (keys and certificates)
Users User accounts, passwords, and files
Webserver Webserver configuration for REST API

Configuration file size for Backup and Restore

Previously, appliance configuration files could be backed up and restored to-and-from an internal HSM, or a Backup HSM, as long as the configuration file size did not exceed 64 kilobytes. With Luna Network HSM 7 appliance software version 7.8.5 onward, the file size constraint is removed, and you can backup and restore configuration files very much larger than 64K bytes in size. A possible use for this ability is if you have a large number of clients configured for the current appliance.

Compatibility with previous practice is preserved.

>If your backup file is less than 64 KB, the sysconf config backup command detects that immediately and carries on with the one file (no different than in prior releases).
Example: lnh202_Config_ntls_20240403_1023.tar.gz

>If your backup file is greater than 64 KB, the sysconf config backup  command alerts you that it will be breaking the file into several smaller chunk files.

The chunk files are named as the full-size file would be named, but with the addition of a sequential number, appended to each.

After the last chunk is created, a SHA512 hash is created and saved under the same name. This is used to verify the chunk files and guide their reassembly, later.

Example:

lnh202_Config_ntls_20240403_1023.tar.gz_00

lnh202_Config_ntls_20240403_1023.tar.gz_01

lnh202_Config_ntls_20240403_1023.tar.gz_sha512

You must retain all the chunk files and the hash file, in order to reassemble into the original file, so do not lose, erase, or rename any in a set.

 

Configuration Backup and Restore - Individual Services

Previously, appliance configuration could be backed up as all services together in one file. With Luna Network HSM 7 appliance software version 7.8.5 onward, the -service option is added, allowing you to specify that

>any single service can be backed up to a file, or

>all services can be backed up in one file.

Backing Up the Appliance Configuration (pre-7.8.5)

Use the following procedure to back up your appliance configuration to the appliance filesystem.

CAUTION!   This procedure does not back up HSM or partition configurations. It applies only to the Luna Network HSM 7 appliance settings configurable in LunaSH.

Prerequisites

>You must be logged in to LunaSH as admin to back up the appliance configuration.

To back up the appliance configuration

1.Back up the appliance configuration, specifying an optional description for the backup file. Use quotes to include spaces in your description. To save a copy of the initial factory configuration instead of the current configuration, include the -factoryconfig option.

lunash:> sysconf config backup [-description <description>]

 

Backing Up the Appliance Configuration (7.8.5 onward)

Use the following procedure to back up your appliance configuration to the appliance filesystem.

CAUTION!   This procedure does not back up HSM or partition configurations. It applies only to the Luna Network HSM 7 appliance settings configurable in LunaSH.

Prerequisites

>You must be logged in to LunaSH as admin to back up the appliance configuration.

To back up the appliance configuration

1.Back up the appliance configuration, specifying an optional description for the backup file. Use quotes to include spaces in your description. To save a copy of the initial factory configuration instead of the current configuration, include the -factoryconfig option.

lunash:> sysconf config backup [-description <description>][-service <one of network, ssh, ntls, syslog, ntp, snmp, users, system, webserver, ctc>]

(See examples at sysconf config backup.)

Restoring the Appliance Configuration

Use the following procedure to restore appliance services from a stored configuration backup. You can restore the entire configuration or select specific services to restore.

Prerequisites

>You must be logged in to LunaSH as admin to restore the appliance configuration.

>If you are restoring the network configuration, log in using a serial connection so that you do not lose contact with the appliance.

>The configuration backup file must be available on the appliance filesystem.

To restore the appliance configuration

1.[Optional] Check the list of configuration backup files available on the appliance.

lunash:> sysconf config list

2.Stop any services you wish to restore.

lunash:> service stop <service>

3.Restore the configuration from backup by specifying the backup file and service you wish to restore.

lunash:> sysconf config restore -file <filename> -service <service>

4.Restart the service or reboot the appliance to activate the restored configuration settings.

lunash:> service restart <service>

lunash:> sysconf appliance reboot

Managing Configuration Backup Files

If you wish, you can keep only the backup files that you find useful, and individually delete any others using the sysconf config delete command. You can also use the sysconf config clear command to delete all of your configuration backup files.

Note that the configuration backup file area is a special-purpose location, accessible only using the sysconf config commands. You will not see those files listed if you run the command my file list.

There is no limit on the size of individual backup files or the number of backups that can be stored on the file system, other than the available space. This space is shared by other files, such as spkg and log files, so account for this when planning your backup and restore strategy. Some size restrictions apply if you plan to export a backup file into your HSM using sysconf config export.

Backing Up the Appliance Configuration to the HSM

You can protect a configuration setup against the possibility of appliance failure by exporting a backup file into the internal HSM or an external backup HSM. The command sysconf config export allows you to place the configuration backup file onto an HSM and sysconf config import allows you to retrieve the file from that HSM, back to the appliance file system. The export command gives you two target options:

>The internal HSM of your Luna Network HSM 7 appliance. This could be useful if a component failed in the appliance, you sent the appliance back to Thales Group for rework under the RMA procedure, received it back repaired, and then retrieved the file from your HSM to restore your appliance settings.

>A locally-installed Luna Backup HSM. This could be useful if the current appliance failed and you wished to install a replacement. Similarly, you could use system configuration backup files restored from a Backup HSM to uniformly configure multiple Luna Network HSM 7 appliances with a standard set of parameters applicable to your enterprise.

If you are exporting a configuration backup to a Luna Network HSM 7, please note the following file size restrictions:

>The maximum size of individual exportable files is 64 KB.

>The maximum storage capacity of the Admin/SO partition is 384 KB.

Automatically generated configuration backup files

A configuration backup file is generated automatically when you run the sysconf config restore or sysconf config factoryReset commands. This allows you to revert to your current configuration if the restore operation did not achieve the expected results.

Listing your configuration backup files

You can use the sysconf config list command to list all of your backup files, complete with the description you provided for each one, as shown in the following example. The configuration settings file area will always contain the original factory file, and might additionally contain any number of intentionally created backups, and possibly one or more automatic backup files:

Upgrading the appliance software changes your configuration settings

If you upgrade your appliance software, your configuration settings may be changed as part of the upgrade process and, as a result, the original factory configuration no longer applies. Immediately after you upgrade your appliance, create a new configuration backup file and make note of the backup file created. Later, if you wish to restore to this configuration, use the sysconf config restore command with the file created after upgrade.

EXAMPLE of sysconf backup, export, import, and restore

First we see why the backup file might be large...

[local_host] lunash:>client list

registered client 1: 192.168.76.95
registered client 2: 192.168.76.45
registered client 3: 192.168.76.67
registered client 4: 192.168.76.121
registered client 5: 192.168.72.61
registered client 6: 192.168.78.66
... <lots more, trimmed for brevity>
registered client 287: 192.168.72.91
registered client 288: 192.168.72.92
registered client 289: 192.168.72.93
registered client 290: 192.168.72.94
registered client 291: 192.168.72.95
registered client 292: 192.168.72.87
registered client 293: 192.168.72.100

Command Result : 0 (Success)

[local_host] lunash:>

Perform the backup, to create the backup file in the host file system...

[local_host] lunash:>sysconf config backup -service ntls -description "taking backup of NTLS configuration with ipcheck disabled"

Created configuration backup file: local_host_Config_ntls_20240510_0145.tar.gz
It is recommended to export the backup file to the internal HSM, or an external backup token to mitigate the risk of data loss.

Command Result : 0 (Success)
[local_host] lunash:>

[local_host] lunash:>sysconf config list


Configuration backup files in file system:

Size (in bytes) |  File Name                                                |  Description
-----------------------------------------------------------------------------------------------------
136661          |  local_host_Config_ntls_20240510_0145.tar.gz              |  taking backup of NTLS configuration with ipcheck disabled

Command Result : 0 (Success)
[local_host] lunash:>

We're here... why not verify it...


[local_host] lunash:>sysconf config show -file local_host_Config_ntls_20240510_0145.tar.gz


System information when this backup was created:

hostname: local_host
eth0 IP Address: 192.168.75.8
eth1 IP Address:
eth2 IP Address:
eth3 IP Address:
Software Version: Luna Network HSM v7.8.5-250 [Build Time: 20240507 14:42]
HSM Firmware Version: 7.8.4
HSM Serial Number: 532016
uptime:  01:45:45 up 15:45,  3 users,  load average: 2.06, 1.92, 1.89
Current time: Fri May 10 01:45:45 EDT 2024

Service backed up: ntls
Description: taking backup of NTLS configuration with ipcheck disabled


Command Result : 0 (Success)

[local_host] lunash:>

We need a place to put it (export)...

[local_host] lunash:>token backup list

   Token Details:
   ============
   Token Label:                        G5Backup
   Slot:                               1
   Serial #:                           7001966
   Firmware:                           6.28.0
   HSM Model:                          G5Backup


Command Result : 0 (Success)

[local_host] lunash:>token backup login -serial 7001966


  Please enter Token Administrator's password:
  > ********

'token backup login' successful.

Command Result : 0 (Success)

[local_host] lunash:>
[local_host] lunash:>sysconf config list -deviceType token -serialNumber 7001966


 Data objects not found.

Command Result : 0 (Success)
[local_host] lunash:>

Looks like a clean landing spot, so we start the export...

[local_host] lunash:>sysconf config export -file local_host_Config_ntls_20240510_0145.tar.gz -deviceType token -serialNumber 7001966 -force


Force option used. Proceed prompt bypassed.

local_host_Config_ntls_20240510_0145.tar.gz is too large. Maximum allowed size for an export to HSM/backup HSM is 64KB

Your backup file will be exported in smaller chunks. (You can still import these using the original backup file name)

If you are sure that you wish to proceed, then type 'proceed', otherwise type 'quit'.

> proceed
Proceeding...
Files exported:
local_host_Config_ntls_20240510_0145.tar.gz_00
local_host_Config_ntls_20240510_0145.tar.gz_01
local_host_Config_ntls_20240510_0145.tar.gz_02
local_host_Config_ntls_20240510_0145.tar.gz_sha512


Command Result : 0 (Success)

[local_host] lunash:>

Export was successful so, for this example clear any config backups from the file system...(not necessary, except to illustrate unambiguously)

[local_host] lunash:>sysconf config clear -force

Force option used. Proceed prompt bypassed.

Command Result : 0 (Success)
[local_host] lunash:>
[local_host] lunash:>sysconf config list

Configuration backup files in file system:

Size (in bytes) |  File Name                                                |  Description
-----------------------------------------------------------------------------------------------------

Command Result : 0 (Success)
[local_host] lunash:>

Perform the import...(notice that the filename provided is as it would be for a single file, without the added chunk-numbering)...

[local_host] lunash:>sysconf config import -file local_host_Config_ntls_20240510_0145.tar.gz -d token -s 7001966


WARNING !!  This command imports the configuration backup file: local_host_Config_ntls_20240510_0145.tar.gz from the token.
It will overwrite the existing configuration file with the same name.
If you are sure that you wish to proceed, then type 'proceed', otherwise type 'quit'.

> proceed
Proceeding...

Command Result : 0 (Success)
[local_host] lunash:>

Did it work?...

[local_host] lunash:>sysconf config list

Configuration backup files in file system:

Size (in bytes) |  File Name                                                |  Description
-----------------------------------------------------------------------------------------------------
136661          |  local_host_Config_ntls_20240510_0145.tar.gz              |  taking backup of NTLS configuration with ipcheck disabled

Command Result : 0 (Success)
[local_host] lunash:>

Looks good, but here is the crucial test...

[local_host] lunash:>sysconf config restore -s ntls -file local_host_Config_ntls_20240510_0145.tar.gz

WARNING !! This command restores the configuration from the backup file: local_host_Config_ntls_20240510_0145.tar.gz.
It first creates a backup of the current configuration before restoring: local_host_Config_ntls_20240510_0145.tar.gz.
If you are sure that you wish to proceed, then type 'proceed', otherwise type 'quit'.

> proceed
Proceeding...

Created configuration backup file: local_host_Config_ntls_20240510_0456.tar.gz

It is recommended to export the backup file to the internal HSM, or an external backup token to mitigate the risk of data loss.


Restore the ntls configuration: Succeeded.

You must either reboot the appliance or restart the service(s) for the changes to take effect.
Please check the new configurations BEFORE rebooting or restarting the services.
You can restore the previous configurations if the new settings are not acceptable.
If the service being restored was disabled prior to restoring, then the user needs to manually enable it.

Command Result : 0 (Success)

[local_host] lunash:>sysconf config list



Configuration backup files in file system:

Size (in bytes) |  File Name                                                |  Description
-----------------------------------------------------------------------------------------------------
136661          |  local_host_Config_ntls_20240510_0145.tar.gz              |  taking backup of NTLS configuration with ipcheck disabled
9654            |  local_host_Config_ntls_20240510_0456.tar.gz              |  Automatic Backup Before Restoring: ntls

Command Result : 0 (Success)
[local_host] lunash:>
[local_host] lunash:>client list

registered client 1: 192.168.76.95
registered client 2: 192.168.76.45
registered client 3: 192.168.76.67
registered client 4: 192.168.76.121
registered client 5: 192.168.72.61
registered client 6: 192.168.78.66
  < and again, hundreds trimmed from this list>
registered client 290: 192.168.72.94
registered client 291: 192.168.72.95
registered client 292: 192.168.72.87
registered client 293: 192.168.72.100

Command Result : 0 (Success)

Yes.