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:

bash 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 | ✅ | ✅ | | Reconnect | ✅ | ❌ | | 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
• Reconnect - able to reconnect after network outages
• 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

```bash

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

```bash

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.

```bash

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

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.