nfqueue

package module
v2.0.0 Latest Latest
Warning

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

 Go to latest Published: May 11, 2024 License: MIT Imports: 9 Imported by: 1

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 

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
	SkbPrio    *uint32
}

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 Logger
}

Config contains options for a Conn.

type ErrorFunc 

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 Logger 

type Logger interface {
	Debugf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
}

Logger provides logging functionality.

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.

func (*Nfqueue) RegisterWithErrorFunc 

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.

Example 
package main

import (
	"context"
	"fmt"
	"time"

	nfqueue "github.com/florianl/go-nfqueue/v2"
	"github.com/mdlayher/netlink"
)

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()

	// Avoid receiving ENOBUFS errors.
	if err := nf.SetOption(netlink.NoENOBUFS, true); err != nil {
		fmt.Printf("failed to set netlink option %v: %v\n",
			netlink.NoENOBUFS, err)
		return
	}

	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.RegisterWithErrorFunc(ctx, fn, func(e error) int {
		fmt.Println(err)
		return -1
	})
	if err != nil {
		fmt.Println(err)
		return
	}

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

Output:

func (*Nfqueue) SetOption 

func (nfqueue *Nfqueue) SetOption(o netlink.ConnOption, enable bool) error

SetOption allows to enable or disable netlink socket options.

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 

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

SetVerdictModPacket signals the kernel the next action for an altered packet

func (*Nfqueue) SetVerdictModPacketWithConnMark 

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

SetVerdictModPacketWithConnMark signals the kernel the next action and connmark for an altered packet

func (*Nfqueue) SetVerdictModPacketWithMark 

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) SetVerdictWithConnMark 

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

SetVerdictWithConnMark signals the kernel the next action and the connmark for a specified package id

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

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.