nfqueue

nfqueue

nfqueue is a go binding to libnetfilter_queue.

It implements partially the libnetfilter_queue functionality. Currently, it provides:

• Start a netfilter queue
• Stop a netfilter queue
• Handle a packet received by netfilter queue and accept, drop or modify it.
• Configure the netfilter queue

See more information about libnetfilter_queue.

Using library

import "github.com/Telefonica/nfqueue"

Netfilter queue configuration

It is possible to pass a configuration object with optional settings to tune the netfilter queue.

// QueueConfig contains optional configuration parameters to initialize a queue.
type QueueConfig struct {
	MaxPackets uint32
	QueueFlags []QueueFlag
	BufferSize uint32
}

The following table lists the queue flags. Note that some queue flags may be unavailable depending on the linux kernel version.

Packet and packet handler

Each packet that is processed by a netfilter queue is encapsulated in the type Packet that contains a byte slice with the packet buffer (starting with the IP layer). This buffer can be parsed with gopacket. It also provides an interface to accept, drop or modify the packet.

// Packet struct provides the packet data and methods to accept, drop or modify the packet.
type Packet struct {
	Buffer []byte
	id     uint32
	q      *Queue
}

// Accept the packet.
func (p *Packet) Accept() error {...}
// Drop the packet.
func (p *Packet) Drop() error {...}
// Modify the packet with a new buffer.
func (p *Packet) Modify(buffer []byte) error {...}

To receive these packets, the client needs to implement the PacketHandler interface.

// PacketHandler is an interface to handle a packet retrieved by netfilter.
type PacketHandler interface {
	Handle(p *Packet)
}

Example

The following example instantiates a netfilter queue (with 1 as queue identifier) and the packet handler accepts all the packets.

import (
	"github.com/Telefonica/nfqueue"
)

type Queue struct {
	id    uint16
	queue *nfqueue.Queue
}

func NewQueue(id uint16) *Queue {
	q := &Queue{
		id: id,
	}
	queueCfg := &nfqueue.QueueConfig{
		MaxPackets: 1000,
		BufferSize: 16 * 1024 * 1024,
		QueueFlags: []nfqueue.QueueFlag{nfqueue.FailOpen},
	}
	// Pass as packet handler the current instance because it implements nfqueue.PacketHandler interface
	q.queue = nfqueue.NewQueue(q.id, q, queueCfg)
	return q
}

// Start the queue.
func (q *Queue) Start() error {
	return q.queue.Start()
}

// Stop the queue.
func (q *Queue) Stop() error {
	return q.queue.Stop()
}

// Handle a nfqueue packet. It implements nfqueue.PacketHandler interface.
func (q *Queue) Handle(p *nfqueue.Packet) {
	// Accept the packet
	p.Accept()
}

func main() {
	q := NewQueue(1)
	go q.Start()
}

Performance

This library is inspired in other nfqueue go bindings. The main difference is that our design does not use go channels to process the packets to avoid introducing an overhead that degrades performance. Note that nfqueue cannot process multiple packets from the same queue concurrently.

The following table compares nfqueue with freki using a host with 4 CPU cores:

Tuning the amount of nfqueue queues with the amount of CPU cores, this library achieves a 75% improvement over freki.

License

Copyright 2018 Telefónica Investigación y Desarrollo, S.A.U

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.