dumbproxy

You can install dumbproxy using several methods depending on your environment:

From Source

Run the following command within the source directory:

go install .

Using Snap

sudo snap install dumbproxy

Using Docker

You can run dumbproxy as a background service using the official Docker image. Example for a proxy with static authentication:

docker run -d \
    --security-opt no-new-privileges \
    -p 8080:8080 \
    --restart unless-stopped \
    --name dumbproxy \
    ghcr.io/senseunit/dumbproxy -auth 'static://?username=admin&password=123456'

Binary Downloads

Pre-built binaries are available on the GitHub releases page.

go install .
# OR
sudo snap install dumbproxy
# OR
docker run -d --security-opt no-new-privileges -p 8080:8080 --restart unless-stopped --name dumbproxy ghcr.io/senseunit/dumbproxy -auth 'static://?username=admin&password=123456'

Using an HTTPS proxy (HTTP-over-TLS) in browsers requires specific configuration because standard proxy settings often only support plaintext HTTP.

Windows (System-wide)

1. Open system network proxy settings.
2. Enable the setup script option.
3. Use a PAC (Proxy Auto-Config) script format: data:,function FindProxyForURL(u, h){return "HTTPS example.com:8080";}

Firefox

• Option 1 (PAC): In proxy settings, select "Automatic proxy configuration URL" and provide the same data:,function... string used for Windows.
• Option 2 (Extension): Use a browser extension like Proxy SwitchyOmega that explicitly supports HTTPS proxies.

Chrome

• Option 1 (CLI): Launch via command line: chromium-browser --proxy-server='https://example.com:8080'
• Option 2 (Extension): Use Proxy SwitchyOmega.

dumbproxy can serve traffic over TLS using pre-issued certificates or by automatically issuing them via ACME (Let's Encrypt/etc.).

Using Pre-issued Certificates

Use -cert and -key to provide your certificate and private key. You can also use -cafile to authenticate clients with certificates (sets ClientAuth to VerifyClientCertIfGiven).

Using Autocert (Automatic TLS)

Enable automatic certificate management with the -autocert flag.

Key Autocert Options:

• -autocert-email: Email for ACME registration.
• -autocert-acme: Custom ACME endpoint (defaults to Let's Encrypt).
• -autocert-http: Listen address for the HTTP-01 challenge handler.
• -autocert-whitelist: A comma-separated list of domains allowed to use autocert.
• -autocert-dir: Path to a directory for the autocert cache.
• -autocert-cache-redis: A Redis URL for the autocert cache.
• -autocert-cache-redis-cluster: A Redis Cluster URL for the autocert cache.
• -autocert-local-cache-ttl: Enables in-memory caching for certificates with a specified TTL.

Note on Encryption: If using a remote cache (Redis), you can encrypt cache entries using -autocert-cache-enc-key (hex-encoded) or the DUMBPROXY_CACHE_ENC_KEY environment variable.

# Example: Using pre-issued certificates
dumbproxy -cert /path/to/cert.pem -key /path/to/key.pem

# Example: Enabling autocert with a specific email and Redis cache
dumbproxy -autocert -autocert-email user@example.com -autocert-cache-redis redis://localhost:6379

When running dumbproxy behind a reverse proxy like Nginx that performs SNI routing, you should enable the -proxyproto flag so dumbproxy can receive the original client connection information. You must also provide the certificate and key files manually using -cert and -key.

dumbproxy \
	-bind-address 127.0.0.1:10443 \
	-proxyproto \
	-auth basicfile://?path=/etc/dumbproxy.htpasswd \
	-cert=/etc/letsencrypt/live/proxy.example.com/fullchain.pem \
	-key=/etc/letsencrypt/live/proxy.example.com/privkey.pem

Nginx Configuration Requirement: Your Nginx stream block must have proxy_protocol on; enabled in the server context to communicate with dumbproxy.

stream {
	ssl_preread on;

	map $ssl_preread_server_name $backend {
		proxy.example.com dumbproxy;
		...
	}

	upstream dumbproxy {
		server 127.0.0.1:10443;
	}

	server {
		listen 443;
		listen [::]:443;
		proxy_protocol on;
		proxy_pass $backend;
	}
}