   .
   .
   .                                                            FILTER.TXT
   .                                  F/X Packet Filter Plugin Release 1.2
   .                                                          June 1, 1999
   .                          
   .
   .
   .
   .
   .
   .       ____   _    ____ _  _______ _____
   .      |  _ \ / \  / ___| |/ / ____|_   _|
   .      | |_) / _ \| |   | ' /|  _|   | |
   .      |  __/ ___ \ |___| . \| |___  | |
   .      |_| /_/   \_\____|_|\_\_____| |_|
   .
   .
   .       _____ ___ _   _____ _____ ____
   .      |  ___|_ _| | |_   _| ____|  _ \
   .      | |_   | || |   | | |  _| | |_) |
   .      |  _|  | || |___| | | |___|  _ <
   .      |_|   |___|_____|_| |_____|_| \_\
   .
   .
   .
   .
   .
   .
   .                                                    F/X Communications
   .                                                       DK-4300 Holbaek
   .                                                               Denmark
   .                                                 E-mail: support@fx.dk
   .                                                      http://www.fx.dk
   .
   .
   .
   .     Copyright (c) 1999, F/X Communications, All Rights Reserved.
   .
   .






==========================================================================
 C O N T E N T S
=======================================What's Where=======================



   o Description...............................................Simple
   o Installation................................................Easy
   o Features................................................Powerful
   o Setup Guidance...........................................General
   o Filter Attributes.......................................Specific
   o Errors.........................................check filters.err
   o Sample Filters................................To Get You Started
   o On The Fly updates...............................Utility program




==========================================================================
 D E S C R I P T I O N
=================================================Simple===================



   This guide includes all you need to get started with the F/X Packet
   Filter Plugin.

   Packet filtering allows TCP/IP packets to be selectively discarded as 
   they flow through the plugin.

   The Packet Filter Plugin binaries operate seamlessly with the following
   F/X Communications products:

      o InJoy Internet Dialer
      o InJoy Connect PPP Server 
      o InJoy Firewall
      o Tunnel/2

   Configuration is by way of simple ASCII files.




==========================================================================
 I N S T A L L A T I O N
=================================================Easy=====================



   There are two ways of getting the Packet Filter Plugin. Either as a 
   zipped archive ready for extraction into the directory of an above 
   mentioned F/X product, or as an integrated part of the host product.

   If you received the plugin as a zipped archive, then extract it with 
   InfoZip's UNZIP.EXE (or PKUNZIP.EXE using the -d option) to create 
   a new /FILTERS subdirectory to contain a sample configuration file.

   After installation the new binary file is demand-loaded by the host
   application when needed.

   Please consult the host-application documentation for possible extra
   installation guidelines.




==========================================================================
 F E A T U R E S
=================================================Powerful=================



   o The Packet Filter Plugin allows all attributes in a packet to be used 
     as a filtering trigger to selectively discard packets when presented.
     These packet attributes (and others listed in Guidance, below) can be 
     used to cause filtering:

     - Incoming traffic
     - Outgoing traffic
     - Source and Destination IP numbers (via netmask match)
     - Protocol match (TCP, UDP, ICMP)
     - Service match (FTP, WWW, TELNET, GOPHER, etc)
     - Bit-match (e.g. FIN or SYN bit of TCP)
     - Byte pattern match at specified offset
     - Byte pattern search


   o The Plugin supports compound Boolean filters for complex filtering
     with great flexibility.

   o There are three possible filter states: 

     - Always active
     - Active when product is off-line
     - Inactive (but easily activated)

   o The plugin reports errors to the file FILTERS.ERR in the home 
     directory of the host-application.

   o Filters are easily identified by linkable names.

   o Filters may have human readable comments attached.

   o Filter usage report at the touch of a key. This feature 
     depends on the host product.

   o Filtering plugs in as a separate loadable component, maintaining
     a modular design.

   o Supports new filters on the fly



==========================================================================
 S E T U P    G U I D A N C E
=================================================General==================



   o Configuration Files

     Filters are specified in one or more ASCII configuration files. Each
     configuration file can contain one or more filters, each identified 
     by a name and a set of attribute/parameter values.

     The plugin expects no more than 3 different configuration files. They
     are:

     - FILTERS.CNF

       This file is in the base directory of the host application. It 
       contains template values used in all user created filters. This 
       means that any attribute value you specify in your own filters will
       override the default values specified in this file.


     - .\FILTERS\FILTERS.CNF
   
       This file contains the actual user crafted filters. The file is 
       usually located in the FILTERS subdirectory of the host 
       application but may be setup differently, depending on the host's
       capabilities.  See the following Filter Attribute section for 
       syntax information.


     - FILTERS.DCT

       This file is in the base directory of the host application. It is a
       descriptor file that instructs the Filter Plugin about allowable
       attributes in the FILTER.CNF files.

       This file should NOT be modified. However, if you take the time to 
       become familiar with it, you will be able to use it as a quick
       reference when writing/modifying filters. Otherwise the following
       specific attributes be of interest.



==========================================================================
 F I L T E R   A T T R I B U T E S
=================================================Specific=================

-----------------    ---------------       ------------------------------      
ATTRIBUTE            POSSIBLE VALUES       DESCRIPTION
-----------------    ---------------       ------------------------------

Filter-Status        Passive               Tells when the filtering is 
                     Offline               active. 'Passive' means the
                     Always                filter is not active at all.

                                           'Offline' means the filter is 
                                           active when the host 
                                           application is not connected. 
                                           This could be (for example) 
                                           the InJoy dialer that is 
                                           offline, waiting for a packet 
                                           to trigger Dial On Demand.

                                           'Always' means that the filter 
                                           is active at all times,
                                           disregarding the connect state 
                                           of the host application.


-----------------    ---------------       ------------------------------
Filter-Scope         Incoming-Packets      Defines which packets that are 
                     Outgoing-Packets      exposed to the filter. Outgoing 
                                           or incoming.


-----------------    ---------------       ------------------------------
Filter-Root          Yes                   Only filters that have 
                     No                    'Filter-Root' set to 'Yes' are 
                                           loaded by the host application 
                                           and used.

                                           Filters not carrying this flag 
                                           are only used if specifically 
                                           addressed by other filters as 
                                           part of a compound filter.

-----------------    ---------------       ------------------------------
Source-IP            An IP address         The source IP address in the 
                                           packet is compared to the 
                                           value of this attribute. Please 
                                           keep the 'Source-Netmask' in 
                                           mind.

                                           Leave field empty if you do not 
                                           wish to filter using the 
                                           source IP address as criteria.


-----------------    ---------------       ------------------------------
Source-Netmask       Netmask               The 'Source-IP' address, 
                                           together with the 
                                           'Source-Netmask' denote a mask 
                                           with which  source IP addresses 
                                           from the IP packets are 
                                           compared.


-----------------    ---------------       ------------------------------
Destination-IP       IP address            The 'Destination-IP' address, 
                                           together with the 
                                           'Destination-Netmask' denote a 
                                           mask with which destination IP 
                                           addresses from the IP packets 
                                           are compared.

                                           Leave field empty if you do not 
                                           wish to filter using the 
                                           destination IP address as 
                                           criteria.


-----------------    ---------------       ------------------------------
Destination-Netmask  Netmask               The 'Destination-IP' address, 
                                           together with the 
                                           'Destination-Netmask' denote a 
                                           mask with which destination IP 
                                           addresses from the IP packets 
                                           are compared.


-----------------    ---------------       ------------------------------
Port                 Any number            The 'Port' attribute defines 
                     Or, one of these:     the type of service that a 
                       DNS                 packet is carrying. You may 
                       FTP                 specify either the number or 
                       FTP-DATA            lettered value for the 
                       GOPHER              service.
                       SMTP                
                       SNMP                Leave the field empty if you do
                       SNMP-TRAP           not wish to filter using this 
                       TELNET              criteria.
                       TFTP
                       NETBIOS
                       NETBIOS-NS
                       NETBIOS-SSN
                       NNTP
                       POP2
                       POP3
                       WWW


-----------------    ---------------       ------------------------------
Protocol             Any number            Each IP header holds a protocol 
                     Or, one of these:     byte that can be addressed by 
                       ICMP                this attribute.
                       TCP
                       UDP                 Leave field empty if you do not 
                                           wish to filter using this 
                                           criteria.


-----------------    ---------------       ------------------------------
Bit-Number           Positive number       This attribute is part of the 
                                           bit field checking, allowing a 
                                           certain bit to be checked 
                                           within an IP packet (see the 
                                           'Bit-Value' parameter).

                                           This is particularly useful for 
                                           checking the bit flags in the 
                                           TCP header.
         
                                           Leave field empty if you do not 
                                           wish to filter using this 
                                           criteria.


-----------------    ---------------       ------------------------------
Bit-Value            Binary value 0 or 1   This attribute is part of the 
                                           bit field checking.

                                           When you check a certain bit 
                                           within a packet, then you 
                                           should use this attribute to 
                                           specify whether the bit should 
                                           have the value of 0 or 1.

                                           Leave field empty if you do not 
                                           wish to filter using this 
                                           criteria.


-----------------    ---------------       ------------------------------
Offset-Relativity    Packet-Start          This attribute is part of the 
                     TCP-Head-Start        hex string matching criteria.
                     Data-Start
                                           Specifying an offset into an IP
                                           packet often doesn't make 
                                           sense, due to various options 
                                           that be used on and off. 
                                           Accordingly this parameter 
                                           lets you define a certain point 
                                           within a packet from where the 
                                           offset is used (refer to the 
                                           'Offset' attribute).

                                           Leave field empty if you do not 
                                           wish to filter using this
                                           criteria.


-----------------    ---------------       ------------------------------
Offset               Any number            This attribute is part of the 
                     Or 'Search-All'       hex string matching criteria,
                                           allowing you to specify an 
                                           offset into an IP packet
                                           for hex string checking (see 
                                           also the 'Offset-Relativity' 
                                           attribute).

                                           To search the entire packet, 
                                           simply specify the value 
                                           'Search-All'.

                                           Leave field empty if you do not 
                                           wish to filter using this
                                           criteria.


-----------------    ---------------       ------------------------------
Hex-String           A string              This attribute is part of the 
                     (See filter samples)  hex string matching criteria,
                                           Letting you specify a string to
                                           be searched for within a 
                                           packet. The string can contain 
                                           both normal characters and 
                                           hex notation.

                                           Leave field empty if you do not 
                                           wish to filter using this 
                                           criteria.


-----------------    ---------------       ------------------------------
Action               Drop-Packet           Specifies the action taken when 
                     Next-Filter           a filter matches a packet.
                     Forward-Packet


-----------------    ---------------       ------------------------------
Next-Filter          Name of a filter      Specifies the name of a 
                                           compound filter that will be
                                           run when the filter is matched 
                                           and the action attribute is 
                                           set to 'Next-Filter'.


-----------------    ---------------       ------------------------------
Comment              A string              A free-text comment for easy 
                                           identifiable filters.



==========================================================================
 E R R O R S 
=================================================Check filters.err========



   The host product will inform you of severe faults, such as inability to
   load the plugin.

   Possible configuration and syntax errors are written to the file
   FILTERS.ERR, located in the working directory of the host application.



==========================================================================
 S A M P L E   F I L T E R S
=================================================To Get You Started=======



   o Turning off ICMP

     Some system administrators turn off all ICMP traffic to harden
     the job for hackers and possible flood pingers. A simple filter
     to turn off ALL ICMP traffic (including ping and tracerte) is
     found below:

     ICMP-FILTER	Filter-Status = Always,
			Filter-Root = Yes,
			Comment = "Remove ICMP using Protocol matching",
			Filter-Scope = Incoming-Packets,
			Protocol = ICMP,
			Action = Drop-Packet,


   o Only new connections cause Dial-on-Demand (DoD)

     When using the InJoy Dialer, it is often seen how just about
     any packet can trigger Dial-on-Demand. With filtering you have
     almost unlimited possibilities for fine-tuning DoD and below
     is a example that will allow only DNS-lookups and new TCP
     connections to trigger DoD. The three filters work together
     and the fact that filters are analyzed top-down helps us to
     simply allow the 2 special situations and then in the third
     filter reject everything else.

     DOD-ALLOW-DNS	Filter-Status = Offline,
			Filter-Root = Yes,
			Comment = "Allow DNS lookups",
			Filter-Scope = Outgoing-Packets,
			Protocol = UDP,
			Port = DNS,
			Action = Forward-Packet,

     DOD-ALLOW-SYN	Filter-Status = Offline,
			Filter-Root = Yes,
			Comment = "Allow SYN packets (new tcp connections)",
			Filter-Scope = Outgoing-Packets,
			Protocol = TCP,
			Bit-Number = 265,
			Bit-Value = 1,
			Action = Forward-Packet,

     DOD-REJECT-ALL	Filter-Status = Offline,
			Filter-Root = Yes,
			Comment = "Reject everything...",
			Filter-Scope = Outgoing-Packets,
			Protocol = IGNORE,
			Port = IGNORE,
			Action = Drop-Packet,


   o Preventing access to an Internet site

     The below filter demonstrates how all people on the 10.2.*.* network
     are cut off from the porn site found at 207.126.124.139.

     PORN-FILTER	Filter-Status = Always,
			Filter-Root = Yes,
			Comment = "Filter WWW using IP Address matching",
			Filter-Scope = Outgoing-Packets,
			Protocol = TCP,
			Port = WWW,
                        Source-IP = "10.2.0.0",
			Destination-IP = "207.126.124.139",
			Source-Netmask = "255.255.0.0",
			Destination-Netmask = "255.255.255.255",
			Action = Drop-Packet,


   o NETBIOS-KEEP-ALIVE

     This filter is just a sample to demonstrate the technique. It's not
     production ready.

     NETBIOS-KEEPALIVE	Filter-Status = Always,
			Filter-Root = Yes,
			Comment = "Remove Keep-Alive via Hex-String match",
			Filter-Scope = Outgoing-Packets,
			Protocol = UDP,
			Port = NETBIOS,
			Offset-Relativity = Data-Start,
			Offset = 0,
			Hex-String = "JustAnExample\x00\x02\x0DBOZO",
			Action = Drop-Packet,


   o TCP session termination

     The tcp/ip stack has a habit of trying to kill tcp connections
     even after the IP connection is lost and the tcp application is
     dead. The below filters will remove these packets in the offline
     state, dramatically reducing the number of bogus packets in your
     network.

     FIN-PACKETS	Filter-Status = Offline,
			Filter-Root = Yes,
			Comment = "Remove FIN pkts using Bit matching",
			Filter-Scope = Outgoing-Packets,
			Protocol = TCP,
			Bit-Number = 264,
			Bit-Value = 1,
			Action = Drop-Packet,

     RST-PACKETS	Filter-Status = Offline,
			Filter-Root = Yes,
			Comment = "Remove RST pkts using Bit matching",
			Filter-Scope = Outgoing-Packets,
			Protocol = TCP,
			Bit-Number = 266,
			Bit-Value = 1,
			Action = Drop-Packet,



   o NETBIOS

     An intranet with many Windows computers will typically generate
     a large number of NETBIOS packets, keeping your network busy.

     Here are two filters that will keep these packets from hitting the
     ISP and the Internet.

     NETBIOS		Filter-Status = Always,
			Filter-Root = Yes,
			Comment = "Remove Outgoing UDP Netbios-NS",
			Filter-Scope = Outgoing-Packets,
			Protocol = UDP,
			Port = NETBIOS,
			Action = Drop-Packet,

     NETBIOS-NS		Filter-Status = Always,
			Filter-Root = Yes,
			Comment = "Remove Outgoing UDP Netbios-NS",
			Filter-Scope = Outgoing-Packets,
			Protocol = UDP,
			Port = NETBIOS-NS,
			Action = Drop-Packet,




==========================================================================
 O N   T H E   F L Y   U P D A T E S
=================================================Utility program==========



   Updating the filter configuration, e.g. with new filters, on the fly
   is done through the use of an external utility program.

   Below a step-wise procedure for updating your filter configuration
   without having to close or reconnect the host application.

	1. Update the filter configuration files with your desired changes.
	2. Open an OS/2 window and switch to the directory of the host
           application.
	3. In the OS/2 window, issue the command "sync -filter".

   The host product should then inform you that the filter config files 
   have been re-read and possible problems are written to FILTERS.ERR
   (in the same directory).




лллллллллллллллллллллллллллллллллллллллллллллллллллллллллллллллллллллллллл

        Copyright (c) 1999 F/X Communications.  All rights reserved.




