gtlsshd(8)

✨ gtlsshd ✨

ok so bestie, this is the gtlsshd page from the System Manager's Manual — it's the server side of the whole gtlssh situation, and it's literally the backbone of shell-over-TLS. buckle up 💖

🌸 NAME 🌸

gtlsshd — Server for shell over TLS

🦋 SYNOPSIS 🦋

gtlsshd [options]

💅 DESCRIPTION 💅

so the way gtlsshd works is: it catches connections coming in from gtlssh, does the whole authentication moment, and then hooks them up to a shell or a program, whatever was requested. main character energy fr.

gtlsshd will listen on both SCTP and TCP sockets unless you tell it otherwise. like, it's not picking favorites 💅

it uses openssl public key certificate authentication in both directions. when something connects, it uses standard SSL handling to validate itself to the user with the given key and certificate files. mutual, respectful, iconic.

on SSL does its job, it then runs an authentication protocol for the user on top of the SSL connection. the user sends the username, and gtlsshd will use the $HOME/.gtlssh/allowed_certs directory to authenticate a certificate the user presents. and if the user doesn't have a certificate that matches the presented certificate, gtlsshd will attempt a normal password login — if that's enabled. otherwise, no entry, bestie 🙈

---

🎀 WINDOWS HACKS 🎀

See "WINDOWS HACKS" in the gtlssh-keygen.1 man page for information about special windows configuration. (yes it's a whole thing, go read that one, iykyk 🪟)

---

🔐 TWO-FACTOR AUTHENTICATION 🔐

gtlsshd supports two-factor authentication in a number of ways, and honestly? versatile queen 👑

the certauth gensio supports sending a second authentication token, and gtlsshd will pick that up and use it if PAM asks for it. if it's not there but PAM asks for it, it will interactively prompt the user for the token — unless --nointeractive is specified. so like, no silent gap, it'll just ask you directly.

this requires, of course, proper PAM setup. it also direclty supports second authentication tokens with certificates. you can specify a different PAM authentication script for logins done with certificates using --pam-cert-auth to allow a second factor to be added for just certificate authentications. cute and targeted 💖

you can also request that the other end prompt for a second-factor authentication token and send it along with the password by adding the --do-2fa option. this will cause the other end to always ask for a second factor. no skipping. periodt.

---

⭐ OPTIONS ⭐

• -p, --port port — Use the given port instead of the default port.
• -h, --keyfile file — Use the given file for the key instead of the default. Defaults to sysconfidr/gtlssh/gtlsshd.key. On unix sysconfdir is generally /etc. On Windows it is one directory up from the executable with /etc appended.
• -c, --certfile file — Set the certificate to use. Defaults to sysconfdir/gtlssh/gtlsshd.crt. On unix sysconfdir is generally /etc. On Windows it is one directory up from the executable with /etc appended.
• --permit-root — Allow root logins. Otherwise root or uid=0 is denied. 🚫
• --allow-password — Allow password logins. By default only certificate-based logins are allowed. Passwords are much less secure than certificate logins, so their use is discouraged.
• --require-password — Require a password in addition to certificate logins. This is primarily for Windows systems that really need a password to be able to log in properly.

On Unix system, you generally use PAM for this, but if you set up PAM to require passwords even with certificates, you should also set this option so the password is transferred as part of the authentication protocol and not interactively.

• --do-2fa — Enable 2-factor authentication. This means that 2-factor authentication is enabled in PAM for gtlssh. This will cause the client end to request 2-factor data and transmit it over along with the password. During authentication, it is expected that PAM will request two authentication tokens and the first will be the password (if certificate failed). Note that this is not required to do 2-factor auth, but is useful to allow gtlssh to read the 2-factor data and transfer it as part of the login data.
• --pam-cert-auth <name> — If the connection is authorized with a certificate, still do a PAM authentication, but use the given name as the program name for PAM to use to find the rules. This will allow 2-factor auth to be done on a certificate login, as the given set of rules can be written to only do the second factor authentication part.
• --pam-service <name> — Use the given name for the pam service, instead of using the program's name.
• --use-login, --no-use-login — Use or do not use the login program to log the user in. Some systems work better with login, others work fine to directly execute the shell. The default depends on the system and should be best.
• --oneshot — Do not fork the program at the beginning or when a connection is received. This allows easier debugging of the program.
• --nodaemon — Do not daemonize (double fork) the program.
• --nointeractive — Disable interactive logins. All authentication information must be passed in via the protocol. This is different than gtlssh's view of interactive, which affects how I/O is done. This only affects prompting for credentials interactively.
• --sctp — Enable SCTP support.
• --notcp — Disable TCP support
• --other_acc <accepter> — Enable the given accepter to receive connections for gtlsshd. This does not disable TCP or SCTP.
• -P, --pidfile file — Create a standard pidfile using the given filename.
• -4 — Do IPv4 only.
• -6 — Do IPv6 only.
• -m, --enable-mdns — Enable MDNS service for this device. This allows gtlssh to find this with "gtlssh -m <name>".
• --mdns-name <name> — Sets the name used for finding this connection with mdns. The default is the first part of the hostname, before the first ., if any.
• --startup-retries — The number of times gtlsshd will retry creating the accepter. It retries once a second. Generally, if creating the accepter fails, that means the nameserver is not yet operational and converting the local name to an address fails, so this can help with the resolver not being ready when gtlsshd starts. Default is 30.
• -d, --debug — Generate debugging output. Specifying more than once increases the output. This also causes syslog output to go to standard error.
• --version — Print the version number and exit.
• -h, --help — Help output

ngl bestie, yes, -h shows up twice in this list — once for --keyfile and once for --help. that's literally what the page says, so we're keeping it exactly like that. no notes 💀

---

🌈 SEE ALSO 🌈

gensio(5), gtlssh(1), gtlssh-keygen(1)

---

💀 KNOWN PROBLEMS 💀

None.

like, zero. flawless. no bugs, we love to see it ✨

---

👑 AUTHOR 👑

Corey Minyard <minyard@acm.org>

---

ok that's the whole page bestie, go forth and serve some shells over TLS 🫶

Server for shell over TLS · version/date on the original: 01/02/19 · that's the System Manager's Manual energy right there, mwah 💋