# Saltbush Terminal

Saltbush Terminal is a desktop terminal with a classic session-oriented workspace for local shells, remote systems, BBSes and serial devices.

## Features

**Tried on real computers:** tear-off tabs and RDP sessions (new in 1.8.0) have been tried on a Linux desktop and on Windows with several monitors, including two RDP sessions at once. The system RDP program option (FreeRDP or mstsc) has not been tried.

### Connections
- A built-in SSH2 engine (libssh): host-key checks against `~/.ssh/known_hosts`, agent, key-file (with passphrase), OpenSSH certificate (RSA, ECDSA and Ed25519), Kerberos (GSSAPI), keyboard-interactive and password logins asked in the terminal, remote commands, local/remote/dynamic (SOCKS) port forwards, X11 forwarding (with a fake cookie, trusted or untrusted like `ssh -Y`/`-X`), agent forwarding, compression, jump hosts (one or a chain), proxy commands, keepalive, algorithm choices, a FIPS-approved-algorithms mode and most OpenSSH `-o` options. It reads `~/.ssh/config`.
- The OpenSSH client (`ssh`) as an alternative engine per session; it is used automatically for `-o` options the built-in engine does not handle and (on Windows) agent forwarding.
- Copy Public Key to Server (Tools menu, right-click an SSH session, or the key generator's Copy to Server button): like `ssh-copy-id`, it logs in once (with your password if needed), creates `~/.ssh` and `authorized_keys` if they are missing, sets the permissions SSH requires (700 and 600), adds the key unless it is already there, then checks that the key logs in on its own.
- Tools → SSH Agent: see the agent's keys, add key files (with a lifetime or confirm-on-use), add and remove smartcard or token keys (PKCS#11, e.g. OpenSC or a YubiKey), remove keys, lock and unlock the agent, or start an agent for Saltbush's sessions.
- SFTP browser (Transfer → SFTP Browser, or right-click an SSH session): two panes, this computer and the server side by side, also through jump hosts. Upload and download files and folders (also by double-clicking or dropping files on the window), resume interrupted transfers, make folders, rename, delete and change permissions, with progress and Cancel. Modification times are kept. SFTP tabs (the `sftp` program) are still available.
- RDP sessions (Windows Remote Desktop) in a tab: TLS + NLA, fit-to-tab resizing, keyboard and mouse, text clipboard, a remembered server certificate, and optionally the system RDP program (FreeRDP or mstsc).
- Built-in Telnet (window size, terminal type, binary mode, suppress-go-ahead, bare CR), RLogin (with the server's window-size requests) and raw TCP.
- Serial ports at any baud rate, 5–8 data bits, none/odd/even/mark/space parity, 1 or 2 stop bits, RTS/CTS or XON/XOFF flow control, and Send Break.
- Local shells with a chosen program, arguments, starting folder and environment.
- Logon automation: a pre-connect command, a remote command, expect/send pairs, an initial carriage return and logon scripts (Python, Lua or any program).
- Automatic reconnection with back-off, close or clear on disconnect, SSH keepalive and anti-idle text.

### Terminal
- Tear-off tabs: drag a tab out to give it its own window, and dock it back with a button, by closing the window or by dragging it onto the tab bar.
- Split panes: View → Split Left/Right (Ctrl+Shift+E) and Split Top/Bottom (Ctrl+Shift+O); click a pane to type in it, drag the divider to resize.
- VT220/xterm emulation: DEC line-drawing and other character sets (G0–G3), tab stops, insert mode, origin mode, scroll regions, cursor shapes set by programs, dim/hidden/strikethrough text, reverse-video screen, double-width and double-height lines, left/right margins, 132-column mode, selective erase, 8-bit C1 controls, sixel graphics, device-attribute and mode reports. Wyse 60 and SCO ANSI terminal types translate their own control codes and send their own keys.
- VT/xterm screen with 256 colours and true colour, a scrollback length per session (up to 1,000,000 lines), find (wraps round) and selection by drag, double-click (word) and triple-click (line).
- BBS support: CP437 and the ANSI-BBS screen (bold = bright, blink, iCE colours, CP437 pictures for control codes), the built-in 8×16 VGA font, 80×25 scaled to the window, BBS keys, replies to cursor-position queries (ANSI detection) and Zmodem downloads that start by themselves.
- Character sets: UTF-8, CP437, ISO-8859-1, Windows-1252, KOI8-R, Shift_JIS and GB18030.
- Three resize modes: follow the window, scale the font to a fixed grid, or keep both fixed.
- Per-session colours, cursor colour, shape and blink, font family and size, tab title, highlighting rules and key mappings (edited in tables).
- Paste safety: bracketed paste, a question before pasting several lines, and paced pasting (line and character delays, wait for a prompt).
- Optional remote clipboard writes (OSC 52), ENQ answerback, local echo, CR translation and 7-bit mode.

### Scripting
- Python and Lua 5.4 scripts (Lua is built in) with the same interface as Lantern Terminal: send text, wait for prompts, read the screen, change settings, open tabs, Zmodem uploads, dialogs. See `SCRIPTING.md`.
- Scripts written for Lantern Terminal and for the SyncTERM-Lua fork run unchanged.
- Logon scripts, Script > Run (F12, remembers the last script) and Cancel, Run Last Script Again (Ctrl+F12), recording to a Lua or Python script, and an Activity pane for output and errors (select and copy while a script runs).

### Workspace
- Saved sessions in folders, a filterable Session Manager with multi-select (Ctrl+click), multi-session editing (only changed settings apply), duplicate and delete with confirmation.
- File → New Session wizard and Tools → New BBS Session wizard, Quick Connect, Save Session As.
- BBS Directory (toolbar button or Tools → BBS Directory): a dialling directory of BBS systems, apart from your saved sessions. Update lists downloads the Synchronet BBS List and the Telnet BBS Guide (only when you press it); the BBSes you have called stay at the top under Recent, with the Kalgoorlie Retro BBS always first. Connect opens the BBS in a tab with the BBS settings; Save as session adds it to the Session Manager. Add your own BBSes, edit the list addresses, and a list update never changes a BBS you have called (a new address is offered instead). The same file format as Lantern Terminal.
- Tools → Import BBS List reads a SyncTERM dialling directory; Apply BBS Settings works on one tab, selected sessions or a whole folder.
- Credentials: user names in the settings, passwords in the desktop password store (`secret-tool`, Windows Credential Manager or the macOS Keychain).
- Sync between computers through a shared folder (Global Options > Sync): sessions, folders, credential user names, button bars and the default session. Passwords are never synced.
- Button bars that send text or run actions, per session or for all sessions.
- Session logs as plain text or raw bytes, with file-name templates, timestamps, a line prefix, rotation at midnight and connect/disconnect messages. Logs are created readable only by you.
- Built-in Zmodem, Ymodem, Xmodem (checksum, CRC and 1K) and Kermit uploads and downloads on Linux and Windows; Zmodem and Kermit downloads start by themselves.
- SSH key generation (Ed25519 or RSA); the passphrase never appears on a command line.
- Command window that sends to the active tab or to every open tab.
- Update notifications: a daily check for a new version, with Update Now, Not Now and Skip This Version, and Help → Check for Updates (see "Updates" below).

## macOS

The source builds on macOS 11 or later with Homebrew: `xcode-select --install`, install Rust, `brew install libssh openssl@3 pkg-config`, then `scripts/build-macos.sh`. It makes `dist/Saltbush Terminal.app`, a .zip and a .dmg (signed ad hoc; on another Mac, Control-click > Open the first time). Settings are kept in `~/Library/Application Support/saltbush`. This has not yet been tried on a Mac.

## Windows

`saltbush-<version>-windows-x64-setup.exe` installs for the current user (no administrator rights) with a Start menu shortcut and an uninstaller; `saltbush-<version>-windows-x64.zip` is the same program as a folder to run from anywhere. Settings are kept in `%APPDATA%\saltbush`. Python scripts need Python 3 from python.org (`python` on the PATH); Lua is built in. The OpenSSH engine and SFTP use Windows' own `ssh.exe` and `sftp.exe`.

## Requirements

Linux x86_64 with X11 or Wayland and OpenGL. The built-in SSH engine uses libssh (`libssh-4`); SFTP sessions and OpenSSH-engine sessions need `openssh-client`. Python scripts need `python3`. Stored credential passwords need `libsecret-tools` (`secret-tool`).

## Install

### Debian package (Debian, Ubuntu, Mint and similar)

```sh
sudo apt install ./saltbush_1.9.2_amd64.deb
```

`apt` installs the required libraries and suggests `libsecret-tools`. Remove it with `sudo apt remove saltbush`.

### Any distribution (no root needed)

```sh
tar xf saltbush-1.9.2-linux-x86_64.tar.gz
cd saltbush-1.9.2-linux-x86_64
./install.sh
```

The installer puts `saltbush` in `$HOME/.local/bin` and a launcher in `$HOME/.local/share/applications`. `./install.sh --uninstall` removes them again. `./install.sh --root /absolute/staging-directory` installs under another folder for testing.

## Build from source

```sh
cargo test
cargo build --release
./target/release/saltbush
scripts/build-packages.sh     # makes dist/*.deb and dist/*.tar.gz
scripts/build-windows.sh      # makes the Windows installer and zip (cross-compiled)
```

Building needs Rust (Cargo) and the development libraries for `eframe`, `rfd` and `arboard`. The project includes a patched copy of the `vt100` crate in `vendored/vt100` (see `vendored/vt100/SALTBUSH-PATCHES.md`).

## Updates

Once a day, a few seconds after it starts, Saltbush reads https://retro.theiguru.au/saltbush/latest.json, a small file that names the newest version and its downloads. It sends nothing about you except the program version and operating system in the User-Agent. When a newer version is out, a window shows its release notes with three choices:

- **Update Now** downloads the new package with `curl`, checks it against the published SHA-256 checksum and installs it:
  - Debian package (`/usr/bin/saltbush`): installs the new `.deb` with `pkexec apt-get install`, which asks for your password, then offers to restart Saltbush.
  - Windows installer: runs the new setup program and closes Saltbush so it can replace the files.
  - Portable ZIP, tar archive or a source build: opens the download page instead.
- **Not Now** asks again at the next daily check.
- **Skip This Version** stops notices for that version; you will hear about the one after it.

Help → Check for Updates checks at any time, even for a skipped version, and says when you already have the latest. Turn the daily check off with "Tell me when a new version is available" in the update window or Options → Global Options. Downloads are kept in `~/.cache/saltbush/updates` (Linux) or the temporary folder (Windows). `SALTBUSH_NO_UPDATE_CHECK=1` disables the automatic check for one run.

## Configuration and shortcuts

Settings are JSON in `$XDG_CONFIG_HOME/saltbush` or `$HOME/.config/saltbush`; `SALTBUSH_CONFIG` overrides the folder. The file is written atomically and readable only by you. If it cannot be read, it is kept as `settings.json.bad-<date>` and defaults are used; it is never silently overwritten.

Application shortcuts use Ctrl+Shift so that Ctrl keys (Ctrl+C, Ctrl+D, Ctrl+W, Ctrl+R …) reach the terminal:

| Keys | Action |
| --- | --- |
| Ctrl+Shift+N | New session |
| Ctrl+Shift+Q | Quick Connect |
| Ctrl+Shift+T | Local shell |
| Ctrl+Shift+S | Save session |
| Ctrl+Shift+C / Ctrl+Shift+V | Copy / paste (Shift+Insert also pastes) |
| Ctrl+Shift+F | Find |
| Ctrl+Shift+P | Command palette |
| Ctrl+Shift+R / Ctrl+Shift+D | Reconnect / disconnect |
| Ctrl+Shift+W | Close tab |
| Ctrl+Shift+E / Ctrl+Shift+O | Split the active pane left/right / top/bottom |
| Ctrl+Tab / Ctrl+Shift+Tab | Next / previous tab |
| F1 | Help (keyboard shortcuts) |
| F2 | Session Options |
| F3 / Shift+F3 | Find next / previous |
| F4 | Quick Connect |
| F5 | Reconnect |
| F6 | Next split pane |
| F7 | SFTP Browser (SSH sessions) |
| F8 | Send a file (Zmodem upload) |
| F9 | Start / stop session logging |
| F10 | Sent to the remote program |
| F11 | Full screen |
| F12 / Shift+F12 / Ctrl+F12 | Run a script / cancel it / run the last script again |
| Alt+F1 … Alt+F12 | Send the plain function key to the remote program |

Session Options > Input can make plain Ctrl+C and Ctrl+V copy and paste instead, and can send all function keys to the remote program. A key mapping (Session Options > Key Mappings) wins over the function keys above.

## Screenshot mode

```sh
xvfb-run -a -s '-screen 0 1280x900x24' \
  env SALTBUSH_CONFIG="$PWD/test-config" \
  saltbush --screenshot "$PWD/terminal.png"
```

`--screenshot-options`, `--screenshot-keys` and `--screenshot-wizard` capture those dialogs. A file name containing "bbs" captures the BBS screen.

See `LIMITATIONS.md` before relying on remote or emulation-specific behaviour, and `CHANGELOG.md` for changes.

## License

Saltbush Terminal's source is MIT-licensed. Third-party crates keep their own licences; the patched `vt100` crate's licence is in `vendored/vt100/LICENSE`, and the VGA font's licence is in `third_party/licenses/`.