Search the docs

Remounting an Ubuntu Client

NFS over TLS requires Linux kernel 6.12 or later. Ubuntu system administrators should verify their kernel version before proceeding: 
uname -r

Ubuntu 25.04 ships kernel 6.14 and meets this requirement out of the box. Ubuntu 24.04 LTS ships kernel 6.8 by default; administrators on 24.04 LTS should verify whether their system is running the Hardware Enablement (HWE) kernel, which tracks more recent upstream releases:

dpkg -l linux-image-generic-hwe-24.04

These instructions apply to Ubuntu 25.04 and later, and to Ubuntu 24.04 LTS with a kernel that meets the ≥ 6.12 requirement.

Prerequisites

Verify the following before remounting:

  1. Install the required packages:

    sudo apt install nfs-common ktls-utils

    nfs-common provides the Ubuntu equivalent of nfs-utils (the mount.nfs and related utilities). ktls-utils provides tlshd, the TLS handshake daemon required by the Linux kernel NFS client.

    Check the installed version with tlshd --version (or journalctl -u tlshd, which logs Built from ktls-utils <version>). Ubuntu 24.04 LTS packages ktls-utils 0.9, which is below the minimum in Reference: Client Requirements. With 0.9, tlshd can only verify the Hammerspace server certificate when the server address reverse-resolves to a name in that certificate, so mounts fail with gnutls: Error in the certificate. (-43) in the tlshd journal. Install a current ktls-utils release (built from source if your distribution does not package one) before continuing.

  1. Install the Hammerspace cluster CA certificate in the Ubuntu trust store. This is the certificate that Administration  TLS  Cluster Root CA  Download Certificate provides; it is the issuer of every Anvil and DSX certificate, so the client must trust it whichever CA issued the client’s own certificate:

    sudo cp hammerspace-ca.crt /usr/local/share/ca-certificates/hammerspace-ca.crt
sudo update-ca-certificates

    The update-ca-certificates command adds the certificate to /etc/ssl/certs/ca-certificates.crt, which tlshd uses as its default trust store.

  2. Configure tlshd with the client certificate and private key. Edit /etc/tlshd.conf and populate the [authenticate.client] section:

    [authenticate.client]
x509.truststore= /etc/ssl/certs/ca-certificates.crt
x509.certificate= /etc/ssl/hs-tls/cert.pem
x509.private_key= /etc/ssl/private/hs-tls/key.pem
    In ktls-utils 1.3.0 and later, the default configuration file is /etc/tlshd/config. If /etc/tlshd.conf exists, tlshd reads it instead and logs Please relocate /etc/tlshd.conf to /etc/tlshd/config. Edit whichever file your distribution uses, and restart tlshd afterward.

    Replace the certificate and key paths with the actual locations of your client certificate and private key. If the client certificate was issued by an intermediate CA, put the intermediate CA certificate after the client certificate in the same file (x509.certificate), or add the intermediate CA to the Hammerspace trust store with cert-add --trust-intermediate-ca; Hammerspace must be able to build the chain from what the client presents to a CA it trusts. Restrict access to the private key file:

    sudo chmod 600 /etc/ssl/private/hs-tls/key.pem

  3. Enable and start the tlshd service:

    sudo systemctl enable --now tlshd.service

  4. Verify that tlshd is running without errors:

    sudo journalctl -u tlshd --no-pager -n 20

    Confirm there are no errors related to certificate loading or TLS handshake failures before proceeding.

Procedure

  1. If the share is currently mounted, stop any processes using it, then unmount:

    sudo umount /mnt/your_mount_point
    If the unmount fails because the mount point is busy, use fuser -m /mnt/your_mount_point to identify and stop the active processes before retrying.

  2. Remount the share with the xprtsec=mtls option to require mutual TLS authentication:

    sudo mount -o xprtsec=mtls <cluster_ip>:/<export_path> /mnt/your_mount_point

  3. To ensure the share remounts automatically with TLS after a system reboot, add or update the entry in /etc/fstab:

    <cluster_ip>:/<export_path>  /mnt/your_mount_point  nfs  xprtsec=mtls,_netdev  0  0

    • xprtsec=mtls — Requires mutual TLS authentication for the NFS connection.

    • _netdev — Ensures the network is available before the system attempts to mount the share at boot time.

Verify the TLS Connection

After remounting, verify that the connection is using TLS:

  • Check the connection status. Connections to the Anvil use port 2049. With a pNFS mount (NFSv4.2), data connections go directly to DSX nodes on port 3049. Check both:

    sudo ss -tni | grep -E -A1 ':(2049|3049)\b'

    A connection that uses TLS shows tcp-ulp-tls in its details, for example tcp-ulp-tls version: 1.3 cipher: aes-gcm-256. Run the command as root: on some kernels the TLS details are omitted for other users.

  • Check the NFS mount statistics. Confirm that xprtsec=mtls appears in the reported mount options:

    nfsstat -m

  • Review tlshd logs to confirm the TLS handshake completed successfully:

    sudo journalctl -u tlshd --no-pager -n 20