### Install dumbproxy from source

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Install dumbproxy by running 'go install .' within the source directory. Ensure Go is installed and configured.

```bash
go install .
```

--------------------------------

### Install dumbproxy on Server

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-deployment-with-mutual-TLS-authentication-using-self‐signed-certificates

Download and install the dumbproxy binary on the server. Ensure the architecture matches your system (amd64 in this example).

```bash
curl -Lo /usr/local/bin/dumbproxy \
	'https://github.com/SenseUnit/dumbproxy/releases/download/v1.28.0/dumbproxy.linux-amd64' \
	&& chmod +x /usr/local/bin/dumbproxy
```

--------------------------------

### Configuration File Example

Source: https://context7.com/senseunit/dumbproxy/llms.txt

An example configuration file demonstrating various settings for dumbproxy, including network, TLS, DNS, and access control.

```bash
# /etc/dumbproxy.cfg - Example configuration file
# Comments start with #

# Listen address and authentication
bind-address :443
auth basicfile://?path=/etc/dumbproxy.htpasswd

# TLS configuration with automatic certificates
autocert
autocert-email admin@example.com
autocert-whitelist proxy.example.com,proxy2.example.com

# Or use pre-issued certificates
# cert /etc/ssl/proxy.crt
# key /etc/ssl/proxy.key

# DNS configuration
dns-server https://1.1.1.1/dns-query
dns-server https://8.8.8.8/dns-query
dns-cache-ttl 5m

# Bandwidth limiting (100KB/s per user)
bw-limit 102400
bw-limit-burst 512000

# Access control
deny-dst-addr 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

# Upstream proxy chaining
proxy socks5h://127.0.0.1:9050

# Logging verbosity (10=debug, 20=info, 30=warning, 40=error)
verbosity 20
```

--------------------------------

### Enable and Start dumbproxy Service

Source: https://github.com/senseunit/dumbproxy/wiki/Quick-deployment

Enable the dumbproxy service to start automatically on boot and then start the service immediately.

```bash
systemctl enable dumbproxy
systemctl start dumbproxy
```

--------------------------------

### Install dumbproxy Binary

Source: https://github.com/senseunit/dumbproxy/wiki/Quick-deployment

Download and install the dumbproxy binary for amd64 architecture. Ensure the binary is executable after installation.

```bash
curl -Lo /usr/local/bin/dumbproxy \
	'https://github.com/SenseUnit/dumbproxy/releases/latest/download/dumbproxy.linux-amd64' \
	&& chmod +x /usr/local/bin/dumbproxy
```

--------------------------------

### Start dumbproxy server

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-deployment-with-mutual-TLS-authentication-using-self‐signed-certificates

Execute the proxy server using a specified configuration file.

```bash
dumbproxy -config dp.cfg
```

--------------------------------

### Install PPP Package

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-PPP‐over‐HTTP2

Installs the 'ppp' package, which provides the pppd daemon necessary for establishing PPP connections.

```bash
apt install ppp
```

--------------------------------

### Install dumbproxy via Snap Store

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Install dumbproxy using the Snap Store. This is a convenient method for Linux systems.

```bash
sudo snap install dumbproxy
```

--------------------------------

### Service Management Commands

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Commands to install, start, and monitor the dumbproxy service.

```bash
# Install and enable service
sudo systemctl daemon-reload
sudo systemctl enable dumbproxy
sudo systemctl start dumbproxy
sudo systemctl status dumbproxy

# View logs
sudo journalctl -u dumbproxy -f
```

--------------------------------

### Run Proxy Using Configuration File

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Starts the dumbproxy server using settings defined in a specified configuration file.

```bash
dumbproxy -config /etc/dumbproxy.cfg
```

--------------------------------

### Show Version

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Displays the installed version of the dumbproxy application.

```bash
dumbproxy -version
```

--------------------------------

### Run plain dumbproxy with Basic authentication

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Start a dumbproxy instance on port 1234 with Basic authentication enabled. Requires a username and password.

```sh
dumbproxy -bind-address :1234 -auth 'static://?username=admin&password=123456'
```

--------------------------------

### Configure dumbproxy

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-deployment-with-mutual-TLS-authentication-using-self‐signed-certificates

Example configuration file defining the bind address and proxy target.

```text
bind-address 127.0.0.1:8080
proxy h2://203.0.113.99?cafile=rootCA.pem&cert=client1-client.pem&key=client1-client-key.pem
```

--------------------------------

### Chain Pseudo-Proxy Example

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Illustrates the 'chain' pseudo-proxy for assembling a proxy chain. The 'next' parameter specifies subsequent proxies and can be repeated.

```shell
chain://?next=http%3A%2F%2F127.0.0.1%3A57800&next=force-resolve%3A%2F%2F
```

--------------------------------

### Client Proxy Integration

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Examples for connecting to the proxy using curl, environment variables, and SSH.

```bash
# Test proxy with curl (HTTP proxy)
curl -x http://user:pass@proxy.example.com:8080 https://api.ipify.org

# Test HTTPS proxy (HTTP-over-TLS)
curl -x https://user:pass@proxy.example.com:443 https://api.ipify.org

# Test SOCKS5 proxy
curl -x socks5h://user:pass@proxy.example.com:1080 https://api.ipify.org

# Environment variables for system-wide proxy
export http_proxy="http://user:pass@proxy.example.com:8080"
export https_proxy="http://user:pass@proxy.example.com:8080"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"

# SSH ProxyCommand using dumbproxy stdio mode
ssh -o ProxyCommand="dumbproxy -config proxy.cfg -mode stdio %h %p" user@remote-server

# SSH config for permanent ProxyCommand
# ~/.ssh/config
# Host remote-server
#     ProxyCommand dumbproxy -proxy 'https://user:pass@proxy.example.com' -mode stdio %h %p
```

--------------------------------

### Enable and Start Dumbproxy Service

Source: https://github.com/senseunit/dumbproxy/wiki/Secure-systemd-deployment

Commands to reload the daemon and activate the socket-based service.

```bash
systemctl daemon-reload
systemctl enable dumbproxy.socket
systemctl start dumbproxy.socket
```

--------------------------------

### Cloud-Init Configuration for Dumbproxy

Source: https://github.com/senseunit/dumbproxy/wiki/Cloud‐init-configuration

This cloud-init script installs dumbproxy, configures its authentication and binding, and sets up a systemd service. Replace USERNAME and PASSWORD with your actual credentials. Ensure the correct binary is downloaded based on the machine architecture.

```yaml
## template: jinja
#cloud-config
write_files:
- source:
{% if v1.machine == 'aarch64' %}
    uri: https://github.com/SenseUnit/dumbproxy/releases/latest/download/dumbproxy.linux-arm64
{% else %}
    uri: https://github.com/SenseUnit/dumbproxy/releases/latest/download/dumbproxy.linux-amd64
{% endif %}
  path: /usr/local/bin/dumbproxy
  permissions: '0755'
- content: |
    auth basicfile://?path=/etc/dumbproxy.htpasswd
    autocert
    bind-address :443
  path: /etc/dumbproxy.cfg
- content: |
    [Unit]
    Description=Dumb Proxy
    Documentation=https://github.com/SenseUnit/dumbproxy/
    After=network.target network-online.target
    Requires=network-online.target
    
    [Service]
    User=root
    Group=root
    ExecStart=/usr/local/bin/dumbproxy -config /etc/dumbproxy.cfg
    TimeoutStopSec=5s
    PrivateTmp=true
    ProtectSystem=full
    LimitNOFILE=20000
    
    [Install]
    WantedBy=default.target
  path: /etc/systemd/system/dumbproxy.service

runcmd:
- [dumbproxy, -passwd, /etc/dumbproxy.htpasswd, USERNAME, PASSWORD]
- [systemctl, daemon-reload]
- [systemctl, enable, --now, --no-block, dumbproxy.service]
```

--------------------------------

### Dumbproxy Command Line Configuration

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Example of configuring dumbproxy using command-line arguments, including bind address, proxy protocol, authentication, certificate, and key.

```bash
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
```

--------------------------------

### Run Basic HTTP Proxy

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Starts a basic HTTP proxy on the default port 8080 without any authentication.

```bash
dumbproxy
```

--------------------------------

### Run dumbproxy locally

Source: https://github.com/senseunit/dumbproxy/wiki/Redirecting-clients-on-local-network-into-a-proxy

Starts the dumbproxy service on a local port to bridge traffic to a remote TLS-enabled proxy.

```bash
dumbproxy -bind-address 127.0.0.1:3128 -proxy https://login:password@example.org
```

--------------------------------

### Command Wrapper Example

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

The 'cmd' wrapper redirects connections to the stdin/stdout of an external program. Environment variables DUMBPROXY_DST_ADDR and DUMBPROXY_DST_NET pass connection details.

```shell
cmd://?cmd=openssl&arg=s_client&arg=-connect&arg=google.com%3A443
```

--------------------------------

### Custom Source IP Hints

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Provide hints for source IP addresses to influence multi-interface routing. This can be useful in complex network setups.

```bash
dumbproxy -ip-hints '10.0.0.1,192.168.1.1,$lAddr,0.0.0.0,::'
```

--------------------------------

### Basicfile Authentication Example

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Authenticates using a file containing username and bcrypt-hashed password pairs. The 'path' parameter specifies the location of this file. Supports conditional reloading of the password file.

```bash
basicfile://?path=/etc/dumbproxy.htpasswd
```

--------------------------------

### Run dumbproxy Docker container

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Run dumbproxy as a background service using Docker. This example configures basic authentication with a static username and password.

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

--------------------------------

### Example of Cached Dialer URL

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Demonstrates the usage of the 'cached' pseudo-dialer with a URL and time-to-live parameter. The URL must be URL-encoded.

```shell
cached://?url=https%3A%2F%2Fexample.org%3Fcert%3Dcert.pem%26key%3Dkey.pem&ttl=5m
```

--------------------------------

### HMAC Authentication Setup

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Configures HMAC authentication using a secret key. The secret can be provided via the 'secret' parameter or the DUMBPROXY_HMAC_SECRET environment variable. A secret key can be generated using 'openssl rand -hex 32' or 'dumbproxy -hmac-genkey'.

```bash
hmac://?secret=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```

--------------------------------

### Configure VPN Routing

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-PPP‐over‐HTTP2

Installs direct routes to upstream proxy hosts and default routes to manage traffic flow and ensure persistence after session termination.

```bash
#	mount --bind --onlyonce "$resolvconf" /etc/resolv.conf
#fi
```

--------------------------------

### Static Authentication Example

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Use for basic authentication with a single username and password pair. The 'hidden_domain' parameter can be used to restrict when the proxy sends a '407 Proxy Authentication Required' response.

```bash
static://?username=admin&password=123456
```

--------------------------------

### Nginx stream configuration for dumbproxy

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Example Nginx stream configuration to route traffic to a dumbproxy instance using SNI routing and Proxy protocol.

```nginx
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;
	}

}
```

--------------------------------

### Dumbproxy Kubernetes Ingress Definition

Source: https://github.com/senseunit/dumbproxy/wiki/k8s-deployment

Configure an Ingress resource to expose dumbproxy externally. This example uses `nginx` as the ingress controller and `cert-manager` for TLS certificates. Remember to replace `<your-namespace>` and `<your-domain>`.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: dumbproxy
  namespace: <your-namespace>
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-production # use cert-manager
spec:
  ingressClassName: nginx # use ingress-nginx
  rules:
  - host: <your-domain>
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: dumbproxy
            port:
              number: 8080
  tls:
  - hosts:
    - <your-domain>
    secretName: <your-domain>-cert

```

--------------------------------

### Wireguard Connection Scripts with VRF Setup

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-redirecting-dumbproxy-into-a-tunnel-or-other-network-interface

These scripts are part of the wireguard configuration to create, activate, and manage a VRF interface. They enslave the wireguard interface to the VRF and re-route the default traffic through it.

```ini
[Interface]
PrivateKey = xxxxxxxxxxxxxxx
Address = 10.2.0.2/32
DNS = 1.1.1.1
Table = proton
PreUp = ip link add dev %i-vrf type vrf table proton
PreUp = ip link set dev %i-vrf up
PostUp =  ip link set dev %i master %i-vrf
PostUp = ip -4 route add default dev proton vrf %i-vrf
PostDown = ip link del dev %i-vrf

[Peer]
# NL-FREE#381133
PublicKey = xxxxxxxxxx
AllowedIPs = 0.0.0.0/0
Endpoint = xxx.xxx.xxx.xx:xxxxx
```

--------------------------------

### Configure dumbproxy Service

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-deployment-with-mutual-TLS-authentication-using-self‐signed-certificates

Set up the dumbproxy service by defining its options in `/etc/default/dumbproxy` and creating a systemd service file.

```bash
OPTIONS=-auth cert:// \
	-cafile /etc/dumbproxy-ca.pem \
	-cert /etc/dumbproxy.pem \
	-key /etc/dumbproxy-key.pem \
	-bind-address :443
```

```systemd
[Unit]
Description=Dumb Proxy
Documentation=https://github.com/SenseUnit/dumbproxy/
After=network.target network-online.target
Requires=network-online.target

[Service]
EnvironmentFile=/etc/default/dumbproxy
User=root
Group=root
ExecStart=/usr/local/bin/dumbproxy $OPTIONS
TimeoutStopSec=5s
PrivateTmp=true
ProtectSystem=full
LimitNOFILE=20000

[Install]
WantedBy=default.target
```

--------------------------------

### Save iptables Rules

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-PPP‐over‐HTTP2

Saves the current iptables rules to make them persistent across reboots, assuming the 'netfilter-persistent' package is installed.

```bash
/etc/init.d/netfilter-persistent save
```

--------------------------------

### Execute VPN Connection

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-PPP‐over‐HTTP2

Initiates the VPN connection using pppd and displays the resulting connection logs.

```bash
user@ws:~> sudo pppd call vpn
Using interface ppp0
Connect: ppp0 <--> /dev/pts/4
MAIN    : 2025/11/18 03:54:20 main.go:656: INFO     Starting proxy server...
MAIN    : 2025/11/18 03:54:20 main.go:812: INFO     Proxy server started.
local  LL address fe80::b940:dde6:f755:0427
remote LL address fe80::e5da:861e:b382:4e83
Script /etc/ppp/ipv6-up finished (pid 47510), status = 0x0
Script /etc/ppp/ip-pre-up finished (pid 47515), status = 0x0
local  IP address 172.22.255.2
remote IP address 172.22.255.1
primary   DNS address 1.1.1.1
secondary DNS address 8.8.8.8
Script /etc/ppp/ip-up finished (pid 47520), status = 0x0
```

--------------------------------

### Run SOCKS5 Proxy with Authentication

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Launches a SOCKS5 proxy on port 1080 with static username and password authentication.

```bash
dumbproxy -mode socks5 -bind-address :1080 -auth 'static://?username=user&password=pass'
```

--------------------------------

### Create dumbproxy Password File

Source: https://github.com/senseunit/dumbproxy/wiki/Quick-deployment

Generate a password file for basic authentication. Replace USERNAME and PASSWORD with your desired credentials.

```bash
dumbproxy -passwd /etc/dumbproxy.htpasswd USERNAME PASSWORD
```

--------------------------------

### Static Authentication with Chaining

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Demonstrates chaining to another authentication provider if static authentication fails. Ensure URLs are properly URL-encoded.

```bash
static://?username=root&password=mycoolpass&else=static%3A%2F%2F%3Fusername%3Dadmin%26password%3D123456
```

--------------------------------

### Proxy Protocol Configuration

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Enabling PROXY protocol support for load balancer deployments.

```bash
# Enable proxy protocol listener
dumbproxy \
    -bind-address 127.0.0.1:8080 \
    -proxyproto \
    -auth 'basicfile://?path=/etc/dumbproxy.htpasswd' \
    -cert /etc/ssl/server.crt \
    -key /etc/ssl/server.key
```

```nginx
# Nginx stream configuration for SNI routing with proxy protocol
stream {
    ssl_preread on;

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

    upstream dumbproxy {
        server 127.0.0.1:8080;
    }

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

--------------------------------

### Deploy with Docker

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Use Docker Compose or standard run commands to deploy Dumbproxy with persistent volumes and security constraints.

```yaml
# docker-compose.yml
version: '3'

services:
  dumbproxy:
    container_name: dumbproxy
    image: ghcr.io/senseunit/dumbproxy:latest-alpine
    ports:
      - "443:443"
      - "80:80"  # For ACME HTTP-01 challenges
    command:
      - "-bind-address=:443"
      - "-auth=basicfile://?path=/etc/dumbproxy.htpasswd"
      - "-autocert"
      - "-autocert-http=:80"
      - "-autocert-whitelist=proxy.example.com"
    volumes:
      - ./dumbproxy.htpasswd:/etc/dumbproxy.htpasswd:ro
      - ./autocert-cache:/.dumbproxy/autocert:rw
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
```

```bash
# Simple Docker run command
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'

# Add user to htpasswd file inside container
docker exec dumbproxy dumbproxy -passwd /etc/dumbproxy.htpasswd newuser newpassword
```

--------------------------------

### Configure Chrome proxy via CLI

Source: https://github.com/senseunit/dumbproxy/wiki/Setup-HTTPS-proxy-clients

Launch Chrome with the --proxy-server flag to route traffic through an HTTPS proxy.

```bash
chromium-browser --proxy-server='https://example.com:8080'
```

--------------------------------

### Configure dumbproxy Service

Source: https://github.com/senseunit/dumbproxy/wiki/Quick-deployment

Set up the dumbproxy configuration file with basic authentication and automatic certificate generation. The proxy will bind to port 443.

```ini
auth basicfile://?path=/etc/dumbproxy.htpasswd
autocert
bind-address :443
```

--------------------------------

### Dumbproxy Configuration File

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Shows how to simplify dumbproxy configuration using a configuration file (dp.cfg). The format is RFC 4180 CSV with space as separator and '#' for comments.

```ini
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
```

--------------------------------

### Run Dumbproxy with a custom router

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-routing-certain-domains-through-a-proxy

Execute the proxy utility specifying the JavaScript routing file.

```bash
dumbproxy -js-proxy-router routeDomains.js
```

--------------------------------

### Configure redsocks

Source: https://github.com/senseunit/dumbproxy/wiki/Redirecting-clients-on-local-network-into-a-proxy

Configuration file for redsocks to handle transparent TCP redirection to the local dumbproxy instance.

```text
base {
	// debug: connection progress & client list on SIGUSR1
	log_debug = off;

	// info: start and end of client session
	log_info = on;

	/* possible `log' values are:
	 *   stderr
	 *   "file:/path/to/file"
	 *   syslog:FACILITY  facility is any of "daemon", "local0"..."local7"
	 */
	log = "syslog:daemon";

	// detach from console
	daemon = on;

	/* Change uid, gid and root directory, these options require root
	 * privilegies on startup.
	 * Note, your chroot may requre /etc/localtime if you write log to syslog.
	 * Log is opened before chroot & uid changing.
	 */
	user = redsocks;
	group = redsocks;
	// chroot = "/var/chroot";

	/* possible `redirector' values are:
	 *   iptables   - for Linux
	 *   ipf        - for FreeBSD
	 *   pf         - for OpenBSD
	 *   generic    - some generic redirector that MAY work
	 */
	redirector = iptables;
}

redsocks {
	/* `local_ip' defaults to 127.0.0.1 for security reasons,
	 * use 0.0.0.0 if you want to listen on every interface.
	 * `local_*' are used as port to redirect to.
	 */
	local_ip = 0.0.0.0;
	local_port = 12345;

	// `ip' and `port' are IP and tcp-port of proxy-server
	// You can also use hostname instead of IP, only one (random)
	// address of multihomed host will be used.
	ip = 127.0.0.1;
	port = 3128;


	// known types: socks4, socks5, http-connect, http-relay
	type = http-connect;

	// login = "foobar";
	// password = "baz";
}
```

--------------------------------

### Configure Static User Authentication

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Sets up static authentication with a single username and password.

```bash
dumbproxy -auth 'static://?username=admin&password=secretpass'
```

--------------------------------

### Generate Client Certificate for Browser (PKCS12)

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-deployment-with-mutual-TLS-authentication-using-self‐signed-certificates

Generate a client certificate in PKCS12 format for easier import into browsers. The password will be 'changeit'.

```bash
mkcert -client -pkcs12 my-chrome-browser
```

--------------------------------

### Configure PAC file for HTTPS proxy

Source: https://github.com/senseunit/dumbproxy/wiki/Setup-HTTPS-proxy-clients

Use this data URI as a proxy configuration script in system or browser settings. Replace example.com:8080 with your actual proxy address.

```text
data:,function FindProxyForURL(u, h){return "HTTPS example.com:8080";}
```

--------------------------------

### Define Dumbproxy Environment Variables

Source: https://github.com/senseunit/dumbproxy/wiki/Secure-systemd-deployment

Specifies command-line options for the dumbproxy service, including authentication and certificate settings.

```text
OPTIONS=-auth basicfile://?path=/var/lib/dumbproxy/dumbproxy.htpasswd \
	-autocert
```

--------------------------------

### Run HTTPS Proxy with Pre-issued Certificate and htpasswd

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Configures an HTTPS proxy using a pre-issued certificate and key, with authentication handled by an htpasswd file.

```bash
dumbproxy \
    -bind-address :443 \
    -auth 'basicfile://?path=/etc/dumbproxy.htpasswd' \
    -cert /etc/ssl/proxy.crt \
    -key /etc/ssl/proxy.key
```

--------------------------------

### Dumbproxy with Systemd Socket Activation and Custom VRF

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-redirecting-dumbproxy-into-a-tunnel-or-other-network-interface

This command demonstrates running dumbproxy with systemd socket activation and specifying a custom VRF ('proton-vrf') directly from the command line.

```bash
sudo systemd-socket-activate -E HOME=/var/lib/dumbproxy -l 0.0.0.0:443 \
    ip vrf exec proton-vrf \
    setpriv --reuid dumbproxy --regid dumbproxy --clear-groups \
    /usr/local/bin/dumbproxy --bind-address=''
```

--------------------------------

### Chained Authentication Methods

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Configure sequential authentication methods, falling back to the next if the previous fails. Use 'reject-static' for a custom rejection response.

```bash
dumbproxy -auth 'static://?username=admin&password=adminpass&else=basicfile%3A%2F%2F%3Fpath%3D%2Fetc%2Fdumbproxy.htpasswd'
```

```bash
dumbproxy -auth 'basicfile://?path=/etc/dumbproxy.htpasswd&else=reject-static%3A%2F%2F%3Fcode%3D403'
```

--------------------------------

### Dumbproxy Command-Line Options

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

This section lists and describes the available command-line flags for configuring the dumbproxy application.

```APIDOC
## Dumbproxy Command-Line Options

This document outlines the various command-line flags available for configuring the `dumbproxy` application.

### General Options

- **-h**
  - Usage: `$ ~/go/bin/dumbproxy -h`
  - Description: Displays the help message and exits.

### Network and Binding

- **-bind-address** (value)
  - Default: `:8080`
  - Description: HTTP proxy listen address. An empty value uses systemd socket activation.
- **-bind-pprof** (value)
  - Description: Enables pprof debug endpoints.
- **-bind-pprof-unix-socket** (value)
  - Description: Enables pprof debug endpoints listening on a Unix domain socket.
- **-bind-reuseport**
  - Description: Allows multiple server instances on the same port.
- **-bind-unix-socket** (value)
  - Description: Unix domain socket to listen to, overrides `bind-address` if set.
- **-proxyproto**
  - Description: Listen for proxy protocol.

### TLS and Security

- **-auth** (string)
  - Default: `none://`
  - Description: Authentication parameters.
- **-autocert**
  - Description: Issue TLS certificates automatically.
- **-autocert-acme** (string)
  - Default: `https://acme-v02.api.letsencrypt.org/directory`
  - Description: Custom ACME endpoint.
- **-autocert-cache-enc-key** (value)
  - Description: Hex-encoded encryption key for cert cache entries. Can also be set with `DUMBPROXY_CACHE_ENC_KEY` environment variable.
- **-autocert-cache-redis** (value)
  - Description: Use Redis URL for autocert cache.
- **-autocert-cache-redis-cluster** (value)
  - Description: Use Redis Cluster URL for autocert cache.
- **-autocert-cache-redis-prefix** (string)
  - Description: Prefix to use for keys in Redis or Redis Cluster cache.
- **-autocert-dir** (value)
  - Description: Use directory path for autocert cache.
- **-autocert-email** (string)
  - Description: Email used for ACME registration.
- **-autocert-http** (string)
  - Description: Listen address for HTTP-01 challenges handler of ACME.
- **-autocert-local-cache-ttl** (duration)
  - Description: Enables in-memory cache for certificates.
- **-autocert-whitelist** (value)
  - Description: Restrict autocert domains to this comma-separated list.
- **-cafile** (string)
  - Description: CA file to authenticate clients with certificates.
- **-cert** (string)
  - Description: Enable TLS and use certificate.
- **-ciphers** (string)
  - Description: Colon-separated list of enabled ciphers.
- **-curves** (string)
  - Description: Colon-separated list of enabled key exchange curves.
- **-deny-dst-addr** (value)
  - Default: `127.0.0.0/8, 0.0.0.0/32, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1/128, ::/128, fe80::/10`
  - Description: Comma-separated list of CIDR prefixes of forbidden IP addresses.
- **-disable-http2**
  - Description: Disable HTTP2.
- **-hmac-genkey**
  - Description: Generate hex-encoded HMAC signing key of optimal length.
- **-hmac-sign**
  - Description: Sign username with specified key for given validity period. Positional arguments are: hex-encoded HMAC key, username, validity duration.
- **-ip-hints** (string)
  - Description: A comma-separated list of source addresses to use on dial attempts. `$lAddr` gets expanded to the local address of the connection. Example: `10.0.0.1,fe80::2,$lAddr,0.0.0.0,::`
- **-key** (string)
  - Description: Key for TLS certificate.
- **-list-ciphers**
  - Description: List ciphersuites.
- **-list-curves**
  - Description: List key exchange curves.
- **-max-tls-version** (value)
  - Default: `TLS13`
  - Description: Maximum TLS version accepted by the server.
- **-min-tls-version** (value)
  - Default: `TLS12`
  - Description: Minimum TLS version accepted by the server.
- **-passwd** (string)
  - Description: Update the given htpasswd file and add/set the password for a username. Username and password can be passed as positional arguments or requested interactively.
- **-passwd-cost** (int)
  - Default: `4`
  - Description: bcrypt password cost for the `-passwd` mode.

### Bandwidth Limiting

- **-bw-limit** (value)
  - Description: Per-user bandwidth limit in bytes per second.
- **-bw-limit-burst** (int)
  - Description: Allowed burst size for bandwidth limit, how many "tokens" can fit into the leaky bucket.
- **-bw-limit-separate**
  - Description: Separate upload and download bandwidth limits.
- **-js-bw-limit** (value)
  - Description: Path to JS script with `bwLimit` function. Overrides every other BW limit option.
- **-js-bw-limit-instances** (int)
  - Default: `4`
  - Description: Number of JS VM instances to handle requests for BW limit parameters.

### DNS Configuration

- **-dns-cache-neg-ttl** (duration)
  - Default: `1s`
  - Description: TTL for negative responses of DNS cache.
- **-dns-cache-timeout** (duration)
  - Default: `5s`
  - Description: Timeout for shared resolves of DNS cache.
- **-dns-cache-ttl** (duration)
  - Description: Enable DNS cache with the specified fixed TTL.
- **-dns-prefer-address** (value)
  - Default: `ipv4`
  - Description: Address resolution preference (none/ipv4/ipv6).
- **-dns-server** (value)
  - Description: Nameserver specification (udp://..., tcp://..., https://..., tls://..., doh://..., dot://..., default://). This option can be used multiple times for parallel use of multiple nameservers. An empty string resets the list.

### JavaScript Integration

- **-js-access-filter** (string)
  - Description: Path to JS script file with the `access` filter function.
- **-js-access-filter-instances** (int)
  - Default: `4`
  - Description: Number of JS VM instances to handle access filter requests.
- **-js-proxy-router** (value)
  - Description: Path to JS script file with the `getProxy` function.
- **-js-proxy-router-instances** (int)
  - Default: `4`
  - Description: Number of JS VM instances to handle proxy router requests.

### Proxy Configuration

- **-mode** (value)
  - Default: `http`
  - Description: Proxy operation mode (http/socks5/stdio/port-forward).
- **-proxy** (value)
  - Description: Upstream proxy URL. Can be repeated multiple times to chain proxies. Examples: `socks5h://127.0.0.1:9050`; `https://user:password@example.com:443`.

### Timeouts

- **-req-header-timeout** (duration)
  - Default: `30s`
  - Description: Amount of time allowed to read request headers.
- **-shutdown-timeout** (duration)
  - Description: Timeout for shutdown.
```

--------------------------------

### Configure HMAC Token Authentication

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Sets up HMAC token authentication. The secret key can be provided via an environment variable or directly in the command.

```bash
export DUMBPROXY_HMAC_SECRET="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
dumbproxy -auth 'hmac://'
# Or inline: -auth 'hmac://?secret=0123456789abcdef...'
```

--------------------------------

### Basicfile Authentication with Chaining

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Chains to another authentication provider if basicfile authentication fails. The 'else' parameter takes a URL-encoded string of the next authentication provider.

```bash
basicfile://?path=/etc/dumbproxy.htpasswd&else=static%3A%2F%2F%3Fusername%3Dadmin%26password%3D123456
```

--------------------------------

### Define Bandwidth Limits with JavaScript

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Implement the bwLimit function to return an object specifying upload and download rate limits and burst values.

```js
function bwLimit(req, dst, username) {
    return {
        uploadBPS: 100000,
        uploadBurst: 1000000,
        downloadBPS: 100000,
        downloadBurst: 1000000,
    };
}
```

--------------------------------

### Docker Compose configuration for dumbproxy and Traefik

Source: https://github.com/senseunit/dumbproxy/wiki/Docker-Compose-Deployment-behind-Traefik-Reverse-Proxy

Full deployment configuration for running dumbproxy and Traefik together in Docker.

```yaml
networks:
  traefik:

services:
  dumbproxy:
    image: ghcr.io/senseunit/dumbproxy:1.27.0
    command:
      - -bind-address=:8080
      - -proxyproto
    deploy:
      labels:
        traefik.enable: "true"
        traefik.tcp.routers.dumbproxy.service: dumbproxy
        traefik.tcp.routers.dumbproxy.rule: HostSNI(`<your-domain>`)
        traefik.tcp.routers.dumbproxy.tls: "true"
        traefik.tcp.routers.dumbproxy.tls.passthrough: "false"
        traefik.tcp.routers.dumbproxy.tls.certResolver: letsencrypt
        traefik.tcp.services.dumbproxy.loadBalancer.server.port: 8080
        traefik.tcp.services.dumbproxy.loadbalancer.proxyProtocol.version: 2
    networks:
      traefik:

  traefik:
    image: traefik:v3.5.0
    networks:
      traefik:
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./traefik.yaml:/etc/traefik/traefik.yaml
      - ./dynamic.yaml:/etc/traefik/dynamic.yaml
      - ./acme.json:/etc/traefik/acme.json
```

--------------------------------

### Run HTTPS Proxy with BuyPass Automatic Certificates

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

This command sets up an HTTPS proxy on port 443 using BuyPass for automatic certificate management. It includes basic authentication with a specified username and password, and uses port 80 for ACME challenges.

```sh
dumbproxy \
	-bind-address :443 \
	-auth 'static://?username=admin&password=123456' \
	-autocert \
	-autocert-acme 'https://api.buypass.com/acme/directory' \
	-autocert-email YOUR-EMAIL@EXAMPLE.ORG \
	-autocert-http :80
```

--------------------------------

### Deploy Dumbproxy in Kubernetes

Source: https://github.com/senseunit/dumbproxy/wiki/k8s-deployment

Use this Deployment definition to deploy the dumbproxy application in your Kubernetes cluster. Ensure you replace `<your-namespace>` with your actual namespace.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: dumbproxy
  namespace: <your-namespace>
  labels:
    app: dumbproxy
spec:
  selector:
    matchLabels:
      app: dumbproxy
  template:
    metadata:
      labels:
        app: dumbproxy
    spec:
      containers:
      - name: dumbproxy
        image: ghcr.io/senseunit/dumbproxy:1.29.0
        args:
        - -bind-address
        - :8080
        ports:
        - containerPort: 8080

```

--------------------------------

### Implement JavaScript Bandwidth Limiter

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Define per-user bandwidth tiers and return configuration objects for traffic shaping. The script must export a bwLimit function.

```javascript
// /etc/dumbproxy/bwlimit.js - Per-user bandwidth tiers

const userTiers = {
    "premium": { bps: 10485760, burst: 52428800 },  // 10MB/s, 50MB burst
    "standard": { bps: 1048576, burst: 5242880 },   // 1MB/s, 5MB burst
    "free": { bps: 102400, burst: 512000 }          // 100KB/s, 500KB burst
};

function bwLimit(req, dst, username) {
    const tier = userTiers[username] || userTiers["free"];

    return {
        uploadBPS: tier.bps,
        uploadBurst: tier.burst,
        downloadBPS: tier.bps,
        downloadBurst: tier.burst,
        groupKey: username,  // Group limits by username
        separate: true       // Separate upload/download accounting
    };
}
```

```bash
# Run with JS bandwidth limiter
dumbproxy \
    -auth 'basicfile://?path=/etc/dumbproxy.htpasswd' \
    -js-bw-limit /etc/dumbproxy/bwlimit.js \
    -js-bw-limit-instances 4
```

--------------------------------

### List Available Ciphers and Curves

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Display the list of supported TLS cipher suites or elliptic curves. Use these commands to verify compatibility or choose specific options.

```bash
dumbproxy -list-ciphers
```

```bash
dumbproxy -list-curves
```

--------------------------------

### Use System Default Resolver

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Configure Dumbproxy to use the system's default DNS resolver. This is useful when you want to rely on the OS's network configuration.

```bash
dumbproxy -dns-server 'default://'
```

--------------------------------

### JavaScript-based Dynamic Bandwidth Limiting

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Implement dynamic bandwidth limiting using a JavaScript file. This allows for complex, scriptable bandwidth control logic.

```bash
dumbproxy -js-bw-limit /etc/dumbproxy/bwlimit.js
```

--------------------------------

### Systemd Service Configuration

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Service unit file for managing dumbproxy as a background process with security hardening.

```ini
[Unit]
Description=dumbproxy - HTTP/SOCKS5 Forward Proxy
Documentation=https://github.com/SenseUnit/dumbproxy/
After=network.target network-online.target
Requires=network-online.target

[Service]
Type=simple
User=dumbproxy
Group=dumbproxy
ExecStart=/usr/local/bin/dumbproxy -config /etc/dumbproxy.cfg
Restart=on-failure
RestartSec=5s
TimeoutStopSec=5s

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/dumbproxy
LimitNOFILE=65535

# Capability for binding to privileged ports
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Deploy dumbproxy with Docker Compose

Source: https://github.com/senseunit/dumbproxy/wiki/Docker-Compose-Deployment

Defines the service configuration including port mapping, authentication settings, and volume mounts.

```yaml
version: '3'

services:
  dumbproxy:
    container_name: dumbproxy
    image: ghcr.io/senseunit/dumbproxy:latest-alpine
    ports:
      - "443:443"
    command:
      - "-bind-address=:443"
      - "-auth=basicfile://?path=/etc/dumbproxy.htpasswd"
      - "-autocert"
    volumes:
      - ./dumbproxy.htpasswd:/etc/dumbproxy.htpasswd:rw
      - ./dumbproxy:/.dumbproxy
```

--------------------------------

### No Authentication

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Disables authentication. This is the default behavior.

```bash
none://
```

--------------------------------

### Configure Redis Authentication

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Uses Redis for authentication, specifying the connection URL and an optional key prefix.

```bash
dumbproxy -auth 'redis://?url=redis://default:password@localhost:6379/0&key_prefix=proxy_auth_'
```

--------------------------------

### Test dumbproxy Operation

Source: https://github.com/senseunit/dumbproxy/wiki/Quick-deployment

Verify that the proxy is operational by making a request through it to an external service. Replace USERNAME, PASSWORD, and DOMAIN with your actual credentials and domain.

```bash
curl -x https://USERNAME:PASSWORD@DOMAIN https://api.ipify.org ; echo
```

--------------------------------

### Create systemd Service File for dumbproxy

Source: https://github.com/senseunit/dumbproxy/wiki/Quick-deployment

Define the systemd service unit for dumbproxy. This configuration specifies how the service should run, including dependencies and resource limits.

```systemd
[Unit]
Description=Dumb Proxy
Documentation=https://github.com/SenseUnit/dumbproxy/
After=network.target network-online.target
Requires=network-online.target

[Service]
User=root
Group=root
ExecStart=/usr/local/bin/dumbproxy -config /etc/dumbproxy.cfg
TimeoutStopSec=5s
PrivateTmp=true
ProtectSystem=full
LimitNOFILE=20000

[Install]
WantedBy=default.target
```

--------------------------------

### Chain Through HTTPS Proxy with Authentication

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Connect to an upstream HTTPS proxy that requires basic authentication. Provide the username and password in the URL.

```bash
dumbproxy -proxy 'https://user:password@upstream.example.com:443'
```

--------------------------------

### Create/Update htpasswd File

Source: https://github.com/senseunit/dumbproxy/blob/master/README.md

Command to create or update an htpasswd-like file for the 'basicfile' authentication provider. It takes the file path, username, and password as arguments.

```bash
dumbproxy -passwd /etc/dumbproxy.htpasswd username password
```

--------------------------------

### Generate Server and Client Certificates with mkcert

Source: https://github.com/senseunit/dumbproxy/wiki/Recipe:-deployment-with-mutual-TLS-authentication-using-self‐signed-certificates

Use mkcert to generate server and client certificates for mutual TLS authentication. Ensure the CAROOT environment variable is set to the current directory.

```bash
export CAROOT=.
mkcert 203.0.113.99 # server certificate
mkcert -client client1 # client certificate
```

--------------------------------

### Separate Upload and Download Limits

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Configure separate bandwidth limits for uploads and downloads. This provides more granular control over traffic rates.

```bash
dumbproxy \
    -bw-limit 102400 \
    -bw-limit-burst 524288 \
    -bw-limit-separate
```

--------------------------------

### Configure Client Certificate Authentication (Mutual TLS)

Source: https://context7.com/senseunit/dumbproxy/llms.txt

Enables client certificate authentication, requiring clients to present valid TLS certificates signed by the specified CA file. Server certificate and key are also provided.

```bash
dumbproxy \
    -cert /etc/ssl/server.crt \
    -key /etc/ssl/server.key \
    -cafile /etc/ssl/client-ca.crt \
    -auth 'cert://'
```

--------------------------------

### Configure SystemD Service for Dumbproxy

Source: https://github.com/senseunit/dumbproxy/wiki/Secure-systemd-deployment

Defines the service unit with system isolation settings like DynamicUser and PrivateTmp.

```ini
[Unit]
Description=Dumb Proxy
Documentation=https://github.com/SenseUnit/dumbproxy/
After=network.target network-online.target
Requires=network-online.target

[Service]
EnvironmentFile=/etc/default/dumbproxy
DynamicUser=yes
StateDirectory=dumbproxy
Environment=HOME=%S/dumbproxy
ExecStart=/usr/local/bin/dumbproxy --bind-address='' $OPTIONS
TimeoutStopSec=5s
PrivateTmp=true
ProtectSystem=full

[Install]
WantedBy=default.target
```