Listen

Starts a server that implements the distant protocol.

distant server listen

Flags

• --current-dir <DIR>: changes the current working directory of the server, which is normally set to its parent process' directory.

• --daemon: runs the server process as a daemon, meaning that it is detached from the parent process and will continue running even after the parent exits. On Unix systems this involves fork while on Windows this uses CreateProcess in a detached state.

• --host <HOST>: used to bind the server to restrict communication over a specific network interface. This can be ssh, any, or a specific IP address representing the interface like 192.168.1.123.

  In the case of ssh, the SSH_CONNECTION environment variable will be parsed to bind to the associated interface. This variable is usually present during an ssh session on the connected machine, and is leveraged by default when using distant launch to start the server.

  In the case of any, the server will bind to 0.0.0.0 to support receiving traffic from any network interface.

• --key-from-stdin: stops the server from generating an authentication key and instead uses the key provided over stdin. The key is contained over the next 32 bytes of stdin. Receiving less than 32 bytes is an error and any bytes beyond the first 32 are ignored.

• --port <PORT[:PORT2]>: used to specify an explicit port or range of ports for the server to attempt to use for listening over TCP. By default, the server will leverage the operating system to provide it an open port (ephemeral port).

  A port can be specified either singularly (8080) or as a range (8080:8089).

• --shutdown <RULE>: indicates whether the server should shutdown based on some logic. The available options are:

  • never: the server will never shutdown on its own.
  • after=N: the server will shutdown after N seconds.
  • lonely=N: the server will shutdown after N seconds with no active connection.

• --use-ipv6: indicates that the server should listen on an IPv6 network address versus an IPv4 one. For a host of any, this results in binding to [::].

• --watch-compare-contents: will attempt to load a file and compare its contents to detect file changes, only relevant when using the polling watcher implementation (VERY SLOW).

• --watch-debounce-tick-rate <N>: how often (in seconds) to check for new events before the debounce timeout occurs. Defaults to 1/4 the debounce timeout if not set.

• --watch-debounce-timeout <N>: maximum time (in seconds) to wait for filesystem changes before reporting them, which is useful to avoid noisy changes as well as serves to consolidate different events that represent the same action.

• --watch-polling: configures the server to use a polling method to watch for filesystem changes instead of the default, native poller.

• --watch-polling-interval <N>: adjusts the time between checks of filesystem changes by the polling filesystem watcher.

Examples

Spawning a server that is long-lived

Typically, you want to spawn a server that will run after your shell has exited. Given that you cannot see any output, you also want to redirect logging to a file via log-file:

distant server listen --daemon --log-file /path/to/server.log

distant server listen --help

Listen for incoming requests as a server

Usage: distant server listen [OPTIONS]

Options:
      --host <ssh|any|IP>
          Control the IP address that the distant binds to

          There are three options here:

          1. `ssh`: the server will reply from the IP address that the SSH connection came from (as found in the SSH_CONNECTION environment variable). This is useful for multihomed servers.

          2. `any`: the server will reply on the default interface and will not bind to a particular IP address. This can be useful if the connection is made through ssh or another tool that makes the SSH connection appear to come from localhost.

          3. `IP`: the server will attempt to bind to the specified IP address.

          [default: any]

      --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

      --port <PORT[:PORT2]>
          Set the port(s) that the server will attempt to bind to

          This can be in the form of PORT1 or PORT1:PORTN to provide a range of ports. With `--port 0`, the server will let the operating system pick an available TCP port.

          Please note that this option does not affect the server-side port used by SSH

          [default: 0]

  -6, --use-ipv6
          If specified, will bind to the ipv6 interface if host is "any" instead of ipv4

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

      --shutdown <SHUTDOWN>
          Logic to apply to server when determining when to shutdown automatically

          1. "never" means the server will never automatically shut down 2. "after=<N>" means the server will shut down after N seconds 3. "lonely=<N>" means the server will shut down after N seconds with no connections

          Default is to never shut down

          [default: never]

      --current-dir <CURRENT_DIR>
          Changes the current working directory (cwd) to the specified directory

      --daemon
          If specified, will fork the process to run as a standalone daemon

      --watch-polling
          If specified, will use the polling-based watcher for filesystem changes

      --watch-poll-interval <WATCH_POLL_INTERVAL>
          If specified, represents the time (in seconds) between polls of files being watched, only relevant when using the polling watcher implementation

      --watch-compare-contents
          If true, will attempt to load a file and compare its contents to detect file changes, only relevant when using the polling watcher implementation (VERY SLOW)

      --watch-debounce-timeout <WATCH_DEBOUNCE_TIMEOUT>
          Represents the maximum time (in seconds) to wait for filesystem changes before reporting them, which is useful to avoid noisy changes as well as serves to consolidate different events that represent the same action

          [default: 0.5]

      --watch-debounce-tick-rate <WATCH_DEBOUNCE_TICK_RATE>
          Represents how often (in seconds) to check for new events before the debounce timeout occurs. Defaults to 1/4 the debounce timeout if not set

      --key-from-stdin
          If specified, the server will not generate a key but instead listen on stdin for the next 32 bytes that it will use as the key instead. Receiving less than 32 bytes before stdin is closed is considered an error and any bytes after the first 32 are not used for the key

      --output-to-local-pipe <OUTPUT_TO_LOCAL_PIPE>


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