Caddyfile support (#217) (close #16)

* Caddyfile support : add caddyfile examples to README * Caddyfile support (build fix): update go.mod and go.sum * Caddyfile support (fix 11/27): flatten health and lb options * Caddyfile support (fix 10/27): flatten tls options * Caddyfile support (fix 9/27): remove l4proxy.LoadBalancing unmarshaler * Caddyfile support (fix 8/27): remove l4proxy.HealthChecks unmarshaler * Caddyfile support (integration): perform adapt tests
mholt · Jul 23, 2024 · ec5408a · ec5408a
1 parent 1507f4e
commit ec5408a
Show file tree

Hide file tree

Showing 48 changed files with 4,380 additions and 250 deletions.
diff --git a/README.md b/README.md
@@ -19,14 +19,14 @@ With it, you can listen on sockets/ports and express logic such as:
 
 Because this is a caddy app, it can be used alongside other Caddy apps such as the [HTTP server](https://caddyserver.com/docs/modules/http) or [TLS certificate manager](https://caddyserver.com/docs/modules/tls).
 
-Note that only JSON config is available at this time. More documentation will come soon. For now, please read the code, especially type definitions and their comments. It's actually a pretty simple code base, and the JSON config isn't that bad once you get used to it! See below for tips and examples writing config.
+Note that both Caddyfile and JSON configs are available at this time. More documentation will come soon. For now, please read the code, especially type definitions and their comments. It's actually a pretty simple code base. See below for tips and examples writing config.
 
 > [!NOTE]
 > This is not an official repository of the [Caddy Web Server](https://github.com/caddyserver) organization.
 
 ## Introduction
 
-This app works similarly to the `http` app. You define servers, and each server consists of routes. A route has a set of matchers and handlers; if a connection matches, the assoicated handlers are invoked.
+This app works similarly to the `http` app. You define servers, and each server consists of routes. A route has a set of matchers and handlers; if a connection matches, the associated handlers are invoked.
 
 Current matchers:
 
@@ -36,15 +36,18 @@ Current matchers:
 - **layer4.matchers.postgres** - matches connections that look like Postgres connections.
 - **layer4.matchers.remote_ip** - matches connections based on remote IP (or CIDR range).
 - **layer4.matchers.local_ip** - matches connections based on local IP (or CIDR range).
+- **layer4.matchers.not** - matches connections that aren't matched by inner matcher sets.
 - **layer4.matchers.proxy_protocol** - matches connections that start with [HAPROXY proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).
 - **layer4.matchers.rdp** - matches connections that look like [RDP](https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/MS-RDPBCGR/%5BMS-RDPBCGR%5D.pdf).
 - **layer4.matchers.socks4** - matches connections that look like [SOCKSv4](https://www.openssh.com/txt/socks4.protocol).
 - **layer4.matchers.socks5** - matches connections that look like [SOCKSv5](https://www.rfc-editor.org/rfc/rfc1928.html).
+- **layer4.matchers.xmpp** - matches connections that look like [XMPP](https://xmpp.org/about/technology-overview/).
 
 Current handlers:
 
 - **layer4.handlers.echo** - An echo server.
 - **layer4.handlers.proxy** - Powerful layer 4 proxy, capable of multiple upstreams (with load balancing and health checks) and establishing new TLS connections to backends. Optionally supports sending the [HAProxy proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).
+- **layer4.handlers.subroute** - Implements recursion logic, i.e. allows to match and handle already matched connections.
 - **layer4.handlers.tee** - Branches the handling of a connection into a concurrent handler chain.
 - **layer4.handlers.throttle** - Throttle connections to simulate slowness and latency.
 - **layer4.handlers.tls** - TLS termination.
@@ -79,6 +82,24 @@ See below for some examples to help you get started.
 
 A simple echo server:
 
+<details>
+    <summary>Caddyfile</summary>
+
+```
+{
+    layer4 {
+        127.0.0.1:5000 {
+            route {
+                echo
+            }
+        }
+    }
+}
+```
+</details>
+<details>
+    <summary>JSON</summary>
+
 ```json
 {
 	"apps": {
@@ -99,10 +120,30 @@ A simple echo server:
 	}
 }
 ```
+</details>
 
 
 A simple echo server with TLS termination that uses a self-signed cert for `localhost`:
 
+<details>
+    <summary>Caddyfile</summary>
+
+```
+{
+    layer4 {
+        127.0.0.1:5000 {
+            route {
+                tls
+                echo
+            }
+        }
+    }
+}
+```
+</details>
+<details>
+    <summary>JSON</summary>
+
 ```json
 {
 	"apps": {
@@ -136,9 +177,41 @@ A simple echo server with TLS termination that uses a self-signed cert for `loca
 	}
 }
 ```
+</details>
 
 A simple TCP reverse proxy that terminates TLS on 993, and sends the PROXY protocol header to 1143 through 143:
 
+<details>
+    <summary>Caddyfile</summary>
+
+```
+{
+    layer4 {
+        0.0.0.0:993 {
+            route {
+                tls
+                proxy {
+                    proxy_protocol v1
+                    upstream localhost:143
+                }
+            }
+        }
+        0.0.0.0:143 {
+            route {
+                proxy_protocol
+                proxy {
+                    proxy_protocol v2
+                    upstream localhost:1143
+                }
+            }
+        }
+    }
+}
+```
+</details>
+<details>
+    <summary>JSON</summary>
+
 ```json
 {
 	"apps": {
@@ -187,9 +260,33 @@ A simple TCP reverse proxy that terminates TLS on 993, and sends the PROXY proto
 	}
 }
 ```
+</details>
 
 A multiplexer that proxies HTTP to one backend, and TLS to another (without terminating TLS):
 
+<details>
+    <summary>Caddyfile</summary>
+
+```
+{
+    layer4 {
+        127.0.0.1:5000 {
+            @insecure http
+            route @insecure {
+                proxy localhost:80
+            }
+            @secure tls
+            route @secure {
+                proxy localhost:443
+            }
+        }
+    }
+}
+```
+</details>
+<details>
+    <summary>JSON</summary>
+
 ```json
 {
 	"apps": {
@@ -235,9 +332,38 @@ A multiplexer that proxies HTTP to one backend, and TLS to another (without term
 	}
 }
 ```
+</details>
 
 Same as previous, but only applies to HTTP requests with specific hosts:
 
+<details>
+    <summary>Caddyfile</summary>
+
+```
+{
+    layer4 {
+        127.0.0.1:5000 {
+            @example http host example.com
+            route @example {
+                subroute {
+                    @insecure http
+                    route @insecure {
+                        proxy localhost:80
+                    }
+                    @secure tls
+                    route @secure {
+                        proxy localhost:443
+                    }
+                }
+            }
+        }
+    }
+}
+```
+</details>
+<details>
+    <summary>JSON</summary>
+
 ```json
 {
 	"apps": {
@@ -299,9 +425,33 @@ Same as previous, but only applies to HTTP requests with specific hosts:
 	}
 }
 ```
+</details>
 
 Same as previous, but filter by HTTP Host header and/or TLS ClientHello ServerName:
 
+<details>
+    <summary>Caddyfile</summary>
+
+```
+{
+    layer4 {
+        127.0.0.1:5000 {
+            @insecure http host example.com
+            route @insecure {
+                proxy localhost:80
+            }
+            @secure tls sni example.net
+            route @secure {
+                proxy localhost:443
+            }
+        }
+    }
+}
+```
+</details>
+<details>
+    <summary>JSON</summary>
+
 ```json
 {
 	"apps": {
@@ -351,11 +501,39 @@ Same as previous, but filter by HTTP Host header and/or TLS ClientHello ServerNa
 	}
 }
 ```
-
+</details>
 
 Forwarding SOCKSv4 to a remote server and handling SOCKSv5 directly in caddy.  
 While only allowing connections from a specific network and requiring a username and password for SOCKSv5.
 
+<details>
+    <summary>Caddyfile</summary>
+
+```
+{
+    layer4 {
+        0.0.0.0:1080 {
+            @s5 {
+                socks5
+                ip 10.0.0.0/24
+            }
+            route @s5 {
+                socks5 {
+                    credentials bob qHoEtVpGRM
+                }
+            }
+            @s4 socks4
+            route @s4 {
+                proxy 10.64.0.1:1080
+            }
+        }
+    }
+}
+```
+</details>
+<details>
+    <summary>JSON</summary>
+
 ```json
 {
 	"apps": {
@@ -402,3 +580,4 @@ While only allowing connections from a specific network and requiring a username
 	}
 }
 ```
+</details>