nfqueue

package module
Version: v1.3.0 Latest Latest
Warning

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

Go to latest
Published: Aug 21, 2021 License: MIT Imports: 9 Imported by: 15

README

go-nfqueue PkgGoDev Build Status Go Report Card

This is go-nfqueue and it is written in golang. It provides a C-binding free API to the netfilter based queue subsystem of the Linux kernel.

Privileges

This package processes information directly from the kernel and therefore it requires special privileges. You can provide this privileges by adjusting the CAP_NET_ADMIN capabilities.

	setcap 'cap_net_admin=+ep' /your/executable

For documentation and more examples please take a look at documentation.

Requirements

Documentation

Overview

Package nfqueue provides an API to interact with the nfqueue subsystem of the netfilter family from the linux kernel.

This package processes information directly from the kernel and therefore it requires special privileges. You can provide this privileges by adjusting the CAP_NET_ADMIN capabilities.

setcap 'cap_net_admin=+ep' /your/executable

Index

Examples

Constants

View Source
const (
	NfQaCfgFlagFailOpen  = (1 << iota)
	NfQaCfgFlagConntrack = (1 << iota)
	NfQaCfgFlagGSO       = (1 << iota)
	NfQaCfgFlagUIDGid    = (1 << iota)
	NfQaCfgFlagSecCx     = (1 << iota)
)

Various configuration flags

View Source
const (
	NfQnlCopyNone = iota
	NfQnlCopyMeta
	NfQnlCopyPacket
)

copy modes

View Source
const (
	NfDrop = iota
	NfAccept
	NfStolen
	NfQeueue
	NfRepeat
)

Verdicts

Variables

View Source
var (
	ErrRecvMsg        = errors.New("received error message")
	ErrUnexpMsg       = errors.New("received unexpected message from kernel")
	ErrInvFlag        = errors.New("invalid Flag")
	ErrNotLinux       = errors.New("not implemented for OS other than linux")
	ErrInvalidVerdict = errors.New("invalid verdict")
)

Various errors

Functions

This section is empty.

Types

type Attribute added in v1.2.0

type Attribute struct {
	PacketID   *uint32
	Hook       *uint8
	Timestamp  *time.Time
	Mark       *uint32
	InDev      *uint32
	PhysInDev  *uint32
	OutDev     *uint32
	PhysOutDev *uint32
	Payload    *[]byte
	CapLen     *uint32
	UID        *uint32
	GID        *uint32
	SecCtx     *string
	L2Hdr      *[]byte
	HwAddr     *[]byte
	HwProtocol *uint16
	Ct         *[]byte
	CtInfo     *uint32
	SkbInfo    *[]byte
	Exp        *[]byte
}

Attribute contains various elements for nfqueue elements. As not every value is contained in every nfqueue message, the elements inside Attribute are pointers to these values or nil, if not present.

type Config

type Config struct {
	// Network namespace the Nfqueue needs to operate in. If set to 0 (default),
	// no network namespace will be entered.
	NetNS int

	// Queue this Nfqueue socket will be assigned to
	NfQueue uint16
	// Maximum number of packages within the Nfqueue.
	MaxQueueLen uint32

	// Only used in combination with NfQnlCopyPacket.
	MaxPacketLen uint32

	// Specifies how the kernel handles a packet in the nfqueue queue.
	Copymode uint8

	// Optional flags for this Nfqueue socket.
	Flags uint32

	// AfFamily for this Nfqueue socket.
	AfFamily uint8

	// Deprecated: Cancel the context passed to RegisterWithErrorFunc() or Register()
	// to remove the hook from the nfqueue gracefully.
	ReadTimeout time.Duration

	// Time till a write action times out - only available for Go >= 1.12
	WriteTimeout time.Duration

	// Interface to log internals.
	Logger *log.Logger
}

Config contains options for a Conn.

type ErrorFunc added in v1.2.0

type ErrorFunc func(e error) int

ErrorFunc is a function that receives all errors that happen while reading from a Netlinkgroup. To stop receiving messages return something different than 0.

type HookFunc

type HookFunc func(a Attribute) int

HookFunc is a function, that receives events from a Netlinkgroup To stop receiving messages on this HookFunc, return something different than 0.

type Nfqueue

type Nfqueue struct {
	// Con is the pure representation of a netlink socket
	Con *netlink.Conn
	// contains filtered or unexported fields
}

Nfqueue represents a netfilter queue handler

func Open

func Open(config *Config) (*Nfqueue, error)

Open a connection to the netfilter queue subsystem

func (*Nfqueue) Close

func (nfqueue *Nfqueue) Close() error

Close the connection to the netfilter queue subsystem

func (*Nfqueue) Register deprecated

func (nfqueue *Nfqueue) Register(ctx context.Context, fn HookFunc) error

Register your own function as callback for a netfilter queue.

The registered callback will stop receiving data if an error happened. To handle errors and continue receiving data with the registered callback use RegisterWithErrorFunc() instead.

Deprecated: Use RegisterWithErrorFunc() instead.

Example
package main

import (
	"context"
	"fmt"
	"time"

	nfqueue "github.com/florianl/go-nfqueue"
)

func main() {
	// Send outgoing pings to nfqueue queue 100
	// # sudo iptables -I OUTPUT -p icmp -j NFQUEUE --queue-num 100

	// Set configuration options for nfqueue
	config := nfqueue.Config{
		NfQueue:      100,
		MaxPacketLen: 0xFFFF,
		MaxQueueLen:  0xFF,
		Copymode:     nfqueue.NfQnlCopyPacket,
		WriteTimeout: 15 * time.Millisecond,
	}

	nf, err := nfqueue.Open(&config)
	if err != nil {
		fmt.Println("could not open nfqueue socket:", err)
		return
	}
	defer nf.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	fn := func(a nfqueue.Attribute) int {
		id := *a.PacketID
		// Just print out the id and payload of the nfqueue packet
		fmt.Printf("[%d]\t%v\n", id, *a.Payload)
		nf.SetVerdict(id, nfqueue.NfAccept)
		return 0
	}

	// Register your function to listen on nflqueue queue 100
	err = nf.Register(ctx, fn)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Block till the context expires
	<-ctx.Done()
}
Output:

func (*Nfqueue) RegisterWithErrorFunc added in v1.2.0

func (nfqueue *Nfqueue) RegisterWithErrorFunc(ctx context.Context, fn HookFunc, errfn ErrorFunc) error

RegisterWithErrorFunc attaches a callback function to a netfilter queue and allows custom error handling for errors encountered when reading from the underlying netlink socket.

func (*Nfqueue) SetVerdict

func (nfqueue *Nfqueue) SetVerdict(id uint32, verdict int) error

SetVerdict signals the kernel the next action for a specified package id

func (*Nfqueue) SetVerdictBatch

func (nfqueue *Nfqueue) SetVerdictBatch(id uint32, verdict int) error

SetVerdictBatch signals the kernel the next action for a batch of packages till id

func (*Nfqueue) SetVerdictModPacket added in v1.2.0

func (nfqueue *Nfqueue) SetVerdictModPacket(id uint32, verdict int, packet []byte) error

SetVerdictModPacket signals the kernel the next action for an altered packet

func (*Nfqueue) SetVerdictModPacketWithMark added in v1.2.0

func (nfqueue *Nfqueue) SetVerdictModPacketWithMark(id uint32, verdict, mark int, packet []byte) error

SetVerdictModPacketWithMark signals the kernel the next action and mark for an altered packet

func (*Nfqueue) SetVerdictWithMark

func (nfqueue *Nfqueue) SetVerdictWithMark(id uint32, verdict, mark int) error

SetVerdictWithMark signals the kernel the next action and the mark for a specified package id

Directories

Path Synopsis
internal
unix
Package unix maps constants from golang.org/x/sys/unix to local constant and makes them available for other platforms as well.
Package unix maps constants from golang.org/x/sys/unix to local constant and makes them available for other platforms as well.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL