Implementing https forward proxy with caddy v2

Using Caddy v2 with the forwardproxy plugin is a quick way to set up an HTTPS forward proxy, especially since Caddy automatically requests SSL certificates, saving a lot of unnecessary hassle.

Step 1: Add DNS Records for Your Domain

If you don’t have an IPv6 address, you can simply add an A record with an IPv4 address for your domain, as shown below:

Name (prefix)	Type	TTL	Target
A	3600		(Enter your VPS’s IPv4 address)
AAAA	3600		(Enter your VPS’s IPv6 address, optional)

Once the DNS records are added, we can move on to the server configuration.

Step 2: Compile Caddy2 with the Forwardproxy Plugin

You need to compile Caddy2 to include the non-standard forwardproxy plugin for HTTPS forward proxy support. First, configure the Go environment.

2.1 Configure Go

Download and extract Go to the /usr/local directory:

1	wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz -O - \| tar -xz -C /usr/local/

Then, set the Go environment variables. You can add them to your ~/.profile file:

1	vi ~/.profile

Add the following content:

export PATH=$PATH:/usr/local/go/bin
export GOROOT=/usr/local/go
export GOBIN=$GOROOT/bin
export PATH=$PATH:$GOBIN

Save the file, then apply the changes with:

1	source ~/.profile

2.2 Download Xcaddy

Xcaddy is a tool for building Caddy with custom plugins. Download it with the following command:

1	wget https://github.com/caddyserver/xcaddy/releases/download/v0.4.4/xcaddy_0.4.4_linux_amd64.tar.gz -O - \| tar -xz -C /usr/bin/

2.3 Build Caddy with the Forwardproxy Plugin

You can now build Caddy with the forwardproxy plugin by running:

1	xcaddy build master --with github.com/caddyserver/forwardproxy

After compilation, the caddy binary file will be located in the root directory. Move it to /usr/bin/:

1	mv caddy /usr/bin

To check if the forwardproxy plugin was successfully added, run:

1	caddy list-modules

Step 3: Configure the Caddyfile

Now that Caddy2 is installed, it’s time to configure the Caddyfile. Caddy v2 uses a more complex JSON configuration, but you can still use Caddy v1’s style for simplicity.

Create a new directory for the Caddyfile:
1
mkdir -p /etc/caddy
Create and edit the https.caddyfile:
1
vi /etc/caddy/https.caddyfile

Add the following content to the https.caddyfile:

:443, proxy.xxxx.com
route {
    forward_proxy {
        basic_auth user1 0NtCL2JPJBgddPMmlPcJ  # Username and password
        hide_ip  # Hide client IP
        hide_via
    }
    file_server
}

You need to replace proxy.xxxx.com with your domain and set a username and password for authentication. Be sure to remove the comments.

To generate a Caddy v2 standard JSON configuration from the above Caddyfile, run:

1	caddy adapt --config /etc/caddy/https.caddyfile

3.1 Check Port Usage

Before starting Caddy, make sure no other services are using ports 80 or 443, as Caddy needs these ports to request SSL certificates. You can check port usage with:

1	netstat -lntp

3.2 Start Caddy

Once the configuration is ready and ports are checked, you can start Caddy using the following command:

1	caddy run -c /etc/caddy/https.caddyfile

If certificate requests fail, it may be because the domain has already requested a certificate. It’s recommended to create a subdomain in your DNS settings and reconfigure and restart the certificate request.

Caddy will run in the foreground by default, which is inconvenient. To run it as a service, you need to register a systemd service.

Step 4: Register a Systemd Service for Caddy

Create the caddy.service file:
1
vi /etc/systemd/system/caddy.service

Add the following content:

[Unit]
Description=Caddy
Documentation=https://caddyserver.com/docs/
After=network.target network-online.target
Requires=network-online.target

[Service]
User=root
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/https.caddyfile
ExecReload=/usr/bin/caddy reload --config /etc/caddy/https.caddyfile --force
TimeoutStopSec=5s
LimitNOFILE=1048576
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

Reload the systemd service:
1
systemctl daemon-reload

Now you can start, restart, stop, or enable Caddy to run on startup:

Start Caddy: systemctl start caddy
Restart Caddy: systemctl restart caddy
Check Caddy status: systemctl status caddy
Stop Caddy: systemctl stop caddy
Enable Caddy on startup: systemctl enable caddy

Step 5: Client-side Configuration

With the server-side configuration complete, we can move on to the client-side. HTTPS forward proxy is fast and secure, and many mobile apps and computers support HTTP/HTTPS proxies. There’s no need to install additional client software for most devices.

Feb 22, 2025