ssh

Run block-scoped operations on SSH hosts through a remote VFS.

Functions

`with[R] host block ...options … -> R`

Runs block on host through SSH and a remote VFS. Filesystem access, spawned programs, environment, working directory, system information, and security queries use the remote target for the duration of the block.

TTY allocation and SSH escape processing are disabled. Agent forwarding is disabled unless forward_agent is true. Advanced settings not represented here continue to come from SSH configuration.

The remote host must provide dolang-vfs in its command search path unless command supplies another location. The SSH session is terminated when block exits, including during unwind.

SSH does not give the remote command the environment a logged-in session would have, so the remote VFS reconstructs it before serving requests. On Unix hosts it runs the account's login shell, which SSH itself skips. On Windows hosts it reads the user environment from the registry, which the OpenSSH server there populates only for PATH.

Parameters

Name	Type	Description
`host`	`Str`	SSH destination.
`block`	`(() -> R)`	Block to run under the remote VFS.
`:user?`	`Str`	Remote user.
`:port?`	`Int`	SSH server port.
`:identities_only?`	`Bool`	Restrict authentication to configured identities.
`:forward_agent?`	`Bool`	Forward the authentication agent.
`:connect_timeout?`	`Int`	Connection timeout in seconds.
`:keepalive_interval?`	`Int`	Protocol keepalive interval in seconds.
`:keepalive_count?`	`Int`	Unanswered keepalives allowed before disconnecting.
`:batch?`	`Bool`	Disable interactive prompts.
`:host_key?`	`(:DEFAULT: \| :STRICT: \| :ACCEPT_NEW:)`	Host-key verification policy.
`:known_hosts?`	`(Str \| fs.Path)`	Override the known-hosts file.
`:command?`	`Iterable[Str]`	Remote VFS launcher command and arguments.
`:cd?`	`(Str \| fs.Path)`	Initial remote working directory.
`:env?`	`Dict[Str \| Sym, Value]`	Initial remote environment overrides.
`:login_env?`	`(Bool \| Str)`	Import the remote login environment. `false` skips it entirely; a path names the login shell to use instead of the one in the passwd database, and is ignored on Windows hosts, which have no login shell. `env` overrides win over imported values.
`...options`		Additional options

`:host_key`

Value	Meaning
`:DEFAULT:`	Use SSH's own configured checking policy
`:STRICT:`	Reject any host key not already in the known-hosts file
`:ACCEPT_NEW:`	Accept and record an unknown host key; reject a changed one

`...options`

Name	Type	Description
`identity`	`Str`\|`Path`	Identity file. Repeatable
`jump`	`Str`	Jump host. Repeatable

Errors

Error	Condition
`proc.Error`	SSH exits unsuccessfully
`sys.Error`	SSH or the remote VFS cannot be contacted
`ValueError`	`host_key` is not a supported policy
`UnexpectedKeyError`	An unrecognized keyword option is passed
`UnexpectedPosError`	An unexpected positional argument is passed

Example

import proc:
  - git
  - cargo

let checkout = Path /srv/build/project

ssh.with build.example.com
  user: builder
  identity: $env["HOME"]/.ssh/build
  jump: bastion.example.com
  batch: true
  host_key: :STRICT:
  do
    checkout.remove all: true ignore: true
    checkout.parent.mkdir all: true
    git clone https://github.com/example/project.git $checkout
    cd $checkout do
      cargo build --release