gonat

README

gonat   

This library only works on Linux.

Dependencies are managed using Go modules. If using a version of Go prior to 1.13, use the environment variable GO111MODULE=on to enable use of modules.

In order to work, this library needs to be able to open raw sockets and update the conntrack table via netlink. You can give the binary the correct capabilities with:

sudo setcap CAP_NET_RAW,CAP_NET_ADMIN+ep <name_of_binary>

This library requires the nf_conntrack module to be installed at runtime.

modprobe nf_conntrack
modprobe nf_conntrack_ipv4

iptables needs to be configured to drop the outbound RST packets that the kernel would usually create in response to SYN/ACK packets responding to our raw TCP connections. We do this only for tcp connections that are already in ESTABLISHED in conntrack. The library manually adds these to conntrack since we're using raw sockets.

sudo iptables -I OUTPUT -p tcp -m conntrack --ctstate ESTABLISHED --ctdir ORIGINAL --tcp-flags RST RST -j DROP

To undo this, run the same command, but replace the -I flag with the -D flag.

To run the unit tests, you need to have root permissions. It's also useful to enable tracing while running the tests.

GO111MODULE=on go test -c && TRACE=true sudo -E ./gonat.test

Documentation

Index

• Constants
• func RunTest(t *testing.T, tunDeviceName, tunAddr, tunGW, tunMask string, mtu int, ...)
• func TUNDevice(name, addr, netmask string, mtu int) (io.ReadWriteCloser, error)
• type Addr
  • func (a Addr) IP() net.IP
  • func (a Addr) String() string
• type FiveTuple
  • func (ft FiveTuple) Reversed() FiveTuple
  • func (ft FiveTuple) String() string
• type IPPacket
  • func (pkt *IPPacket) FT() FiveTuple
  • func (pkt *IPPacket) HasTCPFlag(flag uint8) bool
  • func (pkt *IPPacket) SetDest(addr Addr)
  • func (pkt *IPPacket) SetSource(addr Addr)
• type Opts
  • func (opts *Opts) ApplyDefaults() error
• type ReadWriter
• type ReadWriterAdapter
  • func (rw *ReadWriterAdapter) Read(b bpool.ByteSlice) (int, error)
  • func (rw *ReadWriterAdapter) Write(b bpool.ByteSlice) (int, error)
• type Server
  • func NewServer(downstream ReadWriter, opts *Opts) (Server, error)
• type StatsTracker
  • func NewStatsTracker(statsInterval time.Duration) *StatsTracker
  • func (s *StatsTracker) AcceptedPackets() int
  • func (s *StatsTracker) Close() error
  • func (s *StatsTracker) DroppedPackets() int
  • func (s *StatsTracker) InvalidPackets() int
  • func (s *StatsTracker) NumServers() int
  • func (s *StatsTracker) NumServersClosed() int
  • func (s *StatsTracker) NumServersClosing() int
  • func (s *StatsTracker) NumTCPConns() int
  • func (s *StatsTracker) NumTCPConnsClosed() int
  • func (s *StatsTracker) NumUDPConns() int
  • func (s *StatsTracker) NumUDPConnsClosed() int

Constants

const (
	// DefaultBufferPoolSize is 10 MB
	DefaultBufferPoolSize = 10000000

	// DefaultBufferDepth is 250 packets
	DefaultBufferDepth = 250

	// DefaultIdleTimeout is 65 seconds
	DefaultIdleTimeout = 65 * time.Second

	// DefaultStatsInterval is 15 seconds
	DefaultStatsInterval = 15 * time.Second

	// MinConntrackTimeout sets a lower bound on how long we'll let conntrack entries persist
	MinConntrackTimeout = 1 * time.Minute

	// MaximumIPPacketSize is 65535 bytes
	MaximumIPPacketSize = 65535
)

const (
	TCPFlagRST = 0x04
)

TCPFlags are the different flags supported in the TCP header

Functions

func RunTest

func RunTest(t *testing.T, tunDeviceName, tunAddr, tunGW, tunMask string, mtu int, doTest func(ifAddr string, dev io.ReadWriter, origEchoAddr Addr, finishedCh chan interface{}) (func() error, error))

Note - this test has to be run with root permissions to allow setting up the TUN device.

func TUNDevice

func TUNDevice(name, addr, netmask string, mtu int) (io.ReadWriteCloser, error)

TUNDevice creates a TUN device with the given name and configures an interface for that TUN device at the given address and netmask and given mtu (should usually be 1500).

Types

type Addr

type Addr struct {
	IPString string
	Port     uint16
}

func (Addr) IP

func (a Addr) IP() net.IP

func (Addr) String

func (a Addr) String() string

type FiveTuple

type FiveTuple struct {
	IPProto uint8
	Src     Addr
	Dst     Addr
}

func (FiveTuple) Reversed

func (ft FiveTuple) Reversed() FiveTuple

func (FiveTuple) String

func (ft FiveTuple) String() string

type IPPacket

type IPPacket struct {
	Raw       bpool.ByteSlice
	IPVersion uint8
	IPProto   uint8
	SrcAddr   *net.IPAddr
	DstAddr   *net.IPAddr
	Header    []byte
	Payload   []byte
}

func (*IPPacket) FT

func (pkt *IPPacket) FT() FiveTuple

func (*IPPacket) HasTCPFlag

func (pkt *IPPacket) HasTCPFlag(flag uint8) bool

HasTCPFlag returns true if the packet is a TCP packet that has the given flag set.

func (*IPPacket) SetDest

func (pkt *IPPacket) SetDest(addr Addr)

func (*IPPacket) SetSource

func (pkt *IPPacket) SetSource(addr Addr)

type Opts

type Opts struct {
	// IFName is the name of the interface to use for connecting upstream.
	// If not specified, this will use the default interface for reaching the
	// Internet.
	IFName string

	// IFAddr is the address to use for outbound packets. Overrides the IFName
	// when specified.
	IFAddr string

	// BufferPool is a pool for buffers. If not provided, default to a 10MB pool.
	// Each []byte in the buffer pool should be <MaximumIPPacketSize> bytes.
	BufferPool bpool.ByteSlicePool

	// BufferDepth specifies the number of outbound packets to buffer between
	// stages in the send/receive pipeline. The default is <DefaultBufferDepth>.
	BufferDepth int

	// IdleTimeout specifies the amount of time before idle connections are
	// automatically closed. The default is <DefaultIdleTimeout>.
	IdleTimeout time.Duration

	// StatsTracker allows specifying an existing StatsTracker to use for tracking
	// stats. If not specified, one will be created using the configured StatsInterval.
	// Note - the StatsTracker has to be manually closed using its Close() method, otherwise
	// it will keep logging stats.
	StatsTracker *StatsTracker

	// StatsInterval controls how frequently to display stats. Defaults to
	// <DefaultStatsInterval>.
	StatsInterval time.Duration

	// OnOutbound allows modifying outbound ip packets.
	OnOutbound func(pkt *IPPacket)

	// OnInbound allows modifying inbound ip packets. ft is the 5 tuple to
	// which the current connection/UDP port mapping is keyed.
	OnInbound func(pkt *IPPacket, downFT FiveTuple)
}

func (*Opts) ApplyDefaults

func (opts *Opts) ApplyDefaults() error

ApplyDefaults applies the default values to the given Opts, including making a new Opts if opts is nil.

type ReadWriter

type ReadWriter interface {
	// Read reads data into a ByteSlice
	Read(bpool.ByteSlice) (int, error)

	// Write writes data from a ByteSlice
	Write(bpool.ByteSlice) (int, error)
}

ReadWriter is like io.ReadWriter but using bpool.ByteSlice.

type ReadWriterAdapter

type ReadWriterAdapter struct {
	io.ReadWriter
}

ReadWriterAdapter adapts io.ReadWriter to ReadWriter

func (*ReadWriterAdapter) Read

func (rw *ReadWriterAdapter) Read(b bpool.ByteSlice) (int, error)

func (*ReadWriterAdapter) Write

func (rw *ReadWriterAdapter) Write(b bpool.ByteSlice) (int, error)

type Server

type Server interface {
	// Serve starts processing packets and blocks until finished
	Serve() error

	// Close stops the server and cleans up resources
	Close() error
}

func NewServer

func NewServer(downstream ReadWriter, opts *Opts) (Server, error)

NewServer constructs a new Server that reads packets from downstream and writes response packets back to downstream.

type StatsTracker

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

StatsTracker tracks statistics for one or more gonat servers.

func NewStatsTracker

func NewStatsTracker(statsInterval time.Duration) *StatsTracker

NewStatsTracker creates a new StatsTracker that will log stats at the given statsInterval. Logging only begins once a Server using this StatsTracker is started, and continues until Stop is called

func (*StatsTracker) AcceptedPackets

func (s *StatsTracker) AcceptedPackets() int

AcceptedPackets gives a count of accepted packets

func (*StatsTracker) Close

func (s *StatsTracker) Close() error

Stop stops the StatsTracker

func (*StatsTracker) DroppedPackets

func (s *StatsTracker) DroppedPackets() int

DroppedPackets gives a count of packets dropped due to being stalled writing down or upstream, being unable to assign a port open a connection, etc.

func (*StatsTracker) InvalidPackets

func (s *StatsTracker) InvalidPackets() int

InvalidPackets gives a count of invalid packets (unknown destination, wrong IP version, etc.)

func (*StatsTracker) NumServers

func (s *StatsTracker) NumServers() int

NumServers gives a count of the number of gonat servers currently running

func (*StatsTracker) NumServersClosed

func (s *StatsTracker) NumServersClosed() int

NumServersClosed gives a count of the number of gonat servers closed

func (*StatsTracker) NumServersClosing

func (s *StatsTracker) NumServersClosing() int

NumServersClosing gives a count of the number of gonat servers currently closing

func (*StatsTracker) NumTCPConns

func (s *StatsTracker) NumTCPConns() int

NumTCPConns gives a count of the number of TCP connections being tracked

func (*StatsTracker) NumTCPConnsClosed

func (s *StatsTracker) NumTCPConnsClosed() int

NumTCPConnsClosed gives a count of the number of TCP connections that have been closed

func (*StatsTracker) NumUDPConns

func (s *StatsTracker) NumUDPConns() int

NumUDPConns gives a count of the number of UDP connections being tracked

func (*StatsTracker) NumUDPConnsClosed

func (s *StatsTracker) NumUDPConnsClosed() int

NumUDPConnsClosed gives a count of the number of UDP connections that have been closed