S6-TLSCLIENT(8)

📦 version 2.8.0.1, in nixpkgs unstable

🦋 S6-TLSCLIENT(8) — like, the UCSPI client tool for TLS/SSL over INET domain sockets, bestie

okay so real talk: this is a page from the System Manager's Manual, and it's about s6-tlsclient — an iconic little tool. psa: it's a UCSPI client tool[1] for TLS/SSL connections over INET domain sockets. screaming, crying, throwing up, etc 💅

✨ NAME ✨

s6-tlsclient — UCSPI client tool[1] for TLS/SSL connections over INET domain sockets 🫶

🎀 SYNOPSIS 🎀

s6-tlsclient [options] [--] host port prog...

🌸 DESCRIPTION 🌸

so the way that s6-tlsclient works is: it establishes a TCP connection to a server, layers a TLS transport on top of it, and then executes into a program. literally that's it, that's the whole vibe ✨

s6-tlsclient rewrites itself into a command line involving:

  • s6-tcpclient(8), which establishes a TCP connection to host host port port. 💖
  • s6-tlsc(8), which establishes a TLS transport (client-side) over that connection.
  • prog..., your client program, which is executed into by s6-tlsc(8) once the s6-tlsc-io(8) child it has spawned has set up the TLS connection and performed the handshake. 🤝

prog... is run with the same pid as s6-tlsclient. no cap 🧚

prog is expected to read from its peer on descriptor 6 and write to its peer on descriptor 7. and here's the thing bestie — since there will be an s6-tlsc-io(8) program between prog and the network to perform the TLS encryption/decryption, those descriptors will not be a network socket — they will be pipes. 🥤

🌈 Server name determination for SNI

If the -H option is not given to s6-tlsclient, then host will be used as the server name to verify. You can use the -k option to override this default. 🙈

⚠️ please please PLEASE note: if you use the -H option and do not provide a server name via -k, SNI will not be used, which may be a security risk. like, genuinely. be careful. 💀

💜 OPTIONS 💜

s6-tlsclient accepts a myriad of options, all of which are passed as is to the correct executable. Not giving any options will generally work: the defaults are sensible. lowkey the defaults ate 🔥

⭐ Options passed as-is to s6-tcpclient(8)

  • -q, -Q, -v — Be quiet, normally verbose, or verbose. pick your volume, babe 🎚️
  • -4, -6 — Stick to IPv4 or IPv6 addresses.
  • -d, -D — Enable or disable Nagle's algorithm.
  • -r, -R — Enable or disable IDENT lookup.
  • -H — Disable DNS lookups.
  • -h — Consult /etc/hosts before DNS.
  • -l localname — Get the local name from the command line, don't look it up.
  • -n, -N — Qualify the host or not when resolving it.
  • -t timeout — Global timeout on the connection attempt. ⏰
  • -i localip, -p localport — Force local socket parameters.
  • -T timeoutconn — Configurable connection timeouts.

🦋 Options passed as-is to s6-tlsc(8)

  • -Z, -z — Keep or remove the s6-tlsc-io(8)-specific variables from the application's environment.
  • -S, -s — Use ‘close_notify’ or EOF to signal the end of a TLS connection. 👋
  • -J, -j — Exit nonzero with an error message when the peer fails to ‘close_notify’, or ignore it. 😤
  • -Y, -y — Don't send, or send, a client certificate.
  • -k servername — Use SNI and provide a server name.
  • -K kimeout — Set a timeout for the TLS handshake.

🍓 ENVIRONMENT 🍓

🌸 Read

The following variables should be set before invoking s6-tlsclient, because they will be used by s6-tlsc-io(8):

  • CADIR
  • CAFILE — (alternative to CADIR)
  • KEYFILE — (if you're using a client certificate)
  • CERTFILE — (if you're using a client certificate)
  • TLS_UID and TLS_GID — (if you run s6-tlsclient as root)
🚨 Setting either CADIR or CAFILE is mandatory. not optional. mandatory. periodt.

🌈 Written

prog... is run with the following variables added to, or removed from, its environment by s6-tcpclient(8):

  • PROTO
  • TCPREMOTEIP
  • TCPREMOTEPORT
  • TCPREMOTEHOST
  • TCPLOCALHOST
  • TCPREMOTEINFO

Unless the -Z option is given to s6-tlsclient, the CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID variables will not appear in prog's environment. 🫥

🧚 EXAMPLES 🧚

CADIR=/etc/ssl/certs s6-tlsclient skarnet.org 443 s6-ioconnect

This will open a connection to the skarnet.org web server over TLS and verify its certificate via the trust anchors listed in the /etc/ssl/certs directory. It will then branch your terminal to it: try typing ‘GET / HTTP/1.0’ then hitting return twice. go on, live a little, it's giving main character energy 👑✨

👑 SEE ALSO 👑

s6-tls(7), s6-tlsc(8), s6-tlsc-io(8), s6-tlsd(8), s6-tlsd-io(8), s6-tlsserver(8), s6-ucspitlsc(8), s6-ucspitlsd(8)

[1] https://cr.yp.to/proto/ucspi.txt

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-networking/s6-tlsclient.html 🫶

💖 AUTHORS 💖

  • Laurent Bercot
  • Alexis <flexibeast@gmail.com> (man page port)

and that's the whole thing bestie 🎀 huge shoutout to the Debian squad — this one's from November 20, 2023, page S6-TLSCLIENT(8). mwah, slay, bye 💅💖

📦 where this page comes from