gtlssh(1)

📦
version 3.0.4 · 3 versions
, in arch rolling, fedora 43, fedora 44

gtlssh / gsh — Shell connection over TLS 💅

okay bestie, sit down, hydrate, and let me tell you about the icon that is gtlssh(1) — and its lowercase twin gsh. no cap, this is the manual page you've been waiting for. 🫶

✨ SYNOPSIS ✨

gtlssh [options] <host> [<program>]
gsh [options] <host> [<program>]

literally just pick one of those two names and go. 🌸

💖 DESCRIPTION 💖

so here's the vibe: gtlssh connects to a remote server, authenticates the remote server using SSL, and then authenticates itself with the server. mutual trust, mutual slay. 🔥

gsh is a synonym for gtlssh that runs in ssh compatibility by default. same program, different energy. ✨

and gtlsshd will attempt an SCTP connection first, and fall back to TCP if that doesn't work. it's giving "try the fancy door first, then the normal door." 🚪

🪟 WINDOWS HACKS 🪟

See "WINDOWS HACKS" in the gtlssh-keygen.1 man page for information about special windows configuration. iykyk, windows girlies, go read that one. 🎀

⭐ OPTIONS ⭐

  • -p, --port port — Use the given port instead of the default port. 📮
  • -i, --keyfile file — Use the given file for the key instead of the default. If you specify this, the certfile will be the same name ending in .crt, unless you specify it explicitly. 🗝️
  • --certfile file — Set the certificate to use. 📜
  • --cadir directory — Set the directory that holds the certificate authority used to authenticate the server. 🏛️
  • -e, --escchar char — Specify a character to use for the escape character. Setting it to -1 disables the escape character. This can either be a decimal or hexadeximal number or ^x to set a control character. By default it is ^\ if io1 is the default and stdin is a tty, or disabled otherwise. See ESCAPES below for more details on the escape character. Only handled on io1. 🚪✨
  • --ssh-compat — Enable ssh-compatible command handling. Default for gsh, off by default for gtlssh.

gtlssh normally handles commands by passing individual arguments over as separate arguments then passing them to the remote command as such. In ssh compatible mode, it will work like ssh, combining all remaining arguments with a space between them and passing them as a single command.

gtlssh command handling is a little more sane, if you run gsh server ls '/a b' it will do what you expect. ssh will not. But some programs expect it to work as ssh does.

Added in gensio-3.0.4. 💖

  • --nossh-compat — Disable ssh-compatible command handling. bye compat. 👋
  • -r, --telnet — Do telnet processing with RFC2217 handling. 📞
  • --nosctp — Disable SCTP support. It is disabled by default. (so this is like, double-disabling? whatever, it's here.) 🙈
  • --sctp — Enable SCTP support. let's gooo 🔥
  • --notcp — Disable TCP support. 🚫
  • --transport <connecter> — Instead of using SCTP or TCP, use the given gensio connecter for transport. In this case, the host is required but the hostname part is ignored. This is so the username can be set, if required. 🚚
  • -m, --mdns — Look up the name using mDNS. This will fetch then IP address, IPv4 or IPv6, the port number and whether telnet is required and make the connection. 🦋
  • --mdns-type — Set the type used for the lookup. See the gmdns(1) man page under 'STRING VALUES FOR QUERIES' for detail on how to do regex, glob, etc. 🔍
  • --nomux — Don't use a mux gensio. This may cause issues with gtlsshd, but is useful in some cases for talking with ser2net with no mux support. 😬
  • --nointeractive — Not an interactive login, for programs and such. Do not prompt for passwords or do any other interactive operations. 🤖
  • --nointeractive-pw — If nointeractive is set, allow for prompting for a password on the console. You will only get one time to enter the password correctly. ⚠️ no pressure bestie
  • --privileged — When logging onto a Windows server, don't drop privileges on a privileged account. Normally you are logged in and run as a normal user (with a privileged linked token), this will allow you just run privileged. Requires --allow-root on the server. 👑
  • -L <accept addr>:<connect addr> — Listen at the <accept addr> on the local machine, and if a connection comes in forward it to the <connect addr> from the remote machine on the gtlssh connection. A local address is in the form [<bind addr>:][sctp|tcp,]port or <unix socket path>. Remote addresses are in the form <hostname>:[sctp|tcp,]port or <unix socket path>. If a name begins with / it is a unix socket path. <hostname> and <bindaddr> are standard internet names or addresses. 🔀
  • -R <accept addr>:<connect addr> — Like -L, except the <accept addr> is on the remote machine and <connect addr> is done from the local machine. 🔁
  • -4 — Do IPv4 only. 4️⃣
  • -6 — Do IPv6 only. 6️⃣
  • -d, --debug — Generate debugging output. Specifying more than once increases the output. 🐛 (stack it like a combo, fr fr)
  • --version — Print the version number and exit. 📋
  • -h, --help — Help output. 🆘

🔐 HOST AUTHENTICATION 🔐

After connecting, the host is first validated using standard SSL. The keys used for validation are in $HOME/.gtlssh/server_certs by default. If the given key is not recognized, the user is prompted with the certificate fingerprint asking if the user wants to accept the certificate. 👀

If the user accepts the certificate, then it is added into the default directory. If not, the connection is terminated. bye. 💀

Certificates are stored in the form "<hostname>,<port>.crt" and "<ipaddress>,<port>.crt". Both are created for a connection (unless connecting with an IP address). A connection is verified as matching both entries, if the certificate in the file does not match the certificate from the remote end, the connection is terminated and the user informed. 🚨

🫶 USER AUTHENTICATION 🫶

If host authentication succeeds, gtlssh authenticates itself with a key and certificate. These files are fetch by default from $HOME/.gtlssh/keycerts in the form <host>[,<port>].key and <host>[,<port>].crt. If the form with the host and port exists, that is taken. Otherwise if the form with just the host exists, it is taken. Otherwise it defaults to $HOME/.gtlssh/default.key and $HOME/.gttlssh/default.crt. 🗂️

The remote end looks in $HOME/.gtlssh/allowed_certs for the certificate. If the remote end does not have the certificate presented, then password authentication is tried. 🔑

💫 ITERACTIVE MODE 💫

If the stdin for gtlssh is a tty and no program is given to run, then the login is an interactive login. Any sort of delay in I/O processing is disabled, and the local terminal is used for I/O and it is put into raw mode. 🖥️✨

In non-interactive mode, the local side uses stdio for local I/O and I/O processing delay on the network side is not disabled. This is useful for programs transferring data over the connection. 📦

🚪 ESCAPES 🚪

If the escape character is received from the user, the character is not transferred and the program waits for another character. If the other character is also the escape character, a single escape character is sent. If the other character is not recognized as a valid escape, it is ignore and not transferred. Upper and lower case are equivalent. 💅

Escape characters are:

  • q — Quit the program. 🚪
  • b — Send a break to io2. Ignored if io2 does not support break. 🛑
  • d — Dump serial data for io2. Ignored if io2 is not a RFC2217 capable. 📊
  • s — Set the serial port (baud) rate for io2. Ignored if io2 is not RFC2177 capable. After this, the serial port speed must be typed, terminated by a new line. Invalid speeds are ignore, use escchar-d to know if you set it right. ⏩
  • n, o, e — Set the parity on io2 to none, odd, or even. Ignored if io2 is not RFC2217 capable. ⚖️
  • 7, 8 — Set the data size on io2 to 7 or 8 bits. Ignored if io2 is not RFC2217 capable. 🔢
  • 1, 2 — Set the number of stop bits to 1 or 2 on io2 bits. Ignored if io2 is not RFC2217 capable. 🛑

👀 SEE ALSO 👀

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

go read those too, they're all part of the fam. 🫶

💀 KNOWN PROBLEMS 💀

None.

(not me being shook. she's flawless. periodt. 👑)

🌟 AUTHOR 🌟

Corey Minyard <minyard@acm.org>

and that's the whole thing bestie!! 🌈 this was the gtlssh(1) page, Shell connection over TLS, from 01/02/19 — go forth and connect securely, you absolute icon. 💖✨🎀🦋🌸

📦 where this page comes from