
What is IPACL ?
---------------

    IPACL stands for `IP access list'. It has been designed
    to filter incoming and outgoing TCP/UDP packets in
    the SVR4/386 kernel with Lachamnn Streams TCP.
    Depending on source/destination addresses and port numbers
    packets can be passed through or dropped.
    We run IPACL on Interactive SVR4 and on SINIX-L
    (on MX300 (Intel)). I believe, that it should be easy to
    port IPACL to other SVR4 bases systems, e.g. the new Solaris.

Architecture
------------

    Due to the modularity provided by AT&T's streams
    concept this module could be written without
    modifying any of the TCP/IP kernel sources
    (You just have to install the driver and relink the kernel).
    The access list module will be autopushed on /dev/ip
    whenever this device is opened.
    An IOCTL interface in the driver provides a facility
    to download a filter program into the kernel module
    (The utility command /usr/sbin/ipacl reads and compiles
    a configuration file and downloads the resulting filter
    program into the kernel).
    All TCP and UDP packets that are sent/recived (via IP)
    have to pass the access list module.
    Unfortunately there is no way to filter packtes, when
    your host acts as router (IPFORWARDING != 0), because
    IP will not pass packets, that are to be forwarded, up
    to TCP or UDP.
    ICMP packetes cannot be filtered by a user supplied
    filter program, but are handled in the following way:
    REDIRECT packetes will be dropped and all other ICMP
    packets will be passed through.
    For my application, that did not worry, because I only wanted
    to control access to the host, where IPACL is installed.

    +----------+----------+----------+
    | TCP      | UDP      | ICMP     |         
    +----------+----------+----------+
    | IPACC                          |
    +--------------------------------+
    | IP                             |
    +--------------------------------+
    | Network interfaces ...         |
    +----+-----+-----+---------------+
	 |     |     |    ...
	 |     |     |
	LAN   SLIP   etc. ...

Source files
------------

    COPYING		GNU general public license

    Driver.c		The streams module, that sits between
			/dev/tcp, /dev/udp and /dev/ip

    Makefile		The makefile

    Master		Kernel configuration files for the
    System		ipacc-Driver - written according to the
			SVR4 conventions

    README		The file you are currently reading

    S69ipacl		Startup script, called at boot time

    gram.doc		Brief overview of the configuration
			file grammar. To get an exact definition
			of the grammar look at the yacc/lex
			sources in ipacl.[yl]

    ipacl.cfg		The default configuration file -
			does not filter any packets

    ipacl.l		Lexical analyzer for the
			configuration file - part of the
			utility program /usr/sbin/ipacl

    ipacl.y		Parser for the configuration file -
			part of the utility program /usr/sbin/ipacl

    matcher.c		Interpreter for the filter
			program (in the kernel)

    matcher.h		Header file for matcher.c

    pkg			This directory contains all the
			stuff necessary to build a SVR4 package

    sample.cfg		Sample configuration file, this file will
			give you an overview how to write a
			configuration file for IPACL.

Compiling and installing IPACL
------------------------------

    - First look at the Makefile, maybe you have to
      change something (e.g. you want to use another C compiler).

    - Type `make' to compile the sources.

    - Type `make package' to build the SVR4 package.
      The package will be built in the default package spool
      directory (normally /var/spool/pkg).
      (You need write access to the package spool
      directory - either do it as root or do a chmod on
      the directory).

    - Type `pkgadd ipacl' to install the package that has
      been built in the previous step.
      (Must be run as root).

    - Relink your kernel (type `/etc/conf/bin/idbuild').
      (pkgadd should do this - but it is not yet implemented
      in the install scripts).
      (Must be run as root).

    - Edit the IPACL configuration file in /var/ipacl/ipacl.cfg.
      (Must be run as root).

    - Reboot your system (type `init 6').
      (Must be run as root).

Components
----------

    The installed binaries of IPACL consist of the following
    components:

    - /etc/conf/...

	This is the standard place, where SVR4 drivers, master and
	system files reside. The driver name of the IPACL streams
	module is `ipacc'. The file names, where to find the
	diriver componets in the /etc/conf subtree follow the
	SVR4 conventions  (/etc/conf/pack.d/ipacc/*,
	/etc/conf/sdevice.d/ipacc, ...).

    - /etc/ap/chan.ap

	This is a configuration file for the autopush command.
	It is invoked the following line in /etc/inittab.

	    ap::sysinit:/sbin/autopush -f /etc/ap/chan.ap

	The postinstall script of IPACL edits this file and
	adds some entries to autopush `ipacc' onto /dev/ip.
	E.g. postinstall adds the following lines to
	/etc/ap/chan.ap (note that 24 is the major number of /dev/ip).

	    # ipacc +++ do not edit this line
	    # push ipacc over /dev/dip
	    24	0	255	ipacc
	    # ipacc --- do not edit this line

	When the IPACL package is removed, the lines given above
	will be deleted from this file.

	When you have another (e.g. vendor specific) version
	of SVR4, it may be possible, that you will have to modify
	something to setup autopush correctly.

    - /usr/sbin/ipacl

	This command parses the configuration file, produces
	a binary filter program and loads this program down
	into the ipacc driver.

	The command takes no arguments. The configuration
	file has to be supplied on stdin, error messages
	will be printed to stderr and on stdout there will be
	printed an assembler listing of the generated filter program.

    - /var/ipacl/ipacl.cfg

	IPACL configuration file, that will be downloaded into
	the kernel at boot time.

    - /etc/rc2.d/S69ipacl

	This script will be executed at system startup time and
	load /var/ipacl/ipacl.cfg into the kernel.

Configuration file
------------------

    Definitions:

	Address: An address in the IPACL config file is a tuple
		 consisting of an internet address and a mask.
		 Internet addresses can be specified in dotted
		 notation or as host names, that will be resolved
		 to internet adresses with gethostbyname().
		 Masks can be specified in hex.
		 You can also use a network specification (either
		 in dotted notation or as network name from
		 /etc/networks) to specify both parts
		 of an IPACL address at once.

	Port:	 A port in the IPACL config file is a tuple
		 consisting of the protocol (tcp/udp) and
		 a 16 bit port number.

	Sets:	 IPACL allow you to define sets of addresses or
		 ports.

    The configuration file consists of

	- declarations and
	- statements

    Declarations:

	You can use a declaration to assign a symbolic name to
	an address, a port, an address set or a port set.

    Statements:

	The statements describe, how packets are to be filtered.
	They are a kind of assembly notation of the filter program.

	accept				Accept the current packet
					and pass it through. No further
					statements will be executed for
					this packet.

	deny				Do not accep (drop) the current
					packet. No further statements
					will be executed for this packet.

	<cond> -> accept		If <cond> is true, then accept
					the current packet.

	<cond> -> deny			If <cond> is true, then drop
					the current packet.

	<cond> -> <label>		If <cond> is true, then
					goto <label>.

	The condition <cond> can test, wheter

	    - the src/dst address of the packet matches a given
	      address.
	      The comparison is done in the following way:
	      (address-from-packet & address.mask) == address.address

	    - the src/dst address of the packet does not match a given
	      address.

	    - the src/dst address of the packet is (or is not) a member
	      of a given set of addresses.

	    - the src/dst port of the packet is (or is not) a member
	      of a given set of ports.

	    - the src/dst port of the packet is ==, !=, >, <, >=, <=
	      a given port.
	      Note, that the condition `src >= port 1024/tcp' means
	      protocol-in-packet == tcp && src-port-in-packet >= 1024.
	      Therefore `src < port 1024/tcp' is *not* the opposite
	      of the above condition ! This applies to the operators
	      <, >, <= and >=.

    The file gram.doc gives a brief description of the grammar.
    A detailed description of the grammar you will find in the
    lex/yacc sources ipacl.[yl] itself.
    Example.cfg is a configuration file example.

Bugs
----

    - Sorry, but there exists no documentation at all.

    - The syntax for the configuration file is a little bit '&"%$'& -
      it is a kind of assembler language to describe the filter
      program and does not provide high level features.

    - Some parts of the program are really coded *dirty*, e.g.
      fixed size arrays are used to hold some data structures and
      there are no overflow checks, ...
      (That's not the normal way I do programming, but IPACL
      was a quick and dirty development and I never thouhgt, that
      I would release ist).

    - IPACL silently drops packets, that are not allowed (and prints
      a kernel message to the console). Perhaps an ICMP host unreach
      message should be sent back to the sender of the packet,
      but sometimes this is not desirable.

    - Forwarded packetes (IPFORWARDING != 0) cannot be filtered.

Comments, bug reports, ...
--------------------------

    If you have any comments, find bugs, have some questrions, etc.,
    then send mail to

	fuer@siemens.co.at

    When you make some improvements to IPACL, that might be
    interresting for me or anyone else, I would be appreciated
    to get a copy of the modified version too.

