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@]host[:port]/remote/path

User defaults to the local login name, port to 22, path to /.

The Tools menu offers three SSH-related actions, all 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.

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:

Open Services (services.msc) as Administrator.
Find OpenSSH Authentication Agent, set Startup Type to

 Automatic, click Start.

In PowerShell: ssh-add $HOME\.ssh\id_ed25519.
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:

Press Vorlage:Key → type "environment" → "Edit the system environment variables".
Environment Variables → under User variables, New.
Name: SSH_AUTH_SOCK
Value: \\.\pipe\openssh-ssh-agent
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.

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).  SFTPv5+ features (atomic-overwrite rename via
 SSH_FXF_OVERWRITE) not supported.

Per-host serialisation. Two concurrent operations on the

 same host queue through the host mutex.  See #Future work.

#renameTo: has a TOCTOU window. POSIX-style

 overwrite is emulated as delete-then-rename; 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.

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 atomic-overwrite rename,

 extended attrs, FTP-style canonicalisation.

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.

Remote Access/en

Inhaltsverzeichnis

SSH and SFTP

From the FileBrowserV2

From expecco actions

Generating an SSH key pair

The dialog (FileBrowserV2 / settings page)

From a workspace

Using the shell tools instead

Preparing ssh-agent

Linux / macOS

Permanent setup via systemd

Auto-loading keys on first use

Windows

PowerShell quick-setup

Auto-loading keys on first use

Configuration

Diagnostics

SemaphoreMonitor

Logger

Limitations

Implementation details

Connection pooling

Future work

Command Shell

Telnet

See also

Navigationsmenü

Remote Access/en

SSH and SFTP

From the FileBrowserV2

From expecco actions

Generating an SSH key pair

The dialog (FileBrowserV2 / settings page)

From a workspace

Using the shell tools instead

Preparing ssh-agent

Linux / macOS

Permanent setup via systemd

Auto-loading keys on first use

Windows

PowerShell quick-setup

Auto-loading keys on first use

Configuration

Diagnostics

SemaphoreMonitor

Logger

Limitations

Implementation details

Connection pooling

Future work

Command Shell

Telnet

See also

Navigationsmenü

Suche