🚧 (Alpha stage software) Library and tooling that supports remote filesystem and process operations. 🚧
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Chip Senkbeil 7d1b3ba6f0
Fix stack overflow parsing BindAddress and improve resolution of BindAddress
2 weeks ago
.config Fix ssh system info (#127) 1 month ago
.github/workflows Integrate ignore crate to provide parallel search, binary detection, and support ignore files (#136) 3 weeks ago
distant-core Update SearchQueryCondition to support logical or and contains types; also update non-regex types to escape regex 3 weeks ago
distant-net Add untyped request response (#137) 3 weeks ago
distant-ssh2 Release v0.19.0 4 weeks ago
src Fix stack overflow parsing BindAddress and improve resolution of BindAddress 2 weeks ago
tests Refactor SearchQuery to support multiple paths at once 1 month ago
.dockerignore Add dockerignore to speed up dockerfile 4 months ago
.gitignore Add native ssh (#57) 1 year ago
BUILDING.md Refactor to use distant manager (#112) 2 months ago
CHANGELOG.md Fix stack overflow parsing BindAddress and improve resolution of BindAddress 2 weeks ago
Cargo.lock Update SearchQueryCondition to support logical or and contains types; also update non-regex types to escape regex 3 weeks ago
Cargo.toml Release v0.19.0 4 weeks ago
Dockerfile Minor documentation changes and update dockerfile to build from source 4 months ago
PUBLISH.md Update referenced versions in READMEs and add note about doing so to PUBLISH.md 1 month ago
README.md Add search support (#131) 1 month ago
rustfmt.toml Refactor to use distant manager (#112) 2 months ago

README.md

distant - remotely edit files and run programs

Crates.io Docs.rs CI RustC 1.61+

🚧 (Alpha stage software) This program is in rapid development and may break or change frequently! 🚧

Details

The distant binary supplies both a server and client component as well as a command to start a server and configure the local client to be able to talk to the server.

Additionally, the core of the distant client and server codebase can be pulled in to be used with your own Rust crates via the distant-core crate. The networking library, which is agnostic of distant protocols, can be used via the distant-net crate.

Installation

Prebuilt Binaries

If you would like a pre-built binary, check out the releases section.

Building from Source

If you have cargo installed, you can directly download and build the source via:

cargo install distant

Alternatively, you can clone this repository and build from source following the build guide.

Backend Feature Matrix

Distant supports multiple backends to facilitate remote communication with another server. Today, these backends include:

  • distant - a standalone server acting as the reference implementation
  • ssh - a wrapper around an ssh client that translates the distant protocol into ssh server requests

Not every backend supports every feature of distant. Below is a table outlining the available features and which backend supports each feature:

Feature distant ssh
Capabilities
Filesystem I/O
Filesystem Watching
Process Execution
Search
System Information
  • means full support
  • ⚠ means partial support
  • means no support

Feature Details

  • Capabilities - able to report back what it is capable of performing
  • Filesystem I/O - able to read from and write to the filesystem
  • Filesystem Watching - able to receive notifications when changes to the filesystem occur
  • Process Execution - able to execute processes
  • Search - able to search the filesystem
  • System Information - able to retrieve information about the system

Example

Starting the manager

In order to facilitate communication between a client and server, you first need to start the manager. This can be done in one of two ways:

  1. Leverage the service functionality to spawn the manager using one of the following supported service management platforms:
  1. Run the manager manually by using the listen subcommand

Service management

# If you want to install the manager as a service, you can use the service
# interface available directly from the CLI
#
# By default, this will install a system-level service, which means that you
# will need elevated permissions to both install AND communicate with the
# manager
distant manager service install

# If you want to maintain a user-level manager service, you can include the
# --user flag. Note that this is only supported on MacOS (via launchd) and
# Linux (via systemd)
distant manager service install --user

# ........

# Once you have installed the service, you will normally need to start it
# manually or restart your machine to trigger startup on boot
distant manager service start # --user if you are working with user-level

Manual start

# If you choose to run the manager without a service management platform, you
# can either run the manager in the foreground or provide --daemon to spawn and
# detach the manager

# Run in the foreground
distant manager listen

# Detach the manager where it will not terminate even if the parent exits
distant manager listen --daemon

Interacting with a remote machine

Once you have a manager listening for client requests, you can begin interacting with the manager, spawn and/or connect to servers, and interact with remote machines.

# Connect to my.example.com on port 22 via SSH and start a distant server
distant client launch ssh://my.example.com

# After the connection is established, you can perform different operations
# on the remote machine via `distant client action {command} [args]`
distant client action copy path/to/file new/path/to/file
distant client action spawn -- echo 'Hello, this is from the other side'

# Opening a shell to the remote machine is trivial
distant client shell

# If you have more than one connection open, you can switch between active
# connections by using the `select` subcommand
distant client select '<ID>'

# For programmatic use, a REPL following the JSON API is available
distant client repl --format json

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or apache-license) MIT license (LICENSE-MIT or mit-license) at your option.