zsocket

README

ZSocket

ZSocket is a library that wraps the linux zero-copy socket syscall to create a ring buffer in a memory mapped file. It also contains some utility functions and types to help with a handful of layer 2, 3, and 4 types. It is a lot like libcap, except it has easy to understand facilities for writing (injecting packets) to an interface.

ZSocket doesn't contain or wrap any C/C++, and it is lock free and thread safe.

The following program prints out all know layer types to ZSocket on a given interface:

package main

import (
    "fmt"

    "github.com/newtools/zsocket"
    "github.com/newtools/zsocket/nettypes"
)

func main() {
	// args: interfaceIndex, options, maxFrameSize, and maxTotalFrames

	// inerfaceIndex: the index of the net device you want to open a raw socket to
	// options: RX and TX, or just one or the other?
	// maxFrameSize: must be a power of 2, bigger than zsocket.MinimumFrameSize,
	// 	and smaller than maximum frame size
	// maxTotalFrames: must be at least 16, and be a multiple of 8.
	zs, err := zsocket.NewZSocket(14, zsocket.EnableRX, 2048, 64, nettypes.All)
	// the above will result in a ring buffer of 64 frames at
	// 	(2048 - zsocket.PacketOffset()) *writeable* bytes each
	// 	for a total of 2048*64 bytes of *unswappable* system memory consumed.
	if err != nil {
		panic(err)
	}
	zs.Listen(func(f *nettypes.Frame, frameLen, capturedLen uint16) {
		fmt.Printf(f.String(capturedLen, 0))
	})
}

1. See the examples folder for more simple programs that do various things with ZSocket.

2. Learn how to set up a docker container with a custom veth-pair in the utils folder (useful for setting up complex virtual networking scenarios)

3. Play around with FakeInterface to (and its examples folder) to play around with networking protocols.

Documentation

Index

• Constants
• func PacketOffset() int
• type IZSocket
• type ZSocket
  • func NewZSocket(ethIndex, options int, maxFrameSize, maxTotalFrames uint, ...) (*ZSocket, error)
  • func (zs *ZSocket) Close() error
  • func (zs *ZSocket) CopyToBuffer(buf []byte, l uint16, copyFx func(dst, src []byte, l uint16) uint16) (int32, error)
  • func (zs *ZSocket) FlushFrames() (uint, error, []error)
  • func (zs *ZSocket) Listen(fx func(*nettypes.Frame, uint16, uint16)) error
  • func (zs *ZSocket) MaxPacketSize() uint16
  • func (zs *ZSocket) MaxPackets() int32
  • func (zs *ZSocket) WriteToBuffer(buf []byte, l uint16) (int32, error)
  • func (zs *ZSocket) WrittenPackets() int32

Constants

const (
	TPacketAlignment = 16

	MinimumFrameSize = TPacketAlignment << 7
	MaximumFrameSize = TPacketAlignment << 11

	EnableRX      = 1 << 0
	EnableTX      = 1 << 1
	DisableTXLoss = 1 << 2
)

Functions

func PacketOffset

func PacketOffset() int

Types

type IZSocket

type IZSocket interface {
	MaxPackets() int32
	MaxPacketSize() uint16
	WrittenPackets() int32
	Listen(fx func(*nettypes.Frame, uint16, uint16))
	WriteToBuffer(buf []byte, l uint16) (int32, error)
	CopyToBuffer(buf []byte, l uint16, copyFx func(dst, src []byte, l uint16)) (int32, error)
	FlushFrames() (uint, error, []error)
	Close() error
}

IZSocket is an interface for interacting with eth-iface like objects in the ZSocket code-base. This has basically simply enabled the FakeInterface code to work.

type ZSocket

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

ZSocket opens a zero copy ring-buffer to the specified interface. Do not manually initialize ZSocket. Use `NewZSocket`.

func NewZSocket

func NewZSocket(ethIndex, options int, maxFrameSize, maxTotalFrames uint, ethType nettypes.EthType) (*ZSocket, error)

NewZSocket opens a "ZSocket" on the specificed interface (by interfaceIndex). Whether the TX ring, RX ring, or both are enabled are options that can be passed. Additionally, an option can be passed that will tell the kernel to pay attention to packet faults, called DisableTXLoss.

func (*ZSocket) Close

func (zs *ZSocket) Close() error

Close socket

func (*ZSocket) CopyToBuffer

func (zs *ZSocket) CopyToBuffer(buf []byte, l uint16, copyFx func(dst, src []byte, l uint16) uint16) (int32, error)

CopyToBuffer is like WriteToBuffer, it writes a frame to the TX ring buffer. However, it can take a function argument, that will be passed the raw TX byes so that custom logic can be applied to copying the frame (for example, encrypting the frame).

func (*ZSocket) FlushFrames

func (zs *ZSocket) FlushFrames() (uint, error, []error)

FlushFrames tells the kernel to flush all packets written to the TX ring buffer.n

func (*ZSocket) Listen

func (zs *ZSocket) Listen(fx func(*nettypes.Frame, uint16, uint16)) error

Listen to all specified packets in the RX ring-buffer

func (*ZSocket) MaxPacketSize

func (zs *ZSocket) MaxPacketSize() uint16

Returns the frame size in bytes

func (*ZSocket) MaxPackets

func (zs *ZSocket) MaxPackets() int32

Returns the maximum amount of frame packets that can be written

func (*ZSocket) WriteToBuffer

func (zs *ZSocket) WriteToBuffer(buf []byte, l uint16) (int32, error)

WriteToBuffer writes a raw frame in bytes to the TX ring buffer. The length of the frame must be specified.

func (*ZSocket) WrittenPackets

func (zs *ZSocket) WrittenPackets() int32

Returns the amount of packets, written to the tx ring, that haven't been flushed.