README
¶
point-c
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.
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.
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:
-
Install xcaddy:
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest -
Build Caddy with all modules:
xcaddy build --with github.com/point-c/caddy/module@latest -
Run Your Custom Caddy Build:
./caddy run
Quickstart
Caddy as Server Configuration
{
# (Optional) Don't bind to the host system
default_bind stub://0.0.0.0
point-c {
# WireGuard server config
wgserver <server hostname> {
ip <server address in private network>
port <server listening port>
private <server private key>
# Add peer blocks for each client
peer <client hostname> {
ip <client address in private network>
public <client public key>
shared <shared key>
}
}
}
servers :443 {
listener_wrappers {
merge {
point-c <client hostname> 443
# Add `point-c` for each client
}
}
}
}
# Rest of Caddy config
Remote Listen Configuration
Server
{
# 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 <server hostname> {
ip <server address in private network>
port <server listening port>
private <server private key>
peer <client hostname> {
ip <client address in private network>
public <client public key>
shared <shared key>
}
}
}
# Forward traffic
point-c netops {
forward sys:<client hostname> {
tcp 443:443
}
}
}
:80 {
# Run HTTP server to prevent HTTPS from being used
}
Client
{
# (Optional) Don't bind to the host system
default_bind stub://0.0.0.0
point-c {
wgclient <client hostname> {
ip <client address in private network>
endpoint <server ip/hostname>:<server port>
private <client private key>
public <server public key>
shared <shared key>
}
}
servers :443 {
listener_wrappers {
merge {
point-c <client hostname> 443
}
}
}
}
# Rest of Caddy config
Forward Non-HTTPS Traffic
Caddy As Server
{
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
{
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
{
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
{
servers <listen address> {
listener_wrappers {
merge {
# Listener definitions go here
}
}
}
}
JSON
{
"apps": {
"http": {
"servers": {
"srv0": {
"listen": [
"<listen address>"
],
"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
{
point-c {
}
point-c netops {
}
}
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
{
point-c {
system <network name> <dial ip address or hostname> <local ip address or hostname>
}
}
JSON
{
"apps": {
"point-c": {
"networks": [
{
"dial-addr": "<ip address or hostname>",
"local": "<ip address or hostname>",
"hostname": "<network name>",
"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
{
point-c {
wgclient <hostname> {
ip <address on the virtual network>
endpoint <server address>
private <client private key>
public <server public key>
shared <shared key>
}
wgserver <hostname> {
ip <address on the virtual network>
port <server listen port>
private <server private key>
peer <hostname> {
ip <address on the virtual network>
public <client public key>
shared <shared key>
}
}
}
}
JSON
{
"apps": {
"point-c": {
"networks": [
{
"endpoint": "<server address>",
"ip": "<address on the virtual network>",
"name": "<hostname>",
"preshared": "<shared key>",
"private": "<client private key>",
"public": "<server public key>",
"type": "wgclient"
},
{
"hostname": "<hostname>",
"ip": "<address on the virtual network>",
"listen-port": <server listen port>,
"peers": [
{
"hostname": "<hostname>",
"ip": "<address on the virtual network>",
"preshared": "<shared key>",
"public": "<client public key>"
}
],
"private": "<server private key>",
"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
{
servers <listen address> {
listener_wrappers {
merge {
point-c <hostname> <listen port>
}
tls # should always be last
}
}
}
JSON
{
"apps": {
"http": {
"servers": {
"srv0": {
"listen": [
"<listen address>"
],
"listener_wrappers": [
{
"listeners": [
{
"listener": "<hostname>",
"name": "server",
"port": <listen 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
{
point-c netops {
forward <src host>:<dst host> {
}
}
}
JSON
{
"apps": {
"point-c": {
"net-ops": [
{
"forwards": [],
"hosts": "<src host>:<dst host>",
"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
{
point-c netops {
forward <src host>:<dst host> {
tcp <src port>:<dst port> [buffer size in bytes]
}
}
}
JSON
{
"apps": {
"point-c": {
"net-ops": [
{
"forwards": [
{
"buf": <null | buffer size in bytes>,
"forward": "tcp",
"ports": "<src port>:<dst port>"
}
],
"hosts": "<src host>:<dst host>",
"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
{
default_bind stub://<ip address>
}
JSON
{
"apps": {
"http": {
"servers": {
"srv0": {
"listen": [
"stub://<ip address>:<port>"
]
}
}
}
}
}
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
<site block> {
route {
rand
}
}
JSON Configuration
{
"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
{
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
{
"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:
go test ./...
More tests are also available here.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package module allows importing all modules at once.
|
Package module allows importing all modules at once. |
|
forward
Package forward manages network forwarders.
|
Package forward manages network forwarders. |
|
forward-tcp
Package forward_tcp forwards TCP traffic.
|
Package forward_tcp forwards TCP traffic. |
|
listener
Package listener allows Caddy to listen on arbitrary networks.
|
Package listener allows Caddy to listen on arbitrary networks. |
|
merge-listener-wrapper
Package merge_listener_wrapper allows Caddy to listen on multiple listeners.
|
Package merge_listener_wrapper allows Caddy to listen on multiple listeners. |
|
point-c
Package point_c allows Caddy to manage networks.
|
Package point_c allows Caddy to manage networks. |
|
rand
Package rand contains a Caddy handler that allows random data to be returned.
|
Package rand contains a Caddy handler that allows random data to be returned. |
|
stub-listener
Package stub_listener is a Caddy network that prevents caddy from listening on the host.
|
Package stub_listener is a Caddy network that prevents caddy from listening on the host. |
|
sysnet
Package sysnet is a point-c network for the host network.
|
Package sysnet is a point-c network for the host network. |
|
wg
Package wg is a point-c network for a WireGuard tunnel.
|
Package wg is a point-c network for a WireGuard tunnel. |
|
pkg
|
|
|
caddyreg
Package caddyreg contains basic helpers to assist with creating Caddy modules.
|
Package caddyreg contains basic helpers to assist with creating Caddy modules. |
|
channel-listener
Package channel_listener contains a listener that is able to pass arbitrary connections through a channel.
|
Package channel_listener contains a listener that is able to pass arbitrary connections through a channel. |
|
configvalues
Package configvalues contains types to help with configuring point-c.
|
Package configvalues contains types to help with configuring point-c. |
|
lifecycler
Package lifecycler helps Caddy modules manage the life cycle of submodules.
|
Package lifecycler helps Caddy modules manage the life cycle of submodules. |
|
test-caddy
Package test_caddy provides mock types and utilities for testing caddy modules.
|
Package test_caddy provides mock types and utilities for testing caddy modules. |