How to initialise a Thales Luna Network HSM and set the cloning domain correctly

This is the hands-on companion to our chapter on Luna HSM cloning domains: a numbered walkthrough from first boot of a Thales Luna Network HSM 7 appliance to an initialised partition with a correctly set, correctly recorded cloning domain. The commands below are for the Luna 7 appliance (LunaSH) and Luna HSM Client (LunaCM); where behaviour depends on firmware or client version, we say so inline. For the broader architecture — HA topology, client integration, policy design — see the comprehensive Luna HSM design and operational guide.

One framing note before the first command: initialisation is the only moment the cloning domain can be set. Everything in this procedure is recoverable except that. Treat this as a ceremony with witnesses and a written record, not a configuration task.

Before you touch the console

Have these decided and written down before the ceremony starts:

• Authentication model — password-authenticated or PED-authenticated (multifactor quorum). This decides whether your domain is a string or a red PED key, and it must match across every HSM that will ever clone with this one.
• Domain plan — which partitions on which appliances share which domain, per your replication map (prod HA pair, DR unit, backup device).
• Labels — HSM label, partition names, and (PED estates) physical labels for every iKey you will imprint.
• Custody — who holds each credential and domain artefact after the ceremony, and which safes they go into.
• Witnesses and the record template — a ceremony record your assessor can read later (see step 7).

Step 1 — First boot and appliance basics

Connect to the appliance over the serial console for first login (network comes later). Log in as admin with the factory default password printed in the appliance documentation; LunaSH forces a password change on first login. Then set the network and time:

lunash:> network hostname luna-prod-01
lunash:> network interface static -device eth0 -ip 10.20.30.11 -netmask 255.255.255.0 -gateway 10.20.30.1
lunash:> sysconf ntp addserver 10.20.30.5
lunash:> status date

Accurate time matters more than usual on an HSM — certificate validity and audit logs both depend on it. After the hostname and IP are final, regenerate the appliance’s NTLS server certificate and bind the NTLS service to the network interface (from the factory it is bound to loopback):

lunash:> sysconf regenCert
lunash:> ntls bind eth0

Do regenCert before client registration, not after — the certificate embeds the appliance identity, and regenerating it later breaks every registered client link.

Step 2 — Initialise the HSM

HSM initialisation creates the HSM Security Officer (SO) role and sets the HSM-level domain. On a password-authenticated appliance:

lunash:> hsm init -label PROD_HSM_01 -domain <hsm-domain-string> -password <hsm-so-password>

Omit -domain and -password to be prompted interactively instead — preferable in a witnessed ceremony, since command-line values can land in logs and shoulder-surfaceable scrollback. The label is 1–32 characters; the domain string is 1–128 characters. Be aware of a Luna 7 quirk: on password-authenticated appliances this HSM-level domain is a legacy field that must be set but has no practical function — the domains that govern cloning are set per application partition in step 4. Set it to a recorded value anyway; never leave a secret undocumented merely because it is currently inert.

On a PED-authenticated appliance, run the same command without -password and -domain (any password supplied is ignored). The Luna PED prompts you to imprint a blue key (HSM SO) and then a red key (HSM domain). At the red key prompt you choose between reusing an existing red key’s secret or generating a new one — this is the moment your domain plan is executed or betrayed. If this HSM must share a domain with an existing estate, present that estate’s red key and reuse it. The PED also offers duplicates; make at least one duplicate of every imprinted key and label both copies immediately.

Note that hsm init is destructive — it erases any existing partitions and their contents, and asks you to type proceed to confirm.

Step 3 — Create the application partition

Log in as HSM SO and create the partition shell:

lunash:> hsm login
lunash:> partition create -partition APP_PART_01 -size 100000
lunash:> partition list

Use -allfreestorage instead of -size if this HSM will host a single partition. On appliance software/firmware 7.7.0 and later, partition create also accepts -version: version 0 is the pre-7.7.0 object model, version 1 uses the newer scalable key storage model — the choice affects cloning compatibility with older-firmware peers, so keep versions consistent across an estate that must replicate. The partition exists now but has no roles and no domain: creation allocates it, initialisation (next step) defines it. That happens client-side.

To reach the partition from the client workstation, exchange certificates and register the client against the partition (one-time NTLS setup, abbreviated here — the exact certificate exchange steps are in the client installation guide):

lunash:> client register -client ceremony-ws -ip 10.20.30.50
lunash:> client assignpartition -client ceremony-ws -partition APP_PART_01

Step 4 — Initialise the partition and set the cloning domain

This is the step the whole ceremony exists for. From the client workstation, start LunaCM, select the partition’s slot, and initialise it. Initialisation creates the Partition Security Officer (PO) role and sets the partition’s cloning domain — the domain that actually governs HA, backup and restore for this partition’s keys.

lunacm:> slot list
lunacm:> slot set -slot 0
lunacm:> partition init -label APP_PART_01

On a password-authenticated partition you are prompted for the PO password and then the domain string (or supply -password and -domain inline, with the logging caveat from step 2). Type the domain from your written plan — character-perfect, because there is no readback and no second chance. If a peer partition on another HSM must clone with this one, its init must receive the identical string.

On a PED-authenticated partition, the PED prompts for a blue key (Partition SO) and a red key (partition domain). Again: reuse the planned red key for partitions that must replicate together; generate fresh for a new domain. Version-dependent options worth knowing: firmware 7.8.0+ with client 10.5.0+ supports -domainlabel, a human-readable label attached to the domain; and firmware 7.9.2+ supports up to three domains on a partition (universal cloning), which is also the supported path for bridging password- and PED-authenticated estates now that the older -importpeddomain option is removed from client 10.6.0+.

Initialisation can partially fail in a way that leaves the domain unset. Verify before moving on:

lunacm:> partition showinfo

Confirm that TOKEN_KCV_CREATED appears in the Extended Token Flags. If it does not, the domain was not created — reinitialise before any keys are generated, while reinitialisation is still free.

Step 5 — Initialise the operational roles

The PO now creates the Crypto Officer (CO), and the CO can create a Crypto User (CU) for read-only crypto operations:

lunacm:> role login -name po
lunacm:> role init -name co
lunacm:> role logout
lunacm:> role login -name co
lunacm:> role init -name cu

On password-authenticated partitions the initial CO/CU passwords are single-use: the role must log in and change its password with role changepw before it can operate. On PED-authenticated partitions the PED imprints a black key (CO) and grey key (CU). Roles hold access; the domain set in step 4 holds replication — a CO password can be reset later, the domain cannot.

Step 6 — Verify the domain matches across units

Here is the uncomfortable truth: you cannot directly inspect a cloning domain. No LunaSH or LunaCM command displays the domain string or the red key’s secret, and partition showinfo only proves that a domain exists (and, on firmware 7.8.0+, can show a domain label — but a label is documentation, not proof; two domains can share a label and differ in secret).

The only trustworthy verification is functional: perform a cloning operation between the units and watch it succeed. Two practical options, in order of preference:

• Backup/restore round-trip. Generate a throwaway test key on the source partition, back it up to your backup HSM, and restore it to the peer partition. Success proves all three share the domain.
• HA synchronisation test. If the partitions are destined for an HA group anyway, create the group, add the member, and synchronise (hagroup creategroup, hagroup addmember, hagroup synchronize in LunaCM). A member with a mismatched domain fails at this point — which is exactly when you want to find out.

Run this test during the ceremony, while the people and keys are still in the room, and record the result. A domain mismatch discovered now costs a reinitialisation of an empty partition; discovered in two years, it costs a key rotation programme.

Step 7 — Record domain custody in the ceremony record

The ceremony is not finished when the commands succeed; it is finished when the record is signed. For each partition, the key ceremony record should capture:

• HSM serial number, appliance software and firmware version, partition name and serial.
• The domain’s identity — its planned name/label and which partitions across which appliances share it. Never the secret value itself in the record body.
• Where the secret lives: safe locations for sealed domain-string envelopes, or serial-numbered labels of every red PED key and duplicate, including any M-of-N split scheme and who holds each share.
• The functional verification performed in step 6 and its result.
• Witness signatures, date, and the review date for the next custody audit.

For Australian federal and IRAP-assessed environments this record is not paperwork theatre — it is the evidence chain your assessor will trace from the ISM’s key management expectations to a specific safe, envelope or iKey. It is also the document that saves your successor from the inherited-HSM scenario in the companion chapter. If a red key is ever presented, moved or duplicated after the ceremony, the record gets an entry.

---

Where this leaves you

You have an initialised HSM, a partition with a deliberate and verified cloning domain, and a custody record an assessor can follow. The next problem is everything the domain merely makes possible: building the HA group properly, keeping members actually synchronised, and configuring backups that restore when it matters — each with failure modes of its own. Those are the next chapters in The Luna Field Guide.