Skip to content

feat(ssh): support connection multiplexing (-M, -O, ControlPath) #286

Closed

Description

@inureyes

Part of the OpenSSH drop-in compatibility epic.

Problem

bssh has no connection multiplexing. ControlMaster, ControlPath and ControlPersist are parsed at src/ssh/ssh_config/parser/options/control.rs and never read, and the -M, -O and -S command-line flags do not exist (-S exists but means --sudo-password, which the flag-collision sub-issue addresses).

The regression suite exercises this directly in multiplex.sh, channel-timeout.sh and dynamic-forward.sh. The canonical invocation shows how much is missing at once:

${SSH} -S $CTL -N -M -F $OBJ/ssh_config -f $fwd somehost

Four flags in one line, none of which work in bssh today.

Outside the suite, multiplexing is what makes repeated connections to the same host cheap, and a great deal of tooling assumes it: Ansible's ssh connection plugin enables ControlPersist by default, and interactive workflows rely on a shared master to avoid re-authenticating.

Why this is separate

This is the largest single piece of work in the epic, and it is the only one whose absence does not silently corrupt behavior. A client without multiplexing opens a fresh connection where OpenSSH would reuse one: slower, but correct. Everything else in this epic is either a silent divergence or an outright refusal, so this is deliberately sequenced last and should not delay the rest.

Scope

  • A master connection that listens on a ControlPath unix socket, and client connections that attach to it and open additional channels rather than authenticating again.
  • -M to request master mode, stacking to ControlMaster ask on repetition, and ControlMaster auto, autoask, yes, no and ask from the config.
  • -S ctl_path for the socket path, with the %C, %h, %p, %r and %l token expansions, and ControlPath none as an explicit disable.
  • -O ctl_cmd for check, forward, cancel, exit and stop.
  • ControlPersist with both the boolean and the timeout forms, keeping the master alive after the initial client exits.
  • Correct handling of a stale socket, a master that died, and a path longer than the unix socket limit, all of which are common in practice.

Acceptance criteria

  • A second invocation against an established master reuses the connection, verified by asserting no second authentication occurs.
  • -O check, -O forward, -O cancel, -O exit and -O stop all behave as documented.
  • ControlPersist keeps the master alive for the configured duration and then exits.
  • A stale or unreachable socket falls back to a direct connection rather than failing.
  • The regress tests multiplex, channel-timeout and dynamic-forward pass in the harness. Note that these three also fail on the reference OpenSSH client in the current macOS environment, so the harness environment issue has to be resolved before this can be scored.

Part of #275

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions