Getting Started¶

Requirements¶

Dyalog APL 18.2 or later, Unicode edition (tested with 19.0–21.0; CI runs 20.0)
Conga — the conga workspace and the Conga SSL library from a standard Dyalog installation. SSHClient finds both automatically; no separate install is needed.
Linux, macOS, or Windows.

Loading the class¶

SSHClient.aplc is a single class file. Load it whichever way suits your project:

      ⍝ plain ⎕FIX
      ⎕FIX 'file:///path/to/SSHClient.aplc'

      ⍝ or via Link
      ⎕SE.Link.Import '#' '/path/to/SSHClient.aplc'

In a dyalogscript file:

#!/usr/bin/dyalogscript
{}#.⎕FIX 'file://SSHClient.aplc'

First connection¶

      c←⎕NEW SSHClient ('server.example.com' 22 'alice' 'secret')
      r←c.Connect
      r.rc                ⍝ 0 = connected and authenticated
0
      r←c.Exec 'hostname'
      r.Data
server.example.com
      c.Close

Every operation returns a result namespace:

Field	Meaning
`rc`	`0` on success, nonzero on failure
`msg`	empty on success, otherwise a human-readable reason
`Data`	the payload: command output, file path, directory entries, …
`Host` `Port` `Username`	the connection the result belongs to
`Elapsed`	milliseconds (set by `Connect`)

Check rc first; when it is nonzero, msg says why. Operations do not signal errors for expected failures (bad password, missing file, refused connection) — they report them.

First connection and host keys

By default the client records the server's host key in ~/.ssh/known_hosts on first contact and pins it from then on (OpenSSH accept-new behavior). A server whose key later changes is refused. See Host Key Verification.

One-shot commands¶

For fire-and-forget use, Do wraps create → connect → exec → close:

      ⍝ positional (port 22)
      r←SSHClient.Do 'server.example.com' 'alice' 'secret' 'uptime'

      ⍝ namespace form: any field, any port; Cmd is the command
      ns←⎕NS ''
      ns.(Host Port Username KeyFile)←'server.example.com' 2222 'alice' '/home/alice/.ssh/id_rsa'
      ns.Cmd←'uptime'
      r←SSHClient.Do ns

Troubleshooting¶

Symptom	Likely cause
`neither Conga nor DRC were successfully copied`	Dyalog installation not found — set `SSHClient.CongaPath` to the directory containing `conga.dws`, or `SSHClient.CongaRef` to an existing Conga instance
`TCP connect to host:port failed`	wrong host/port, or nothing listening
`Error waiting for SSH server banner`	the port is open but it is not an SSH server, or it stayed silent past `WaitTime`
`Algorithm negotiation failed: server does not offer …`	the server has the required algorithm disabled — most commonly `diffie-hellman-group14-sha256` on OpenSSH ≥10; see Algorithms & Limitations for the `sshd_config` fix
`HOST KEY VERIFICATION FAILED …`	the server's key does not match your known_hosts entry — see Host Key Verification before overriding anything
`Authentication failed`	wrong credentials, or the key is not in the server's `authorized_keys`