nfqueue

README

go-nfqueue

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.

For documentation and more examples please take a look at

Documentation

Overview

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

Index

• Constants
• Variables
• type Config
• type ErrMsg
• type HookFunc
• type Msg
• type Nfqueue
  • func Open(config *Config) (*Nfqueue, error)
  • func (nfqueue *Nfqueue) Close() error
  • func (nfqueue *Nfqueue) Register(ctx context.Context, fn HookFunc) error
  • func (nfqueue *Nfqueue) SetVerdict(id uint32, verdict int) error
  • func (nfqueue *Nfqueue) SetVerdictBatch(id uint32, verdict int) error
  • func (nfqueue *Nfqueue) SetVerdictWithMark(id uint32, verdict, mark int) error

Examples

• Nfqueue.Register

Constants

const (
	AttrPacketID = iota
	AttrHook
	AttrHwProtocol
	AttrIfIndexInDev
	AttrIfIndexOutDev
	AttrIfIndexPhysInDev
	AttrIfIndexPhysOutDev
	AttrPayload
	AttrCapLen
	AttrTimestamp
	AttrHwAddr
	AttrMark
	AttrUID
	AttrGID
	AttrL2HDR
	AttrCt
	AttrCtInfo
	AttrSkbInfo
	AttrExp
	AttrSecCtx
	AttrVlanProto
	AttrVlanTCI
)

Various identifier,that can be the key of Msg map

const (
	NfQaCfgFlagFailOpen  = (1 << iota)
	NfQaCfgFlagConntrack = (1 << iota)
	NfQaCfgFlagGSO       = (1 << iota)
	NfQaCfgFlagUidGid    = (1 << iota)
	NfQaCfgFlagSecCx     = (1 << iota)
)

Various configuration flags

const (
	NfQnlCopyNone = iota
	NfQnlCopyMeta
	NfQnlCopyPacket
)

copy modes

const (
	NfDrop = iota
	NfAccept
	NfStolen
	NfQeueue
	NfRepeat
)

Verdicts

Variables

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

Types

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 and mask for this Nfqueue socket.
	Flags     uint32
	FlagsMask uint32

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

Config contains options for a Conn.

type ErrMsg

type ErrMsg struct {
	Code  int
	Len   uint32
	Type  uint16
	Flags uint16
	Seq   uint32
	Pid   uint32
}

ErrMsg as defined in nlmsgerr

type HookFunc

type HookFunc func(m Msg) int

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

type Msg

type Msg map[int]interface{}

Msg contains all the information of a connection

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

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

Register your own function as callback for a netfilter queue

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

	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(m nfqueue.Msg) int {
		id := m[nfqueue.AttrPacketID].(uint32)
		// Just print out the id and payload of the nfqueue packet
		fmt.Printf("[%d]\t%v\n", id, m[nfqueue.AttrPayload])
		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()
}

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