RPC.TLSSERVD(8)

💖 RPC.TLSSERVD 💖

okay so bestie, welcome to rpc.tlsservd — the Sun RPC over TLS Server Daemon — straight out of your System Manager's Manual. grab a strawberry 🍓, this one's actually kind of iconic.

---

✨ NAME ✨

rpc.tlsservd — Sun RPC over TLS Server Daemon. that's her. that's the whole name. 💅

---

🦋 SYNOPSIS 🦋

rpc.tlsservd [-2] [-C available_ciphers] [-D certdir] [-d] [-h]
             [-l CAfile] [-m] [-N max_threads] [-n domain] [-p CApath]
             [-r CRLfile] [-u] [-v] [-W] [-w]

---

🌸 DESCRIPTION 🌸

so rpc.tlsservd is the server side of the kernel's Sun RPC over TLS implementation, and like… she has to be running. periodt. no daemon, no TLS handshake — and the kernel RPC literally cannot do the handshake after a TCP client sends the STARTTLS Null RPC request to the server. so yeah, she's kind of the main character.

her requirements are real, though — not me being dramatic, this is actually what she needs:

• the kernel has to be built with options KERNEL_TLS
• the machine has to be on an architecture such as amd64 that supports a direct map — not i386, bestie 💀
• ktls(4) needs to be enabled

now let's talk about the exports(5) file, because the flags in there are doing a lot of work:

• the -tls option in exports(5) says the client must use RPC over TLS.
• the -tlscert option in exports(5) says the client must provide a certificate that verifies.
• the -tlscertuser option in exports(5) says the client must provide a certificate that verifies and has an otherName:1.3.6.1.4.1.2238.1.1.1;UTF8: field of subjectAltName of the form user@domain — where domain matches the one for this server, and user is a valid user name that maps to a <uid, gid_list>.

for those last two cases, the -m option plus either the -l or -p option must be specified. and the -tlscertuser option also requires that the -u option on this daemon be specified. yes, all of them. iykyk 🫶

also, quick PSA: if the IP address used by the client can't be trusted, the rules in exports(5) cannot be applied safely. like, at all. so the -h option can be used along with -m and either the -l or -p options to require that the client certificate have the correct Fully Qualified Domain Name (FQDN)</> in it. safety first, bestie. 🔥

a certificate and associated key must exist in /etc/rpc.tlsservd (or the certdir specified by the -D option) in files named cert.pem and certkey.pem.

💡 SIGHUP hive, listen up: if a SIGHUP signal is sent to the daemon it will reload the CRLfile and will shut down any extant connections that presented certificates during TLS handshake that have been revoked. but if the -r option was not specified, the SIGHUP signal will be ignored. so… specify -r. 🙈

the daemon will log failed certificate verifications via syslogd(8) using LOG_INFO | LOG_DAEMON when the -m option has been specified.

the options are as follows: ↓↓↓ (she has range)

---

🎀 OPTIONS 🎀

• -2, --allowtls1_2 — permits clients to mount using TLS version 1.2. by default the daemon only allows mounts using TLS version 1.3, as required by the RFC. but early FreeBSD (13.0 and 13.1) clients actually need this option, since they use TLS version 1.2. retro queens only 💜
• -C available_ciphers, --ciphers=available_ciphers — specifies which ciphers are available during the TLS handshake. if you pass this, SSL_CTX_set_ciphersuites() gets called with available_ciphers as the argument. if you don't pass it, the cipher gets chosen by ssl(7), which should be adequate for most cases. the format is a simple ':' separated list, in order of preference. the command openssl ciphers -s -tls1_3 lists available ciphers. slay 🔥
• -D certdir, --certdir=certdir — use certdir instead of /etc/rpc.tlsservd as the location for the certificate in a file called cert.pem and the associated key in certkey.pem. moving day 🎀
• -d, --debuglevel — run in debug mode. in this mode, rpc.tlsservd will not fork when it starts. she stays put.
• -h, --checkhost — specifies that the client must provide a certificate that both verifies and has an FQDN that matches the reverse DNS name for the IP address the client uses to connect to the server. the FQDN should be in the DNS field of subjectAltName, but is also allowed to be in the CN field of subjectName in the certificate. by default a wildcard "*" in the FQDN is not allowed. with this option, a failure to verify the client certificate or match the FQDN will result in the server sending AUTH_REJECTEDCRED replies to all client RPCs. 💀 this option requires the -m and either the -l or -p options.
• -l CAfile, --verifylocs=CAfile — specifies the path name of a CA certificate(s) file in pem format, which is used to verify client certificates and to set the list of CA(s) sent to the client so it knows which certificate to send to the server during the TLS handshake. this path name is used in the SSL_CTX_load_verify_locations(ctx,CAfile,NULL) and SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile)) openssl library calls. note that this is a path name for the file and is not assumed to be in certdir. either this option or the -p option must be specified when the -m option is specified, so that the daemon can verify the client's certificate.
• -m, --mutualverf — specifies that the server is to request a certificate from the client during the TLS handshake. it does not require that the client provide a certificate. it should be specified unless no client doing RPC over TLS is required to have a certificate. for NFS, either the exports(5) option -tlscert or -tlscertuser may be used to require a client to provide a certificate that verifies. see exports(5). mutual vibes only 🫶
• -N max_threads, --maxthreads=max_threads — for a server with a large number of NFS-over-TLS client mounts, this daemon might get overloaded after a reboot, when many clients attempt to do a TLS handshake at the same time. to speed up recovery after reboot, the daemon always processes a TLS handshake in a separate spawned thread. by default the maximum number of concurrent threads (and thus parallel handshakes) is limited to 1/2 of available CPUs on a system. this option may be used to override this default. multitasking icon 💅
• -n domain, --domain=domain — specifies what the domain is for use with the -u option, overriding the domain taken from the gethostname(2) of the server this daemon is running on. if you have specified the -domain command line option for nfsuserd(8) then you should specify this option with the same domain that was specified for nfsuserd(8). this option is only meaningful when used with the -u option. consistency is key, bestie ✨
• -p CApath, --verifydir=CApath — similar to the -l option, but specifies the path of a directory with CA certificates in it. when this option is used, SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file()) is not called, so a list of CA names might not be passed to the client during the TLS handshake. (she's a little mysterious like that 🙈)
• -r CRLfile, --crl=CRLfile — specifies a Certificate Revocation List (CRL) file that is to be loaded into the verify certificate store and checked during verification. this option is only meaningful when either the -l or -p have been specified. no -l/-p, no vibes.
• -u, --certuser — specifies that if the client provides a certificate that both verifies and has a subjectAltName with an otherName component of the form otherName:1.3.6.1.4.1.2238.1.1.1;UTF8:user@domain where domain matches the one for this server, then the daemon will attempt to map user in the above to a user credential <uid, gid_list>. there should only be one of these otherName components for each domain. if user is a valid username in the password database, then the <uid, gid_list> for user will be used for all RPCs on the mount instead of the credentials in the RPC request header. this option requires the -m and either the -l or -p options. > ⚠️ heads up bestie: use of this option might not conform to RFC-9289, which does not allow certificates to be used for user authentication. so like… know that going in. 😭
• -v, --verbose — run in verbose mode. in this mode, rpc.tlsservd will log activity messages to syslogd(8) using LOG_INFO | LOG_DAEMON — or to stderr, if the -d option has also been specified. she's a talker 🗣️
• -W, --multiwild — used with the -h option to allow use of a wildcard "*" that matches multiple components of the reverse DNS name for the client's IP address. for example, the FQDN *.uoguelph.ca would match both laptop21.uoguelph.ca and laptop3.cis.uoguelph.ca. wildcard ate 💅
• -w, --singlewild — similar to -W but allows the wildcard "*" to match a single component of the reverse DNS name. for example, the FQDN *.uoguelph.ca would match laptop21.uoguelph.ca but not laptop3.cis.uoguelph.ca. only one of the -W and -w options is allowed. pick a lane, babe. 💀

---

⭐ EXIT STATUS ⭐

the rpc.tlsservd utility exits 0 on success, and >0 if an error occurs. clean exit = clean conscience 🌈

---

👑 SEE ALSO 👑

openssl(1), ktls(4), exports(5), ssl(7), mount_nfs(8), nfsuserd(8), rpc.tlsclntd(8), syslogd(8)

---

🧚 STANDARDS 🧚

the implementation is based on the specification in "Towards Remote Procedure Call Encryption By Default", RFC 9289. we stan a documented queen 📜✨

---

🦄 HISTORY 🦄

the rpc.tlsservd manual page first appeared in FreeBSD 13.0. she's been iconic since day one, fr fr.

---

💀 BUGS 💀

this daemon cannot be safely shut down and restarted if there are any active RPC-over-TLS connections.

doing so will orphan the KERNEL_TLS connections, so that they can no longer do upcalls successfully — because the SSL * structures in userspace have been lost. gone. vanished. bestie they are not coming back 😭 so please, for the love of everything, don't do that.

---

okay that's the whole page, you made it!! 🎉🫶 this was RPC.TLSSERVD(8) from the Debian build, dated January 25, 2025 — so if anyone asks, that's the version tea. now go run your TLS server like the main character you are. bye bestie!! 💖✨🎀