### Sandhole Startup Log Output Source: https://github.com/epiceric/sandhole/blob/main/book/src/quick_start.md Example log output indicating a successful Sandhole startup. Shows the application initializing, creating key files if missing, and listening on default ports. ```log 2025-06-07T02:34:01.346654097+00:00 INFO sandhole: Starting Sandhole... 2025-06-07T02:34:01.347502369+00:00 INFO sandhole: Key file not found. Creating... 2025-06-07T02:34:01.351344652+00:00 INFO sandhole: Listening for HTTP connections on port 80. 2025-06-07T02:34:01.351376882+00:00 INFO sandhole: Listening for HTTPS connections on port 443. 2025-06-07T02:34:01.351420152+00:00 INFO sandhole: Listening for SSH connections on port 2222. 2025-06-07T02:34:01.351424230+00:00 INFO sandhole: Sandhole is now running. ``` -------------------------------- ### Run Sandhole with Domain Source: https://github.com/epiceric/sandhole/blob/main/book/src/quick_start.md Execute the downloaded Sandhole binary, specifying your domain name. This command starts Sandhole, exposing default ports for HTTP, HTTPS, and SSH. ```bash ./sandhole --domain sandhole.com.br ``` -------------------------------- ### Download Sandhole Executable (x64/AArch64) Source: https://github.com/epiceric/sandhole/blob/main/book/src/quick_start.md Download the latest Sandhole release binary for Linux. Supports both x64 and AArch64 architectures using wget. Alternatively, consider Docker Compose or compiling from source. ```bash # x64 wget --output-document sandhole https://github.com/EpicEric/sandhole/releases/latest/download/sandhole-linux-amd64 # # -- OR -- # # AArch64 wget --output-document sandhole https://github.com/EpicEric/sandhole/releases/latest/download/sandhole-linux-arm64 ``` -------------------------------- ### Ping Statistics Example Source: https://github.com/epiceric/sandhole/blob/main/book/src/benchmarks.md Example output from a ping command, showing network latency statistics between a client and a service. ```shell --- sandhole.com.br ping statistics --- 30 packets transmitted, 30 received, 0% packet loss, time 29131ms rtt min/avg/max/mdev = 141.265/144.842/150.421/2.243 ms ``` -------------------------------- ### Install Sandhole using Cargo Source: https://github.com/epiceric/sandhole/blob/main/book/src/compiling_from_source.md Installs the Sandhole project directly using Cargo. Supports installation from the latest release on crates.io or from the development version on GitHub. ```bash # Install from latest release cargo install --locked sandhole ``` ```bash # Install the current development version cargo install --locked --git https://github.com/EpicEric/sandhole ``` -------------------------------- ### Connect to Forwarded SSH Server via ProxyJump Source: https://github.com/epiceric/sandhole/blob/main/book/src/faq.md Provides instructions for connecting to an SSH server through a Sandhole proxy. It includes the direct command-line usage and an example of how to configure your SSH client's config file for persistent proxy jump settings. ```bash ssh -p 2222 -J sandhole.com.br:2222 mysshserver.com ``` ```ssh-config Host mysshserver.com ProxyJump sandhole.com.br:2222 Port 2222 ``` -------------------------------- ### Sandhole Example Flow Sequence Diagram Source: https://github.com/epiceric/sandhole/blob/main/book/src/technical_overview.md A Mermaid sequence diagram illustrating the step-by-step process of how Sandhole handles a client request to expose a local service through SSH tunneling. It shows the interaction between SSH client, server, connection map, HTTP server, and web client. ```mermaid sequenceDiagram participant SC as SSH client participant SS as SSH server participant M as Connection map participant HS as HTTP server participant HC as Web client Note over SC, M: Tunnel setup SC ->> SS: SSH connection + tcpip_forward SS ->> SS: Validate login SS ->> M: Register tunnel handler Note over SC, HC: Traffic routing HC ->>+ HS: HTTP request to assigned domain HS ->> M: Look up tunnel for domain HS ->>+ SS: Forward request via tunnel SS ->>+ SC: Relay to local service SC -->>- SS: Response from local service SS -->>- HS: Forward response HS -->>- HC: Return HTTP response ``` -------------------------------- ### Start Sandhole with Docker Compose Source: https://github.com/epiceric/sandhole/blob/main/book/src/docker_compose.md This command starts the Sandhole application in detached mode using Docker Compose. It's the primary method for running Sandhole, ensuring background operation and proper daemonization. Re-run this command after configuration changes or image updates. ```bash docker compose up -d # ... which is shorthand for: docker compose up --detach ``` -------------------------------- ### Request Multiple Tunnels Simultaneously Source: https://github.com/epiceric/sandhole/blob/main/book/src/exposing_your_first_service.md Allows exposing multiple local services concurrently by specifying multiple reverse tunnel configurations (`-R`) in a single SSH command. This example exposes two HTTP services and one SSH service. ```bash ssh -i /your/private/key -p 2222 -R 80:localhost:3000 -R 80:localhost:4000 -R 22:localhost:5000 sandhole.com.br ``` -------------------------------- ### Password Authentication Request Body Source: https://github.com/epiceric/sandhole/blob/main/book/src/configuration.md Example JSON payload for password authentication requests sent to the `--password-authentication-url`. The service must accept a JSON POST request with user credentials. ```json { "user": "eric", "password": "super$ecret123", "remote_address": "[::ffff:10.0.5.32]:12703" // std::net::SocketAddr } ``` -------------------------------- ### Get SSH Key Fingerprint Source: https://github.com/epiceric/sandhole/blob/main/book/src/custom_domains.md Command to retrieve the fingerprint of an SSH private key. This fingerprint is used for domain authorization with Sandhole. ```bash ssh-keygen -lf /path/to/private/key ``` -------------------------------- ### Expose Service on Multiple Domains Source: https://github.com/epiceric/sandhole/blob/main/book/src/faq.md Demonstrates how to expose a local service running on localhost:3000 to multiple custom domains (e.g., example.com and www.example.com) via Sandhole. This command establishes SSH reverse tunnels for each domain. ```bash ssh -p 2222 -R example.com:80:localhost:3000 -R www.example.com:80:localhost:3000 sandhole.com.br ``` -------------------------------- ### Build and SCP Sandhole Binary Source: https://github.com/epiceric/sandhole/blob/main/book/src/compiling_from_source.md Clones the Sandhole repository, builds the release binary using Cargo, and securely copies it to a remote server using SCP for deployment. ```bash git clone https://github.com/EpicEric/sandhole cd sandhole cargo build --locked --release scp target/release/sandhole user@sandhole.com.br:/usr/local/bin/sandhole ``` -------------------------------- ### Sandhole CLI Options Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md Details the available command-line options for the Sandhole application, including their purpose, expected arguments, default values, and behavior. This documentation is generated from the `--help` output. ```APIDOC Sandhole CLI Options: Expose HTTP/SSH/TCP services through SSH port forwarding. Usage: sandhole [OPTIONS] --domain Options: --domain The root domain of the application --domain-redirect Where to redirect requests to the root domain [default: https://github.com/EpicEric/sandhole] --user-keys-directory Directory containing public keys of authorized users. Each file must contain at least one key [default: ./deploy/user_keys/] --admin-keys-directory Directory containing public keys of admin users. Each file must contain at least one key [default: ./deploy/admin_keys/] --certificates-directory Directory containing SSL certificates and keys. Each sub-directory inside of this one must contain a certificate chain in a fullchain.pem file and its private key in a privkey.pem file [default: ./deploy/certificates/] --acme-cache-directory Directory to use as a cache for Let's Encrypt's account and certificates. This will automatically be created for you. Note that this setting ignores the --disable-directory-creation flag. [default: ./deploy/acme_cache/] --private-key-file File path to the server's secret key. If missing, it will be created for you [default: ./deploy/server_keys/ssh] --disable-directory-creation If set, disables automatic creation of the directories expected by the application. This may result in application errors if the directories are missing --listen-address
Address to listen for all client connections [default: ::] --ssh-port Port to listen for SSH connections [default: 2222] --http-port Port to listen for HTTP connections [default: 80] --https-port Port to listen for HTTPS connections [default: 443] --connect-ssh-on-https-port Allow connecting to SSH via the HTTPS port as well. This can be useful in networks that block binding to other ports --force-https Always redirect HTTP requests to HTTPS --disable-http-logs Disable sending HTTP logs to clients --disable-tcp-logs Disable sending TCP/proxy logs to clients --acme-contact-email Contact e-mail to use with Let's Encrypt. If set, enables ACME for HTTPS certificates. By providing your e-mail, you agree to the Let's Encrypt Subscriber Agreement. --acme-use-staging Controls whether to use the staging directory for Let's Encrypt certificates (default is production). Only set this option for testing --password-authentication-url If set, defines a URL which password authentication requests will be validated against. This is done by sending the following JSON payload via a POST request: {"user": "...", "password": "...", "remote_address": "..."} Any 2xx response indicates that the credentials are authorized. --bind-hostnames Policy on whether to allow binding specific hostnames. Beware that this can lead to domain takeovers if misused! [default: txt] Possible values: - all: Allow any hostnames unconditionally, including the main domain - cname: Allow any hostnames with a CNAME record pointing to the main domain - txt: Allow any hostnames with a TXT record containing a fingerprint, including the main domain - none: Don't allow user-provided hostnames, enforce subdomains --load-balancing Strategy for load-balancing when multiple services request the same hostname/port. By default, traffic towards matching hostnames/ports will be load-balanced. [default: allow] Possible values: - allow: Load-balance with all available handlers - replace: Don't load-balance; When adding a new handler, ``` -------------------------------- ### Run Tests and Linting Source: https://github.com/epiceric/sandhole/blob/main/CONTRIBUTING.md Execute project tests and linting checks using the 'just' command-line tool. This ensures code quality and adherence to project standards before submitting changes. ```shell just test just clippy ``` -------------------------------- ### Sandhole Command-Line Options Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md This section details the command-line arguments and flags available for the Sandhole application. It covers various timeouts for connections and requests, authentication settings, and options for displaying help or version information. ```APIDOC Sandhole CLI Options: --idle-connection-timeout Timeout for idle connections. If unset, defaults to the value set by --idle-connection-timeout. --authentication-request-timeout Time until a user+password authentication request is canceled. Any timed out requests will not authenticate the user. [default: 5s] --http-request-timeout Time until an outgoing HTTP request is automatically canceled. By default, outgoing requests are not terminated by Sandhole. --tcp-connection-timeout How long until TCP connections (including Websockets and local forwardings) are automatically garbage-collected. By default, these connections are not terminated by Sandhole. -h, --help Print help (see a summary with '-h'). -V, --version Print version. ``` -------------------------------- ### Sandhole CLI Configuration Flags Source: https://github.com/epiceric/sandhole/blob/main/book/src/faq.md Details various command-line interface (CLI) flags for configuring Sandhole's behavior. This includes disabling specific protocols, managing load balancing, forcing HTTPS redirection, and setting IP allow/block lists. ```APIDOC Sandhole CLI Flags: --disable-http Disables HTTP protocol handling. --disable-tcp Disables TCP protocol handling. --disable-aliasing Disables aliasing functionality. --disable-https Disables HTTPS protocol handling. --disable-sni Disables Server Name Indication (SNI) handling. --load-balancing=deny|replace Controls load balancing behavior. 'deny' prevents it, 'replace' replaces existing configurations. --force-https Globally forces all HTTP requests to redirect to HTTPS. --ip-allowlist Globally allows connections only from specified IP address ranges (CIDR notation). --ip-blocklist Globally blocks connections from specified IP address ranges (CIDR notation). Note: It is not possible to disable all three of --disable-http, --disable-tcp, and --disable-aliasing simultaneously, as this would remove all core Sandhole functionality. ``` -------------------------------- ### Sandhole Per-Service Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/faq.md Explains how to configure specific Sandhole behaviors on a per-service basis by passing options within the tunneling connection string. This allows for granular control over features like HTTPS redirection and IP filtering. ```APIDOC Per-Service Configuration Options: force-https Forces HTTP requests for this specific service to redirect to HTTPS. Example: "force-https" ip-allowlist= Allows connections only from specified IP address ranges for this service. Example: "ip-allowlist=192.168.1.0/24" ip-blocklist= Blocks connections from specified IP address ranges for this service. Example: "ip-blocklist=10.0.0.0/8" These options are passed as part of the tunneling connection string, similar to how you might pass arguments to a command. ``` -------------------------------- ### Generate CLI Documentation Source: https://github.com/epiceric/sandhole/blob/main/CONTRIBUTING.md Generate command-line interface documentation using the 'just cli' command. This process involves updating the `cli.html` file and subsequently the `cli.md` documentation page. ```shell just cli ``` -------------------------------- ### Sandhole DNS TXT Record Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md Specifies a prefix for TXT DNS records used for authorization to bind under a specific domain. Valid records are in the format: TXT . SHA256:.... ```APIDOC --txt-record-prefix Prefix for TXT DNS records containing key fingerprints, for authorization to bind under a specific domain. In other words, valid records will be of the form: TXT . SHA256:... [default: _sandhole] ``` -------------------------------- ### Configure Sandhole with dnsrobocert Certificates (Bash) Source: https://github.com/epiceric/sandhole/blob/main/book/src/tls_support.md This command configures Sandhole to use TLS certificates managed by dnsrobocert. It points Sandhole to the directory where dnsrobocert typically places its live certificates, allowing Sandhole to utilize these for TLS signing. ```bash sandhole --domain sandhole.com.br --certificates-directory ./letsencrypt/live ``` -------------------------------- ### Sandhole Subdomain and Port Handling Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md Controls whether users can request specific subdomains and ports, and configures the generation and filtering of random subdomains. ```APIDOC --allow-requested-subdomains Allow user-requested subdomains. By default, subdomains are always random ``` ```APIDOC --allow-requested-ports Allow user-requested ports. By default, ports are always random ``` ```APIDOC --random-subdomain-seed Which value to seed with when generating random subdomains, for determinism. This allows binding to the same random address until Sandhole is restarted. Beware that this can lead to collisions if misused! If unset, defaults to a random seed. Possible values: - ip-and-user: From IP address, SSH user, and requested address. Recommended if unsure - user: From SSH user and requested address - fingerprint: From SSH user, key fingerprint, and requested address - address: From SSH connection socket (address + port) and requested address ``` ```APIDOC --random-subdomain-length The length of the string appended to the start of random subdomains [default: 6] ``` ```APIDOC --random-subdomain-filter-profanities Prevents random subdomains from containing profanities ``` ```APIDOC --requested-domain-filter-profanities Prevents user-requested domains/subdomains from containing profanities. Beware that this can lead to false positives being blocked! ``` -------------------------------- ### Sandhole Connection and Buffer Settings Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md Configures the size of bidirectional buffers used for data transfer and the grace periods for idle or unauthenticated connections before they are disconnected. ```APIDOC --buffer-size Size to use for bidirectional buffers, in bytes. A higher value will lead to higher memory consumption. [default: 32768B] ``` ```APIDOC --idle-connection-timeout Grace period for dangling/unauthenticated connections before they are forcefully disconnected. A low value may cause valid connections to be erroneously removed. [default: 2s] ``` ```APIDOC --unproxied-connection-timeout Grace period for unauthenticated SSH connections after closing the last proxy tunnel before they are forcefully disconnected. A low value may cause valid proxy/tunnel connections to be erroneously ``` -------------------------------- ### Configure Sandhole with Agnos Certificates (Bash) Source: https://github.com/epiceric/sandhole/blob/main/book/src/tls_support.md This command configures Sandhole to use TLS certificates managed by Agnos. It specifies the domain and the directory where Agnos stores the fullchain.pem and privkey.pem files, enabling Sandhole to access them for TLS signing. ```bash sandhole --domain sandhole.com.br --certificates-directory ./agnos ``` -------------------------------- ### Sandhole Proxy Headers Source: https://github.com/epiceric/sandhole/blob/main/book/src/faq.md Lists the standard proxy headers set by Sandhole that can be used to retrieve information about the original client request. These headers are crucial for understanding the context of incoming traffic. ```APIDOC Sandhole Proxy Headers: X-Forwarded-For Contains the original IP address of the client making the request. X-Forwarded-Host Contains the original hostname header sent by the client. X-Forwarded-Proto Indicates the protocol used by the client (e.g., 'http' or 'https'). X-Forwarded-Port Specifies the original port number used by the client. ``` -------------------------------- ### Optimize Sandhole Performance with Ciphers Source: https://github.com/epiceric/sandhole/blob/main/book/src/faq.md Provides recommendations for optimizing Sandhole's performance by selecting appropriate encryption ciphers based on hardware capabilities. It suggests AES-GCM for x64 processors and ChaCha20-Poly1305 for ARM processors when supported by OpenSSH. ```bash # For x64 processors with AES hardware support: ssh -c aes256-gcm@openssh.com ... # For ARM processors with modern OpenSSH: ssh -c chacha20-poly1305@openssh.com ... ``` -------------------------------- ### Connect with Password Authentication Source: https://github.com/epiceric/sandhole/blob/main/book/src/exposing_your_first_service.md Demonstrates how to connect to Sandhole using password authentication instead of SSH keys. This requires the administrator to enable password authentication and specifies the authentication method explicitly. ```bash ssh -p 2222 -o PubkeyAuthentication=no -o PreferredAuthentications=password username@sandhole.com.br ``` -------------------------------- ### Admin Interface Features Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Details on Sandhole's terminal-based admin interface, including real-time metrics, connection viewing, user management, and admin-only aliases. ```APIDOC Admin Interface: terminal-ui: Provides a terminal-based interface accessible via admin key authentication. - Access method: Admin key authentication. system-metrics: Displays real-time system metrics (CPU, memory, network usage). - Available in terminal UI. active-connections: - Views all active connections (SSH, HTTP, SNI, TCP, and alias). - Displays real-time connection statistics. - Shows user details for connections, including key algorithm and comments. - Allows removal of user connections and keys. - Available in terminal UI. admin-only-aliases: - Provides access to special aliases only forwardable by admin users. - Example: `prometheus.sandhole:10` for exposing Prometheus metrics. ``` -------------------------------- ### Networking Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure Sandhole's network interface settings, including listen address, SSH port, HTTP port, HTTPS port, and domain redirect page. ```APIDOC Networking Configuration: listen-address: Configures the address for network interfaces. - CLI: `--listen-address
` ssh-port: Changes the SSH port from the default 2222. - CLI: `--ssh-port ` http-port: Changes the HTTP port from the default 80. - CLI: `--http-port ` https-port: Changes the HTTPS port from the default 443. - CLI: `--https-port ` domain-redirect: Configures the redirect page for the root domain. - CLI: `--domain-redirect ` ``` -------------------------------- ### Bind Service to Specific Subdomain Source: https://github.com/epiceric/sandhole/blob/main/book/src/exposing_your_first_service.md Configures Sandhole to bind a local service to a specific subdomain, such as 'test.sandhole.com.br', or a custom subdomain name. This requires the server owner to enable this functionality. ```bash ssh -i /your/private/key -p 2222 -R test:80:localhost:3000 sandhole.com.br ``` ```bash ssh -i /your/private/key -p 2222 -R test.sandhole.com.br:80:localhost:3000 sandhole.com.br ``` -------------------------------- ### Reverse Proxy Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure Sandhole's reverse proxy features, including access logs, load balancing, IP allowlisting/blocklisting, and user quotas/rate limits. ```APIDOC Reverse Proxy: access-logs: Enables access logs for HTTP, TCP, and aliases. - SSH exec: `access-logs` (implied) load-balancing: - Controls if and how services are load-balanced. - CLI: `--load-balancing ` (e.g., round-robin, least-connections) - CLI: `--load-balancing-algorithm ` ip-allowlist: Controls allowed incoming connections by IP address CIDRs. - SSH exec: `ip-allowlist ` - CLI: `--ip-allowlist ` ip-blocklist: Controls blocked incoming connections by IP address CIDRs. - SSH exec: `ip-blocklist ` - CLI: `--ip-blocklist ` quota-per-user: Restricts maximum services exposed by users. - CLI: `--quota-per-user ` rate-limit-per-user: Restricts maximum transfer rate by the users' services. - CLI: `--rate-limit-per-user ` ``` -------------------------------- ### Sandhole Load Balancing Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md Configures the algorithm used for service selection when load-balancing traffic between services. The default is random distribution. ```APIDOC --load-balancing-algorithm Algorithm to use for service selection when load-balancing. By default, traffic will be randomly distributed between services. [default: random] Possible values: - random: Choose randomly - round-robin: Round robin - ip-hash: Choose based on IP hash ``` -------------------------------- ### Basic Remote Port Forwarding with Sandhole Source: https://github.com/epiceric/sandhole/blob/main/book/src/local_forwarding.md Establishes a remote port forward using SSH, aliasing a remote service to `my.tunnel`. This allows subsequent local forwards to connect to the remote service via the alias. ```bash ssh -p 2222 -R my.tunnel:3000:localhost:2000 sandhole.com.br ``` -------------------------------- ### ACME (Let's Encrypt) Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure Sandhole's integration with Let's Encrypt's ACME server for dynamic TLS certificates, including contact email and staging server options. ```APIDOC ACME (Let's Encrypt): acme-contact-email: Specifies the contact email for Let's Encrypt ACME server. - CLI: `--acme-contact-email ` acme-use-staging: Uses Let's Encrypt's staging server for ACME debug mode. - CLI: `--acme-use-staging` ``` -------------------------------- ### Resource Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure Sandhole's resource management, including buffer size, idle connection timeouts, unproxied connection timeouts, and request timeouts. ```APIDOC Resource Configuration: buffer-size: Configurable buffer size for bidirectional proxying. - CLI: `--buffer-size ` idle-connection-timeout: Automatic cleanup of idle connections via timeout. - CLI: `--idle-connection-timeout ` unproxied-connection-timeout: Automatic cleanup of unproxied connections via timeout. - CLI: `--unproxied-connection-timeout ` http-request-timeout: Configures a timeout for HTTP/HTTPS requests. - CLI: `--http-request-timeout ` tcp-connection-timeout: Configures a timeout for TCP/WebSocket/aliasing connections. - CLI: `--tcp-connection-timeout ` ``` -------------------------------- ### Enable HTTP/2 with Sandhole (Bash) Source: https://github.com/epiceric/sandhole/blob/main/book/src/advanced_options.md The `http2` option instructs Sandhole to serve traffic using the HTTP/2 protocol instead of the default HTTP/1.1. This option requires the connection to be over HTTPS, so it's often used in conjunction with `force-https`. ```bash ssh -p 2222 -R my.tunnel:80:localhost:8080 sandhole.com.br http2 force-https ``` -------------------------------- ### Aliasing and ProxyJump Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure Sandhole's aliasing features for TCP, HTTP, SNI, and generic forwardings, including ProxyJump support and fingerprint restrictions. ```APIDOC Aliasing (Local Forwarding): tcp-alias: Enables TCP aliasing via SSH remote forwarding. - SSH exec: `tcp-alias` http-alias: Enables HTTP aliasing via SSH remote forwarding. - SSH exec: `http-alias` (implied with HTTP tunneling) sni-alias: Enables SNI aliasing via SSH remote forwarding. - SSH exec: `sni-alias` (implied with SNI proxying) proxyjump: Proxies SSH hosts via SSH remote forwarding. - SSH exec: `proxyjump` generic-aliases: Enables generic aliases via SSH remote forwarding. - SSH exec: `generic-aliases` allowed-fingerprints: Restricts fingerprints for local aliasing forwardings. - SSH exec: `allowed-fingerprints` ``` -------------------------------- ### File System Configuration Options Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configuration options related to directory management for SSH keys, TLS certificates, ACME cache, and private keys. It also includes a flag to disable automatic directory creation. ```APIDOC File System Configuration: - `--user-keys-directory `: Configures the directory for SSH user keys. - `--admin-keys-directory `: Configures the directory for SSH admin keys. - `--certificates-directory `: Configures the directory for TLS certificates and private keys. - `--acme-cache-directory `: Configures the directory for ACME cache. - `--private-key-file `: Specifies the file path for the server's private key. - `--disable-directory-creation`: Disables automatic creation of missing directories. ``` -------------------------------- ### Sandhole User Quotas and Rate Limits Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md Sets limits on the number of services a single user can expose and the maximum data transmission rate per user. These limits do not apply to admin users. ```APIDOC --quota-per-user How many services can be exposed for a single user at once. Doesn't apply to admin users. Each user is distinguished by their key fingerprint or, in the case of API logins, by their username. By default, no limit is set. ``` ```APIDOC --rate-limit-per-user How many bytes per second a single user's services can transmit at once. Doesn't apply to admin users. Each user is distinguished by their key fingerprint or, in the case of API logins, by their username. By default, no rate limit is set. For better results, this should be a multiple of --buffer-size. ``` -------------------------------- ### SSH Remote Port Forwarding Command Source: https://github.com/epiceric/sandhole/blob/main/book/src/technical_overview.md Demonstrates how to use the `ssh` command to establish a remote port forwarding tunnel. This allows a service running on a local machine to be exposed to a remote server via SSH. ```bash ssh -p 2222 -R mytunnel:80:localhost:8080 sandhole.com.br ``` -------------------------------- ### Authentication Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure authentication methods for Sandhole, including SSH public key authentication, password-based authentication, and timeout settings. ```APIDOC Authentication: ssh-public-key-auth: Enables SSH public key-based authentication for users and admins. - SSH exec: `ssh-key-auth` (implied) ssh-key-restricted-connection: Restricts SSH connections for local forwarding users to specific keys. - SSH exec: `ssh-key-restricted-connection` password-authentication: Enables password-based authentication for users. - CLI: `--password-authentication-url ` authentication-request-timeout: Configures the authentication request timeout. - CLI: `--authentication-request-timeout ` ``` -------------------------------- ### Filter IPs with Sandhole (Bash) Source: https://github.com/epiceric/sandhole/blob/main/book/src/advanced_options.md The `ip-allowlist` and `ip-blocklist` options provide granular control over which IP addresses can connect to your forwarded service. You can specify ranges using CIDR notation to permit or deny access. ```bash ssh -p 2222 -R website.com:80:localhost:3000 sandhole.com.br ip-allowlist=10.0.0.0/8,20ff::/16 ip-blocklist=10.1.0.0/16 ``` -------------------------------- ### Local Forwarding to Sandhole Alias Source: https://github.com/epiceric/sandhole/blob/main/book/src/local_forwarding.md Creates a local SSH tunnel to connect to a service aliased by Sandhole. Traffic sent to `localhost:4000` is redirected to the remote service specified in the remote forward command. ```bash ssh -L 4000:my.tunnel:3000 ``` -------------------------------- ### Sandhole IP Filtering Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md Defines IP address ranges that are allowed or blocked from connecting to the Sandhole service. The allowlist takes precedence if both are set. ```APIDOC --ip-allowlist Comma-separated list of IP networks to allow. Setting this will block unknown IPs from connecting ``` ```APIDOC --ip-blocklist Comma-separated list of IP networks to block. Setting this will allow unknown IPs to connect, unless --ip-allowlist is set ``` -------------------------------- ### HTTP/HTTPS Tunneling Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure Sandhole's HTTP and HTTPS tunneling capabilities, including redirect options, SNI proxying, HTTP/2 support, and subdomain generation settings. ```APIDOC HTTP/HTTPS Tunneling: force-https: Forces HTTP redirects to HTTPS. - SSH exec: `force-https` - CLI: `--force-https` sni-proxy: Enables Server Name Indication (SNI) proxying. - SSH exec: `sni-proxy` http2: Enables HTTP/2 proxying. - SSH exec: `http2` connect-ssh-on-https-port: Connects SSH clients via the HTTPS port. - CLI: `--connect-ssh-on-https-port` random-subdomain-generation: - Default: Generates random subdomains. - seed: Sets the seed for random subdomain generation. - CLI: `--random-subdomain-seed ` - length: Sets the length for random subdomains. - CLI: `--random-subdomain-length ` - filter-profanities: Skips subdomains containing profanities. - CLI: `--random-subdomain-filter-profanities` allow-requested-subdomains: Allows requested subdomains instead of random generation by default. - CLI: `--allow-requested-subdomains` forwarded-headers: Supports automatic X-Forwarded headers. - SSH exec: `x-forwarded` (implied) ``` -------------------------------- ### Authorization Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure authorization rules for Sandhole, controlling how external hostnames are bound and filtering requested domains. ```APIDOC Authorization: bind-hostnames: Controls how external hostnames are allowed to be bound. - CLI: `--bind-hostnames ` txt-record-prefix: Configures the prefix for TXT external hostname authorization for binding. - CLI: `--txt-record-prefix ` requested-domain-filter-profanities: Disables domains containing profanities from binding. - CLI: `--requested-domain-filter-profanities` ``` -------------------------------- ### Access Sandhole Admin Interface via SSH Source: https://github.com/epiceric/sandhole/blob/main/book/src/administration.md Connect to the Sandhole admin interface using SSH. This provides access to system information, proxied connections, and management capabilities. Requires admin credentials. ```bash ssh -p 2222 -t sandhole.com.br admin ``` -------------------------------- ### Expose Local HTTP Service via SSH Tunnel Source: https://github.com/epiceric/sandhole/blob/main/book/src/exposing_your_first_service.md Establishes a reverse SSH tunnel to expose a local HTTP service running on port 3000 to the public internet via Sandhole. The command forwards traffic from port 80 on the Sandhole server to the local service. ```bash ssh -i /your/private/key -p 2222 -R 80:localhost:3000 sandhole.com.br ``` -------------------------------- ### Module and Proxying Control Options Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Flags to disable various network functionalities and proxying mechanisms, including HTTP, HTTPS, SNI, TCP port binding, and generic aliasing. ```APIDOC Module and Proxying Control: - `--disable-http`: Disables HTTP proxying. - `--disable-https`: Disables HTTPS proxying. - `--disable-sni`: Disables SNI proxying. - `--disable-tcp`: Disables TCP port binding. - `--disable-aliasing`: Disables generic aliases and SSH ProxyJump. - `--disable-prometheus`: Disables Prometheus metrics collection and admin-only alias. ``` -------------------------------- ### Bind Service to Specific Port Source: https://github.com/epiceric/sandhole/blob/main/book/src/exposing_your_first_service.md Configures Sandhole to expose a local service on a specific public port, such as port 4321. This allows clients to connect to the service using a non-standard port. ```bash ssh -i /your/private/key -p 2222 -R 4321:localhost:3000 sandhole.com.br ``` ```bash ssh -i /your/private/key -p 2222 -R localhost:4321:localhost:3000 sandhole.com.br ``` -------------------------------- ### Connect SSH via HTTPS Port Source: https://github.com/epiceric/sandhole/blob/main/book/src/configuration.md Demonstrates connecting to Sandhole via the HTTPS port (443) to bypass network restrictions on port 22. This allows exposing services when standard SSH ports are blocked. ```bash ssh -R example:80:localhost:3000 sandhole.com.br -p 443 ``` -------------------------------- ### Expose Service via SSH Tunnel Source: https://github.com/epiceric/sandhole/blob/main/book/src/custom_domains.md Command to expose a local service (e.g., on localhost:3000) to a custom domain via an SSH tunnel. It forwards traffic from the custom domain to the local service. ```bash ssh -p 2222 -R my.domain.net:80:localhost:3000 sandhole.com.br ``` -------------------------------- ### TCP Tunneling Configuration Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Configure Sandhole's TCP tunneling capabilities, including options for port selection and handling requested ports. ```APIDOC TCP Tunneling: random-port-selection: Uses random port selection for TCP tunneling. - Default behavior. allow-requested-ports: Allows requested ports instead of random selection by default. - CLI: `--allow-requested-ports` ``` -------------------------------- ### Enforce Aliasing for HTTP Hosts Source: https://github.com/epiceric/sandhole/blob/main/book/src/local_forwarding.md Enables aliasing for HTTP hosts by passing the `tcp-alias` command to the remote forwarding command. This ensures that the alias is enforced for HTTP traffic. ```bash ssh -p 2222 -R my.tunnel:80:localhost:8080 sandhole.com.br tcp-alias ``` -------------------------------- ### Run Sandhole on Port 22 Source: https://github.com/epiceric/sandhole/blob/main/book/src/configuration.md Configures Sandhole to listen on port 22 for SSH connections, allowing the default SSH server to run on a different port. Requires adjusting the `sshd_config` file and restarting the SSH daemon. ```bash sandhole --domain server.com --ssh-port 22 ``` -------------------------------- ### Logging Configuration Options Source: https://github.com/epiceric/sandhole/blob/main/book/src/features.md Options to control logging behavior, including filtering based on tracing and disabling specific log types like HTTP or TCP access logs. ```APIDOC Logging Configuration: - Log Filtering: Supports `tracing`-based log filtering (see https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html). - `--disable-http-logs`: Disables HTTP access logs. - `--disable-tcp-logs`: Disables TCP access logs. ``` -------------------------------- ### Configure Allowed SSH Fingerprints with Sandhole (Bash) Source: https://github.com/epiceric/sandhole/blob/main/book/src/advanced_options.md The `allowed-fingerprints` option restricts access to remote forwardings by requiring specific SSH key fingerprints. This enhances security by ensuring only authorized clients can connect. It accepts a comma-separated list of SHA256 fingerprints. ```bash ssh -p 2222 -R my.tunnel:3000:localhost:2000 sandhole.com.br allowed-fingerprints=SHA256:GehKyA21BBK6eJCouziacUmqYDNl8BPMGG0CTtLSrbQ,SHA256:bwf4FDtNeZzFv8xHBzHJwRpDRxssCll8w2tCHFC9n1o ``` -------------------------------- ### Update Sandhole Docker Image Source: https://github.com/epiceric/sandhole/blob/main/book/src/docker_compose.md This command pulls the latest Sandhole Docker image and restarts the containers with the updated version. It's essential for applying new features or security patches. Ensure you run `docker compose up -d` afterwards if the containers do not restart automatically. ```bash docker compose pull docker compose up -d ``` -------------------------------- ### Restrict Access to Local Forwardings Source: https://github.com/epiceric/sandhole/blob/main/book/src/local_forwarding.md Restricts access to a Sandhole tunnel by providing a comma-separated list of allowed SSH public key fingerprints. This option also enforces aliasing for HTTP hosts. ```bash ssh -p 2222 -R my.tunnel:3000:localhost:2000 sandhole.com.br allowed-fingerprints=SHA256:GehKyA21BBK6eJCouziacUmqYDNl8BPMGG0CTtLSrbQ,SHA256:bwf4FDtNeZzFv8xHBzHJwRpDRxssCll8w2tCHFC9n1o ``` -------------------------------- ### Use SNI Proxy with Sandhole (Bash) Source: https://github.com/epiceric/sandhole/blob/main/book/src/advanced_options.md The `sni-proxy` option allows Sandhole to utilize a provided TLS backend, ensuring that Sandhole itself cannot decrypt unencrypted traffic. This option is intended for HTTPS connections and is often paired with `force-https`. ```bash ssh -p 2222 -R my.tunnel:80:localhost:8080 sandhole.com.br sni-proxy force-https ``` -------------------------------- ### Force HTTPS Redirection with Sandhole (Bash) Source: https://github.com/epiceric/sandhole/blob/main/book/src/advanced_options.md The `force-https` option ensures that all proxied HTTP requests are automatically redirected to HTTPS. This is a security measure to enforce encrypted communication for your forwarded service. ```bash ssh -p 2222 -R my.tunnel:80:localhost:8080 sandhole.com.br force-https ``` -------------------------------- ### Sandhole Tunneling Protocol Disabling Source: https://github.com/epiceric/sandhole/blob/main/book/src/cli.md Options to disable specific tunneling protocols or features globally. By default, most tunneling methods are enabled. ```APIDOC --disable-http Disable all HTTP tunneling. By default, this is enabled globally ``` ```APIDOC --disable-https Disable all HTTPS tunneling. By default, this is enabled globally ``` ```APIDOC --disable-sni Disable SNI proxy tunneling. By default, this is enabled globally ``` ```APIDOC --disable-tcp Disable all TCP port tunneling except HTTP. By default, this is enabled globally ``` ```APIDOC --disable-aliasing Disable all aliasing (i.e. local forwarding). By default, this is enabled globally ``` ```APIDOC --disable-prometheus Disable the admin-only alias for the Prometheus exporter. By default, it is enabled ``` -------------------------------- ### Enforce TCP Aliasing with Sandhole (Bash) Source: https://github.com/epiceric/sandhole/blob/main/book/src/advanced_options.md The `tcp-alias` option forces an HTTP remote forwarding request to act as an alias rather than a proxy. This is useful for scenarios where you need to enforce specific aliasing behavior for your forwarded service. ```bash ssh -p 2222 -R my.tunnel:80:localhost:8080 sandhole.com.br tcp-alias ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.