Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fuomag9/caddy-proxy-manager/llms.txt

Use this file to discover all available pages before exploring further.

L4 proxy hosts configure Caddy’s layer-4 stream proxying for TCP and UDP traffic. The API provides full CRUD operations for creating and managing these stream proxy entries programmatically.

​
Endpoints

MethodPathDescription
GET/api/v1/l4-proxy-hostsList all L4 proxy hosts
POST/api/v1/l4-proxy-hostsCreate an L4 proxy host
GET/api/v1/l4-proxy-hosts/{id}Get an L4 proxy host by ID
PUT/api/v1/l4-proxy-hosts/{id}Update an L4 proxy host
DELETE/api/v1/l4-proxy-hosts/{id}Delete an L4 proxy host

​
Create an L4 proxy host

POST /api/v1/l4-proxy-hosts 
curl -X POST https://your-instance:3000/api/v1/l4-proxy-hosts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Proxy",
    "protocol": "tcp",
    "listenAddress": ":5432",
    "upstreams": ["db.internal:5432"],
    "matcherType": "none",
    "enabled": true
  }'

​
Request fields

​
name
string
required
Display name for the L4 proxy host.
​
protocol
"tcp" | "udp"
required
The transport protocol to proxy.
​
listenAddress
string
required
The address and port to listen on, e.g. :5432 or 0.0.0.0:2222.
​
upstreams
string[]
required
One or more upstream addresses to forward traffic to, e.g. ["db.internal:5432"].
​
matcherType
"none" | "tls_sni" | "http_host" | "proxy_protocol"
How to match incoming connections. Use tls_sni to route based on TLS Server Name Indication. Defaults to none.
​
matcherValue
string[]
Values for the matcher (e.g. hostnames for tls_sni or http_host).
​
tlsTermination
boolean
Whether to terminate TLS at Caddy rather than passing it through to the upstream.
​
proxyProtocolVersion
"v1" | "v2" | null
Send proxy protocol header to the upstream to pass the real client IP. Set to v1 or v2 to enable.
​
proxyProtocolReceive
boolean
Accept proxy protocol headers from upstream clients (for chained proxies).
​
enabled
boolean
Whether Caddy should listen on this port. Defaults to true.

​
Response object

{
  "id": 1,
  "name": "Database Proxy",
  "protocol": "tcp",
  "listenAddress": ":5432",
  "upstreams": ["db.internal:5432"],
  "matcherType": "none",
  "matcherValue": [],
  "tlsTermination": false,
  "proxyProtocolVersion": null,
  "proxyProtocolReceive": false,
  "enabled": true,
  "loadBalancer": null,
  "geoblock": null,
  "geoblockMode": "merge",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
Port changes trigger a Caddy container restart via the l4-port-manager sidecar. Brief downtime (a few seconds) is expected when adding or removing L4 hosts.

Build docs developers (and LLMs) love

Get started for freeTalk to us