Provided by: ipfwadm_2.3.0-4_i386 bug

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
       mechanisms  for  accounting IP packets, for building firewalls based on
       packet-level filtering, for building firewalls using transparent  proxy
       servers (by redirecting packets to local sockets), and for masquerading
       forwarded packets.  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 4 categories of rules are:

       Accounting
              The  accounting  rules are used for all IP packets that are sent
              or received via one of  the  local  network  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 having another remote host  as
              destination  are  checked against the forwarding 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 forwarding firewall is used.

       Each  of  the  firewall  rules  (not  the  accounting rules) contains a
       policy, which specifies what action has  to  be  taken  when  a  packet
       matches with the rule.  There are 3 different policies possible: accept
       (let the packet pass the firewall), 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 input rules also define whether or not packets should be redirected
       to a local socket after being accepted by the input firewall.  In  this
       case,  the  packet  will be received by a local process, even if it was
       sent to another host and/or another port number.   This  function  only
       applies to TCP or UDP packets.

       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
       (temporary)   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  original address and port number that was saved when
       the first packet was masqueraded.  This function only applies to TCP or
       UDP packets.

       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 (network interface) that is used when trying to match
       a rule with an IP packet is listed between brackets.  After this  step,
       a  packet  will  optionally  be  redirected  to a local socket.  When a
       packet has to be forwarded to a remote host, it will also pass the next
       set of rules:
              forwarding firewall (outgoing 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
       forwarded, will pass the following sets of rules:
              output firewall (outgoing device)
              accounting (outgoing device)
       Note  that  masqueraded  packets  will  pass  the  output  firewall and
       accounting rules with the new packet headers (after passing  the  input
       and 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  4
       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 directory (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
       following 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
              firewall,  respectively.   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 beginning 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  firewall  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.  Note that a (dummy) integer  has  to  be
              passed  as  data with this command.  See also the description 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.  Note that
              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   following   possible  values:
              IP_FW_F_ACCEPT (accept  a  packet),  IP_FW_F_ICMPRPL  (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 firewall rules in
              the appropriate list matches the packet being screened.  For the
              forwarding firewall, the given policy may also be IP_FW_F_ACCEPT
              | IP_FW_F_MASQ ®(accept a packet to be forwarded, but  also  use
              masquerading for TCP and UDP packets).

       IP_FW_MASQ_TIMEOUTS
              Set  the  timeout values used for masquerading.  The data passed
              with this command is a structure containing  3  fields  of  type
              int,  representing  the timeout values (in jiffies, 1/HZ second)
              for TCP sessions, TCP sessions after receiving a FIN packet, and
              UDP  packets,  repectively.   A  timeout  value 0 means that the
              current timeout value of the corresponding entry is preserved.

       IP_FW_CHECK_IN
       IP_FW_CHECK_OUT
       IP_FW_CHECK_FWD
              Check whether a packet would be accepted, denied, or rejected by
              the   input   firewall  (IP_FW_CHECK_IN),  the  output  firewall
              (IP_FW_CHECK_OUT), or the forwarding firewall (IP_FW_CHECK_FWD).
              The  data  passed  with  this  command 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 meaning: 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_ICMPRPL  (reject  the  packet  by  sending  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.

              Redirection  and  masquerading  are  also  defined with 2 flags.
              IP_FW_F_REDIR redirects an accepted packet  to  a  local  socket
              (specified  by  a  port number, see below).  It is only valid in
              input firewall rules and can only be used  when  the  kernel  is
              compiled with CONFIG_IP_TRANSPARENT_PROXY defined.  IP_FW_F_MASQ
              masquerades an accepted packet.  It is only valid in  forwarding
              firewall  rules and can only be used when the kernel is compiled
              with CONFIG_IP_MASQUERADE defined.

              The  other  options  are:  IP_FW_F_BIDIR  (bidirectional   rule,
              matching  in both directions), IP_FW_F_TCPACK (only matches with
              TCP packets when the ACK bit is set in the TCP  header,  ignored
              with  other  protocols),  IP_FW_F_TCPSYN  (only matches with TCP
              packets when the SYN bit is set and the ACK bit  is  cleared  in
              the  TCP  header,  ignored with other protocols), IP_FW_F_ACCTIN
              and IP_FW_F_ACCTOUT (only match incoming  or  outgoing  packets,
              respectively;  these  options  only  have  effect  in accounting
              rules),  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_FIREWALL_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  followed  by  the  destination  ports.   If the option
              IP_FW_F_REDIR  is  used,  these  ports  are  followed   by   the
              redirection   port.    If   this  redirection  port  is  0,  the
              destination port of a packet will be  used  as  the  redirection
              port.   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 2 port
              numbers of the list are taken as the minimum and maximum  values
              of the 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 in accounting
              rules  as if both port numbers are equal to 65535.  For the same
              reason, all second and further fragments of an ICMP  packet  are
              treated  in accounting rules as if the ICMP message type is 255.
              Furthermore, all second and further fragments of  TCP,  UDP,  or
              ICMP  packets  will  be accepted by any of the 3 firewalls.  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  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,  contains  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  pretended  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  redirection  or
       masquerading.    Otherwise,   -1  is  returned  and  errno  is  set  to
       ECONNABORTED (packet would be accepted using  redirection),  ECONNRESET
       (packet  would be accepted using masquerading), 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).  Reading 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_ICMPRPL, and 0; the
       policy  of  the  forwarding  firewall  may  also  be  IP_FW_F_ACCEPT  |
       IP_FW_F_MASQ).

       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 preceded by the letter  A  and
       X, repectively, and the other values are represented in decimal format.
       Individual fields are separated by white space, by a ’/’  (the  address
       and  the  corresponding  mask),  or by "->" (the source 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, destination 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  values  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)

                                 June 17, 1996                         IPFW(4)