Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/point-c/caddy
Caddy modules for WireGuard integration and network routing.
https://github.com/point-c/caddy
caddy caddy-plugin generics golang golang-library networking vpn wireguard wireguard-go
Last synced: about 10 hours ago
JSON representation
Caddy modules for WireGuard integration and network routing.
- Host: GitHub
- URL: https://github.com/point-c/caddy
- Owner: point-c
- License: mit
- Created: 2024-01-09T03:12:15.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-08-09T01:11:13.000Z (3 months ago)
- Last Synced: 2024-08-09T04:31:43.276Z (3 months ago)
- Topics: caddy, caddy-plugin, generics, golang, golang-library, networking, vpn, wireguard, wireguard-go
- Language: Go
- Homepage: https://godocs.io/github.com/point-c/[email protected]
- Size: 521 KB
- Stars: 28
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# point-c
[](https://godocs.io/github.com/point-c/[email protected])
[](https://raw.githack.com/wiki/point-c/caddy/coverage.html)
`point-c` is a collection of Caddy modules designed to handle network traffic between host systems and WireGuard tunnels. This library is for users looking to integrate network handling into their Caddy server configurations, particularly in VPN scenarios.
- [point-c](#point-c)
- [Features](#features)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Caddy as Server Configuration](#caddy-as-server-configuration)
- [Remote Listen Configuration](#remote-listen-configuration)
- [Server](#server)
- [Client](#client)
- [Forward Non-HTTPS Traffic](#forward-non-https-traffic)
- [Caddy As Server](#caddy-as-server)
- [Server/Client Pair - Server](#serverclient-pair---server)
- [Server/Client Pair - Client](#serverclient-pair---client)
- [Modules](#modules)
- [`merge-listener-wrapper`](#merge-listener-wrapper)
- [Caddyfile](#caddyfile)
- [JSON](#json)
- [`point-c`](#point-c-1)
- [Caddyfile](#caddyfile-1)
- [JSON](#json-1)
- [`sysnet`](#sysnet)
- [Caddyfile](#caddyfile-2)
- [JSON](#json-2)
- [`wg`](#wg)
- [Caddyfile](#caddyfile-3)
- [JSON](#json-3)
- [`listener`](#listener)
- [Caddyfile](#caddyfile-4)
- [JSON](#json-4)
- [`forward`](#forward)
- [Caddyfile](#caddyfile-5)
- [JSON](#json-5)
- [`forward-tcp`](#forward-tcp)
- [Caddyfile](#caddyfile-6)
- [JSON](#json-6)
- [`stub-listener`](#stub-listener)
- [Caddyfile](#caddyfile-7)
- [JSON](#json-7)
- [`rand`](#rand)
- [Caddyfile](#caddyfile-8)
- [JSON Configuration](#json-configuration)
- [Full Configuration](#full-configuration)
- [Caddyfile](#caddyfile-9)
- [JSON Configuration](#json-configuration-1)
- [Testing](#testing)
## Features
- Easy integration with Caddy and WireGuard.
- Customizable modules for different network operations.
- Streamlined handling of TCP traffic and listener wrapping.
- [Full test of these modules using Docker.](https://github.com/point-c/integration)
## Installation
To install the modules from `point-c`, you will need to build a custom Caddy binary that includes that module. This can be achieved using the `xcaddy` utility:
1. **Install xcaddy**:
```sh
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
```
2. **Build Caddy with all modules**:
```sh
xcaddy build --with github.com/point-c/caddy/module@latest
```
3. **Run Your Custom Caddy Build**:
```sh
./caddy run
```
## Quickstart
### Caddy as Server Configuration
```Caddyfile
{
# (Optional) Don't bind to the host system
default_bind stub://0.0.0.0
point-c {
# WireGuard server config
wgserver {
ip
port
private
# Add peer blocks for each client
peer {
ip
public
shared
}
}
}
servers :443 {
listener_wrappers {
merge {
point-c 443
# Add `point-c` for each client
}
}
}
}
# Rest of Caddy config
```
### Remote Listen Configuration
#### Server
```Caddyfile
{
# Don't bind to the host system
default_bind stub://0.0.0.0
point-c {
# Default network
system sys 0.0.0.0 0.0.0.0
# WireGuard server config
wgserver {
ip
port
private
peer {
ip
public
shared
}
}
}
# Forward traffic
point-c netops {
forward sys: {
tcp 443:443
}
}
}
:80 {
# Run HTTP server to prevent HTTPS from being used
}
```
#### Client
```Caddyfile
{
# (Optional) Don't bind to the host system
default_bind stub://0.0.0.0
point-c {
wgclient {
ip
endpoint :
private
public
shared
}
}
servers :443 {
listener_wrappers {
merge {
point-c 443
}
}
}
}
# Rest of Caddy config
```
### Forward Non-HTTPS Traffic
#### Caddy As Server
```Caddyfile
{
point-c {
system ssh 0.0.0.0 ssh-host
system sys 0.0.0.0 localhost
wgserver server {
# config...
}
}
point-c netops {
forward server:sys {
tcp 80:80
}
forward server:ssh {
tcp 22:22
}
}
}
```
#### Server/Client Pair - Server
```Caddyfile
{
default_bind stub://0.0.0.0
point-c {
system sys 0.0.0.0 0.0.0.0
wgserver server {
# config...
}
}
point-c netops {
forward sys:server {
tcp 443:443
tcp 80:80
tcp 22:22
}
}
}
:80 {
}
```
#### Server/Client Pair - Client
```Caddyfile
{
point-c {
system ssh 0.0.0.0 ssh-host
system sys 0.0.0.0 localhost
wgclient client {
# config...
}
}
point-c netops {
forward client:sys {
tcp 80:80
}
forward client:ssh {
tcp 22:22
}
}
servers :443 {
listener_wrappers {
merge {
point-c client 443
}
tls
}
}
}
```
## Modules
### `merge-listener-wrapper`
The merge-listener-wrapper module acts as a wrapper for TCP listeners within the Caddy server. This module enables the bundling of multiple listeners into a single `net.Listener`. It's useful for allowing different networks to combine traffic.
#### Caddyfile
```Caddyfile
{
servers {
listener_wrappers {
merge {
# Listener definitions go here
}
}
}
}
```
#### JSON
```json
{
"apps": {
"http": {
"servers": {
"srv0": {
"listen": [
""
],
"listener_wrappers": [
{
"listeners": [],
"wrapper": "merge"
},
{
"wrapper": "tls"
}
]
}
}
}
}
}
```
### `point-c`
The centerpiece of this library, `point-c`, is designed to handle and manage registered networks and their associated operations within Caddy. This module serves as the backbone for integrating Caddy with various network setups, including both system networks and WireGuard configurations. It's essential for users looking to leverage Caddy in network-intensive applications or in scenarios requiring network control.
#### Caddyfile
```Caddyfile
{
point-c {
}
point-c netops {
}
}
```
#### JSON
```json
{
"apps": {
"point-c": {
"networks": [],
"net-ops": []
}
}
}
```
### `sysnet`
`sysnet` is a dedicated point-c network module for the host system. It provides a streamlined way to integrate the host's network settings into the point-c ecosystem. This module is for scenarios where the host system's network needs to be used in a `point-c` network operation.
The dial address is the address used as the local IP when dialing. The local address is returned by the `LocalAddr` method.
The hostname is resolved against the system to get an IP address, it is not a `point-c` network.
#### Caddyfile
```Caddyfile
{
point-c {
system
}
}
```
#### JSON
```json
{
"apps": {
"point-c": {
"networks": [
{
"dial-addr": "",
"local": "",
"hostname": "",
"type": "system"
}
]
}
}
}
```
### `wg`
The `wg` module enables registration of WireGuard tunnels, allowing integration of WireGuard-based VPN configurations with Caddy. The module is for users looking to combine WireGuard Caddy's web-serving functionality.
#### Caddyfile
```Caddyfile
{
point-c {
wgclient {
ip
endpoint
private
public
shared
}
wgserver {
ip
port
private
peer {
ip
public
shared
}
}
}
}
```
#### JSON
```json
{
"apps": {
"point-c": {
"networks": [
{
"endpoint": "",
"ip": "
",
"name": "",
"preshared": "",
"private": "",
"public": "",
"type": "wgclient"
},
{
"hostname": "",
"ip": "",
"listen-port": ,
"peers": [
{
"hostname": "",
"ip": "",
"preshared": "",
"public": ""
}
],
"private": "",
"type": "wgserver"
}
]
}
}
}
```
### `listener`
The `listener` module for `point-c` allows for the use of registered networks with the `merge-listener-wrapper`. This module allows using networks as Caddy listeners.
#### Caddyfile
```Caddyfile
{
servers {
listener_wrappers {
merge {
point-c
}
tls # should always be last
}
}
}
```
#### JSON
```json
{
"apps": {
"http": {
"servers": {
"srv0": {
"listen": [
""
],
"listener_wrappers": [
{
"listeners": [
{
"listener": "",
"name": "server",
"port":
}
],
"wrapper": "merge"
},
{
"wrapper": "tls"
}
]
}
}
}
}
}
```
### `forward`
The `forward` module specializes in directing traffic from a source to a destination. It allows multiple port forwards to be made for a `src host:dst host` pair.
#### Caddyfile
```Caddyfile
{
point-c netops {
forward : {
}
}
}
```
#### JSON
```json
{
"apps": {
"point-c": {
"net-ops": [
{
"forwards": [],
"hosts": ":",
"op": "forward"
}
]
}
}
}
```
### `forward-tcp`
As a submodule of `forward`, `forward-tcp` focuses on forwarding TCP traffic. It allows specifying a specific buffer size in bytes. The default is `4096`.
#### Caddyfile
```Caddyfile
{
point-c netops {
forward : {
tcp : [buffer size in bytes]
}
}
}
```
#### JSON
```json
{
"apps": {
"point-c": {
"net-ops": [
{
"forwards": [
{
"buf": ,
"forward": "tcp",
"ports": ":"
}
],
"hosts": ":",
"op": "forward"
}
]
}
}
}
```
### `stub-listener`
`stub-listener` allows binding to nothing, preventing Caddy from listening on the host system. This is useful for isolating Caddy from the host environment, such as when it is unable to open ports on the host system.
#### Caddyfile
```Caddyfile
{
default_bind stub://
}
```
#### JSON
```json
{
"apps": {
"http": {
"servers": {
"srv0": {
"listen": [
"stub://:"
]
}
}
}
}
}
```
### `rand`
`rand` is a `caddyhttp.MiddlewareHandler` that returns random data, useful for testing.
Accepts the following headers:
- `Rand-Seed`: The seed for the random data generator. If not specified, the current Unix microsecond timestamp is used.
- `Rand-Size`: The size of the random data in bytes. If not specified or set to a negative value, the module will stream random data indefinitely.
#### Caddyfile
```Caddyfile
{
route {
rand
}
}
```
#### JSON Configuration
```json
{
"apps": {
"http": {
"servers": {
"srv0": {
"routes": [
{
"handle": [
{
"handler": "subroute",
"routes": [{"handle": [{"handler": "rand"}]}]
}
]
}
]
}
}
}
}
}
```
## Full Configuration
For advanced users, point-c offers extended configuration options to tailor the modules to specific needs.
### Caddyfile
```Caddyfile
{
default_bind stub://0.0.0.0
point-c {
system sys 0.0.0.0 0.0.0.0
wgclient client {
ip 192.168.45.2
endpoint 127.0.0.1:51820
private UCoEdsc8Mw7ZY81jSAHOGIw23QxqxfN8SQ8YktOrw0I=
public 5GIGlLmvYnTyoQ59QIUYEo2FFUgubTibAO2qFI859hY=
shared Z9Ad3ZhTQbIUCLEKATYXS1m380vYrYFhGA75tspxsOU=
}
wgserver server {
ip 192.168.45.1
port 51820
private 2Jgm2q3tFu21cO1IMyhjENqp7t5qep0++novkdKHe0k=
peer client-1 {
ip 192.168.45.3
public Tdbxgh9AHWXodT60AiwCUPDTEITyVD+ecMhp2TDY1xw=
shared Z9Ad3ZhTQbIUCLEKATYXS1m380vYrYFhGA75tspxsOU=
}
}
}
point-c netops {
forward server:client-1 {
tcp 443:443
}
forward sys:server {
tcp 443:443 8192
}
}
servers :443 {
listener_wrappers {
merge {
point-c server 443
point-c client 443
}
tls
}
}
}
:443 {
route {
rand
}
}
```
### JSON Configuration
```json5
{
"apps": {
"http": {
"servers": {
"srv0": {
"listen": [
"stub://0.0.0.0:443"
],
"listener_wrappers": [
{
"listeners": [
{
"listener": "point-c",
"name": "server",
"port": 443
},
{
"listener": "point-c",
"name": "client",
"port": 443
}
],
"wrapper": "merge"
},
{
"wrapper": "tls"
}
],
"routes": [
{
"handle": [
{
"handler": "subroute",
"routes": [
{
"handle": [
{
"handler": "rand"
}
]
}
]
}
]
}
]
}
}
},
"point-c": {
"networks": [
{
"dial-addr": "0.0.0.0",
"local": "0.0.0.0",
"hostname": "sys",
"type": "system"
},
{
"endpoint": "127.0.0.1:51820",
"ip": "192.168.45.2",
"name": "client",
"preshared": "Z9Ad3ZhTQbIUCLEKATYXS1m380vYrYFhGA75tspxsOU=",
"private": "UCoEdsc8Mw7ZY81jSAHOGIw23QxqxfN8SQ8YktOrw0I=",
"public": "5GIGlLmvYnTyoQ59QIUYEo2FFUgubTibAO2qFI859hY=",
"type": "wgclient"
},
{
"hostname": "server",
"ip": "192.168.45.1",
"listen-port": 51820,
"peers": [
{
"hostname": "client-1",
"ip": "192.168.45.3",
"preshared": "Z9Ad3ZhTQbIUCLEKATYXS1m380vYrYFhGA75tspxsOU=",
"public": "Tdbxgh9AHWXodT60AiwCUPDTEITyVD+ecMhp2TDY1xw="
}
],
"private": "2Jgm2q3tFu21cO1IMyhjENqp7t5qep0++novkdKHe0k=",
"type": "wgserver"
}
],
"net-ops": [
{
"forwards": [
{
"buf": null,
"forward": "tcp",
"ports": "443:443"
}
],
"hosts": "server:client-1",
"op": "forward"
},
{
"forwards": [
{
"buf": 8192,
"forward": "tcp",
"ports": "443:443"
}
],
"hosts": "sys:server",
"op": "forward"
}
]
}
}
}
```
## Testing
The package includes tests that demonstrate its functionality. Use Go's testing tools to run the tests:
```bash
go test ./...
```
More tests are also available [here](https://github.com/point-c/integration).