ZSSH(1)

💖 ZSSH(1) 💖

okay bestie, welcome to the zssh manual, section 1 of the ZSSH docs. grab a snack, we're going in 🍓

---

✨ NAME ✨

zssh — your interactive file transfer wrapper for ssh. that's the whole vibe. she's a wrapper, she's interactive, she moves files. iconic behavior honestly 👑

---

🌸 SYNOPSIS 🌸

zssh [zssh options] [--] [ssh options]
ztelnet [zssh options] [--] [telnet options]

like, that's the shape of her. yes there's a second one, we'll get to her 💅

---

🦋 DESCRIPTION 🦋

okay so zssh (short for Zmodem SSH, cute right?) is a program for interactively transferring files to a remote machine while you're using the secure shell (ssh). she's meant to be the convenient alternative to scp, so you can move files without having to open another session and re-authenticate yourself. no cap, that's the entire point. no extra logins, no extra windows, just vibes ✨

zssh is an interactive wrapper for ssh used to switch the ssh connection between the remote shell and file transfers. how does she do it? by using another tty/pty pair between you and the local ssh process, so she can plug either your tty (that's remote shell mode) or another process (that's file transfer mode) onto the ssh connection. she's literally just swapping who's holding the aux cord 🔥

ztelnet behaves similarly to zssh, except telnet is used instead of ssh. it is equivalent to:

zssh -s "telnet -8 -E"

Files are transferred through the zmodem protocol, using the rz and sz commands.

zssh behaves as a usual ssh session until the escape sequence is depressed. the default is ^@, which you can produce by pressing C-space, or C-2, or **C-** — three options, pick your fighter 🙈 that's what enables **file transfer mode**. a new prompt is then displayed, and commands can be executed **locally** to initiate file transfers (among other things). she roughly behaves as a local shell featuring line edition, history and completion (thanks to libreadline), globbing, and escape characters (", 'and`). it's giving "shell but make it a side quest" 🧚

The following builtins are handled by zssh itself:

?, cd, disconnect, escape, exit, help, hook, quit, repeat, rz, suspend, sz, version

and here's the full rundown of every single one, no skipping, periodt 💅

• cd <dir> — change current directory
• disconnect — disconnect and exit
• escape [^X] — Change escape key to ^X. Without argument, print current escape key
• exit — exit file transfer mode. ^D may also be used for this purpose.
• help, ? — print help and tips
• hook prg [args] — Hook program 'prg' on the the pty. Its standard input and output will go through the ssh channel. typing 'sz'/'rz' is in fact equivalent to 'hook sz'/'hook rz'. A weird imagination is most useful to gain full advantage of this feature.
• quit — same as exit.
• repeat — repeats cmd forever (^C to interrupt). Useful for example if you use a remote script invoking "sz" and you don't want to be typing "rz" each time... Remember however that several files can be transferred by a single sz/rz pair so this is not usually necessary to use repeat.
• rz — Receive files from the remote machine. runs rz and plugs the process on the ssh connection. running sz on the REMOTE machine is required :
  1. run `sz <remote_file> ...` from the remote machine shell
  2. press the escape sequence (C-space) to enter file transfer mode
  3. run the `rz` builtin
• suspend — suspend zssh (back to the local machine shell)
• sz <file> ... — Send files to the remote machine. runs sz and plugs the process on the ssh connection. There is no need to manually run rz on the remote side.
• version — print version information

also important: the builtins rz, sz, hook and exit return to shell mode after completion. they know when to leave the party 🫶

---

✨ OPTIONS ✨

• -f, --force — Do not ask user any question
• -h, --help — show basic help
• -s cmd, --shell cmd — run cmd as remote shell instead of the default "ssh -e none" (zssh) or "telnet -8 -E" (ztelnet) ex: zssh -s "rsh -x"
• -V, --version — show version
• -z ^X, --zssh-escape ^X — set escape sequence to ^X

-- may be used to separate zssh options from ssh ones. Other arguments are passed verbatim to ssh/telnet/whatever. she's not gonna gatekeep your flags 💜

---

🌈 ENVIRONMENT 🌈

• ZSSHESCAPE — Setting the ZSSHESCAPE environment variable allows one to override the default escape sequence. ZSSHESCAPE should contain only two characters of the form `^X', meaning that ^X is to be the new escape sequence.

---

🎀 REQUIREMENTS 🎀

the following binaries need to be properly installed for zssh to work :

• ssh/telnet/... — the remote shell to be executed (local machine)
• sz rz — zmodem send and receive programs. Should be both on local and remote machine, and (hopefully) of compatible versions.

ngl the "(hopefully)" is doing a lot of heavy lifting there 😭 but it's what the manual says and we respect her

---

⭐ TIPS ⭐

If file transfer is initiated but never completes — ie a line like:

Bytes Sent:  38144/4610624   BPS:3424     ETA 22:15

or

Bytes Sent:      0/    513   BPS:0        ETA 00:00  Retry 0: Got ZCAN

can be seen, but transfer never completes — chances are the pty/tty on one of the systems are not 8-bit clean. (Linux is 8-bit clean, NetBSD is not). Using the -e (escape) option of rz should solve this problem.

Transfers can be interrupted with ^C (somewhat experimental =)

If you get stuck in rz/sz (for example you've just ran rz, but you then decided not to transmit anything), hit a dozen ^X (Ctrl-X, not the zssh escape!) to stop it. yes this is real, no this is not a drill 💀

Use `sz -y <files>' to overwrite files on the other side.

---

💅 BUGS / LIMITATIONS 💅

You may sometimes have to hit return 2 or 3 times after file transfer completion in order get back to the shell. Some digits are usually displayed; don't worry it won't harm (you or your term) ...

the tty may (sometimes) be somewhat upset after an interrupted transfer ( using ^C ). typing `reset' in this case should help.

no pipe, redirection (and other stuff) support in shell ... but after all there are already wonderful shells around =)

lowkey she's right. she does one thing and she does it. main character energy but make it scoped 🌸

---

🫶 CREDITS 🫶

• ttssh's author — Robert O'Callahan — for the original idea
• The sourceforge team.

---

👑 AUTHOR 👑

Matthieu Lucotte <gounter@users.sourceforge.net>

zssh homepage: http://zssh.sourceforge.net

---

🔥 SEE ALSO 🔥

ssh(1), telnet(1), scp(1), sz(1), rz(1), readline(3),

---

and that's the whole thing bestie 💖 this was the ZSSH manual page, dated June 26, 2000, and it's been serving ever since. go transfer some files, you've got this 🦋✨