diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 273a8de..39bfb17 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -59,7 +59,6 @@ jobs: - uses: actions/checkout@v4 with: persist-credentials: false - - uses: Swatinem/rust-cache@v2 - name: Install cargo-llvm-cov run: | wget https://github.com/taiki-e/cargo-llvm-cov/releases/download/v${CARGO_LLVM_COV_VERSION}/cargo-llvm-cov-x86_64-unknown-linux-gnu.tar.gz \ diff --git a/book/src/admin_interface.md b/book/src/admin_interface.md index 924d759..f9fbf76 100644 --- a/book/src/admin_interface.md +++ b/book/src/admin_interface.md @@ -1,6 +1,6 @@ # Admin interface -Sandhole comes with a command-line admin interface available through SSH, which displays information about the system, as well as specific connections. In order to access it, you must be a [user with admin credentials](./configuration.md#adding-users-and-admins). +Sandhole comes with a command-line admin interface available through SSH, which displays information about the system and proxied connections. In order to access it, you must be a [user with admin credentials](./configuration.md#adding-users-and-admins). To access it, simply run the command: diff --git a/book/src/advanced_uses.md b/book/src/advanced_uses.md index 2e7957f..4fa9b07 100644 --- a/book/src/advanced_uses.md +++ b/book/src/advanced_uses.md @@ -20,14 +20,14 @@ For the former, you can run `ssh-keygen -lf /path/to/private/key` and take note SHA256:bwf4FDtNeZzFv8xHBzHJwRpDRxssCll8w2tCHFC9n1o ``` -Then, add the following entries to your DNS (assuming that your custom domain is `my.domain.net`): +Then, add the following entries to your DNS server (assuming that your custom domain is `my.domain.net`): | Type | Domain | Data | | ----- | ----------------------------------- | ------------------------------------------------------------- | | CNAME | 
my.domain.net
| 
sandhole.com
| | TXT | 
\_sandhole.my.domain.net
| 
SHA256:bwf4FDtNeZzFv8xHBzHJwRpDRxssCll8w2tCHFC9n1o
| -This instructs your DNS to redirect requests to Sandhole, and tells Sandhole to authorize your SSH key for the given domain, respectively. +This instructs your DNS server to redirect requests to Sandhole, and tells Sandhole to authorize your SSH key for the given domain, respectively. If you need to use multiple keys for the same domain, simply add a TXT record for each one. @@ -39,7 +39,7 @@ ssh -R my.domain.net:80:localhost:3000 sandhole.com -p 2222 ### HTTPS support -If your administrator has configured [ACME support](./tls_support.md#acme-support), you don't need any extra steps. HTTPS will be automatically provisioned for your custom domain. +If your administrator has configured [ACME support](./tls_support.md#acme-support), you don't need any extra steps to enable HTTPS support. It will be automatically provisioned for your custom domain. However, if you require DNS challenges for your domain's certification for any reason, and your administrator is running [dnsrobocert](./tls_support.md), you can simply set another DNS entry: @@ -47,4 +47,4 @@ However, if you require DNS challenges for your domain's certification for any r | ----- | ----------------------------------------- | ------------------------------------------------------ | | CNAME | 
\_acme-challenge.my.domain.net
| 
\_acme-challenge.my.domain.net.sandhole.com
| -This lets dnsrobocert manage the ACME challenge for you, as long as the admin updates its configuration. +This lets dnsrobocert manage the ACME challenge for you, as long as the admin updates dnsrobocert's configuration with [`follow_cnames`](https://adferrand.github.io/dnsrobocert/configuration_reference.html#follow-cnames). diff --git a/book/src/compiling_from_source.md b/book/src/compiling_from_source.md index 238d099..fecc5a8 100644 --- a/book/src/compiling_from_source.md +++ b/book/src/compiling_from_source.md @@ -11,7 +11,7 @@ cargo build --release scp target/release/sandhole user@sandhole.com:/usr/local/bin/sandhole ``` -If you're compiling on the machine that's running Sandhole, you can install it directly with `cargo install`. This should also add `sandhole` to your `PATH`: +If you're compiling on the machine that'll be running Sandhole, you can install it directly with `cargo install`. This should also add `sandhole` to your `PATH`: ```bash cargo install --git https://github.com/EpicEric/sandhole diff --git a/book/src/configuration.md b/book/src/configuration.md index b3c8a0a..cf8c017 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -38,7 +38,7 @@ Otherwise, if you wish the subdomains to still be random, but persist between re In some scenarios, it makes more sense to authenticate users dynamically with a password, rather than manually adding public keys to a directory. -For such use cases, you can provide a URL to `--password-authentication-url`. This should be running an HTTP or HTTPS service which accepts a POST request with a JSON body containing the user's credentials, and returns 2xx on successful authentication. This is what the JSON payload looks like: +In order to support this, you can provide a URL to `--password-authentication-url`. This should be running an HTTP or HTTPS service, which must accept a JSON POST request containing the user's credentials as follows: ```json { @@ -48,10 +48,12 @@ For such use cases, you can provide a URL to `--password-authentication-url`. Th } ``` +Any 2xx status will signify a successful authentication. + ## Restricting resources for users By default, users are able to bind as many services as they want. In order to limit this amount, Sandhole provides the `--quota-per-user` option, which must be a number greater than 0. The user's quota includes all services across HTTP, SSH, and TCP. -To enforce this quota across multiple connections, a user is purpoted to be any forwardings sharing _the same public key_. In the case of [password-authenticated users](#alternative-authentication-with-password), _their username_ will be considered instead. +To enforce this quota across multiple connections, Sandhole considers a unique user to be any number of forwardings sharing _the same public key_. In the case of [password-authenticated users](#alternative-authentication-with-password), _their username_ will be considered instead. The quota is not enforced for admin users. diff --git a/book/src/docker_compose.md b/book/src/docker_compose.md index 21eb6c1..fe389b5 100644 --- a/book/src/docker_compose.md +++ b/book/src/docker_compose.md @@ -1,10 +1,10 @@ # Using Docker Compose -The most straightforward way to have Sandhole up and running is with Docker Compose. Mainly, this takes care of running dnsrobocert for you, and daemonizes your application. +The most straightforward way to have Sandhole up and running is with Docker Compose. Mainly, this takes care of running [dnsrobocert](https://adferrand.github.io/dnsrobocert/) for you, and also daemonizes your application. For this, you'll first need to install [Docker Engine](https://docs.docker.com/engine/install/) on your server. -An example configuration is provided in the repository's [docker-compose-example](https://github.com/EpicEric/sandhole/tree/main/docker-compose-example) directory, using `sandhole.com` as the example domain and Hetzner as the DNS provider for DNS-01 challenges. Adjust the `compose.yml` and `le-config.yml` files as necessary. +An example configuration is provided in the repository's [docker-compose-example](https://github.com/EpicEric/sandhole/tree/main/docker-compose-example) directory, using `sandhole.com` as the example domain and Hetzner as the DNS provider for DNS-01 challenges. Copy the `compose.yml` and `le-config.yml` files and adjust them as necessary. Then, simply run: diff --git a/book/src/exposing_your_first_service.md b/book/src/exposing_your_first_service.md index 9d33a8a..01d63f7 100644 --- a/book/src/exposing_your_first_service.md +++ b/book/src/exposing_your_first_service.md @@ -1,14 +1,12 @@ # Exposing your first service -Now that you have a Sandhole instance running, and you [authorized your public key](./configuration.md#adding-users-and-admins), you can expose a local service through Sandhole. Assuming that your local HTTP service is running on port 3000, and that Sandhole is listening on `sandhole.com:2222`, all you have to do is run +Once you have [an authorized public key](./configuration.md#adding-users-and-admins) in Sandhole, you can expose a local service. Assuming that your local HTTP service is running on port 3000, and that Sandhole is listening on `sandhole.com:2222`, all you have to do is run ```bash ssh -i /your/private/key -R 80:localhost:3000 sandhole.com -p 2222 ``` -Yep, that's it! Sandhole will log that HTTP is being served for you on a certain subdomain, and you can access the provided URL to see that your service is available to the public. - -For HTTP and HTTPS services, Websockets work out of the box. +Yep, that's it! Sandhole will log that HTTP is being served for you on a certain subdomain, and you can access the URL printed to the console to see that your service is available to the public. ## Requesting multiple tunnels @@ -40,7 +38,7 @@ ssh -i /your/private/key -R localhost:4321:localhost:3000 sandhole.com -p 2222 ## Connecting with user + password -If you'd like to connect with a password instead of your public key, make sure that [HTTP(S) login](./configuration.md#alternative-authentication-with-password) has been enabled by the administrator, then run: +If you'd like to connect with a password instead of your public key, make sure that [password authentication](./configuration.md#alternative-authentication-with-password) has been enabled by the administrator, then run: ```bash ssh -o PubkeyAuthentication=no -o PreferredAuthentications=password username@sandhole.com -p 2222 ... @@ -48,6 +46,6 @@ ssh -o PubkeyAuthentication=no -o PreferredAuthentications=password username@san ## Automatic reconnection -If you'd like to have persistent tunnels, use a tool like `autossh` with the `-M 0` option to automatically reconnect when disconnected. Note that you might be assigned a new subdomain or port through disconnects, depending on the server configuration. +If you'd like to have persistent tunnels, use a tool like `autossh` to automatically reconnect when disconnected. Note that you might be assigned a new subdomain or port through disconnects, depending on the server configuration. For a container-based alternative, [check out the Docker Compose client example](https://github.com/EpicEric/sandhole/tree/main/docker-compose-example/client) in the repository. diff --git a/book/src/faq.md b/book/src/faq.md index 7e4f04c..750a4a4 100644 --- a/book/src/faq.md +++ b/book/src/faq.md @@ -6,7 +6,7 @@ ssh -R website.com:80:localhost:3000 -R www.website.com:80:localhost:3000 sandhole.com -p 2222 ``` -See ["Advanced Uses"](./advanced_uses.md#custom-domains) on how to add custom domains. +See also ["Advanced uses"](./advanced_uses.md#custom-domains) on how to add custom domains. ## How do I connect to a forwarded SSH server? @@ -26,7 +26,7 @@ Websockets are always enabled for HTTP services. ## How do I disable HTTP/TCP/aliasing? -With the `--disable--http`, `--disable-tcp`, and `--disable-aliasing` [CLI flags](./cli.md) respectively. Note that you cannot disable all three at once. +With the `--disable--http`, `--disable-tcp`, and `--disable-aliasing` [CLI flags](./cli.md) respectively. Note that you cannot disable all three at once, as that'd remove all of Sandhole's functionality. ## How do I prevent multiple services from load-balancing? @@ -34,15 +34,15 @@ With the `--load-balancing=deny` or `--load-balancing=replace` [CLI flag](./cli. ## How do I force HTTP requests to get redirected to HTTPS? -With the `--force-https` [CLI flag](./cli.md), or by passing `force-https` on the tunneling connection(s): +You may do so globally with the `--force-https` [CLI flag](./cli.md), or per service by passing `force-https` on the tunneling connection(s): ```bash -ssh -R website.com:80:localhost:3000 sandhole.com -p 2222 force-https +ssh -R website.com:443:localhost:3000 sandhole.com -p 2222 force-https ``` ## How do I allow/block certain IP ranges? -With the `--ip-allowlist` and `--ip-blocklist` [CLI flags](./cli.md) respectively, or by passing `ip-allowist=...` and/or `ip-blocklist=...` on the tunneling connection(s): +You may do so globally with the `--ip-allowlist` and `--ip-blocklist` [CLI flags](./cli.md) respectively, or per service by passing `ip-allowist=...` and/or `ip-blocklist=...` on the tunneling connection(s): ```bash ssh -R website.com:80:localhost:3000 sandhole.com -p 2222 ip-allowlist=10.0.0.0/8 ip-blocklist=10.1.0.0/16 @@ -59,4 +59,4 @@ COPY --from=epiceric/sandhole:latest /sandhole /sandhole ENTRYPOINT [ "/sandhole" ] ``` -If you don't need the [HTTPS login API functionality](./configuration.md#alternative-authentication-with-password), you can skip mounting the certificates directory, and just use the plain Docker image. +However, if you don't intend to use the [HTTPS login API functionality](./configuration.md#alternative-authentication-with-password), you can skip using certificates entirely. diff --git a/book/src/introduction.md b/book/src/introduction.md index d774a90..e4720e5 100644 --- a/book/src/introduction.md +++ b/book/src/introduction.md @@ -6,11 +6,11 @@ Welcome to the **Sandhole book**. This is a guide on how to install, configure, ## About the project -[Sandhole](https://github.com/EpicEric/sandhole) is an unconventional reverse proxy which uses the built-in reverse port forwarding from OpenSSH, allowing services to expose themselves to the Internet with minimal configuration. This is especially useful for services behind NAT, but you may also want this for: +[Sandhole](https://github.com/EpicEric/sandhole) is an unconventional reverse proxy which uses the built-in reverse port forwarding from OpenSSH, allowing services to expose themselves to the Internet with minimal configuration. This is especially useful for services behind NAT, but you may also use Sandhole for: - Quickly prototyping websites, APIs, and TCP services, and sharing them with others. - Exposing endpoints or ports on IoT devices, game servers, and other applications. - Hosting a dual-stack HTTP+SSH service (via ProxyJump), such as a Git instance. - Handling a multi-tenant network with several websites under the same domain. -- Using the tunnel for peer-to-peer connections, or [even as a basic VPN](./local_forwarding.md). +- Using the tunnel for ad hoc peer-to-peer connections, or [even as a basic VPN](./local_forwarding.md). - And possibly more! diff --git a/book/src/local_forwarding.md b/book/src/local_forwarding.md index 142f5d7..5cc508d 100644 --- a/book/src/local_forwarding.md +++ b/book/src/local_forwarding.md @@ -2,13 +2,13 @@ In addition to remote port forwarding, Sandhole also supports local port forwarding by default. This allows you to create SSH-based tunnels to connect to a service. -Given a remote service running as +Given a remote service running as: ```bash ssh -R my.tunnel:3000:localhost:2000 sandhole.com -p 2222 ``` -Note that the server won't listen on port 3000; instead, you can establish a local forward to the port from your machine: +Note that the server won't listen on port 3000; the service will instead alias to `my.tunnel`. You can establish a local forward to the port from your machine: ```bash ssh -L 4000:my.tunnel:3000 @@ -16,11 +16,11 @@ ssh -L 4000:my.tunnel:3000 Then you can access `localhost:4000`, and all traffic will be redirected to port 2000 on the remote service. It's almost like a VPN! -## Enforcing local forwarding +## Enforcing aliasing -Local forwarding is always enabled for SSH hosts, and is conditionally enabled for TCP hosts that have a requested address different from `localhost`. +Aliasing is always enabled for SSH hosts, and is conditionally enabled for TCP hosts that have requested a address different from `localhost` (for example, `my.tunnel` in the previous section). -To enable local forwarding for HTTP hosts, pass either the `tcp-alias` or [the `allowed-fingerprints`](#restricting-access-to-local-forwardings) command to the remote forwarding command as follows: +To enable aliasing for HTTP hosts, pass either the `tcp-alias` command to the remote forwarding command as follows: ```bash ssh -R my.tunnel:80:localhost:8080 sandhole.com -p 2222 tcp-alias @@ -34,6 +34,10 @@ If you'd like to restrict which users can access your service, you can provide t ssh -R my.tunnel:3000:localhost:2000 sandhole.com -p 2222 allowed-fingerprints=SHA256:GehKyA21BBK6eJCouziacUmqYDNl8BPMGG0CTtLSrbQ,SHA256:bwf4FDtNeZzFv8xHBzHJwRpDRxssCll8w2tCHFC9n1o ``` +These fingerprints may belong to keys unrecognized by Sandhole, and they'll still be able to connect to your tunnel. + +This option will also enforce aliasing for HTTP hosts. + ## Disabling local forwarding The administrator can disable all local forwardings with the [`--disable-aliasing` CLI flag](./cli.md). diff --git a/book/src/tls_support.md b/book/src/tls_support.md index c12983d..9e13f02 100644 --- a/book/src/tls_support.md +++ b/book/src/tls_support.md @@ -2,9 +2,9 @@ Sandhole supports TLS signing out of the box, including ACME challenges via TLS-ALPN-01 for custom domains. -However, especially for your main domain, it's recommended that you set up a tool like [dnsrobocert](https://github.com/adferrand/dnsrobocert) to handle the wildcard certification via DNS. Sandhole already matches dnsrobocert's output directly. Please see its documentation to set it up yourself. +However, especially for your main domain (eg. `*.sandhole.com`), it's recommended that you set up a tool like [dnsrobocert](https://github.com/adferrand/dnsrobocert) to handle the wildcard certification via DNS. Sandhole already matches dnsrobocert's output directly. Please see [dnsrobocert's documentation](https://adferrand.github.io/dnsrobocert/) to set it up yourself. -Assuming that the output of dnsrobocert is `./letsencrypt`, Sandhole can then read the certificates via: +Assuming that the output of dnsrobocert is in `./letsencrypt`, Sandhole can then read the certificates via: ```bash sandhole --domain sandhole.com --certificates-directory ./letsencrypt/live @@ -12,4 +12,4 @@ sandhole --domain sandhole.com --certificates-directory ./letsencrypt/live ## ACME support -Adding ACME support is as simple as adding your contact e-mail address via `--acme-contact-email you@your.email.com`, but first, make sure that you agree to the Let's Encrypt Subscriber Agreement ([available here](https://letsencrypt.org/repository/)). Sandhole will automatically manage the cache for your account and any certificates generated this way. +Adding ACME support is as simple as adding your contact e-mail address via `--acme-contact-email you@your.email.com`, but first, make sure that you agree to [the Let's Encrypt Subscriber Agreement](https://letsencrypt.org/repository/). Sandhole will automatically manage the cache for your account and any certificates generated this way.