Setting up HA and Load balancing for LunaSA

3.7.6. Setting up HA and Load balancing for LunaSA#

Several LunaSAs can join a HA group.

You have to configure the LinOTP machine with each LunaSA. Using the vtl tool you can now create the HA group.


The policies “Allow Cloning” and “Allow Network Replication” must be turned on. Use “hsm setPolicy” to set those policies if necessary.


Both partitions need to have the “AutoActivated” policy turned on.


Both HSMs need to use the same red Domain key.


The HA is set up between two partitions on two HSMs. Therefore these partitions need to have the same password. The partitions do not need to have the same name.

Change the passwords of the partitions, so that the partitions have the same password:

partition changePw

Use “partition show” to record the serial number of the partition.

Register LinOTP#

You need to register the LinOTP (client) with both HSMs as described in section Setting up HSM clients and assigning clients to HSM partitions.

Creating HA group#

Finally when the vtl verify command shows you both HSMs you can setup the HA group:

./vtl haAdmin -newGroup
              -serialNum <serialnumber-of-first-HSM>
              -label <label-of-HA-group>
              -password <partition-Password>

The file /etc/Chrystoki.conf now should have a new entry VirtualToken.


Internally the partition gets an HA key created to identify to which HA group this partition belongs. If this new HA group is a copy of a group on another LinOTP server, you will be warned that there is an existing HA key on this partition. If you want to have both LinOTP servers talk to this same HA group, you must type ‘copy’ to keep the existing HA key. If you want to start over with the HA group, then type ‘remove’. The HA key on this partition will be removed.

For adding further members to the group, you need the HA group number. You can either see this number in the cryptoki.conf file or you can see this number by issuing the command:

./vtl haAdmin -listGroups

You can now add the second HSM to the HA group:

./vtl haAdmin -addMember
              -group <serialnumber-of-the-ha-group>
              -serialNum <serialnumber-of-second-HSM>
              -password <partition-password>

Finally, when all members are added, you need to issue the command:

./vtl haAdmin -synchronize -group <group-label>


In case you need to recover a failed member, use the command haadmin -recover. For more details see section Restore an HA group.

The “VirtualToken” in the file cryptoki.conf now should contain both the serial numbers of the two partitions.


The vtl verify command will not show the virtual token. You can use the cmu list tool to list all three slots. The virtual token (HA) usually will be slot #3. Using cmu list you should also list the objects in the virtual slot to check, which handles the three encryption keys were assigned.

Please reconfigure /etc/linotp2/linotp.ini to use the “HA Virtual Card Slot”.


On the LinOTP machine you can use the command:

/usr/lunasa/bin/vtl haAdmin -status -show

to check which HSM is alive.

Restore an HA group#

Usually you will not have to restore using the backup token.

If only one member of the HA group failed, you can use the command:

./vtl haAdmin -recover <group name>

which will recover a failed member (power outage) to the HA group.

If you had a hardware failure and need to install a new HSM, you need to remove the broken member from the HA group and add the new HSM to the HA group:

  1. Remove the broken HSM from the HA group using the command:

    vtl haAdmin -removeMember <group-name> -serialNum <serial-of-the-failing-partition>
  2. Initialize the new HSM, create the new partition, assign the partition to the client, set the partition password and

  3. add the partition to the HA group using the command vtl haAdmin --addMember.

  4. Synchronize the HA group, so that the keys are synchronized to the new HSM:

    vtl haAdmin -synchronize -group <group-name>

If both of your HSMs fail, you need to setup both HSMs with the HA groups from the scratch (see Restore). Then you need your backup token to populate the first partition with the keys again.


In this case, the handles of the keys may have changed. Check if you need to adapt /etc/linotp2/linotp.ini.