• Stars
    star
    963
  • Rank 47,492 (Top 1.0 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 4 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Layer 4 (TCP/UDP) app for Caddy

Project Conncept: a TCP/UDP app for Caddy

Project Conncept is an experimental layer 4 app for Caddy. It facilitates composable handling of raw TCP/UDP connections based on properties of the connection or the beginning of the stream.

With it, you can listen on sockets/ports and express logic such as:

  • "Echo all input back to the client."
  • "Proxy all the raw bytes to 10.0.3.14:1592."
  • "If connection is TLS, terminate TLS then proxy all bytes to :5000."
  • "Terminate TLS; then if it is HTTP, proxy to localhost:80; otherwise echo."
  • "If connection is TLS, proxy to :443 without terminating; if HTTP, proxy to :80; if SSH, proxy to :22."
  • "If the HTTP Host is example.com or the TLS ServerName is example.com, then proxy to 192.168.0.4."
  • "Block connections from these IP ranges: ..."
  • "Throttle data flow to simulate slow connections."
  • And much more!

⚠️ This app is very capable and flexible, but is still in development. Please expect breaking changes.

Because this is a caddy app, it can be used alongside other Caddy apps such as the HTTP server or TLS certificate manager.

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.

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.

Current matchers:

  • layer4.matchers.http - matches connections that start with HTTP requests. In addition, any http.matchers modules can be used for matching on HTTP-specific properties of requests, such as header or path. Note that only the first request of each connection can be used for matching.
  • layer4.matchers.tls - matches connections that start with TLS handshakes. In addition, any tls.handshake_match modules can be used for matching on TLS-specific properties of the ClientHello, such as ServerName (SNI).
  • layer4.matchers.ssh - matches connections that look like SSH connections.
  • layer4.matchers.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.proxy_protocol - matches connections that start with HAPROXY proxy protocol.
  • layer4.matchers.socks4 - matches connections that look like SOCKSv4.
  • layer4.matchers.socks5 - matches connections that look like SOCKSv5.

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.
  • 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.
  • layer4.handlers.proxy_protocol - Accepts the HAPROXY proxy protocol on the receiving side.
  • layer4.handlers.socks5 - Handles SOCKSv5 proxy protocol connections.

Like the http app, some handlers are "terminal" meaning that they don't call the next handler in the chain. For example: echo and proxy are terminal handlers because they consume the client's input.

Compiling

The recommended way is to use xcaddy:

$ xcaddy build --with github.com/mholt/caddy-l4

Alternatively, to hack on the plugin code, you can clone it down, then build and run like so:

  1. Download or clone this repo: git clone https://github.com/mholt/caddy-l4.git
  2. In the project folder, run xcaddy just like you would run caddy. For example: xcaddy list-modules --versions (you should see the layer4 modules).

Writing config

Since this app does not support Caddyfile (yet?), you will have to use Caddy's native JSON format to configure it. I highly recommend this caddy-json-schema plugin by @abiosoft which can give you auto-complete and documentation right in your editor as you write your config!

See below for some examples to help you get started.

Config examples

A simple echo server:

{
	"apps": {
		"layer4": {
			"servers": {
				"example": {
					"listen": ["127.0.0.1:5000"],
					"routes": [
						{
							"handle": [
								{"handler": "echo"}
							]
						}
					]
				}
			}
		}
	}
}

A simple echo server with TLS termination that uses a self-signed cert for localhost:

{
	"apps": {
		"layer4": {
			"servers": {
				"example": {
					"listen": ["127.0.0.1:5000"],
					"routes": [
						{
							"handle": [
								{"handler": "tls"},
								{"handler": "echo"}
							]
						}
					]
				}
			}
		},
		"tls": {
			"certificates": {
				"automate": ["localhost"]
			},
			"automation": {
				"policies": [
					{
						"issuers": [{"module": "internal"}]
					}
				]
			}
		}
	}
}

A simple TCP reverse proxy that terminates TLS on 993, and sends the PROXY protocol header to 1143 through 143:

{
	"apps": {
		"layer4": {
			"servers": {
				"secure-imap": {
					"listen": ["0.0.0.0:993"],
					"routes": [
						{
							"handle": [
								{
									"handler": "tls"
								},
								{
									"handler": "proxy",
									"proxy_protocol": "v1",
									"upstreams": [
										{"dial": ["localhost:143"]}
									]
								}
							]
						}
					]
				},
				"normal-imap": {
					"listen": ["0.0.0.0:143"],
					"routes": [
						{
							"handle": [
								{
									"handler": "proxy_protocol"
								},
								{
									"handler": "proxy",
									"proxy_protocol": "v2",
									"upstreams": [
										{"dial": ["localhost:1143"]}
									]
								}
							]
						}
					]
				}
			}
		}
	}
}

A multiplexer that proxies HTTP to one backend, and TLS to another (without terminating TLS):

{
	"apps": {
		"layer4": {
			"servers": {
				"example": {
					"listen": ["127.0.0.1:5000"],
					"routes": [
						{
							"match": [
								{
									"http": []
								}
							],
							"handle": [
								{
									"handler": "proxy",
									"upstreams": [
										{"dial": ["localhost:80"]}
									]
								}
							]
						},
						{
							"match": [
								{
									"tls": {}
								}
							],
							"handle": [
								{
									"handler": "proxy",
									"upstreams": [
										{"dial": ["localhost:443"]}
									]
								}
							]
						}
					]
				}
			}
		}
	}
}

Same as previous, but only applies to HTTP requests with specific hosts:

{
	"apps": {
		"layer4": {
			"servers": {
				"example": {
					"listen": ["127.0.0.1:5000"],
					"routes": [
						{
							"match": [
								{
									"http": [
										{"host": ["example.com"]}
									]
								}
							],
							"handle": [
								{
									"handler": "subroute",
									"routes": [
										{
											"match": [
												{
													"http": []
												}
											],
											"handle": [
												{
													"handler": "proxy",
													"upstreams": [
														{"dial": ["localhost:80"]}
													]
												}
											]
										},
										{
											"match": [
												{
													"tls": {}
												}
											],
											"handle": [
												{
													"handler": "proxy",
													"upstreams": [
														{"dial": ["localhost:443"]}
													]
												}
											]
										}
									]
								}
							]
						}
					]
				}
			}
		}
	}
}

Same as previous, but filter by HTTP Host header and/or TLS ClientHello ServerName:

{
	"apps": {
		"layer4": {
			"servers": {
				"example": {
					"listen": ["127.0.0.1:5000"],
					"routes": [
						{
							"match": [
								{
									"http": [
										{"host": ["example.com"]}
									]
								}
							],
							"handle": [
								{
									"handler": "proxy",
									"upstreams": [
										{"dial": ["localhost:80"]}
									]
								}
							]
						},
						{
							"match": [
								{
									"tls": {
										"sni": ["example.net"]
									}
								}
							],
							"handle": [
								{
									"handler": "proxy",
									"upstreams": [
										{"dial": ["localhost:443"]}
									]
								}
							]
						}
					]
				}
			}
		}
	}
}

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.

{
	"apps": {
		"layer4": {
			"servers": {
				"socks": {
					"listen": ["0.0.0.0:1080"],
					"routes": [
						{
							"match": [
								{
									"socks5": {},
									"ip": {"ranges": ["10.0.0.0/24"]}
								}
							],
							"handle": [
								{
									"handler": "socks5",
									"credentials": {
										"bob": "qHoEtVpGRM"
									}
								}
							]
						},
						{
							"match": [
								{
									"socks4": {}
								}
							],
							"handle": [
								{
									"handler": "proxy",
									"upstreams": [
										{"dial": ["10.64.0.1:1080"]}
									]
								}
							]
						}
					]
				}
			}
		}
	}
}

More Repositories

1

PapaParse

Fast and powerful CSV (delimited text) parser that gracefully handles large files and malformed input
JavaScript
12,285
star
2

json-to-go

Translates JSON into a Go type in your browser instantly (original)
JavaScript
4,408
star
3

archiver

Easily create & extract archives, and compress & decompress files of various formats
Go
4,055
star
4

timeliner

All your digital life on a single timeline, stored locally
Go
3,436
star
5

curl-to-go

Convert curl commands to Go code in your browser
JavaScript
1,773
star
6

binding

Reflectionless data binding for Go's net/http (not actively maintained)
Go
795
star
7

photobak

Back up your content from Google Photos - DEPRECATED: use Timeliner
Go
307
star
8

caddy-dynamicdns

Caddy app that keeps your DNS records (A/AAAA) pointed at itself.
Go
231
star
9

acmez

Premier ACME client library for Go
Go
216
star
10

caddy-webdav

WebDAV handler module for Caddy
Go
207
star
11

golang-graphics

Community-contributed Go graphics files
138
star
12

caddy-ratelimit

HTTP rate limiting module for Caddy 2
Go
131
star
13

conncept

Project Conncept: A layer 4 app for Caddy that multiplexes raw TCP/UDP streams
58
star
14

caddy-embed

Caddy plugin for embedding static files directly into the server binary
Go
38
star
15

meetupchat

Simple chat using TCP, as a quick workshop for beginner (Go) programmers
Go
20
star
16

caddy-events-exec

Run commands on Caddy events
Go
19
star
17

vidagent

Easily filter your video files for content (requires ffmpeg)
Go
15
star
18

caddy-grpc-web

Caddy module to Convert gRPC-Web requests to normal gRPC for servers
Go
14
star
19

diskspace

A little Go package for measuring disk space/usage
Go
13
star
20

phpile

A file-system-based trie data structure that's persistent, portable, and super-fast. Experimental. Not for production use.
PHP
12
star
21

chessml

PGN file parser and Chess engine for machine learning, CS 478 group project
Go
6
star
22

dhall-adapter

Configure Caddy with Dhall
Go
4
star
23

caddy-psl

A public suffix list module for Caddy
Go
3
star
24

mholt.github.io

3
star
25

ysaward

An entire website for managing high-turnover YSA wards, with multi-stake support
PHP
1
star
26

lzip-go

An unmaintained copy of sorairolake/lzip-go before it disappeared (v0.3.5)
Go
1
star
27

blogtest

Testing testing 123
Shell
1
star
28

caddy-sqlite-fs

Go
1
star
29

caddy-hitcounter

Add a classic retro hit counter to your modern Caddy site
Go
1
star