Remote Access/en

Language:	English

Remote access is the ability to drive a remote computer or network from this expecco image — opening shells, running commands, moving files, or driving a test target. Three protocol families are supported, listed in current-recommended order:

• SSH and SFTP (recommended) — encrypted shell + secure file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation in exept:libcrypt/ssh; no external dependency on OpenSSL or libssh. Use this for anything that touches credentials or sensitive payloads.
• Local Command Shell — fork + exec on the local machine. Used for local-tool integration and for the local end of a remote workflow that bridges via another protocol.
• Telnet (legacy) — plain-text terminal session. No encryption, passwords on the wire in clear. Use only when the target hardware has no other option.

SSH and SFTP

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305 transport cipher and the SFTP v3 file-transfer subsystem (draft-ietf-secsh-filexfer-02). Two layers:

• SSH::Client — programmatic SSH access (remote

exec, TTY shell, agent forwarding, ProxyJump bastion).

• SSH::SftpFilename — a Filename subclass that lets the rest of ST/X treat a remote SFTP path the same way it treats a local file.

The rest of this section is organised user-task-first: what the user sees and does, the expecco-library hooks below that, then the implementation detail at the end for the curious.

From the FileBrowserV2

Open the location dropdown and paste an sftp:// URL. The browser tab populates as if it were a local path. Tree expansion, column sort (name / size / mtime), preview, and double-click-to-open-in-editor all behave normally. The first click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent clicks reuse the pooled connection.

URL syntax:

sftp://[user[:password]@]host[:port]/remote/path

User defaults to the local login name, port to 22, path to /. The optional :password piece is the RFC-3986-style userinfo password — see #Password authentication for when this is appropriate and what the security trade-offs are. When present, it is used as a USERAUTH fallback after the normal publickey/agent attempts and is never re-emitted by the printable URL form, so logging the filename does not leak the credential.

The Refresh button in the toolbar (the round-arrow icon between Forward and DirectoryUp) re-reads both the directory tree and the contents pane on demand. Works uniformly for local and SFTP paths; for SFTP it also flushes the per-file STAT cache, so changes made directly on the remote side become visible immediately rather than waiting for the 5-second cache TTL to expire.

The small arrow next to the Refresh icon opens a dropdown with a single checkbox, Automatic Refresh, controlling the background polling task that walks every expanded tree item to detect external changes. The default depends on the current root:

• Local filesystem → on (10-second cycle, matches the long-standing behaviour).
• SFTP → off. Each cycle costs one STAT round-trip per child, which is fine for a handful of local directories but painful over the network. Click Refresh manually when you need to pick up remote changes.

When you navigate between local and SFTP roots the toggle flips automatically — but only if you haven't overridden it for the previous root. An explicit user choice is preserved across navigations.

The Tools menu offers four browser actions, three of them gated on the SSH library being loaded:

• Generate SSH Key Pair... — opens the same key-generation dialog described under #Generating an SSH key pair below.
• SSH Connect... — opens an interactive VT100 terminal to a remote host.
• SFTP Connect... — points this browser tab at a remote filesystem via SFTP.
• Filesystem Info... — shows size, free space and usage of the filesystem holding the currently displayed directory. Works uniformly for local paths and SFTP paths; for SFTP it requires the server to advertise the statvfs@openssh.com extension (every modern OpenSSH does). Sizes are reported in IEC binary units (MiB, GiB, TiB) — the largest unit yielding a value ≥ 1 is chosen, so a TB-scale volume reads as X TiB rather than 10240 GiB.

From the Launcher

The Launcher's Workspace submenu carries two stand-alone entries (gated on the SSH package being loaded):

• SSH Terminal — prompts for a target in the form user[:password]@host[:port] and opens a top-level VT100 terminal connected to it. No FileBrowser involved — this is the launcher analogue of the FileBrowserV2 Tools → SSH Connect... entry.
• SFTP Connection — prompts for an SFTP target (same URL grammar as the FileBrowserV2 location bar, see #From the FileBrowserV2) and opens a fresh FileBrowserV2 already navigated to that path.

Both entries honour the URL-embedded password syntax described in #Password authentication.

From expecco actions

The Expecco RemoteAccess plugin (Expecco::RemoteAccessImportPlugin) exposes the following test actions to the expecco action palette:

• CmdShell - Open SSH Remote Connection — opens an SSH session via the platform's ssh binary (PuTTY's

plink on Windows).

• CmdShell - Open SSH Remote Connection and PublicKey — same but with explicit public-key authentication.

To run these you need a configured keypair (private key on this machine, public key in the remote host's ~/.ssh/authorized_keys). Generate one via the dialog below or via ssh-keygen.

The plugin also adds a settings page at Extras → Settings → Plugins → Remote Access — SSH Keys carrying a single Generate SSH Key Pair... button that opens the same dialog.

Generating an SSH key pair

The dialog (FileBrowserV2 / settings page)

The dialog asks for all parameters in one form:

• Comment — embedded in the generated key (defaults to

stx@<hostname>).

• Storage:
  • Save to disk file only — writes ~/.ssh/id_ed25519_stx (or wherever) plus a matching .pub companion.
  • Save to disk AND load into ssh-agent — writes the file and also hands the key to the running ssh-agent.
  • Load into ssh-agent only — key lives in agent memory only; gone on agent restart.
• Private key file — full path; disabled in agent-only mode.
• Passphrase / Confirm — empty leaves the on-disk file unencrypted (agent-only mode ignores the passphrase, since the OpenSSH agent wire protocol carries only the decrypted key).

On Generate, the public-key line (the same ssh-ed25519 AAAA... comment string ssh-keygen emits) is copied to the system clipboard for pasting into the remote host's ~/.ssh/authorized_keys.

From a workspace

For headless deployments, sandboxed builds, or scripts, SSH::Client exposes a pure-Smalltalk key generator that produces output bit-compatible with ssh-keygen -t ed25519:

| seed comment priv |
seed    := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
    saveOpenSshEd25519Seed:seed
    toFile:priv
    comment:comment
    passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
    (SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).

Keys generated this way are interoperable with OpenSSH's own tooling (ssh-keygen -y -f ... re-derives the public key, ssh-keygen -p -f ... changes the passphrase, etc.).

Using the shell tools instead

The traditional path also works:

ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519

Preparing ssh-agent

The agent path is strongly preferred over reading raw keyfiles: it keeps encrypted private keys unlocked once per session, and handles identities (hardware-token-backed keys, KeePassXC entries) that ST/X should never see directly.

ST/X picks the agent path automatically when $SSH_AUTH_SOCK is set in the process environment at the time stx is launched. Setting it later from a workspace does not help.

Linux / macOS

Most desktop distributions launch an agent automatically as part of the session (gnome-keyring on GNOME, ssh-agent.service on systemd, KWallet on KDE). Verify in a terminal:

echo $SSH_AUTH_SOCK    # /run/user/1000/keyring/ssh or similar
ssh-add -l             # lists loaded identities
ssh-add ~/.ssh/id_ed25519   # load yours if not loaded

If no agent runs at all, add this snippet to your shell rc:

# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
    eval "$(ssh-agent -s)" > /dev/null
fi

ST/X must be launched from a shell that has seen this rc — a desktop launcher started from the file manager does NOT inherit the variable. Wrap the stx start command in a small script under ~/.local/bin/ that sources the rc first.

The Remote Access settings page (Extras → Settings → Plugins → Remote Access — SSH Keys) shows whether the running image sees an agent.

Permanent setup via systemd

For a truly cross-session agent (survives desktop logouts, comes up automatically at next login), enable the per-user systemd unit shipped with most distros' openssh-clients package:

systemctl --user enable --now ssh-agent.service

Then point SSH_AUTH_SOCK at the user-service socket in your shell rc (this replaces the eval $(ssh-agent -s) snippet above):

export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"

Auto-loading keys on first use

To skip the manual ssh-add step, let OpenSSH load keys into the agent automatically the first time they are needed. Add to ~/.ssh/config:

Host *
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519

The first SSH connection then prompts for the key passphrase once and hands the unlocked key to the agent; subsequent connections use the cached identity without prompting.

Windows

Windows 10+ ships native OpenSSH including an agent service. One-time setup:

1. Open Services (services.msc) as Administrator.
2. Find OpenSSH Authentication Agent, set Startup Type to Automatic, click Start.
3. In PowerShell: ssh-add $HOME\.ssh\id_ed25519.
4. Verify: ssh-add -l.

The Windows OpenSSH agent listens on a named pipe (\\.\pipe\openssh-ssh-agent), not a Unix socket. ST/X supports both transports, but Windows ssh-add does not set SSH_AUTH_SOCK for you. Add it manually:

1. Press Vorlage:Key → type "environment" → "Edit the system environment variables".
2. Environment Variables → under User variables, New.
3. Name: SSH_AUTH_SOCK
4. Value: \\.\pipe\openssh-ssh-agent
5. Log out and back in (or restart stx) so the new env propagates.

PowerShell quick-setup

The same setup from an elevated PowerShell prompt, for scripts or unattended provisioning:

# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
    'SSH_AUTH_SOCK',
    '\\.\pipe\openssh-ssh-agent',
    'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519

For a one-shot agent start without making it persistent (e.g. single-session test), drop the Set-Service line and just run Start-Service ssh-agent. The env-var line can also be omitted if SSH_AUTH_SOCK is only needed in the current shell — use $env:SSH_AUTH_SOCK = '...' instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not be present. Add it once via Settings → Apps → Optional features → OpenSSH Client.

Alternative agents:

• PuTTY pageant — uses its own protocol; NOT supported by ST/X's SSH::Agent. Migrate the keys to OpenSSH.
• Git for Windows ssh-agent — works; point

SSH_AUTH_SOCK at the socket it publishes.

• WSL 2 — a ST/X inside WSL sees WSL's Linux agent normally; a ST/X on the Windows side does not. Bridging needs a helper like npiperelay + socat.

Verify in the Remote Access settings page (Extras → Settings → Plugins → Remote Access — SSH Keys) — the agent indicator there reports whether the running image sees the agent.

Auto-loading keys on first use

Windows OpenSSH does not persist agent-loaded keys across agent restarts. To avoid running ssh-add manually after each reboot, add the same lazy-load configuration to %USERPROFILE%\.ssh\config:

Host *
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519

OpenSSH then loads the key into the agent on first use (prompts for the passphrase once) and reuses it for the rest of the session.

Password authentication

Public-key (with or without ssh-agent) is the recommended path. Password authentication is supported as a fallback for the cases where keys are not available: legacy hosts, on-the-fly access to a test box, scripted access to an account whose owner refuses to add your public key. Keep in mind:

• The plaintext password lives in memory on the ST/X side for the lifetime of the SSH::Client — treat it like any other in-memory secret.
• The server still controls which methods it accepts. If sshd_config has PasswordAuthentication no, no Smalltalk-side configuration can override that.
• Wire-level the handshake is RFC 4252 §8: the password is sent inside the encrypted SSH transport, never in clear over the network.

From a URL

Both the FileBrowserV2 location bar and the launcher's Workspace → SFTP Connection / Workspace → SSH Terminal prompts accept an inline password in the standard RFC-3986 userinfo position:

sftp://alice:s3cret@host.example.com/srv/data
ssh   alice:s3cret@host.example.com:2222

The parser splits on the last @ so passwords containing @ still parse; the first : inside the userinfo separates user from password. Passwords containing : are not supported in this form — use the programmatic API below.

The password is stripped from the printable URL: every place that ends up logging or displaying the filename (status line, printOn:, nameString, the breadcrumb path) shows the credential-free form sftp://alice@host.example.com/....

From code

Two equivalent ways to attach a password to an SSH::Client:

"/ literal -- simplest, password is just an ivar
client := SSH::Client newToHost:'host.example.com' port:22 user:'alice'.
client password:'s3cret'.
client connect.

"/ callback -- lazy; the password never lives on the client.
"/ Useful with an interactive prompt, a keychain lookup, or a
"/ vault-fetched secret that you do not want long-lived in memory.
client passwordCallback:[ Dialog requestPassword:'SSH password' ].
client connect.

The callback wins if both are set. Both are evaluated lazily during #connect, after publickey/agent attempts have been rejected, so a working key always wins over a password when both are configured.

Authentication order

SSH::Client>>authenticate walks every available credential in this order, returning on the first one the server accepts:

1. ssh-agent identities, if #useAgent was called and the agent has loaded keys.
2. ed25519 private-key seed, if #privateKeyFromFile: picked one up.
3. RSA private key.
4. ECDSA private key.
5. Password, if #password: / #passwordCallback: was set and the server still advertises password in its USERAUTH_FAILURE methods list.

Each step is skipped when the server's last USERAUTH_FAILURE reply dropped the relevant method from its allowed list — we do not bang on publickey after the server stops offering it. The password attempt is only fired when the server still wants password, so a misconfigured client password against a key-only server raises a clean SSH::AuthenticationError without an extra useless round-trip.

Configuration

All tunables are class-side on SSH::SftpFilename:

Accessor	Default	What it controls
#idleEvictionSeconds:	240 (4 min)	How long a pooled connection sits idle before the next access proactively closes + reopens it. Just under typical sshd ClientAliveInterval × ClientAliveCountMax so we recycle before the server TCP-RESETs us. Pass nil to restore the default.
#attrsCacheTtlSeconds:	5	Max age (s) of a cached STAT before #ensureAttrs refetches. Parent listDir always re-stamps fresh attrs onto children, so navigating an open directory does not pay the TTL. Set to 0 to disable caching.
#closeAllConnections	(action)	Tears down every pooled connection. Useful after a known-bad network event, before a deliberate identity swap, or as part of a clean image shutdown.

Diagnostics

SemaphoreMonitor

Open SemaphoreMonitor from the Launcher's "Status" sub-menu. Per-host SFTP mutex appears as SFTP/<user@host:port>; the pool-wide mutex as SFTP/pool. Right-click a row:

• Copy Waiters Stack to Clipboard — dumps the last-owner's walkback plus each waiter's, formatted as plain text. Use when a process is wedged in readWait inside

withSftpClientDo: and you need to see which SFTP request it is on.

• Copy List to Clipboard — the whole table, for an email-this-to-someone diagnosis.
• Detect Deadlocks — DFS over the wait-for graph, reports cycles.

Logger

The SSH stack logs interesting events:

• warning: on auto-reconnect after a dead connection.
• warning: when a pool entry is idle-evicted.
• warning: when an SSH key file cannot be parsed (e.g. legacy PEM, encrypted-without-agent) — the file is skipped, others tried.

Limitations

• SFTP v3 only. No SETSTAT (no remote chmod / chown / utime), no SSH_FXP_READLINK exposed (#isSymbolicLink always

false, #linkInfo returns the regular stat info). Several SFTPv5+ niceties are nevertheless picked up via OpenSSH SSH_FXP_EXTENDED requests — see #OpenSSH SFTP extensions below.

• Per-host serialisation. Two concurrent operations on the same host queue through the host mutex. See #Future work.
• #renameTo: fallback has a TOCTOU window. On servers that advertise posix-rename@openssh.com (every modern OpenSSH does), overwrite is atomic; on the rare server that does not, the receiver is emulated as delete-then-rename and another process can race in between.
• #isNonEmptyDirectory is heuristic. Always returns #isDirectory (the accurate answer would cost three round-trips per directory icon, which made the original tree expansion unbearably slow).

Implementation details

For readers wanting the architecture. Five classes, top-down:

Class	Role
SSH::SftpFilename	Filename subclass; the public API. Maps sftp://... URLs to remote files; exposes directoryContents, readingFileDo:, renameTo: etc.
SSH::SftpClient	SFTP-v3 protocol (request/response codec, listDir, stat, open, read, write, mkdir). Driven by SftpFilename.
SSH::Channel	SSH channel multiplexer (CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical session per Channel instance.
SSH::Client	High-level SSH client: opens the transport, runs KEX, host-key check, userauth, then dispenses Channels.
SSH::Transport	Wire layer. Banner + KEXINIT exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq, heartbeat, SSH_MSG_DISCONNECT.

OpenSSH SFTP extensions

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal. OpenSSH ships an open-ended extension mechanism: the server lists extension names it understands in its SSH_FXP_VERSION reply, and the client invokes them via SSH_FXP_EXTENDED(200) packets carrying the extension name as the first string. Each extension is feature-detected via SSH::SftpClient>>supportsExtension:; callers fall back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

• posix-rename@openssh.com — atomic rename-with-overwrite. Picked up automatically by

SftpFilename>>renameTo:; the delete-then-rename fallback only fires on servers that lack it.

• hardlink@openssh.com — create a POSIX hard link. Exposed as SftpFilename>>createHardLinkAs:.
• statvfs@openssh.com — POSIX

statvfs(3)-shape filesystem stats. Exposed as SftpFilename>>fileSystemInfo; the result is shape-compatible with OperatingSystem getDiskInfoOf: so callers can treat local and remote uniformly. Drives the Tools → Filesystem Info... menu entry described at the top of this page.

• fsync@openssh.com — flush server-side write buffer to disk on an open handle. Available on the low-level

SftpClient>>fsyncHandle:; not yet plumbed into a Filename-level "durable write" API.

The remaining OpenSSH extensions (lsetstat@openssh.com, fstatvfs@openssh.com) are recognised in the advertised-extensions list but not wrapped at Filename level — there's no Filename-side caller for them yet.

Connection pooling

Every SftpFilename instance pointing at the same user@host:port triple shares one SSH::Client plus one SSH::SftpClient. Pool is class-side, guarded by a single ConnectionPoolMutex:

• Lazy bring-up — TCP + KEX + userauth + SFTP INIT happens on the first SFTP operation, not on forUrl:.
• Per-host serialisation — SFTP requests on a given host are serialised through a RecursionLock named

SFTP/<user@host:port> (visible in SemaphoreMonitor).

• Idle eviction — unused for longer than

idleEvictionSeconds, the entry is proactively closed + reopened on the next access.

• Auto-reconnect — a transport-level failure (broken pipe, EOF, MNU on nil socket) evicts the dead pool entry, opens a fresh client, retries the request once. Application-level SFTP STATUS errors propagate immediately.

Future work

Tracked but not yet implemented:

• Multi-channel parallelism per host — today one TCP + one SFTP channel per host means N concurrent requests serialise. Pipelining over multiple SshClients in the pool (preferred), or a transport-level reader process demultiplexing to per-channel inboxes, would let the tree pane keep listing while the content pane reads a large file.
• Accurate #isNonEmptyDirectory via OPEN_DIR + READ_DIR (first batch only) + CLOSE — three RTTs per probe; needs SftpClient to pipeline requests before this pays off.
• SFTP v5/v6 negotiation for extended attrs and FTP-style canonicalisation. (Atomic-overwrite rename is already handled via the OpenSSH posix-rename@openssh.com extension; see #OpenSSH SFTP extensions.)

Command Shell

Local command shell on this expecco machine. Typical applications: local command-line, running a local helper tool, bridging a remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

• CmdShell - Open
• CmdShell - Close

No credentials, no network — runs as the expecco process's own user. Output streams to expecco's log.

Telnet

Warning Telnet is a legacy protocol with no encryption. Passwords are transmitted in plain text on the wire; anyone on the network path can read them. Use Telnet ONLY when the target device has no other option (typically: old industrial controllers, lab instruments, embedded measurement equipment without an SSH stack). For everything else use #SSH and SFTP.

The expecco plugin exposes:

• Telnet - Open Remote Connection With Login
• Telnet - Execute Remote Command
• Example - Remote Device Control via Telnet (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream over TCP, with in-band control sequences for terminal options. A connection is established to a target host:port; after optional in-band login, both sides can send data.

See also

• SSH::Client — the SSH layer (exec, TTY, agent forwarding, ProxyJump).
• FileBrowserV2 — the main UI client of this stack.
• Claude Code — uses the same SSH stack for its HTTPS transport.
• RFC 4251 (SSH-2 Architecture)
• RFC 854 (Telnet Protocol)

---

Copyright © 2014-2024 eXept Software AG