contrib/ipfilter/man/ipf.4

   1 .\" $FreeBSD: src/contrib/ipfilter/man/ipf.4,v 1.4.2.2 2002/04/27 17:31:00 darrenr Exp $
   2 .TH IPF 4
   3 .SH NAME
   4 ipf \- packet filtering kernel interface
   5 .SH SYNOPSIS
   6 #include <netinet/ip_compat.h>
   7 .br
   8 #include <netinet/ip_fil.h>
   9 .SH IOCTLS
  10 .PP
  11 To add and delete rules to the filter list, three 'basic' ioctls are provided
  12 for use.  The ioctl's are called as:
  13 .LP
  14 .nf
  15         ioctl(fd, SIOCADDFR, struct frentry **)
  16         ioctl(fd, SIOCDELFR, struct frentry **)
  17         ioctl(fd, SIOCIPFFL, int *)
  18 .fi
  19 .PP
  20 However, the full complement is as follows:
  21 .LP
  22 .nf
  23         ioctl(fd, SIOCADAFR, struct frentry **) (same as SIOCADDFR)
  24         ioctl(fd, SIOCRMAFR, struct frentry **) (same as SIOCDELFR)
  25         ioctl(fd, SIOCADIFR, struct frentry **)
  26         ioctl(fd, SIOCRMIFR, struct frentry **)
  27         ioctl(fd, SIOCINAFR, struct frentry **)
  28         ioctl(fd, SIOCINIFR, struct frentry **)
  29         ioctl(fd, SIOCSETFF, u_int *)
  30         ioctl(fd, SIOGGETFF, u_int *)
  31         ioctl(fd, SIOCGETFS, struct friostat **)
  32         ioctl(fd, SIOCIPFFL, int *)
  33         ioctl(fd, SIOCIPFFB, int *)
  34         ioctl(fd, SIOCSWAPA, u_int *)
  35         ioctl(fd, SIOCFRENB, u_int *)
  36         ioctl(fd, SIOCFRSYN, u_int *)
  37         ioctl(fd, SIOCFRZST, struct friostat **)
  38         ioctl(fd, SIOCZRLST, struct frentry **)
  39         ioctl(fd, SIOCAUTHW, struct frauth_t **)
  40         ioctl(fd, SIOCAUTHR, struct frauth_t **)
  41         ioctl(fd, SIOCATHST, struct fr_authstat **)
  42 .fi
  43 .PP
  44 The variations, SIOCADAFR vs. SIOCADIFR, allow operation on the two lists,
  45 active and inactive, respectively.  All of these ioctl's are implemented
  46 as being routing ioctls and thus the same rules for the various routing
  47 ioctls and the file descriptor are employed, mainly being that the fd must
  48 be that of the device associated with the module (i.e., /dev/ipl).
  49 .LP
  50 .PP
  51 The three groups of ioctls above perform adding rules to the end of the
  52 list (SIOCAD*), deletion of rules from any place in the list (SIOCRM*)
  53 and insertion of a rule into the list (SIOCIN*).  The rule place into
  54 which it is inserted is stored in the "fr_hits" field, below.
  55 .LP
  56 .nf
  57 typedef struct  frentry {
  58         struct  frentry *fr_next;
  59         u_short fr_group;       /* group to which this rule belongs */
  60         u_short fr_grhead;      /* group # which this rule starts */
  61         struct  frentry *fr_grp;
  62         int     fr_ref;         /* reference count - for grouping */
  63         void    *fr_ifa;
  64 #if BSD >= 199306
  65         void    *fr_oifa;
  66 #endif
  67         /*
  68          * These are only incremented when a packet  matches this rule and
  69          * it is the last match
  70          */
  71         U_QUAD_T        fr_hits;
  72         U_QUAD_T        fr_bytes;
  73         /*
  74          * Fields after this may not change whilst in the kernel.
  75          */
  76         struct  fr_ip   fr_ip;
  77         struct  fr_ip   fr_mip; /* mask structure */
  78
  79         u_char  fr_tcpfm;       /* tcp flags mask */
  80         u_char  fr_tcpf;        /* tcp flags */
  81
  82         u_short fr_icmpm;       /* data for ICMP packets (mask) */
  83         u_short fr_icmp;
  84
  85         u_char  fr_scmp;        /* data for port comparisons */
  86         u_char  fr_dcmp;
  87         u_short fr_dport;
  88         u_short fr_sport;
  89         u_short fr_stop;        /* top port for <> and >< */
  90         u_short fr_dtop;        /* top port for <> and >< */
  91         u_32_t  fr_flags;       /* per-rule flags && options (see below) */
  92         u_short fr_skip;        /* # of rules to skip */
  93         u_short fr_loglevel;    /* syslog log facility + priority */
  94         int     (*fr_func) __P((int, ip_t *, fr_info_t *));
  95         char    fr_icode;       /* return ICMP code */
  96         char    fr_ifname[IFNAMSIZ];
  97 #if BSD > 199306
  98         char    fr_oifname[IFNAMSIZ];
  99 #endif
 100         struct  frdest  fr_tif; /* "to" interface */
 101         struct  frdest  fr_dif; /* duplicate packet interfaces */
 102 } frentry_t;
 103 .fi
 104 .PP
 105 When adding a new rule, all unused fields (in the filter rule) should be
 106 initialised to be zero.  To insert a rule, at a particular position in the
 107 filter list, the number of the rule which it is to be inserted before must
 108 be put in the "fr_hits" field (the first rule is number 0).
 109 .LP
 110 .PP
 111 Flags which are recognised in fr_flags:
 112 .nf
 113
 114      FR_BLOCK        0x000001   /* do not allow packet to pass */
 115      FR_PASS         0x000002   /* allow packet to pass */
 116      FR_OUTQUE       0x000004   /* outgoing packets */
 117      FR_INQUE        0x000008   /* ingoing packets */
 118      FR_LOG          0x000010   /* Log */
 119      FR_LOGB         0x000011   /* Log-fail */
 120      FR_LOGP         0x000012   /* Log-pass */
 121      FR_LOGBODY      0x000020   /* log the body of packets too */
 122      FR_LOGFIRST     0x000040   /* log only the first packet to match */
 123      FR_RETRST       0x000080   /* return a TCP RST packet if blocked */
 124      FR_RETICMP      0x000100   /* return an ICMP packet if blocked */
 125      FR_FAKEICMP     0x00180    /* Return ICMP unreachable with fake source */
 126      FR_NOMATCH      0x000200   /* No match occurred */
 127      FR_ACCOUNT      0x000400   /* count packet bytes */
 128      FR_KEEPFRAG     0x000800   /* keep fragment information */
 129      FR_KEEPSTATE    0x001000   /* keep `connection' state information */
 130      FR_INACTIVE     0x002000
 131      FR_QUICK        0x004000   /* match & stop processing list */
 132      FR_FASTROUTE    0x008000   /* bypass normal routing */
 133      FR_CALLNOW      0x010000   /* call another function (fr_func) if matches */
 134      FR_DUP          0x020000   /* duplicate the packet */
 135      FR_LOGORBLOCK   0x040000   /* block the packet if it can't be logged */
 136      FR_NOTSRCIP     0x080000   /* not the src IP# */
 137      FR_NOTDSTIP     0x100000   /* not the dst IP# */
 138      FR_AUTH         0x200000   /* use authentication */
 139      FR_PREAUTH      0x400000   /* require preauthentication */
 140
 141 .fi
 142 .PP
 143 Values for fr_scomp and fr_dcomp (source and destination port value
 144 comparisons) :
 145 .LP
 146 .nf
 147         FR_NONE         0
 148         FR_EQUAL        1
 149         FR_NEQUAL       2
 150         FR_LESST        3
 151         FR_GREATERT     4
 152         FR_LESSTE       5
 153         FR_GREATERTE    6
 154         FR_OUTRANGE     7
 155         FR_INRANGE      8
 156 .fi
 157 .PP
 158 The third ioctl, SIOCIPFFL, flushes either the input filter list, the
 159 output filter list or both and it returns the number of filters removed
 160 from the list(s).  The values which it will take and recognise are FR_INQUE
 161 and FR_OUTQUE (see above).  This ioctl is also implemented for
 162 \fB/dev/ipstate\fP and will flush all state tables entries if passed 0
 163 or just all those which are not established if passed 1.
 164
 165 .IP "\fBGeneral Logging Flags\fP" 0
 166 There are two flags which can be set to log packets independently of the
 167 rules used.  These allow for packets which are either passed or blocked
 168 to be logged.  To set (and clear)/get these flags, two ioctls are
 169 provided:
 170 .IP SIOCSETFF 16
 171 Takes an unsigned integer as the parameter.  The flags are then set to
 172 those provided (clearing/setting all in one).
 173 .nf
 174
 175         FF_LOGPASS      0x10000000
 176         FF_LOGBLOCK     0x20000000
 177         FF_LOGNOMATCH   0x40000000
 178         FF_BLOCKNONIP   0x80000000    /* Solaris 2.x only */
 179 .fi
 180 .IP SIOCGETFF 16
 181 Takes a pointer to an unsigned integer as the parameter.  A copy of the
 182 flags currently in used is copied to user space.
 183 .IP "\fBFilter statistics\fP" 0
 184 Statistics on the various operations performed by this package on packets
 185 is kept inside the kernel.  These statistics apply to packets traversing
 186 through the kernel.  To retrieve this structure, use this ioctl:
 187 .nf
 188
 189         ioctl(fd, SIOCGETFS, struct friostat *)
 190
 191 struct  friostat        {
 192         struct  filterstats     f_st[2];
 193         struct  frentry         *f_fin[2];
 194         struct  frentry         *f_fout[2];
 195         struct  frentry         *f_acctin[2];
 196         struct  frentry         *f_acctout[2];
 197         struct  frentry         *f_auth;
 198         u_long  f_froute[2];
 199         int     f_active;       /* 1 or 0 - active rule set */
 200         int     f_defpass;      /* default pass - from fr_pass */
 201         int     f_running;      /* 1 if running, else 0 */
 202         int     f_logging;      /* 1 if enabled, else 0 */
 203         char    f_version[32];  /* version string */
 204 };
 205
 206 struct  filterstats {
 207         u_long  fr_pass;        /* packets allowed */
 208         u_long  fr_block;       /* packets denied */
 209         u_long  fr_nom;         /* packets which don't match any rule */
 210         u_long  fr_ppkl;        /* packets allowed and logged */
 211         u_long  fr_bpkl;        /* packets denied and logged */
 212         u_long  fr_npkl;        /* packets unmatched and logged */
 213         u_long  fr_pkl;         /* packets logged */
 214         u_long  fr_skip;        /* packets to be logged but buffer full */
 215         u_long  fr_ret;         /* packets for which a return is sent */
 216         u_long  fr_acct;        /* packets for which counting was performed */
 217         u_long  fr_bnfr;        /* bad attempts to allocate fragment state */
 218         u_long  fr_nfr;         /* new fragment state kept */
 219         u_long  fr_cfr;         /* add new fragment state but complete pkt */
 220         u_long  fr_bads;        /* bad attempts to allocate packet state */
 221         u_long  fr_ads;         /* new packet state kept */
 222         u_long  fr_chit;        /* cached hit */
 223         u_long  fr_pull[2];     /* good and bad pullup attempts */
 224 #if SOLARIS
 225         u_long  fr_notdata;     /* PROTO/PCPROTO that have no data */
 226         u_long  fr_nodata;      /* mblks that have no data */
 227         u_long  fr_bad;         /* bad IP packets to the filter */
 228         u_long  fr_notip;       /* packets passed through no on ip queue */
 229         u_long  fr_drop;        /* packets dropped - no info for them! */
 230 #endif
 231 };
 232 .fi
 233 If we wanted to retrieve all the statistics and reset the counters back to
 234 0, then the ioctl() call would be made to SIOCFRZST rather than SIOCGETFS.
 235 In addition to the statistics above, each rule keeps a hit count, counting
 236 both number of packets and bytes.  To reset these counters for a rule,
 237 load the various rule information into a frentry structure and call
 238 SIOCZRLST.
 239 .IP "Swapping Active lists" 0
 240 IP Filter supports two lists of rules for filtering and accounting: an
 241 active list and an inactive list.  This allows for large scale rule base
 242 changes to be put in place atomically with otherwise minimal interruption.
 243 Which of the two is active can be changed using the SIOCSWAPA ioctl.  It
 244 is important to note that no passed argument is recognised and that the
 245 value returned is that of the list which is now inactive.
 246 .br
 247 .SH FILES
 248 /dev/ipauth
 249 .br
 250 /dev/ipl
 251 .br
 252 /dev/ipnat
 253 .br
 254 /dev/ipstate
 255 .SH SEE ALSO
 256 ipl(4), ipnat(4), ipf(5), ipf(8), ipfstat(8)