Execute a command on the remote host over the ssh session.

Note: If session is detected as a map like structure, it is assumed to be a babashka.process Process. This enables threading ssh processes in with local babashka.process processes. In such a situation you need to pass the session reference in via the :session key in options.

options should be a hashmap with the following keys:

• :session Override the value passed into the first argument. Use this as the ssh session instead.
• :agent-forwarding If set to true enables ssh authentication agent for this command.
• :pty If set to true allocate a pseudo terminal for this command execution.
• :in Specify the data to be passed to stdin of the process. Can be:
  • nil: (default) Pass nothing into stdin of the process and immediately close the input pipe.
  • a string: Pass this string into the stdin of the process (using encoding :in-enc) and then close the input pipe.
  • a byte array: Pass this data into the stdin of the process and then close the input pipe.
  • babashka InputStream instance: Use this instance to provide streaming data to the stdin of the process (the .read method will be repeatedly called to provide data)
  • bbssh input-stream reference: Use this instance to provide streaming data to the stdin of the process (the input-stream/read function will be repeatedly called to provide data)
  • :stream: A PipedOutputStream/PipedInputStream instance pair is created and the PipedOutputStream will be returned in the :in key of the result (for you to .write or clojure.java.io/copy to).
• :in-enc If :in is :string then optionally set the input encoding with this. Defaults to “utf-8”.
• :out Specify how you want the output to be returned. The values can be:
  • :string: the returned :out value will be a future that will deref to a string of data. The future deref will block until the process is complete and the processes output is finished.
  • :bytes: the returned :out value will be a future that will deref to a byte array of data. The future deref will block until the process is complete and the processes output is finished.
  • babashka OutputStream instance: The OutputStream will have its .write method called as data becomes available from the process.
  • bbssh output-stream reference: The pod side output-stream will be written to with output-stream/write as data becomes available from the process.
  • :stream (default): A PipedOutputStream/PipedInputStream instance pair is created and the PipedInputStream will be returned in the :out key of the result (for you to .read or clojure.java.io/copy from).
• :out-enc If :out is :string then optionally set the output encoding with this. Defaults to “utf-8”.
• :err Specify how you want the output to be returned. The values can be:
  • :string: the returned :err value will be a future that will deref to a string of data. The future deref will block until the process is complete and the processes output is finished.
  • :bytes: the returned :err value will be a future that will deref to a byte array of data. The future deref will block until the process is complete and the processes output is finished.
  • babashka OutputStream instance: The OutputStream will have its .write method called as data becomes available from the process.
  • bbssh output-stream reference: The pod side output-stream will be written to with output-stream/write as data becomes available from the process.
  • :stream (default): A PipedOutputStream/PipedInputStream instance pair is created and the PipedInputStream will be returned in the :err key of the result (for you to .read or clojure.java.io/copy from).
• :err-enc If :err is :string then optionally set the output encoding with this. Defaults to “utf-8”.
• :pipe-buffer-size when :in, :out or :err are set to :stream, this value can be passed an integer to set the pipe buffer size. Larger values create more chunked output but increase through-put. Default is 8192.
• :no-connect when true do not connect this channel to the command. Simply set it up and return it. You will need to call channel-exec/connect on the channel to actually initiate the process and channel.

Start an SSH session. If connection is successful, returns the SSH session reference. If connection is unsuccessful, raises an exception. Requires a string for hostname. Pass in an optional hashmap with the following keys:

• :port The port to connect to. Defaults to 22.
• :username The username to connect as. Defaults to the current username.
• :password Pass in a string to use for password authentication.
• :identity Pass in a file or filename of the private key to use in key authentication.
• :passphrase Pass in a string to decrypt the private key with if needed.
• :private-key Pass in a string (base64) or byte array of the private key to use for authentication.
• :public-key Pass in a string (base64) or byte array of the public key associated with the private-key
• :strict-host-key-checking Control strict host key checking. If set to true, bbssh will never add host keys to known host and will refuse to connect to hosts whose host key has changed. If set to false, bbssh will allow connection to hosts with unknown or changed keys. If the key is unknown it will add it to known hosts, but it will not change a key if it is present. A value of :ask will mean new host keys will be added to the known hosts, or a changed key modified, only after the user has confirmed this is what they wish to do via the terminal. Default is :ask
• :config-file A string or java.io.File referencing an OpenSSH config file to use for configuration settings. Defaults to "~/.ssh/config". Passing in false disables any config file.
• :port-forward-local A vector of local port forwarding directives. Each element should be a hashmap with the keys :local-port, :remote-host and :remote-port. All connections to :local-port on the local machine will be forwarded to :remote-host :remote-port on the remote machine. Instead of setting :remote-host and :remote-port you may set :remote-unix-socket to the remote file path of a unix domain socket to forward to that. An optional key of :bind-address can be used to control the local interface that is bound. Defaults to 127.0.0.1. Optional key :connect-timeout defines how many milliseconds to persist in attempting the remote connection. Defaults to 0 (try forever).
• :port-forward-remote A vector of remote port forwarding directives. Each element should be a hashmap with the keys :remote-port, :local-host and :local-port. All connections to :remote-port on the remote machine will be forwarded to :local-host :local-port on the local machine. An optional key of :bind-address can be used to control the remote interface that is bound. Defaults to 127.0.0.1. Note: remote port forwarding cannot be setup until the connection is made. Thus setting :no-connect to true will prevent :port-forward-remote from initiating.
• :known-hosts A string defining the path to the known_hosts file to use. It is set to ~/.ssh/known_hosts by default. Set to false to disable using a known hosts file.
• :accept-host-key When :strict-host-key-checking is set to :ask this setting controls the adding of the key. If unset, or set to nil the default behavior of asking the user via the terminal applies. If true accept the host key if it is unknown or changed. If false reject the connection if the host key is unknown or changed. If set to a string, accept the host-key only if the key fingerprint matches the string. If set to :new, accept the key if it is unknown, but reject it if it has changed. Defaults to nil.
• :connection-options A hashmap of lesser used connection options. See below for details.
• :no-connect Set to true to prevent the connection from being initiated. Just returns the prepared session reference. You will then need to call session/connect on it to initiate the connection.
• :agent The bbssh agent to use to construct the session. If none is supplied a new bbssh agent will be created. Note: this is not an ssh-agent. It is the root class that contains all the session instances and settings.
• :identity-repository Use a custom identity-repository in the connection.
• :user-info Use a custom user-info in the connection. Specifying this value will override :accept-host-key and change the behavior of password and passphrase prompts (your user-info functions will be called instead).
• :host-key-repository Use a custom host-key-repository in the connection. Specifying this value will override :known-hosts setting (your host-key-repository functions will be called instead).
• :proxy Use a http or socks proxy to make the connection. The provided arg must have at least :type (one of #{:http :socks4 :socks5}), :host, :port and optionally :username and :password for proxy authentication.
• :silence-messages When set to true do not echo SSH messages to stdout in the default user-info. Such messages include any Banner setup on the server. Only has an effect if you are not using a custom user-info.

The hashmap passed in :connection-options can have the following keys. Each key takes a string or a function as a configuration value. If passed a string, that string becomes the set value. If passed a function this function should take a single string as an argument and return a string. It will be passed the existing configuration setting and should return the new configuration setting. These can be used to append or prepend extra values onto the default settings.

:kex, :server-host-key, :prefer-known-host-key-types, :enable-server-sig-algs, :cipher, :cipher-s2c, :cipher-c2s, :mac, :mac-s2c, :mac-c2s, :compression, :compression-s2c, :compression-c2s, :lang, :lang-s2c, :lang-c2s, :dhgex-min, :dhgex-max, :dhgex-preferred, :compression-level, :preferred-authentications, :client-pubkey, :check-ciphers, :check-macs, :check-kexes, :check-signatures, :fingerprint-hash, :max-auth-tries