Connect

Connects to a remote machine through some method. Today, distant supports two schemes: distant and ssh.

Flags

• --format <FORMAT>: determines how connecting is handled when it comes to communication. By default, authentication requests are handled with human-readable prompts. With json specified, authentication will be provided using JSON-formatted requests and responses.

• --options <OPTIONS>: implementation-specific options to provide when connecting. These can vary based on using distant or ssh as the scheme.

Options for distant://

• key: provide the authentication key to streamline authentication versus needing to answer the authentication prompt.

Options for ssh://

All options for ssh have ssh. as an optional prefix. For example, you can supply backend or ssh.backend as the key.

• ssh.backend: used by ssh to determine which client library to use both for authentication and general options. The choices are ssh2 and libssh with ssh2 being the default. If you encounter errors such related to banners, invalid protocol messages, etc. try to switch to libssh.

• ssh.identity_files: used to provide explicit list of files from which the user's DSA, ECDSA, Ed25519, or RSA authentication identity are read. These are comma-separated. Defaults are:

  • ~/.ssh/id_dsa
  • ~/.ssh/id_ecdsa
  • ~/.ssh/id_ed25519
  • ~/.ssh/id_rsa

• ssh.identities_only: if true, specifies that ssh should only use the configured authentication and certificate files (either the defaults or configured from identity_files).

• ssh.proxy_command: specifies the command to use to connect to the server.

• ssh.user_known_hosts_files: specifies one or more files to use for the user host key database. These are comma-separated and default to:

  • ~/.ssh/known_hosts
  • ~/.ssh/known_hosts2

• ssh.verbose: if true, output tracing information from the underlying ssh implementation.

Examples

Connecting to a distant server

When connecting to a distant server, you need to use the distant scheme and provide an explicit port such as 8080 as seen below:

distant connect distant://example.com:8080

Supplying an authentication key as an option to a distant server

distant connect distant://example.com --options 'key=abcd'

Connecting to an ssh server

When connecting to an ssh server, you need to use the ssh scheme. If a port is not specified, the default port of 22 is used as seen below:

distant connect ssh://example.com

Supplying ssh-specific options

distant connect ssh://example.com \
  --options 'backend=libssh,verbose=true,identity_files="path/to/file1,path/to/file2"'

distant connect --help

Requests that active manager connects to the server at the specified destination

Usage: distant connect [OPTIONS] <DESTINATION>

Arguments:
  <DESTINATION>


Options:
      --cache <CACHE>
          Location to store cached data

          [default: /home/runner/.cache/distant/cache.toml]

      --log-level <LOG_LEVEL>
          Log level to use throughout the application

          [possible values: off, error, warn, info, debug, trace]

      --log-file <LOG_FILE>
          Path to file to use for logging

      --options <OPTIONS>
          Additional options to provide, typically forwarded to the handler within the manager facilitating the connection. Options are key-value pairs separated by comma.

          E.g. `key="value",key2="value2"`

          [default: ]

      --config <CONFIG_PATH>
          Configuration file to load instead of the default paths

      --unix-socket <UNIX_SOCKET>
          Override the path to the Unix socket used by the manager (unix-only)

      --windows-pipe <WINDOWS_PIPE>
          Override the name of the local named Windows pipe used by the manager (windows-only)

  -f, --format <FORMAT>
          [default: shell]

          Possible values:
          - json:  Sends and receives data in JSON format
          - shell: Commands are traditional shell commands and output responses are inline with what is expected of a program's output in a shell

  -h, --help
          Print help (see a summary with '-h')