ipfw

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       ipfw - IP firewall and accounting


SYNOPSIS

       #include <sys/types.h>
       #include <sys/socket.h>
       #include <netinet/in.h>
       #include <linux/ip.h>
       #include <linux/tcp.h>
       #include <linux/udp.h>
       #include <linux/icmp.h>
       #include <linux/if.h>
       #include <linux/ip_fw.h>

       int  setsockopt (int socket, IPPROTO_IP, int command, void
       *data, int length)


DESCRIPTION

       The IP firewall and accounting  facilities  in  the  Linux
       kernel  provide  a mechanism for accounting IP packets and
       for building firewalls based  on  packet-level  filtering.
       The administration of these functions is maintained in the
       kernel as 4 separate lists, each containing zero  or  more
       rules.   Each  rule  contains  specific  information about
       source and destination addresses, protocols, port numbers,
       and  some other characteristics.  A packet will match with
       a rule when the characteristics of the rule match those of
       the IP packet.  The three categories of rules are:

       Accounting
              The  accounting  rules  are used for all IP packets
              that are sent or received via one of the local net-
              work  interfaces.   Every  packet  will be compared
              with all rules in this list, and every  match  will
              cause  an increment of the packet and byte counters
              associated with that rule.

       Input Firewall
              These rules regulate the acceptance of incoming  IP
              packets.   All  packets  coming  in  via one of the
              local network interfaces are  checked  against  the
              input  firewall rules.  The first rule that matches
              with a packet determines the policy to use and will
              also cause the rule's packet en byte counters being
              adapted.  When  no  matching  rule  is  found,  the
              default policy for the input firewall is used.

       Output Firewall
              These  rules  define the permissions for sending IP
              packets.  All packets that are ready to be be  sent
              via one of the local network interfaces are checked
              against the output firewall rules.  The first  rule
              that matches with a packet determines the policy to
              use and will also cause the rule's packet and  byte
              counters  being  adapted.  When no matching rule is
              found, the default policy for the  output  firewall
              is used.

       Forwarding firewall
              These  rules  define the permissions for forwarding
              IP packets.  All packets sent by a remote host hav-
              ing  another remote host as destination are checked
              against the forwarding firewall rules.   The  first
              rule that matches with a packet determines the pol-
              icy to use and will also cause  the  rule's  packet
              and  byte counters being adapted.  When no matching
              rule is found, the default policy for the  forward-
              ing firewall is used.

       Each of the firewall rules (not the accounting rules) con-
       tains a policy, which specifies  what  action  has  to  be
       taken  when  a  packet matches with the rule.  There are 4
       different policies possible: accept (let the  packet  pass
       the  firewall in a normal way), masquerade (let the packet
       pass the firewall using masquerading; this policy is  only
       valid  for  forwarding  rules),  reject (do not accept the
       packet and send an ICMP host unreachable message  back  to
       the  sender  as notification), and deny (ignore the packet
       without sending any notification).  For  all  3  types  of
       firewalls  there  also  exists  a  default  policy,  which
       applies to all packets for which none of the rules  match.

       The  forwarding  rules  also define whether or not packets
       should be masqueraded when being forwarded.  In that case,
       the  sender  address  in the IP packets is replaced by the
       address of the local host and the source port in  the  TCP
       or  UDP  header is replaced by a locally generated (tempo-
       rary) port number before being  forwarded.   Because  this
       administration  is  kept  in  the  kernel, reverse packets
       (sent to the temporary port number on the local host)  are
       recognized  automatically.   The  destination  address and
       port number of these packets will be replaced by the orig-
       inal  address/number  that was saved when the first packet
       was masqueraded.

       This paragraph describes the way a packet goes through the
       firewall  and  accounting rules.  Packets received via one
       of the local network interface  will  pass  the  following
       sets of rules:
              accounting (incoming device)
              input firewall (incoming device)
       Here,  the  device  (interface  address) that is used when
       trying to match a rule with an IP packet is listed between
       brackets.   When  a packet has to be forwarded to a remote
       host, it will also pass:
              forwarding firewall (incoming device)
       After this step, a packet will optionally be  masqueraded.
       Responses  to  masqueraded  packets  will  never  pass the
       forwarding firewall (but they will pass both the input and
       output  firewalls).  All packets sent via one of the local
       network interfaces, either locally generated or being for-
       warded, will pass:
              output firewall (outgoing device)
              accounting (outgoing device)
       Note  that  masqueraded packets will pass the output fire-
       wall and accounting rules  with  the  new  packet  headers
       (after  passing the input anf forwarding firewall with the
       original headers).  Also, responses to masqueraded packets
       will  have  different  headers  when passing the input and
       output firewall rules.

       The firewall and accounting administration can be  changed
       via  calls  to  setsockopt(2).   The existing rules can be
       inspected by looking  at  three  files  in  the  /proc/net
       directory:  ip_acct,  ip_input, ip_output, and ip_forward.
       The current administration related to masqueraded sessions
       can  be found in the file ip_masquerade in the same direc-
       tory (note that the rules specifying which sessions should
       be masqueraded are in ip_forward).


COMMANDS

       Commands  for  changing  the lists of rules or the default
       policies have to be given as options to the  setsockopt(2)
       system  call,  working  on a raw IP socket.  Most commands
       require some additional data to be passed.  A  pointer  to
       this  data and the length of the data are passed as option
       value and option length arguments to setsockopt.  The fol-
       lowing commands are available:

       IP_ACCT_APPEND
       IP_FW_APPEND_IN
       IP_FW_APPEND_OUT
       IP_FW_APPEND_FWD
              Add  a  rule  to  one of the accounting or firewall
              lists.  Depending on the command, the rule is added
              to  the list for accounting, input firewall, output
              firewall,  or  forwarding  firewalls,  repectively.
              The  new  rule  rule  is appended to the end of the
              list.  The data passed  with  this  command  is  an
              ip_fw  structure,  defining the contents of the new
              rule.

       IP_ACCT_INSERT
       IP_FW_INSERT_IN
       IP_FW_INSERT_OUT
       IP_FW_INSERT_FWD
              These commands are equal to  the  append  commands,
              except  that the new rule is inserted at the begin-
              ning of the list.

       IP_ACCT_DELETE
       IP_FW_DELETE_IN
       IP_FW_DELETE_OUT
       IP_FW_DELETE_FWD
              Remove a rule from one of the accounting  or  fire-
              wall  lists.   Depending  on  the command, the rule
              will be removed from the list for accounting, input
              firewall,  output firewall, or forwarding firewall,
              repectively.  The data passed with this command  is
              an  ip_fw  structure,  defining the contents of the
              rule to be removed.  The first rule  conforming  to
              the given definition is removed from the list.

       IP_ACCT_ZERO
       IP_FW_ZERO_IN
       IP_FW_ZERO_OUT
       IP_FW_ZERO_FWD
              Reset  the packet and byte counters in all rules of
              the list for  accounting,  input  firewall,  output
              firewall, or forwarding firewall, repectively.  For
              unknown reasons, a (dummy) integer has to be passed
              as  data  with this command.  See also the descrip-
              tion of the /proc/net files for a way to atomically
              list and reset the counters.

       IP_ACCT_FLUSH
       IP_FW_FLUSH_IN
       IP_FW_FLUSH_OUT
       IP_FW_FLUSH_FWD
              Remove  all  rules  from  the  list for accounting,
              input  firewall,  output  firewall,  or  forwarding
              firewall,  repectively.   For  unknown  reasons,  a
              (dummy) integer has to be passed as data with  this
              command.

       IP_FW_POLICY_IN
       IP_FW_POLICY_OUT
       IP_FW_POLICY_FWD
              Change  the  default policy for the input firewall,
              output firewall, or the forwarding  firewall.   The
              new  policy is passed as integer data with the fol-
              lowing possible values:  IP_FW_F_ACCEPT  (accept  a
              packet),  IP_FW_F_ACCEPT | IP_FW_F_MASQ (accept the
              packet   and   additionally   use    masquerading),
              IP_FW_F_ICMRPL  (reject a packet by sending an ICMP
              host unreachable message back to the sender), or  0
              (deny  a packet, without any further notification).
              The policy is used when none of the available fire-
              wall  rules  in  the  appropriate  list matches the
              packet being screened.

       IP_FW_CHECK_IN
       IP_FW_CHECK_OUT
       IP_FW_CHECK_FWD
              Check whether a packet would be accepted  (with  or
              without  masquerading),  denied, or rejected by the
              input firewall (IP_FW_CHECK_IN), the  output  fire-
              wall  (IP_FW_CHECK_OUT), or the forwarding firewall
              (IP_FW_CHECK_FWD).  The data passed with this  com-
              mand  is an ip_fwpkt structure, defining the packet
              headers and the interface address.


STRUCTURES

       The ip_fw structure contains the following relevant fields
       to be filled in for adding or deleting a rule:

       struct in_addr fw_src, fw_dst
              Source and destination IP addresses.

       struct in_addr fw_smsk, fw_dmsk
              Masks  for the source and destination IP addresses.
              Note that a mask of 0.0.0.0 will result in a  match
              for all hosts.

       struct in_addr fw_via
              IP  address  of the interface via which a packet is
              received by the system or is going to  be  sent  by
              the  system.   The  address  0.0.0.0  has a special
              meaning:  it  will   match   with   all   interface
              addresses.

       char fw_vianame[IFNAMSIZ]
              Name  of  the  interface  via  which  a  packet  is
              received by the system or is going to  be  sent  by
              the  system.   The empty string has a special mean-
              ing: it will match with all device names.

       unsigned short fw_flg
              Flags for this rule.  The flags for  the  different
              options can be bitwise or'ed with each other.

              The  protocol  (mandatory).   Possible  values  are
              IP_FW_F_TCP (TCP), IP_FW_F_UDP (UDP),  IP_FW_F_ICMP
              (ICMP),   or   IP_FW_F_ALL  (all  protocols,  which
              defines a universal firewall/accounting rule).

              The policy to be used when a  packet  matches  with
              this  rule.   This  policy  can  be  IP_FW_F_ACCEPT
              (accept the packet), IP_FW_F_ACCEPT |  IP_FW_F_MASQ
              (accept  the packet and additionally use masquerad-
              ing), or IP_FW_F_ICMRPL (reject the packet by send-
              ing  an  ICMP  host unreachable message back to the
              sender).  When none of these  flags  is  specified,
              the  packet  is  denied  without  any notification.
              Note that  the  policy  is  ignored  in  accounting
              rules.

              There are some other options that can be specified:
              IP_FW_F_BIDIR (bidirectional rule, matching in both
              directions),  IP_FW_F_TCPACK (only matches when the
              ACK bit is set in the TCP  header),  IP_FW_F_TCPSYN
              (only  matches  when the SYN bit is set and the ACK
              bit is cleared in the  TCP  header),  IP_FW_F_SRNG,
              and  IP_FW_F_DRNG  (see  below for a description of
              these flags).  The option IP_FW_F_PRN can  be  used
              to  list  some  information about a matching packet
              via printk().  This option will only  be  effective
              when  the  kernel  is compiled with CONFIG_IP_FIRE-
              WALL_VERBOSE defined.

       unsigned short fw_nsp, fw_ndp, fw_pts[IP_FW_MAX_PORTS]
              These fields specify the number  of  source  ports,
              the  number  of destination ports, and the array in
              which these ports are  stored,  respectively.   The
              array  starts  with the source ports, directly fol-
              lowed by the destination ports.  The  total  number
              of  ports  is limited to IP_FW_MAX_PORTS (currently
              10).  Both the list of source and destination ports
              may  contain  at most one range.  In that case, the
              first two port numbers of the list are taken as the
              minimum  and  maximum  values of a range.  For ICMP
              packets, source ports are interpreted as ICMP types
              and  destination  ports  are  ignored.  Because the
              second and further fragments of a TCP or UDP packet
              do  not  contain port numbers, these IP packets are
              treated as if both port numbers are equal to  zero.
              The  flags  IP_FW_F_SRNG  and  IP_FW_F_DRNG  in the
              fw_flg field specify whether or not a source and/or
              destination range is specified.

       unsigned char fw_tosand, fw_tosxor
              These  8-bit  masks define how the TOS field in the
              IP header  should  be  changed  when  a  packet  is
              accepted  (with  or  without  masquerading)  by the
              firewall rule.  The  TOS  field  is  first  bitwise
              and'ed  with  fw_tosand and the result of this will
              be bitwise xor'ed with fw_tosxor.  The  fields  are
              ignored  in  accounting  rules or in firewall rules
              for rejecting or denying a packet.

       The ip_fwpkt structure, used when checking a packet,  con-
       tains the following fields:

       struct iphdr fwp_iph
              The  IP  header.  See  <linux/ip.h>  for a detailed
              description of the iphdr structure.

       struct tcphdr fwp_protoh.fwp_tcph
       struct udphdr fwp_protoh.fwp_udph
       struct icmphdr fwp_protoh.fwp_icmph
              The TCP, UDP, or ICMP header, combined in  a  union
              named      fwp_protoh.       See     <linux/tcp.h>,
              <linux/udp.h>, or  <linux/icmp.h>  for  a  detailed
              description of the respective structures.

       struct in_addr fwp_via
              The  interface address via which the packet is pre-
              tended to be received or sent.


RETURN VALUE

       On success, zero is returned.  On error,  -1  is  returned
       and  errno  is set appropriately.  See setsockopt(2) for a
       list of possible error values.  When one of  the  2  check
       packet  commands is used, zero is returned when the packet
       would be accepted (without masquerading).   Otherwise,  -1
       is  returned  and errno is set to ECONNRESET (packet would
       be accepted using massquerading), ETIMEDOUT (packet  would
       be denied), or ECONNREFUSED (packet would be rejected).


LISTING RULES

       In the directory /proc/net there are 4 entries to list the
       currently  defined  rules  for  each  of  the  categories:
       ip_acct  (for IP accounting rules), ip_input (for IP input
       firewall rules), ip_output (for IP output firewall rules),
       and  ip_forward (for IP forwarding firewall rules).  Read-
       ing these files results in a header line and one line  for
       each  defined  rule.   For  all  3  types of firewall, the
       header line includes at the end a  decimal  representation
       of    the    corresponding    default   policy   (one   of
       IP_FW_F_ACCEPT,     IP_FW_F_ACCEPT     |     IP_FW_F_MASQ,
       IP_FW_F_ICMPRPL, or 0).

       Each  following  line  lists the contents of a rule in the
       following order:  source  address  and  mask,  destination
       address  and  mask,  interface  address,  flags, number of
       source and destination ports, packet  and  byte  counters,
       the  list  of  ports,  a TOS and-mask, and a TOS xor-mask.
       The IP addresses and masks are  listed  as  8  hexadecimal
       digits,  the  TOS masks are listed as 2 hexadecimal digits
       preceeded by the letter A  and  X,  repectively,  and  the
       other  values are represented in decimal format.  Individ-
       ual fields are seperated by white spave,  by  a  '/'  (the
       address  and  the  corresponding  mask),  or  by "->" (the
       sources and destination address/mask pairs).

       The files may also be opened in read/write mode (only root
       is allowed to do this).  In that case, the packet and byte
       counters in all the rules of that category will  be  reset
       to zero after listing their current values.

       The   file  /proc/net/ip_masquerade  contains  the  kernel
       administration related to masquerading.   After  a  header
       line,  each masqueraded session is described on a separate
       line with the following entries, separated by white  space
       or  by  ':' (the address/port number pairs): protocol name
       ("TCP" or "UDP"), source IP address and port number,  des-
       tination  IP address and port number, the new port number,
       the initial sequence number for adding a delta value,  the
       delta value, the previous delta value, and the expire time
       in jiffies (1/HZ second).  All addresses and numeric  val-
       ues  are in hexadecimal format, except the last 3 entries,
       being represented in decimal format.


FILES

       /proc/net/ip_acct
       /proc/net/ip_input
       /proc/net/ip_output
       /proc/net/ip_forward
       /proc/net/ip_masquerade


SEE ALSO

       setsockopt(2), socket(2), ipfwadm(8)
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.