point_c

package module
v0.0.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 23, 2024 License: MIT Imports: 17 Imported by: 0

README

Point-c

Overview

These plugins allow caddy to manage networks more efficiently. Networking applications can be run under this module allowing fine grained networking.

Features

  • Lifecycle Manegement: Multiple submodules can be run from this module.
  • Networking Apps: Networking applications can be created and used via this module.
  • Network Listener: Listen on custom networks.

Getting Started

Prerequisites

Ensure you have Go installed on your system.

Installation

To install the Caddy Merge Listener Wrapper, you will need to build a custom Caddy binary that includes this module. This can be achieved using the xcaddy utility:

  1. Install xcaddy:

    go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

  2. Build Caddy with the Merge Listener Wrapper:

    xcaddy build --with github.com/point-c/caddy

  3. Run Your Custom Caddy Build:

    ./caddy run
Configuration
JSON Configuration

Edit your Caddy JSON configuration to include the Merge Listener Wrapper. Here's a snippet to get you started:

{
    // Other Caddy configurations...
    "apps": {
        "http": {
            "servers": {
                "example": {
                    "listener_wrappers": [
                        {
                            "wrapper": "multi",
                            "listeners": [
                            	{
                            		"listener": "<listener>",
                            		...
                            	},
                            	...
                            ]
                        }
                    ],
                    // Other server configurations...
                }
            }
        }
    }
}
Caddyfile Configuration

In your Caddyfile, you can use the Merge Listener Wrapper as follows:

{
   # Global config section
    point-c {
        <submodule name> <submodule options...>
    }
    netop {
        <submodule name> <submodule options...>
    }
}

Documentation

Index

Constants

View Source 
const (
	CaddyfilePointCName = "point-c"
)
View Source 
const NetworkStubName = "stub:"

NetworkStubName is the matcher for the network protocol. The ':' suffix is required.

Variables

This section is empty.

Functions

func CaddyListen added in v0.0.14 

func CaddyListen[T any](ctx context.Context, addr net.Addr) (v T, err error)

func DialRemoteLoop added in v0.0.3 

func DialRemoteLoop(n Net, dstPort uint16, pairs <-chan *ConnPair, dialed chan<- *ConnPair)

DialRemoteLoop is responsible for dialing the receiver.

func ListenLoop added in v0.0.3 

func ListenLoop(ln net.Listener, conns chan<- net.Conn)

ListenLoop accepts connections and sends them to the next operation.

func PrepareConnPairLoop added in v0.0.3 

func PrepareConnPairLoop(ctx context.Context, logger *slog.Logger, conns <-chan net.Conn, pairs chan<- *ConnPair)

PrepareConnPairLoop initializes the forwarding session.

func StartCopyLoop added in v0.0.3 

func StartCopyLoop(pairs <-chan *ConnPair, copyFn func(done func(), logger *slog.Logger, dst io.Writer, src io.Reader))

StartCopyLoop manages starting the copy for both TCP stream directions.

func StubListener added in v0.0.3 

func StubListener(_ context.Context, _, addr string, _ net.ListenConfig) (any, error)

StubListener creates a stub network listener. This listener does not accept actual network connections but instead blocks on Accept calls until Close is called. It can be used as a base listener when only tunnel listeners are required.

func TcpCopy added in v0.0.3 

func TcpCopy(done func(), logger *slog.Logger, dst io.Writer, src io.Reader, buf []byte)

TcpCopy is the low level function that does the actual copying of TCP traffic. It only copies the stream in one direction e.g. src->dst or dst->src.

Types

type BufSize added in v0.0.14 

type BufSize = configvalues.CaddyTextUnmarshaler[uint16, configvalues.ValueUnsigned[uint16], *configvalues.ValueUnsigned[uint16]]

type ConnPair added in v0.0.3 

type ConnPair struct {
	Ctx    context.Context
	Cancel context.CancelFunc
	Remote net.Conn
	Tunnel net.Conn
	Logger *slog.Logger
}

ConnPair helps manage the state of a forwarding session.

func (*ConnPair) DialTunnel added in v0.0.3 

func (cp *ConnPair) DialTunnel(n Net, dstPort uint16) bool

DialTunnel does the actual remote dialing.

type Dialer 

type Dialer interface {
	// Dial dials a remote address with the TCP protocol.
	Dial(context.Context, *net.TCPAddr) (net.Conn, error)
	// DialPacket dials a remote address with the UDP protocol.
	DialPacket(*net.UDPAddr) (net.PacketConn, error)
}

type Forward added in v0.0.3 

type Forward struct {
	ForwardsRaw []json.RawMessage         `json:"forwards,omitempty" caddy:"namespace=point-c.op.forward inline_key=forward"`
	Hosts       configvalues.HostnamePair `json:"hosts"`
	// contains filtered or unexported fields
}

Forward manages forwarders for internet traffic.

func (*Forward) CaddyModule added in v0.0.3 

func (f *Forward) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (*Forward) Cleanup added in v0.0.3 

func (f *Forward) Cleanup() error

Cleanup implements caddy.CleanerUpper.

func (*Forward) Provision added in v0.0.3 

func (f *Forward) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*Forward) Start added in v0.0.3 

func (f *Forward) Start(lookup NetLookup) error

Start implements NetOp.

func (*Forward) UnmarshalCaddyfile added in v0.0.3 

func (f *Forward) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile unmarshals the caddyfile. ``` 

point-c netops {
    forward <src network name>:<dst network name> {
		    <submodule name> <submodule config>
    }
}

```

type ForwardNetworks added in v0.0.14 

type ForwardNetworks struct{ Src, Dst Net }

ForwardNetworks contains the networks that have their traffic forwarded.

type ForwardProto added in v0.0.3 

type ForwardProto = lifecycler.LifeCyclable[*ForwardNetworks]

ForwardProto is implemented by modules in the "point-c.op.forward" namespace.

type ForwardTCP added in v0.0.3 

type ForwardTCP struct {
	Ports   configvalues.PortPair `json:"ports"`
	BufSize BufSize               `json:"buf"`
	// contains filtered or unexported fields
}

ForwardTCP is able to forward TCP traffic through networks.

func (*ForwardTCP) CaddyModule added in v0.0.3 

func (f *ForwardTCP) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (*ForwardTCP) Cleanup added in v0.0.3 

func (f *ForwardTCP) Cleanup() error

Cleanup implements caddy.CleanerUpper.

func (*ForwardTCP) Provision added in v0.0.3 

func (f *ForwardTCP) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*ForwardTCP) Start added in v0.0.3 

func (f *ForwardTCP) Start(n *ForwardNetworks) error

Start implements ForwardProto. It is responsible for starting the forwarding of network traffic.

func (*ForwardTCP) UnmarshalCaddyfile added in v0.0.3 

func (f *ForwardTCP) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile unmarshals the caddyfile. Buffer size is the size of the buffer to use per stream direction. Buffer size will be double the specified amount per connection. ``` 

point-c netops {
    forward <src network name>:<dst network name> {
		    tcp <src port>:<dst port> [buffer size]
    }
}

```

type Listener 

type Listener struct {
	Name configvalues.Hostname `json:"name"`
	Port configvalues.Port     `json:"port"`
	// contains filtered or unexported fields
}

Listener allows a caddy server to listen on a point-c network.

func (*Listener) Accept 

func (p *Listener) Accept() (net.Conn, error)

Accept implements net.Listener.

func (*Listener) Addr 

func (p *Listener) Addr() net.Addr

Addr implements net.Listener.

func (*Listener) CaddyModule 

func (*Listener) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (*Listener) Close 

func (p *Listener) Close() error

Close implements net.Listener.

func (*Listener) Provision 

func (p *Listener) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*Listener) Start added in v0.0.13 

func (p *Listener) Start(fn func(net.Listener)) error

Start implement ListenerProvider.

func (*Listener) UnmarshalCaddyfile 

func (p *Listener) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile unmarshals the caddyfile. ``` 

	{
	  servers :443 {
	    listener_wrappers {
	      merge {
            # this is the actual listener definition
	        point-c <network name> <port to expose>
	      }
          # make sure tls goes after otherwise encryption will be dropped
	      tls
	    }
	  }
	}

```

type ListenerProvider added in v0.0.13 

type ListenerProvider lifecycler.LifeCyclable[func(net.Listener)]

ListenerProvider is implemented by modules in the "caddy.listeners.merge" namespace.

type MergeWrapper added in v0.0.3 

type MergeWrapper struct {
	// ListenerRaw is a slice of JSON-encoded data representing listener configurations.
	// These configurations are used to create the actual net.Listener instances.
	// Listeners should implement [net.Listener] and be in the 'caddy.listeners.merge.listeners' namespace.
	ListenerRaw []json.RawMessage `json:"listeners" caddy:"namespace=caddy.listeners.merge inline_key=listener"`
	// contains filtered or unexported fields
}

MergeWrapper loads multiple [net.Listener]s and aggregates their [net.Conn]s into a single net.Listener. It allows caddy to accept connections from multiple sources.

func (*MergeWrapper) CaddyModule added in v0.0.3 

func (p *MergeWrapper) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (*MergeWrapper) Cleanup added in v0.0.3 

func (p *MergeWrapper) Cleanup() (err error)

Cleanup implements caddy.CleanerUpper. All wrapped listeners are closed and the struct is cleared.

func (*MergeWrapper) Provision added in v0.0.3 

func (p *MergeWrapper) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner. It loads the listeners from their configs and asserts them to net.Listener. Any failed assertions will cause a panic.

func (*MergeWrapper) UnmarshalCaddyfile added in v0.0.3 

func (p *MergeWrapper) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler. Must have at least one listener to aggregate with the wrapped listener. `tls` should come specifically after any `merge` directives.

``` 

 http caddyfile:
	{
	  servers :443 {
	    listener_wrappers {
	      merge {
	        <submodule name> <submodule config>
	      }
	      tls
	    }
	  }
	}

```

func (*MergeWrapper) WrapListener added in v0.0.3 

func (p *MergeWrapper) WrapListener(ls net.Listener) net.Listener

WrapListener implements caddy.ListenerWrapper. The listener passed in is closed by MergeWrapper during cleanup.

type Net 

type Net interface {
	// Listen listens on the given address with the TCP protocol.
	Listen(addr *net.TCPAddr) (net.Listener, error)
	// ListenPacket listens on the given address with the UDP protocol.
	ListenPacket(addr *net.UDPAddr) (net.PacketConn, error)
	// Dialer returns a [Dialer] with a given local address. If the network does not support arbitrary remote addresses this value can be ignored.
	Dialer(laddr net.IP, port uint16) Dialer
	// LocalAddr is the local address of the net interface. If it does not have one, return nil.
	LocalAddr() net.IP
}

Net is a peer in the networking stack. If it has a local address [Net.LocalAddress] should return a non-nil value.

type NetLookup 

type NetLookup interface {
	Lookup(string) (Net, bool)
}

NetLookup is implemented by Pointc.

type NetOp 

type NetOp = lifecycler.LifeCyclable[NetLookup]

NetOp is implemented by modules in the "point-c.op" namespace.

type Network 

type Network = lifecycler.LifeCyclable[RegisterFunc]

Network is implemented by modules in the "point-c.net" namespace.

type Pointc 

type Pointc struct {
	NetworksRaw []json.RawMessage `json:"networks,omitempty" caddy:"namespace=point-c.net inline_key=type"`
	NetOps      []json.RawMessage `json:"net-ops,omitempty" caddy:"namespace=point-c.op inline_key=op"`
	// contains filtered or unexported fields
}

Pointc allows usage of networks through a net-ish interface.

func (*Pointc) CaddyModule 

func (*Pointc) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (*Pointc) Cleanup 

func (pc *Pointc) Cleanup() error

Cleanup implements caddy.CleanerUpper.

func (*Pointc) Lookup 

func (pc *Pointc) Lookup(name string) (Net, bool)

Lookup gets a Net by its declared name.

func (*Pointc) Provision 

func (pc *Pointc) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*Pointc) Register added in v0.0.7 

func (pc *Pointc) Register(key string, n Net) error

Register adds a new network to the Pointc instance. The 'key' parameter is a unique identifier for the network. On success, the network is registered with the Pointc instance.

func (*Pointc) Start 

func (pc *Pointc) Start() error

Start implements caddy.App.

func (*Pointc) Stop 

func (pc *Pointc) Stop() error

Stop implements caddy.App.

func (*Pointc) UnmarshalCaddyfile 

func (pc *Pointc) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile unmarshals a submodules from a caddyfile. The `netops` modifier causes the modules to be loaded as netops. 

 ```
	{
	  point-c [netops] {
	    <submodule name> <submodule config>
	  }
	}
 ```

type RegisterFunc 

type RegisterFunc func(string, Net) error

RegisterFunc registers a unique name to a Net tunnel. Since ip addresses may be arbitrary depending on what the application is doing in the tunnel, names are used as lookup. This also helps with configuration, so that users don't need to remember ip addresses.

type SysDialer added in v0.0.14 

type SysDialer struct {
	// contains filtered or unexported fields
}

func (*SysDialer) Dial added in v0.0.14 

func (s *SysDialer) Dial(ctx context.Context, addr *net.TCPAddr) (net.Conn, error)

func (*SysDialer) DialPacket added in v0.0.14 

func (s *SysDialer) DialPacket(addr *net.UDPAddr) (net.PacketConn, error)

type Sysnet added in v0.0.14 

type Sysnet struct {
	Hostname configvalues.Hostname `json:"hostname"`
	Addr     configvalues.IP       `json:"addr"`
	// contains filtered or unexported fields
}

func (*Sysnet) CaddyModule added in v0.0.14 

func (s *Sysnet) CaddyModule() caddy.ModuleInfo

func (*Sysnet) Cleanup added in v0.0.14 

func (s *Sysnet) Cleanup() error

func (*Sysnet) Dialer added in v0.0.14 

func (s *Sysnet) Dialer(ip net.IP, port uint16) Dialer

func (*Sysnet) Listen added in v0.0.14 

func (s *Sysnet) Listen(addr *net.TCPAddr) (net.Listener, error)

func (*Sysnet) ListenPacket added in v0.0.14 

func (s *Sysnet) ListenPacket(addr *net.UDPAddr) (net.PacketConn, error)

func (*Sysnet) LocalAddr added in v0.0.14 

func (s *Sysnet) LocalAddr() net.IP

func (*Sysnet) Provision added in v0.0.14 

func (s *Sysnet) Provision(c caddy.Context) error

func (*Sysnet) Start added in v0.0.14 

func (s *Sysnet) Start(fn RegisterFunc) error

func (*Sysnet) UnmarshalCaddyfile added in v0.0.14 

func (s *Sysnet) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (*Sysnet) Validate added in v0.0.14 

func (s *Sysnet) Validate() error

Source Files

View all Source files

Directories

Path Synopsis
pkg
caddyreg
configvalues
lifecycler
test-caddy

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.