ssh

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

Functions

`with host block :user? :port? :identities_only? :forward_agent? :connect_timeout? :keepalive_interval? :keepalive_count? :batch? :host_key? :known_hosts? :command? :cd? :env? :login_env? ...options`

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.

identity: and jump: may be repeated. 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.

Pass login_env: false to skip this, or a path to use that login shell instead of the one in the passwd database; a path is ignored by Windows hosts, which have no login shell. env overrides win over imported values.

Parameters

Name	type	Description
`host`	`Str`	SSH destination
`block`	callable	Block to run
`user`	`Str?`	Remote user
`port`	`Int?`	SSH server port
`identity`	`*`	Identity file; may be repeated
`identities_only`	`Bool?`	Restrict authentication to configured identities
`forward_agent`	`Bool?`	Forward the authentication agent
`jump`	`Str*`	Jump host; may be repeated
`connect_timeout`	`Int?`	Connection timeout in seconds
`keepalive_interval`	`Int?`	Protocol keepalive interval in seconds
`keepalive_count`	`Int?`	Unanswered keepalives allowed
`batch`	`Bool?`	Disable interactive prompts
`host_key`	`sym?`	`:DEFAULT:`, `:STRICT:`, or `:ACCEPT_NEW:`
`known_hosts`	`Path?`	Override the known-hosts file
`command`	`array?`	Remote VFS launcher prefix
`cd`	`Path?`	Initial remote working directory
`env`	`Dict`	Initial remote environment overrides
`login_env`	`Bool?`	Import the remote login environment; may name a Unix shell

Returns

The result of block.

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.run:
  - git
  - cargo

let checkout = Path /srv/build/project

ssh.with build.example.com
  user: builder
  identity: ~/.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