Server Certificate

By default, Hammerspace ships with a self-signed certificate. This will often cause warnings when clients are connecting to the Management GUI over HTTPS because the certificate does not match what is installed in their browser. The resolution is for the customer to add their certificate to the installation.

Administrators can add a customer-specific X.509 server certificate. A new certificate can be used to prevent browser security warnings during regular logins to the Management GUI. A new certificate would also be used in other external communication as appropriate.

The following additional information applies to certificates:

The same certificate is used across all HTTPS connections in Hammerspace, including the S3 endpoint on port 8443.
By default, without a customer-installed certificate, security warnings will appear on the S3 client.
The default certificate is self-generated:
- Key: RSA 3072 bits
- Algorithm: SHA384withRSA
The self-generated certificate expires 824 days after it is created. Hammerspace does not warn you before it expires. Track its expiration date, or install your own certificate.
The self-generated certificate carries only the cluster IP address as a subject alternative name. Browsers and clients that connect by a host name show a warning even after they trust the certificate. To connect by name without a warning, install a certificate that includes the name.

You can install a certificate, view or download the installed certificate, and reset to a new self-generated certificate, either in the Management GUI or with the cluster-config command in the Admin CLI.

A new or reset certificate takes effect only after the primary Anvil is rebooted or, in a high-availability (HA) cluster, after a failover to the other Anvil. The Management GUI and the Admin CLI both show the reboot instruction, with the name of the primary Anvil, when the change is accepted. Plan the reboot or failover for a maintenance window.

Installing a Certificate Using the Management GUI

Before you start, have the following files:

The server certificate in PEM format, optionally followed by its intermediate CA certificates and root CA certificate, in one file. Accepted file extensions are .pem, .crt, and .cer.

The certificate’s RSA private key in PKCS#1 or PKCS#8 PEM format, in a file with the extension .key, .pem, .crt, or .cer. The key can be an encrypted PKCS#8 key. If it is, you need its passphrase.

Log in to the Management GUI as an administrator.
Navigate to Administration Certificates. The Cluster Certificate Details section shows the installed certificate.
Click Upload New Certificate.

In the Upload New Certificate dialog, under Private Key:, select how you will provide the private key:

File: In Private Key File:, select the key file. If the key is encrypted, enter its passphrase in Key File Passphrase:. Leave the passphrase empty if the key is not encrypted.

Do not type anything in Key File Passphrase: for an unencrypted key, even if you delete it again. Once the field has held a value, the upload of an unencrypted key fails with the Bad certificate chain or private key message. Close the dialog and open it again.

Plain text: Paste the PEM-encoded private key, including its -----BEGIN and -----END lines. The key must not be encrypted; the passphrase field is available only with File.

In Certificate:, select the certificate file. If you click Upload without one, the dialog shows Please select a certificate file. under the field.
Click Upload.

When the certificate is accepted, a dialog shows Certificate uploaded successfully. and instructs you to reboot the primary Anvil, by name, for the new certificate to take effect. For a few seconds after you close the dialog, the Web Server Certificate tab shows CERTIFICATE UNDER CONSTRUCTION with empty fields and 1970 dates; it then shows the uploaded certificate’s details. The certificate that the GUI and REST API serve does not change until the reboot (or, in an HA cluster, a failover).

Click Close.
Reboot the primary Anvil during a maintenance window.
After the reboot, check that the details section shows the new certificate’s Subject and Validity, then reload the Management GUI in your browser and confirm that it presents the new certificate.

If the key is in an unsupported format, if the passphrase is wrong, or if a passphrase is given for a key that is not encrypted, the upload fails with the message Bad certificate chain or private key. Ensure the private key format is valid and the passphrase is correct if the key is encrypted. A key that does not match the certificate fails with Private key is invalid for specified certificate.

Viewing and Downloading the Installed Certificate

Navigate to Administration Certificates. The Cluster Certificate Details section shows the installed certificate’s version, serial number, signature algorithm, issuer, subject, validity dates, and fingerprints.

To save the certificate chain to a file, click Download Certificate. The browser saves a file named certificate-chain.crt.

In the Admin CLI, cluster-config --view shows the same details under Server Certificate chain.

Installing a New Certificate Using the Admin CLI

Log in to the Anvil as an admin-level role and install the new certificate with cluster-config --server-certificate-chain. It is essential that the entire certificate is copied exactly as it appears. Use " " to ensure that the system correctly interprets the input text.

The --server-private-key option must also be used. If you omit it, the Admin CLI prompts for the private key; the prompt works only in an interactive session. The --server-private-key option cannot be used without --server-certificate-chain.

The --server-private-key option accepts only an unencrypted RSA private key in PKCS#1 or PKCS#8 PEM format. To install a certificate whose private key is encrypted, use the Management GUI and provide the key as a file with its passphrase. See the Installing a Certificate Using the Management GUI section of this page.

Type or paste the command in an interactive Admin CLI session. The quoted certificate and key span several lines, and the CLI only continues a quoted value across lines in an interactive session; input that is piped or scripted (for example, ssh with a command argument) is read one line at a time and fails with syntax errors.

Admin CLI

Command:

cluster-config --server-certificate-chain "-----BEGIN CERTIFICATE-----
<server certificate, followed by any intermediate and root CA certificates>
-----END CERTIFICATE-----" --server-private-key "-----BEGIN RSA PRIVATE KEY-----
<private key>
-----END RSA PRIVATE KEY-----"

The command prints the cluster configuration (the output of cluster-view) and ends by confirming that the certificate was accepted, with the command to reboot the primary Anvil. Reboot the primary Anvil at this time to activate the certificate. On a high-availability cluster, a failover to the other Anvil also activates it.

Expected output:

ID:                                 0ec84e65-0258-45bf-8d29-85db81588f5f
Name:                               AE742ZCK22YBB0
State:                              Standalone
Management IPs:                     [192.0.2.10/20]
Data IPs:                           [192.0.2.10/20]
Cluster floating IPs:               [192.0.2.10/20]
Since:                              2026-09-21 23:51:44 UTC
Created:                            2026-09-21 23:51:24 UTC
Timezone:                           UTC
GFS participant max suspected time: 30 minutes
Metered billing:                    Disabled
Prometheus exporters:               Disabled
Evaluation expiration:              2026-10-21 23:51:24 UTC
Online license activation support:  true
NAS volume capacity:                [Total: 42.9GB, Used: 1.3GB, Free: 41.6GB]
Share space (quota):                [Total: 1GB, Used: 943.7MB, Free: 56.2MB]
EULA accepted:                      2026-09-22 00:26:56 UTC
Metadata servers:
                         [Object type: Anvil, Node name: anvil.example.com, Role: Primary, Admin state: Up, Oper state: Up]
Server Certificate chain:
                         Version:                 3
                         Serial:                  8030382114916146565125259499546693869292100833 (0x1681844070edeea0ba30832cad5548120d61ce1)
                         Algorithm:               SHA256withRSA
                         Issuer:                  CN=Example Docs Root CA, O=Example Docs, C=US
                         Subject:                 CN=anvil.example.com, O=Example Docs, C=US
                         Validity:                Not Before:              2026-09-22 00:39:31 UTC
                                                  Not After:               2028-12-25 00:39:31 UTC
                         Fingerprints:            SHA1:                    2c:9f:b9:30:10:1a:a1:73:be:41:7f:38:89:d8:50:e8:83:fb:c:e1
                                                  MD5:                     de:a3:c2:37:ca:3d:25:4c:af:86:da:68:ff:ea:f6:cd
                                                  CRC32:                   0xfcad84d8

                         Version:                 3
                         Serial:                  170571743814341827810356851105946558195636701158 (0x1de0b39728beeb751870a62aebdfa3b55c0d07e6)
                         Algorithm:               SHA256withRSA
                         Issuer:                  CN=Example Docs Root CA, O=Example Docs, C=US
                         Subject:                 CN=Example Docs Root CA, O=Example Docs, C=US
                         Validity:                Not Before:              2026-09-22 00:39:31 UTC
                                                  Not After:               2036-09-19 00:39:31 UTC
                         Fingerprints:            SHA1:                    bb:e3:b6:b8:3:28:8d:5a:28:c5:5c:30:a5:d3:d8:57:69:33:61:98
                                                  MD5:                     41:e9:65:dd:9:41:ca:53:68:1d:68:d:7a:b6:82:21
                                                  CRC32:                   0x39c9096a

The certificate fingerprint can be viewed using the cluster-view command.

Admin CLI

Command:

cluster-config --view

Expected output:

ID:                                 0ec84e65-0258-45bf-8d29-85db81588f5f
Name:                               AE742ZCK22YBB0
State:                              Standalone
Management IPs:                     [192.0.2.10/20]
Data IPs:                           [192.0.2.10/20]
Cluster floating IPs:               [192.0.2.10/20]
Since:                              2026-09-21 23:51:44 UTC
Created:                            2026-09-21 23:51:24 UTC
Timezone:                           UTC
GFS participant max suspected time: 30 minutes
Metered billing:                    Disabled
Prometheus exporters:               Disabled
Evaluation expiration:              2026-10-21 23:51:24 UTC
Online license activation support:  true
NAS volume capacity:                [Total: 42.9GB, Used: 1.3GB, Free: 41.6GB]
Share space (quota):                [Total: 1GB, Used: 943.7MB, Free: 56.2MB]
EULA accepted:                      2026-09-22 00:26:56 UTC
Metadata servers:
                         [Object type: Anvil, Node name: anvil.example.com, Role: Primary, Admin state: Up, Oper state: Up]
Server Certificate chain:
                         Version:                 3
                         Serial:                  8030382114916146565125259499546693869292100833 (0x1681844070edeea0ba30832cad5548120d61ce1)
                         Algorithm:               SHA256withRSA
                         Issuer:                  CN=Example Docs Root CA, O=Example Docs, C=US
                         Subject:                 CN=anvil.example.com, O=Example Docs, C=US
                         Validity:                Not Before:              2026-09-22 00:39:31 UTC
                                                  Not After:               2028-12-25 00:39:31 UTC
                         Fingerprints:            SHA1:                    2c:9f:b9:30:10:1a:a1:73:be:41:7f:38:89:d8:50:e8:83:fb:c:e1
                                                  MD5:                     de:a3:c2:37:ca:3d:25:4c:af:86:da:68:ff:ea:f6:cd
                                                  CRC32:                   0xfcad84d8

                         Version:                 3
                         Serial:                  170571743814341827810356851105946558195636701158 (0x1de0b39728beeb751870a62aebdfa3b55c0d07e6)
                         Algorithm:               SHA256withRSA
                         Issuer:                  CN=Example Docs Root CA, O=Example Docs, C=US
                         Subject:                 CN=Example Docs Root CA, O=Example Docs, C=US
                         Validity:                Not Before:              2026-09-22 00:39:31 UTC
                                                  Not After:               2036-09-19 00:39:31 UTC
                         Fingerprints:            SHA1:                    bb:e3:b6:b8:3:28:8d:5a:28:c5:5c:30:a5:d3:d8:57:69:33:61:98
                                                  MD5:                     41:e9:65:dd:9:41:ca:53:68:1d:68:d:7a:b6:82:21
                                                  CRC32:                   0x39c9096a

Resetting the Installed Certificate

The system can be reset to use a self-generated certificate, effectively removing any manually installed certificate. The new self-generated certificate is valid for 824 days.

To reset the certificate in the Management GUI:

Navigate to Administration Certificates.
Click Reset Certificate.
The confirmation dialog states that the current certificate will be replaced with a fresh internally generated self-signed certificate, and that a reboot of the primary Anvil is required. Click Yes.
Reboot the primary Anvil during a maintenance window. On a high-availability cluster, a failover to the other Anvil also activates the new certificate.

To reset the certificate in the Admin CLI:

Admin CLI

Command:

cluster-config --server-certificate-reset

Expected output:

ID:                                 0ec84e65-0258-45bf-8d29-85db81588f5f
Name:                               AE742ZCK22YBB0
State:                              Standalone
Management IPs:                     [192.0.2.10/20]
Data IPs:                           [192.0.2.10/20]
Cluster floating IPs:               [192.0.2.10/20]
Since:                              2026-09-21 23:51:44 UTC
Created:                            2026-09-21 23:51:24 UTC
Timezone:                           UTC
GFS participant max suspected time: 30 minutes
Metered billing:                    Disabled
Prometheus exporters:               Disabled
Evaluation expiration:              2026-10-21 23:51:24 UTC
Online license activation support:  true
NAS volume capacity:                [Total: 42.9GB, Used: 1.3GB, Free: 41.6GB]
Share space (quota):                [Total: 1GB, Used: 943.7MB, Free: 56.2MB]
EULA accepted:                      2026-09-22 00:26:56 UTC
Metadata servers:
                         [Object type: Anvil, Node name: anvil.example.com, Role: Primary, Admin state: Up, Oper state: Up]
Server Certificate chain:
                         Version:                 3
                         Serial:                  8711156112346315821 (0x78e43e549b5ffc2d)
                         Algorithm:               SHA384withRSA
                         Issuer:                  O=Hammerspace, C=US, CN=Hammerspace-97013624
                         Subject:                 O=Hammerspace, C=US, CN=Hammerspace-97013624
                         Validity:                Not Before:              2026-09-22 00:45:25 UTC
                                                  Not After:               2028-12-24 00:45:25 UTC
                         Fingerprints:            SHA1:                    d:eb:32:9c:e:3e:ca:2a:89:ff:b:f:5d:4:de:d4:c4:9a:b5:d9
                                                  MD5:                     18:6b:5b:8c:e:53:99:4d:e0:5a:ef:c3:b9:c5:ba:e8
                                                  CRC32:                   0x780535db