libiptc

README

libiptc Go bindings

libiptc bindings for Go language. Object-oriented design, support for IPv6 (libip6tc) and same wait locking mechanism as iptables/ip6tables official binaries.

This project currently contains Go bindings to libip4tc/libip6tc dynamic link libraries, most headers/commenst are from original iptables C headers.

Please note that there is no public/stable C/C++ API for libiptc, quoting from official Netfilter FAQs:

4.5 Is there an C/C++ API for adding/removing rules?

The answer unfortunately is: No.

Now you might think 'but what about libiptc?'. As has been pointed out numerous times on the mailinglist(s), libiptc was NEVER meant to be used as a public interface. We don't guarantee a stable interface, and it is planned to remove it in the next incarnation of linux packet filtering. libiptc is way too low-layer to be used reasonably anyway.

We are well aware that there is a fundamental lack for such an API, and we are working on improving that situation. Until then, it is recommended to either use system() or open a pipe into stdin of iptables-restore. The latter will give you a way better performance.

How to use

Install the dependency with go get or your dependency system of choice.

go get github.com/gdm85/go-libiptc

You can use xtables locking features by importing github.com/gdm85/go-libiptc and IPv4/IPv6 features by importing either github.com/gdm85/go-libiptc/ipv4 or github.com/gdm85/go-libiptc/ipv6.

Once the package is imported and being used, the OS thread is locked to a specific background goroutine and all calls are performed serially through such goroutine.

Building

In order to build this package it is necessary for it to reside within a proper GOPATH and that iptables headers are globally available on the system; on Debian/Ubuntu systems these are provided by iptables-dev package, otherwise you can refer to the official upstream iptables git repository: git://git.netfilter.org/iptables.git.

To build everything (except tests):

make

To build the package it will suffice a:

make build

To run tests (with proper root privileges):

make test

To build the examples:

make examples

TODO

• separate libip6tc package that uses '#cgo LDFLAGS: -lip6tc'
• unit tests coverage
• finally, some analysis of memory leakage

Useful resources

• http://www.bani.com.br/2012/05/programmatically-managing-iptables-rules-in-c-iptc/

License

Licensed under GNU/GPL v2.

Documentation

Index

• Constants
• func GetErrno() int
• func RelayCall(f RelayedFunc, context string, e ErrorFunc) error
• func XtablesLock(wait bool, maxSeconds uint) (result bool, osErr error)
• func XtablesUnlock() (result bool, osErr error)
• type ErrorFunc
• type Not
  • func (n Not) String() string
• type RelayedCall
• type RelayedFunc
• type Rule
  • func (r Rule) String() string
• type XtChainLabel
• type XtCounters

Constants

const (
	// the constants are copied from #define declarations in libiptc.h
	IPTC_LABEL_ACCEPT = "ACCEPT"
	IPTC_LABEL_DROP   = "DROP"
	IPTC_LABEL_QUEUE  = "QUEUE"
	IPTC_LABEL_RETURN = "RETURN"
)

Functions

func GetErrno

func GetErrno() int

GetErrno returns the OS-level errno value. It is used internally to properly report about errors.

func RelayCall

func RelayCall(f RelayedFunc, context string, e ErrorFunc) error

RelayCall will perform the C call on a OS-locked goroutine, serially.

func XtablesLock

func XtablesLock(wait bool, maxSeconds uint) (result bool, osErr error)

XtablesLock acquires the same lock that a call to `iptables --wait` would.

func XtablesUnlock

func XtablesUnlock() (result bool, osErr error)

XtablesUnlock releases an iptables lock previously acquired with XtablesLock().

Types

type ErrorFunc

type ErrorFunc func() string

ErrorFunc generates an error based on a libip*tc_strerror call. Used internally to report about errors.

type Not

type Not bool

Not is a shortand for rule negation description.

func (Not) String

func (n Not) String() string

String returns '!' for a negated rule.

type RelayedCall

type RelayedCall struct {
	// Context is the C function being called.
	Context string
	// Func is the function that performs the wrapper around the C function call that does the conversion of input/output parameters.
	Func RelayedFunc
	// Error is the specific ErrorFunc needed to extract an error after the C call.
	Error ErrorFunc
}

RelayedCall

type RelayedFunc

type RelayedFunc func() bool

RelayedFunc is a function that returns false if there is an 'errno' to query about. Used internally to perform all lib*iptc calls serially.

type Rule

type Rule struct {
	Src    *net.IPNet
	Dest   *net.IPNet
	InDev  string
	OutDev string
	Not    struct {
		Src    Not
		Dest   Not
		InDev  Not
		OutDev Not
	}
	Target string
	XtCounters
}

Rule is a complete iptables rule descriptor.

func (Rule) String

func (r Rule) String() string

String returns a human-readable description of a rule.

type XtChainLabel

type XtChainLabel string

XtChainLabel is a chain label.

type XtCounters

type XtCounters struct {
	// Pcnt is the packet counter.
	Pcnt uint64
	// Bcnt is the byte counter.
	Bcnt uint64
}

XtCounters contains packet and byte counters.