How to register a Luna HSM NTLS client — and recover it after an IP or hostname change

This is the hands-on companion to the Luna Field Guide chapter on NTLS trust and DR failovers. It walks through registering an NTLS client against a Luna Network HSM partition from a clean install, then — the part most runbooks skip — recovering that registration after the client’s IP address or hostname changes, and pre-registering a DR identity so the next failover needs no HSM work at all.

Commands below are drawn from the Luna Network HSM 7 documentation. Exact syntax and file locations vary between client and appliance software versions — where a detail is version-dependent we say so. If your output differs, trust thalesdocs.com for your specific release over any blog post, including this one. For the broader deployment context, see our Luna HSM design and operational guide.

Before you start

• Luna HSM Client installed on the application server (vtl and LunaCM available).
• TCP 1792 open from the client to the appliance (NTLS default port), and TCP 22 from your admin host for lunash.
• An appliance admin account, and a partition already created for this client.
• A decision, made deliberately, on whether to register by hostname (DNS) or IP. Register by DNS name if you want DR to be survivable — the certificate binds to whichever you choose.

Note: recent Luna clients also offer a one-step setup (lunacm clientconfig deploy) that automates the whole exchange. The multi-step procedure below is worth knowing anyway, because recovery after an address change is the multi-step procedure.

Step 1: Generate the client certificate

On the client, generate the certificate and private key. The -n value must be the client’s hostname exactly as the OS reports it (or its IP address, if you’re registering by IP):

vtl createCert -n clientapp01.agency.gov.au

This writes clientapp01.agency.gov.au.pem (certificate) and clientapp01.agency.gov.auKey.pem (private key) into <client_install_dir>/cert/client/. Whatever name you put in -n is the name the appliance will demand at registration time — this is the binding that breaks when addresses change. If this client will talk to several appliances, you only generate the certificate once.

Step 2: Exchange certificates with the appliance

Two transfers, both over scp/pscp/sftp. First, pull the appliance’s server certificate down to the client:

scp [email protected]:server.pem .

Then register it in the client’s trust store:

vtl addServer -n hsm01.agency.gov.au -c server.pem

Use the same hostname/IP form here that the client will use to reach the appliance. Second, push the client certificate up to the appliance:

scp <client_install_dir>/cert/client/clientapp01.agency.gov.au.pem [email protected]:

The private key never leaves the client. Only the .pem certificate is transferred.

Step 3: Register the client and assign the partition

SSH to the appliance as admin (lunash). Register the client against the certificate you just uploaded — -hostname if the cert was generated with a hostname, -ip if it was generated with an IP:

lunash:> client register -client clientapp01 -hostname clientapp01.agency.gov.au

Then grant it access to its partition, and confirm:

lunash:> client assignpartition -client clientapp01 -partition app_partition
lunash:> client show -client clientapp01

If you registered by IP and later map a hostname to that client, restart NTLS so the change takes effect (service restart ntls). Note that restarting NTLS briefly interrupts all clients on the appliance, so treat it as a change-window action on shared appliances.

Step 4: Verify with vtl verify

Back on the client:

vtl verify

Success looks like a slot listing showing your partition’s serial number and label. That listing is the proof that the whole trust chain — client cert, server cert, registration, partition assignment — is intact. Record the expected output in your runbook: during an incident, “what does good look like” is half the diagnosis.

Recovery: the client’s IP or hostname changed

This is the DR-failover scenario: the server came up on a new subnet (or was renamed), TCP to port 1792 works, and vtl verify shows nothing. The certificate still names the old identity, so the appliance refuses the client. The fix is regenerate and re-register — the appliance keeps a copy of the old certificate, so both sides must be refreshed:

1. On the client, regenerate the certificate with the new hostname or IP:

vtl createCert -n clientapp01-dr.agency.gov.au

Be aware this overwrites the client’s existing certificate and key, which breaks this client’s registrations on every appliance it talks to — plan to re-register it everywhere, not just on one HSM.

2. Copy the new certificate to the appliance as in Step 2.

3. On the appliance, remove the stale client entry and register the new one (partition assignments do not carry over — reassign them):

lunash:> client delete -client clientapp01
lunash:> client register -client clientapp01 -hostname clientapp01-dr.agency.gov.au
lunash:> client assignpartition -client clientapp01 -partition app_partition
lunash:> service restart ntls

4. On the client, run vtl verify again and confirm the slot listing returns.

If the client is a member of an HA group, repeat the appliance-side steps on every appliance in the group — the regenerated certificate invalidated the old registration on all of them, and an HA group with one dead member link will limp along in production and then fail completely at exactly the wrong moment. Re-run vtl verify and confirm every member partition is visible before declaring the recovery done.

If only the appliance’s identity changed (its server.pem was regenerated, or it moved address), the client-side fix is the mirror image: vtl deleteServer -n <old>, fetch the new server.pem, then vtl addServer -n <new> -c server.pem. If SSH complains about a changed host key when you reconnect to a moved appliance, that’s your own known-hosts file, not the HSM — clear the stale entry and continue.

Common errors and what they actually mean

Symptom	What it actually means
vtl verify finds no slots, but TCP 1792 connects	A trust problem, not a network problem. Certificate CN vs registered identity mismatch, stale registration, or source-IP check rejecting the new address. Check the appliance’s NTLS logs for the handshake failure.
TLS/SSL handshake errors in the appliance NTLS log	The client presented a certificate the appliance doesn’t accept — regenerated cert not re-registered, or expired cert on either side.
Application reports token/slot not present (e.g. CKR_TOKEN_NOT_PRESENT-class errors)	The client authenticated but has no partition it can see: client assignpartition missing after a re-registration, or the wrong partition assigned.
Worked from the old site, fails from DR, config untouched	The appliance may be enforcing source-IP verification on NTLS (the lunash ntls ipcheck setting) — a valid certificate arriving from an unregistered address is still refused. Verify the setting and make the enable/disable decision deliberately; it is a documented security control.
Registration succeeded but the client isn’t recognised until later	NTLS needed a restart to pick up the change (notably after IP-registration plus hostname mapping): service restart ntls.

Pre-register a DR client identity

Everything above is recovery under pressure. The better position is to never need it: register the DR identity while nothing is on fire.

Option A — same name everywhere (preferred). Generate the client certificate against a stable FQDN, register with -hostname, and ensure DNS at the DR site resolves that name to the DR address. If the appliance’s source-IP check would still reject the moved client, that’s the deliberate risk decision from the concept chapter — resolve it at design time, in writing, not on the bridge.

Option B — a second registered client. Where the DR server is a distinct machine with its own name, generate its certificate on the DR host itself (the private key stays there), then register it on every appliance as its own client and assign the same partitions:

lunash:> client register -client clientapp01-dr -hostname clientapp01-dr.agency.gov.au
lunash:> client assignpartition -client clientapp01-dr -partition app_partition

Then prove it: run vtl verify from the DR host during the next DR test, before the application tier starts, and record the output as the pass criterion. In ISM-aligned environments this doubles as evidence for your continuity controls — an IRAP assessor is far happier with a tested DR trust path than with an untested diagram. If your client is a CyberArk vault, do this before you ever need it; the multi-site failure patterns are covered in our CyberArk CorePAS multi-site guide.

---

Where this leaves you

Your clients can now be registered, recovered, and failed over without drama — which means the next thing to bite you is no longer the connection layer. It’s the partitions themselves: partition software versions and the SMK create an upgrade trap that can quietly strand backups and break restores, and that’s where the guide goes next. The full series lives at The Luna Field Guide.