Unison Help
7.8.2.Packet filter control: pfctl
NAME
Packet filter control – pfctl
SYNOPSIS
#include <pfctl.h>
DESCRIPTION
The pfctl library communicates with the packet filter using the ioctl interface described in pf. It allows rule set and parameter configuration and retrieval of status information from the packet filter.
Packet filtering restricts the types of packets that pass through network interfaces entering or leaving the host based on filter rules as described in pf.filtering. The packet filter can also replace addresses and ports of packets. Replacing source addresses and ports of outgoing packets is called NAT (Network Address Translation) and is used to connect an internal network (usually reserved address space) to an external one (the Internet) by making all connections to external hosts appear to come from the gateway. Replacing destination addresses and ports of incoming packets is used to redirect connections to different hosts and/or ports. A combination of both translations, bidirectional NAT, is also supported. Translation rules are described in pf.nat.
User functions
The pfctl library provides many commands for user interface.
- int pfctl_setup(int dev, int (*print_func)(const char *, …), int opts);
- Setup pfctl library.
dev – control file descriptor (socket);
print_func – printout function;
opts – options:
PF_OPT_NOACTION – do not actually load rules, just parse them
PF_OPT_QUIET – only print errors and warnings
- int pfctl_enable(void);
- Enable the packet filter.
- int pfctl_disable(void);
- Disable the packet filter.
- int pfctl_rules_begin(void);
- Clears the inactive filter rule set.
- int pfctl_rules_parse(char *line)
- Adds filter rule at the end of the inactive filter rule set. line is a pointer to the string with the rule represented in format described in pf.filtering.
- int pfctl_rules_commit(void);
- Switch inactive to active filter rule set.
- int pfctl_nat_begin(void);
- Clears the inactive filter NAT set.
- int pfctl_nat_parse(char *line)
- Adds filter rule at the end of the inactive filter NAT set. line is a pointer to the string with the rule represented in format described in pf.nat.
- int pfctl_nat_commit(void);
- Switch inactive to active filter NAT set.
- int pfctl_clear_rules(void);
- Flush the filter rules.
- int pfctl_clear_nat(void);
- Flush the NAT rules.
- int pfctl_clear_states(void);
- Flush the state table (NAT and filter).
- int pfctl_kill_states(const char *host1, const char *host2)
- Kill all of the state entries from the host1. If host2 is not NULL, this command will kill all the state entries from the first host to the second host.
- int pfctl_log(char *ifname);
- Enable collection of packet and byte count statistics for interface ifname.
- int pfctl_clear_stats(void);
- Flush the filter information (statistics that are not bound to rules).
- int pfctl_get_status(struct pf_status *status);
- Gets filter information (statistics and counters).
struct pf_status { u_int64_t counters[PFRES_MAX]; u_int64_t fcounters[FCNT_MAX]; u_int64_t pcounters[2][2][3]; u_int64_t bcounters[2][2]; u_int32_t running; u_int32_t states; u_int32_t since; u_int32_t debug; };
- int pfctl_gettimeout(const char *opt);
- Gets a timeout or interval value. opt is a pointer to the string with timeout or interval name:
"tcp.first" - PFTM_TCP_FIRST_PACKET "tcp.opening" - PFTM_TCP_OPENING "tcp.established" - PFTM_TCP_ESTABLISHED "tcp.closing" - PFTM_TCP_CLOSING "tcp.finwait" - PFTM_TCP_FIN_WAIT "tcp.closed" - PFTM_TCP_CLOSED "udp.first" - PFTM_UDP_FIRST_PACKET "udp.single" - PFTM_UDP_SINGLE "udp.multiple" - PFTM_UDP_MULTIPLE "icmp.first" - PFTM_ICMP_FIRST_PACKET "icmp.error" - PFTM_ICMP_ERROR_REPLY "other.first" - PFTM_OTHER_FIRST_PACKET "other.single" - PFTM_OTHER_SINGLE "other.multiple" - PFTM_OTHER_MULTIPLE "frag" - PFTM_FRAG "interval" - PFTM_INTERVAL "all" - print all values
Function print result using printout function specified by pfctl_setup().
- int pfctl_settimeout(const char *opt, int seconds);
- Sets a timeout or interval value. opt is a pointer to the string with timeout or interval name (see above), seconds – new value.
- int pfctl_getlimit(const char *opt);
- Gets hard limits on the memory pools used by the packet filter. opt is a pointer to the string with memory pool name:
"states" - PF_LIMIT_STATES "frags" - PF_LIMIT_FRAGS "all" - print all values
Function print result using printout function specified by pfctl_setup().
- int pfctl_setlimit(const char *opt, int limit);
- Sets hard limits on the memory pools used by the packet filter. opt is a pointer to the string with memory pool name (see above), limit – new value.
- int pfctl_debug(u_int32_t level);
- Set the debug level. level can be:
PF_DEBUG_NONE – don’t generate debug messages
PF_DEBUG_URGENT – generate debug messages only for serious errors.
PF_DEBUG_MISC – generate debug messages for various errors
All messages will be printed using printout function specified by pfctl_setup().
EXAMPLE
The following example demonstrates how to use the pfctl commands to init NAT and filtering rules.
#define LAN_IP "192.168.17.198"
#define WAN_IP "192.168.20.198"
#define WAN_IF "eth0"
void pf_setup(void)
{
int i;
int s;
// Init the packet filter
pfattach();
/*
* open control socket
*/
s = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
if (s < 0)
{
printf("pf sock open error %d\n", errno);
return;
}
else
printf("pf sock %d\n", s);
// Set socket, printout function and options for pfctl library
pfctl_setup(s, printf, 0);
/*
* NAT
*/
pfctl_nat_begin();
// Parse nat rules and put its to packet filter
pfctl_nat_parse("nat on "WAN_IF" from "LAN_IP"/24 to any -> "WAN_IP"\n");
pfctl_nat_commit();
/*
* FILTER
*/
pfctl_rules_begin();
// Parse pf rules and put its to packet filter
pfctl_rules_parse("block out on "WAN_IF" proto udp from any port > 9000 to any\n");
pfctl_rules_commit();
pfctl_enable();
close(s);
}
NOTES
There is a demo available for the Unison and DSPnano pfctl which is found in installdir/demos.