distant - remotely edit files and run programs

🚧 (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.

• Asynchronous in nature, powered by tokio
• Data is serialized to send across the wire via msgpack
• Encryption & authentication are handled via XChaCha20Poly1305 for an authenticated encryption scheme via RustCrypto/ChaCha20Poly1305

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:

• sc.exe for use with Window Service (Windows)
• Launchd (MacOS)
• systemd (Linux)
• OpenRC (Linux)
• rc.d (FreeBSD)

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