NFS xprtsec mTLS Depends on a Network Namespace Keyring You Can Actually Operate
Transport security for NFS is often described as a mount option. The Linux client implementation shows a more precise boundary: an xprtsec=mtls mount presents a client certificate and private key selected by serial numbers, and the handshake uses the network namespace's .nfs keyring. The certificate configuration and the mount are therefore connected through kernel key management, not only through a path in /etc.
What the mount actually references
The Linux NFS client keeps one .nfs keyring per network namespace. For an mTLS mount, cert_serial and privkey_serial name keys in that keyring. The handshake links the mount namespace's keyring into tlshd before tlshd reads the keys. A TLS helper in another network namespace does not possess those keys.
This design provides useful separation. The keyring is owned by the owner of the network namespace's user namespace, and NFS keys can be placed there without granting ordinary user read access. The client uses possessor permissions rather than relying on a broad filesystem ACL.
The operational consequence is simple: a certificate file that works for another service may not be enough for this mount. The mount needs the right key objects in the right namespace, with the right serial numbers. A copied key file without a matching cert_serial and privkey_serial is not a complete configuration.
Provision credentials deliberately
Create or import the certificate and private key using the kernel key-management interface supported by the distribution. Record the key descriptions, serials, namespace, and the mount that consumes them. Do not place the private key on a shared path readable by every local user merely to make automation easier.
The namespace matters when containers, network namespaces, or service isolation are involved. A process that keeps a session keyring while changing network namespaces still resolves the nfs_keyring serial in the namespace where it makes the request. That behavior helps prevent cross-namespace reuse, but it also means a mount can fail after being moved into an environment that never received the keys.
Before changing production credentials, test the complete path from key installation to a fresh mount. A cached mount can hide a provisioning error because the handshake already happened.
Plan rotation as a mount operation
Key rotation is not finished when a new certificate is installed. The kernel must possess the new key objects, the mount must reference the new serials, and the server must trust the new client certificate chain. Existing mounts may continue using an established session, while a reconnect after network disruption exercises the new material.
Use a controlled rotation sequence. Add the new certificate and key, verify their serials in the intended namespace, mount a test export with xprtsec=mtls, check application access, and then move production mounts. Keep the prior certificate valid until the new path survives a reconnect test and the rollback window ends. Remove the old key material after all mounts and automation have migrated.
Monitor for failures that look like authentication errors rather than storage errors. tlshd logs, kernel messages, mount diagnostics, certificate expiry, and trust-chain errors should be collected together. If the server rejects the certificate, changing NFS export options may not solve the problem.
Keep authorization separate
Mutual TLS authenticates the client transport endpoint. It does not define which files the client may read or write. NFS export policy, identity mapping, Kerberos or other NFS security flavors where used, and server-side share permissions still govern access. A valid client certificate should not become a blanket bypass for filesystem authorization.
Also verify the network path. A sidecar, jump host, or alternate namespace can terminate the connection under a different identity. The keyring serial and namespace should be part of the deployment record so responders know which credential a failed mount was trying to use.
The reviewable evidence is a chain: key object description, serial, namespace, mount options, server trust, successful reconnect, and application authorization. When any link is missing, the mTLS claim is incomplete even if one mount happened to work.
References
- The per-namespace NFS client keyring, Linux kernel documentation. Retrieved 2026-11-18.
- NFSv4 client identifier, Linux kernel documentation. Retrieved 2026-11-18.
- rpcsec_gss support for kernel RPC servers, Linux kernel documentation. Retrieved 2026-11-18.
Top comments (0)