diff --git a/Cargo.toml b/Cargo.toml index 0457d0f..c5f0041 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -12,3 +12,4 @@ clap = { version = "3.1.8", features = ["derive"] } serde = { version = "1.0.136", features = ["derive"] } serde_json = "1.0.79" tokio = { version = "1.17.0", features = ["full"] } +uuid = { version = "0.8.2", features = ["serde", "v4"] } diff --git a/README.md b/README.md index 51c7ca0..14f6f91 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,37 @@ # bore -A modern, simple TCP tunnel in Rust that exposes local ports to a self-hosted remote server, bypassing standard NAT connection firewalls. **That's all it does: no more, and no less.** +A modern, simple TCP tunnel in Rust that exposes local ports to a remote server, bypassing standard NAT connection firewalls. **That's all it does: no more, and no less.** ```shell -# Step 1: Installation (requires Rust) +# Installation (requires Rust) cargo install bore-cli -# Step 2: On a remote server at example.com -bore proxy - -# Step 3: On your local machine -bore local 8000 --to example.com:9000 +# On your local machine +bore local 8000 --to bore.pub ``` -This will expose your local port at `localhost:8000` to the public internet at `example.com:9000`. +This will expose your local port at `localhost:8000` to the public internet at `bore.pub:`, where the port number is assigned randomly. -Inspired by [localtunnel](https://github.com/localtunnel/localtunnel) and [ngrok](https://ngrok.io/), except `bore` is intended to be a highly efficient, unopinionated tool for real production workloads that is simple to install and use, with no frills attached. +Like [localtunnel](https://github.com/localtunnel/localtunnel) and [ngrok](https://ngrok.io/), except `bore` is intended to be a highly efficient, unopinionated tool for forwarding TCP traffic that is simple to install and easy to self-host, with no frills attached. ## Detailed Usage +This section describes detailed usage for the `bore` CLI command. + +### Local Forwarding + TODO +### Self-Hosting + +As mentioned in the startup instructions, there is an public instance of the `bore` server running at `bore.pub`. However, if you want to self-host `bore` on your own network, you can do so with the following command: + +```shell +bore server +``` + +That's all it takes! After the server starts running at a given address, you can then update the `bore local` command with option `--to
` to forward a local port to this remote server. + ## Protocol There is an implicit _control port_ at `7835`, used for creating new connections on demand. This can be configured in the command-line options. diff --git a/src/client.rs b/src/client.rs new file mode 100644 index 0000000..7fa7770 --- /dev/null +++ b/src/client.rs @@ -0,0 +1 @@ +//! Client implementation for the `bore` service. diff --git a/src/lib.rs b/src/lib.rs index 1b4a90c..2cc80d5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,23 @@ +//! A modern, simple TCP tunnel in Rust that exposes local ports to a remote +//! server, bypassing standard NAT connection firewalls. +//! +//! This is the library crate documentation. If you're looking for usage +//! information about the binary, see the command below. +//! +//! ```shell +//! $ bore help +//! ``` +//! +//! There are two components to the crate, offering implementations of the +//! server network daemon and client local forwarding proxy. Both are public +//! members and can be run programmatically with a Tokio 1.0 runtime. + +#![forbid(unsafe_code)] +#![warn(missing_docs)] + +pub mod client; +pub mod server; + #[cfg(test)] mod tests { #[test] diff --git a/src/main.rs b/src/main.rs index b0c65a6..97927f7 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,41 @@ +use clap::{Parser, Subcommand}; + +#[derive(Parser, Debug)] +#[clap(author, version, about)] +#[clap(propagate_version = true)] +struct Args { + #[clap(subcommand)] + command: Command, +} + +#[derive(Subcommand, Debug)] +enum Command { + /// Starts a local proxy to the remote server. + Local { + /// The local port to listen on. + local_port: u16, + + /// Address of the remote server to expose local ports to. + #[clap(short, long)] + to: String, + + /// Optional port on the remote server to select. + #[clap(short, long, default_value_t = 0)] + port: u16, + }, + + /// Runs the remote proxy server. + Server { + /// Minimum TCP port number to accept. + #[clap(long, default_value_t = 1024)] + min_port: u16, + }, +} + fn main() { + let args = Args::parse(); + + println!("{:?}", args); + println!("bore cli running"); } diff --git a/src/server.rs b/src/server.rs new file mode 100644 index 0000000..30eb1b9 --- /dev/null +++ b/src/server.rs @@ -0,0 +1 @@ +//! Server implementation for the `bore` service.