IPF(4)

NAME
ipf - packet filtering kernel interface

SYNOPSIS
#include <sys/ip_fil.h>

IOCTLS

To add and delete rules to the filter list, three 'basic' ioctls are provided for use. The ioctl's are called as:

	ioctl(fd, SIOCADDFR, struct frentry *)
	ioctl(fd, SIOCDELFR, struct frentry *)
	ioctl(fd, SIOCIPFFL, int *)

However, the full complement is as follows:

	ioctl(fd, SIOCADAFR, struct frentry *) (same as SUICADDFR)
	ioctl(fd, SIOCRMAFR, struct frentry *) (same as SUICDELFR)
	ioctl(fd, SIOCADIFR, struct frentry *)
	ioctl(fd, SIOCRMIFR, struct frentry *)
	ioctl(fd, SIOCINAFR, struct frentry *)
	ioctl(fd, SIOCINIFR, struct frentry *)
	ioctl(fd, SIOCIPFFL, int *)

The variations, SIOCADAFR vs. SIOCADIFR, allow operation on the two lists, active and inactive, respectively. All of these ioctl's are implemented as being routing ioctls and thus the same rules for the various routing ioctls and the file descriptor are employed, mainly being that the fd must be that of the device associated with the module (i.e., /dev/ipl).

The three groups of ioctls above perform adding rules to the end of the list (SIOCAD*), deletion of rules from any place in the list (SIOCRM*) and insertion of a rule into the list (SIOCIN*). The rule place into which it is inserted is stored in the "fr_hits" field, below.

typedef struct  frentry {
        struct  frentry *fr_next;
        struct  ifnet   *fr_ifa;
        u_long  fr_hits;
        u_long  fr_bytes;       /* this is only incremented when a packet */
                                /* stops matching on this rule */
        /*
         * Fields after this may not change whilst in the kernel.
         */
        struct  fr_ip   fr_ip;
        struct  fr_ip   fr_mip;
        u_char  fr_tcpfm;       /* tcp flags mask */
        u_char  fr_tcpf;        /* tcp flags */
        u_short fr_icmpm;       /* data for ICMP packets (mask) */
        u_short fr_icmp;
        u_char  fr_scmp;        /* data for port comparisons */
        u_char  fr_dcmp;
        u_short fr_dport;
        u_short fr_sport;
        u_short fr_stop;        /* top port for <> and >< */
        u_short fr_dtop;        /* top port for <> and >< */
        u_long  fr_flags;       /* per-rule flags && options (see below) */
        int     (*fr_func)();   /* call this function */
        char    fr_icode;       /* return ICMP code */
        char    fr_ifname[IFNAMSIZ];
        struct  frdest  fr_tif; /* "to" interface */
        struct  frdest  fr_dif; /* duplicate packet interfaces */
} frentry_t;

When adding a new rule, all unused fields (in the filter rule) should be initialised to be zero. To insert a rule, at a particular position in the filter list, the number of the rule which it is to be inserted before must be put in the "fr_hits" field (the first rule is number 0).

Flags which are recognised in fr_pass:
	FR_BLOCK        0x00001    /* do not allow packet to pass */
	FR_PASS         0x00002    /* allow packet to pass */
	FR_OUTQUE       0x00004    /* outgoing packets */
	FR_INQUE        0x00008    /* ingoing packets */
	FR_LOG          0x00010    /* Log */
	FR_LOGP         0x00011    /* Log-pass */
	FR_LOGB         0x00012    /* Log-fail */
        FR_LOGBODY      0x00020    /* log the body of packets too */
        FR_LOGFIRST     0x00040    /* log only the first packet to match */
	FR_RETRST       0x00080    /* return a TCP RST packet if blocked */
	FR_RETICMP      0x00100    /* return an ICMP packet if blocked */
        FR_NOMATCH      0x00200    /* no match occured */
        FR_ACCOUNT      0x00400    /* count packet bytes */
        FR_KEEPFRAG     0x00800
        FR_KEEPSTATE    0x01000    /* keep packet flow state information */
        FR_INACTIVE     0x02000
        FR_QUICK        0x04000    /* quick-match and return */
        FR_FASTROUTE    0x08000
        FR_CALLNOW      0x10000
        FR_DUP          0x20000    /* duplicate the packet (not Solaris2)

Values for fr_scomp and fr_dcomp (source and destination port value comparisons) :

	FR_NONE         0
	FR_EQUAL        1
	FR_NEQUAL       2
	FR_LESST        3
	FR_GREATERT     4
	FR_LESSTE       5
	FR_GREATERTE    6
	FR_OUTRANGE     7
	FR_INRANGE      8

The third ioctl, SIOCIPFFL, flushes either the input filter list, the output filter list or both and it returns the number of filters removed from the list(s). The values which it will take and recognise are FR_INQUE and FR_OUTQUE (see above). General Logging Flags There are two flags which can be set to log packets independantly of the rules used. These allow for packets which are either passed or blocked to be logged. To set (and clear)/get these flags, two ioctls are provided:

SIOCSETFF
    Takes an unsigned integer as the parameter. The flags are then set to those provided (clearing/setting all in one).
    	FF_LOGPASS	1
    	FF_LOGBLOCK	2

SIOCGETFF
    Takes a pointer to an unsigned integer as the parameter. A copy of the flags currently in used is copied to user space.

Filter statistics Statistics on the various operations performed by this package on packets is kept inside the kernel. These statistics apply to packets traversing through the kernel. To retrieve this structure, use this ioctl:
	ioctl(fd, SIOCGETFS, struct friostat *)
struct	friostat        {
	struct  filterstats     f_st[2];
	struct  frentry *f_fin;
	struct  frentry *f_fout;
};
struct	filterstats {
        u_long  fr_pass;        /* packets allowed */
        u_long  fr_block;       /* packets denied */
        u_long  fr_nom;         /* packets which don't match any rule */
        u_long  fr_ppkl;        /* packets allowed and logged */
        u_long  fr_bpkl;        /* packets denied and logged */
        u_long  fr_npkl;        /* packets unmatched and logged */
        u_long  fr_pkl;         /* packets logged */
        u_long  fr_skip;        /* packets to be logged but buffer full */
        u_long  fr_ret;         /* packets for which a return is sent */
        u_long  fr_acct;        /* packets for which counting was performed */
        u_long  fr_bnfr;        /* bad attempts to allocate fragment state */
        u_long  fr_nfr;         /* new fragment state kept */
        u_long  fr_cfr;         /* add new fragment state but complete pkt */
        u_long  fr_bads;        /* bad attempts to allocate packet state */
        u_long  fr_ads;         /* new packet state kept */
        u_long  fr_chit;        /* cached hit */
#if SOLARIS
        u_long  fr_bad;         /* bad IP packets to the filter */
        u_long  fr_notip;       /* packets passed through no on ip queue */
        u_long  fr_drop;        /* packets dropped - no info for them! */
#endif
};

SEE ALSO
ipfstat(1), ipf(1), ipf(5)