   .
   .
   .                                                          FIREWALL.TXT
   .                                           Firewall Plugin Release 1.4
   .                                                      February 1, 2000
   .                          
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .     _____ ___ ____  _______        ___    _     _
   .    |  ___|_ _|  _ \| ____\ \      / / \  | |   | |
   .    | |_   | || |_) |  _|  \ \ /\ / / _ \ | |   | |
   .    |  _|  | ||  _ <| |___  \ V  V / ___ \| |___| |___
   .    |_|   |___|_| \_\_____|  \_/\_/_/   \_\_____|_____|
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .                                                    F/X Communications
   .                                                       DK-4300 Holbaek
   .                                                               Denmark
   .                                                 E-mail: support@fx.dk
   .                                                      http://www.fx.dk
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .
   .     Copyright (c) 1999-2000, F/X Communications, All Rights Reserved.
   .     Your usage of this product and its documentation are subject to
   .     your acceptance of the license agreement included with this product.
   .
   .     IBM and OS/2 are registered trademarks of International
   .     Business Machines, Inc. All other trademarks, registered trade
   .     marks, service marks and other registered marks are the property
   .     of their respective owners.




==========================================================================
 C O N T E N T S
==========================================================================



   1.  Abstract
   2.  Features
   3.  Installation
   4.  Firewall Architecture
   5.  General Setup
   6.  General Firewall Attributes
   7.  Access Control Attributes
   8.  Network Address Translation
   9.  Port and Address Redirection
   10. Packet Filtering
   11. Accounting
   12. Logging
   13. Errors
   14. Sample Configurations
   15. On The Fly Updates



==========================================================================
 1. A B S T R A C T
==========================================================================



   The InJoy Firewall security solution allow corporations using the
   IBM OS/2 operating system to connect securely to the Internet.

   Used in combination with sound security policies, the Firewall 
   Plugin provides a secure technology to regulate both in-bound and 
   out-bound communications.

   Implemented as a high performance, low-level security solution,
   the Firewall makes full use of the OS/2 system capabilities such
   as: 32 bit code, OS/2 multi-threading and the robust OS/2 TCP/IP Stack.

   The Firewall relies on Stateful Inspection and packet filtering to
   provide security for services. Network Address Translation (NAT) 
   protects your local network from outside attacks, yet preserving
   the desired transparent support for Internet services. For VPN
   support, the Firewall solution coexists with the InJoy IPSec Plugin.

   The Firewall is implemented as a seperate plugin component.
   The modular design facilitates easier testing, clean interfaces and
   code-reuse. The Firewall Plugin seamlessly enables security in the
   following stand-alone products:

      o InJoy Internet Dialer
      o InJoy Firewall

   Configuration is by way of simple text (ASCII) files.



==========================================================================
 2. F E A T U R E S
==========================================================================



   The Firewall is a plug-in module that offers the following key features:


        * Rule Based Access Control

        * Network Address Translation

        * Port and Address Redirection

	* IPSec VPN Support

        * Packet Filtering

        * Alerts

        * Accounting

        * Logging


   Read the remainder of this section for a brief introduction to these
   features and a definition of the terminology used.


   o Rule Based Access Control

   When a connection attempt is presented to the firewall, the firewall
   must determine whether or not the requested connection is allowed. 
   This decision is made according to rules the firewall's administrator 
   sets up based on your organization's security policy. 

   The Firewall Administrator records these rules in a file of rules. 
   Rules are consulted each time a user requests a connection. 

   For example, one rule might specify that NO internal systems are 
   permitted to make FTP connections to systems on the Internet. 
   In this case, the user's connection request is denied and the 
   firewall closes the connection. 


   o Network Address Translation

   Since all Internet connections to or from the internal network
   must first pass through the firewall, the firewall uses Network
   Address Translation to hide internal IP addresses. With Network
   Address Translation, the firewall makes all outbound traffic from
   the internal network appear to originate from the firewall's external
   network IP address. All packets are essentially re-addressed before
   leaving the firewall, and references to internal IP addresses are
   replaced with the firewall's external IP address.


   o Port and Address Redirection

   The firewall's Access Control rules provide the capability of redirection, 
   which allows a connection request from an external client to be remapped
   to a system on the internal network.

   Redirection can be applied to both IP addresses and ports, and allows the
   destination address to be changed from the external address of the firewall
   to specific hosts behind the internal network. 

   Port and address Redirection is extremely useful in providing access to 
   servers on the internal network that are otherwise not accessible from 
   the outside world.


   o IPSec VPN Support

   Virtual Private Networks (VPNs) exploit the worldwide reach of the
   public Internet to provide secure, cost-effective intra-company and
   inter-company communications.

   The purpose of the IPSec (Internet Protocol Security) protocol suite is
   to provide a standard way for protecting all traffic on the Internet
   transparently, irrespective of the application.

   The IPSec protocol offers a set of security extensions, providing privacy
   and authentication services by using modern cryptographic methods.
   It can protect all traffic against unauthorized modification and 
   eavesdropping and securely authenticate the parties that are
   communicating with each other. It renders the commonly used security
   attack methods completely ineffective. 

   IPSec makes it possible to securely connect company offices, individual
   host, and services to the network. It makes the network safe for
   transmitting confidential information. For the first time, security
   is transparent, requiring absolutely no actions on the part of end users. 

   From a customer's perspective IPSec brings two main benefits: strong
   standardized network security inherent with IPSec compliant products,
   and interoperability with other IPSec compliant vendors. 

   IPSec customers have the comfort of knowing that IP based communications
   passing over the network are using the most secure and comprehensive
   standard available today where encryption, authentication and data
   integrity are wrapped together. 

   Please refer to the IPSec documentation for more information.


   o Packet Filtering

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

   The Packet filtering is a highly valued control method that is 
   typically used where rules are not appropriate. With maximum 
   granularity, filtering finishes the job of protecting certain 
   networking resources. Filtering allows you to check everything 
   from just one single bit (literally) to complex string patterns.

   Packet Filtering can be configured to inspect both incoming and 
   outgoing communications.

   Please refer to the filter documentation for more information.


   o Alerts

   The firewall's Access Control rules provide the capability of Alerts.

   Alerts provide an easy way to be notified when an access control rule
   is matched. 

   The firewall administrator has the possibility of defining
   custom alerts to e.g. send out e-mails, beep, contact a radio-pager,
   etc.


   o Accounting

   The Firewall provides full accounting of network activity.

   Configuration of accounting is as flexible as rule configuration,
   giving the firewall administrator the possibility to carefully
   define for which IP segment accounting should be generated.

   Both accounting per service (ftp, www, etc) and accounting per 
   IP-address (workstation) usage are supported.


   o Logging

   Using the logging features of this product, you can selectively log
   transactions in order to keep track of the visitors. Logging is an
   extremely powerful tool, helping you discover errors and
   misconfigurations before they become severe security issues.



==========================================================================
 3. I N S T A L L A T I O N
==========================================================================



   The Firewall Plugin is delivered as part of the InJoy Firewall PRO
   and the InJoy Dialer SOHO/PRO version. Simply unzip and register
   the host product and the firewall plugin will be ready for use.

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

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



==========================================================================
 4. F I R E W A L L   A R C H I T E C T U R E
==========================================================================



   This section gives you the background to understand the technology which
   underlies the Firewall.


   o What Is a Firewall?

   There has been a lot of discussion as to what a firewall is and many 
   people have a strong opinion.

   Some individuals believe that nothing is a firewall unless it has been
   purpose-built as such and has the word "Firewall" stamped on the side of
   the box. This is not the case; many very effective firewalls have been
   built out of off-the-shelf routers.

   In fact, a firewall is a conceptual object rather than a specific software
   or hardware product. It is the idea of rejecting all traffic except for
   that which is specifically allowed. This should allow the administrator of
   the firewall to control all traffic into and out of a network.


   o Firewall Technology

   Today, firewalls are devided into two major categories based on the type
   of security scheme they implement. The evolution in the industry has been
   from packet filters to application-layer proxies, to stateful inspection.
   This evolution has taken place based upon the advantages introduced with
   each new generation of firewall technology.

   Application proxies track only application state, not packet or connection 
   state, which may introduce security vulnerabilities. Application-layer 
   proxies require a separate proxy for every service to be secured, resulting
   in a large resource requirement on the host computer. Application-layer
   proxies only check layers 5-7 of the OSI model, whereas modern inspection
   technology can check layers 3-7.

   The new generation of firewall technology is often referred to as Stateful 
   Inspection. Stateful inspection delivers full firewall capability, assuring 
   the highest level of network security and by preventing packets from 
   passing through numerous network layers, throughput is increased 
   dramatically.

   Stateful inspection resides below the network layer, at the lowest software
   level. By inspecting communications at this level, a firewall can intercept 
   and analyze all packets before they reach the Internet or the TCP/IP
   Protocol Stack.


   o Understanding The Firewall

   To understand the Firewall network security, you must first 
   understand the interaction of the following three key technologies:

	* Access Control Rules
	* Stateful Inspection
	* Network Address Translation

   Access Control Rules:

   The basic premise behind the Firewall is that all traffic is blocked, 
   unless specifically allowed (an "opt-in" security model). Openings in the
   Firewall are in a single direction. For example, here at F/X
   Communications, we allow all outgoing FTP traffic to travel unhindered.
   Incoming FTP traffic is only allowed to a couple of hosts. This way, we
   can FTP to anywhere on the Internet, but people roaming the Internet
   cannot probe into F/X at random. These openings are called rules and by
   design, only traffic which complies with the active rule set can penetrate
   a firewall.

   Stateful Inspection:

   The implementation of Access Control Rules is done by means of 
   stateful inspection technology. Using stateful inspection, the Firewall
   inspection module has full access to all available information about
   any particular network request. The inspection module examines
   IP addresses, port numbers, and any other information required in order 
   to determine whether packets comply with the company security policy.

   Network Address Translation:

   NAT provides unlimited local host addresses and allows you to connect 
   to the Internet without having to provide a new real-world address to
   each and every internal host. NAT makes all outbound traffic from the
   internal network appear to originate from the firewall's external 
   network IP address. All packets are re-addressed before leaving the
   firewall, and references to internal IP addresses are replaced with
   the firewall's external IP address

   o The Firewall Engine

   The Firewall engine serves as a software wedge that is located 
   between the IP protocol stack and the external firewall interface.

   The Firewall Engine captures and filters all packets that travel
   through the network interface before they reach the protocol stack
   or the external interface.

   Below is a context diagram for the Firewall:


                             Accounting
                                 |
                 Configuration   |   IPSec
                            \    |   /
                             \   |  /
    External interface -----  Firewall ----- Internal interface
    (Internet)            |      |       |   (intranet)
                      Filtering  |   Filtering
                                 |
                                 |
                              Logging


   The main functionality of the firewall is to maintain the security policy
   defined by the access control rules. This is done by a stateful inspection 
   of connections, but also by means of packet filtering and Network Address
   Translation.

   Before we continue, it is important to understand the collaboration between
   Network Address Translation and the access control rules.

   Access control rules have priority over NAT. Let us examine four simple
   examples to illustrate this.

   NB: The following examples assume that NAT is enabled and the general
   firewall attributes are configured so the settings

	* Permit-Incoming
	* Permit-Outgoing

   are both set to the value 'YES'. Read more about these two settings
   in the "General Firewall Attributes" section.


   Example 1)

   If a rule ALLOWS transparent access for a workstation on the internal 
   interface then NAT has NO influence on the traffic. In other words, the
   workstation has unhindered access to the Internet (provided the work-
   station has real-life IP address).

   Example 2)

   If a rule DENIES access to a workstation on the internal interface,
   then NAT has NO influence on the traffic.

   Note: Only internal hosts equipped with real-world Network IP Addresses
   can be denied access by rule. Hosts equipped with only domestic
   (nonroutable) Network IP Addresses (such as 10.x.x.x or 192.x.x.x) are
   typically not accessible to workstations on the Internet due to the
   natural limitation of domestic IP addresses.

   Example 3)

   If NO RULES have been defined for a workstation on the internal interface,
   then NAT will be able to do its job, by getting the workstation safely
   on the Internet. From the viewpoint of an external observer, connections
   made by this workstation will appear to originate from the firewall's
   external IP address. Workstations getting on the Internet via NAT
   are not open to connections from the Internet, except when enabled through
   the use of port and IP redirection.

   Example 4)

   If NO RULES have been defined for a workstation on the internal interface,
   then NAT will reject all incoming connections.


   o Firewall Name Resolving

   The Firewall supports Domain Name Server lookups of host names
   specified in access control rules. Looking up names on an Internet 
   Domain Name Server (DNS) can be a lengthy process and as long as a 
   rule is having names looked up, the rule will not be matched and
   accordingly be out of action (as if it did not exist).

   It is recommended that you specify Network IP Addresses when FULL 
   security for a host is required from the instant the firewall is
   started.

   IP addresses are currently not reverse looked up for the purpose
   of logging with host names.


   o Firewall Integration

   The Firewall plugs into a host application as a plugin. This means
   that it is possible to use the firewall with normal dial-up or leased
   line connections, as provided by the InJoy Internet dialer.

   When the firewall is not loaded, it will not take up resources and a
   network administrator will easily be able to determine when the firewall
   is in use.



==========================================================================
 5. G E N E R A L   S E T U P
==========================================================================



   o Configuration Files

     Firewall options and rules are specified in one or more ASCII 
     configuration files. Each configuration file can contain one or 
     more sets of information, each identified by a name and a set 
     of attribute/parameter values.

     IMPORTANT NOTICE: The configuration files are read when the host
     product connects to the Internet, but on-the-fly updates of the
     configuration files are also supported.

     The plugin expects to be able to read the following files:

     FIREWALL.CNF  This file is located in the base directory of the host
     (template)    application. It contains the default values for the
                   general firewall options. This means that any attribute
                   value you specify in your own configuration files will
                   override the default values specified in this file.

     FIRERULE.CNF  This file is in the base directory of the host application.
     (template)    It contains the default values used in all user created
                   rules. Any attribute value you specify in your own access
                   control rules will override the default values specified
                   in this file.

     FIREWALL.CNF  This file contains the actual general firewall options.
                   The file is typically located in the FIREWALL subdirectory
                   of the host application (ie. ".\FIREWALL\FIREWALL.CNF")
                   but may be set up differently, depending on the host's
                   capabilities.  See the General Attribute section for syntax
                   information.

     FILERULE.CNF  This file contains the user-defined access control rules.
                   The file is typically located in the FIREWALL subdirectory
                   of the host application (ie. ".\FIREWALL\FIREWALL.CNF")
                   but may be set up differently, depending on the host's
                   capabilities. See the following Access Control Attribute
                   section for syntax information.

     FIREWALL.DCT  These files are located in the base directory of the host
     FIRERULE.DCT  application. They are descriptor files which instruct the
                   Firewall Plugin about allowable attributes in the same .CNF
                   files. These files should NOT be modified. However, if you
                   take the time to become familiar with them, you will be
                   able to use them as a quick reference when writing or
                   modifying rules.



==========================================================================
 6. G E N E R A L   F I R E W A L L   A T T R I B U T E S
==========================================================================



   The Firewall supports a set of GENERAL settings which define 
   the overall operation of the firewall. These are:

	- Permit-Incoming
	- Permit-Outgoing
	- Logging-Control
	- Account-Interval

   Remember, both Attributes and Values are case-sensitive.

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

   Permit-Incoming      YES                   Defines the default treatment
                        NO                    of incoming traffic from the
                                              external interface.

                                              Setting the attribute 'Permit-
                                              Incoming' to the value 'NO' 
                                              defines that any incoming 
                                              connection MUST be allowed by 
                                              rule, otherwise it will be 
                                              REJECTED.

                                              If 'Permit-Incoming' is set to
                                              the value 'YES', then incoming
                                              connections are first checked 
                                              for a matching rule. If no rule 
                                              was matched, then the connection
                                              is processed by the Network
                                              Address Translation. 

                                              If NAT is disabled, Permit-
                                              Incoming will allow direct 
                                              access to real-life IP addresses 
                                              on your internal network.

                                              Note: NAT will ONLY accept
                                              packets initially destined for 
                                              the InJoy PC, so even if you
                                              'Permit-Incoming' traffic, this
                                              doesn't necessarily mean that
                                              your network is open to attacks.


   -----------------    ---------------       ------------------------------
   Permit-Outgoing      YES                   Defines the default treatment
                        NO                    of outgoing traffic to the
                                              external interface.

                                              Setting 'Permit-Outgoing' to the 
                                              value 'NO' defines that any 
                                              outgoing connection MUST be 
                                              allowed  by rule, otherwise it
                                              will be REJECTED.

                                              If 'Permit-Outgoing' is set to
                                              the value 'YES', then outgoing
                                              connections are first checked 
                                              for a matching rule. If no rule 
                                              was matched, then the connection
                                              is processed by the Network
                                              Address Translation.

                                              If NAT is disabled, 'Permit-
                                              Outgoing' will provide direct 
                                              Internet access to real-life 
                                              IP addresses on your internal 
                                              network.


   -----------------    ---------------       ------------------------------
   Logging-Control      Enabled               Tells whether logging is
                        Disabled              enabled or disabled. 

                                              The option is global and has
                                              top-level control of all the
                                              firewall logging.

                                              Further granularity is available
                                              per rule basis.

                                              The option is useful in a small 
                                              office environment where 
                                              performance is more important 
                                              than the security.


   -----------------    ---------------       ------------------------------
   Account-Interval     Any number            Defines the number of seconds
                                              between writing accounting
                                              information to the disk.

                                              Updating the accounting files
                                              can be a performance demanding
                                              task, so it is adviced to
                                              specify a fairly long duration
                                              between updates (e.g. 30
                                              minutes).



==========================================================================
 7. A C C E S S   C O N T R O L   A T T R I B U T E S
==========================================================================



   The Firewall uses access control rules to implement security.

   Rules are applied in the order they appear in the configuration file.
   For example, let us assume that you want to allow Internet access for
   a whole IP segment, except for just one specific IP address.

   To achieve this, you should organize your rules in the demonstrated
   sequence.

        - First rule - deny access for the specific workstation.    
        - Second rule - allow access for the whole segment.

   Access control rules are defined in ASCII (text) files.
   The following attributes are available:

	- Rule-Name
	- Rule-Status
	- Comment
	- Protocol
        - Source-Port
	- Service
	- Service-List
	- Source
	- Source-Netmask
	- Destination
	- Destination-Netmask
	- Rule-Action
	- Alert-Type
	- Alert-Info
	- Log-Control
	- Log-Mask
	- Log-File
	- Log-Size
	- Account-Control
	- Account-File
	- Account-Type
	- Mapping-Dest-IP
	- Mapping-Dest-Port


   In the following section, you will find descriptions of each attribute
   and its possible values. Refer to the sample section to see how these 
   attributes are organized into rules. Notice that all rules must have
   a unique name.

   Remember, both Attributes and Values are case-sensitive.

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

   Rule-Status          Disabled              Tells if the rule is active
                        Enabled               or not. 


   -----------------    ---------------       ------------------------------
   Comment              A string              A free-text comment allowing
                                              you to identify (for future
                                              readers) what each section of
                                              the rules file is intended to
                                              accomplish.


   -----------------    ---------------       ------------------------------
   Protocol             Any number            Each IP header holds a protocol 
                        Or, one of these:     byte that can be addressed by 
                          IGNORE              this attribute.
                          ICMP                
                          TCP                 Use the value IGNORE if you do 
                          UDP                 not want to rule out connections
                                              using these criteria.


   -----------------    ---------------       ------------------------------
   Source-Port          Any number            All TCP and UDP connections 
                        Or, one of these:     have a source service-port
                          IGNORE              number in the header.
                          DNS
                          FTP                 Typically, the Source-Port is
                          FTP-DATA            not used, except in very
                          GOPHER              few cases, such as with
                          SMTP                Port Redirection.
                          SNMP
                          SNMP-TRAP           Use the value IGNORE if you do
                          TELNET              not want your rule to check
                          TFTP                this field.
                          NETBIOS
                          NETBIOS-NS
                          NETBIOS-SSN
                          NNTP
                          POP2
                          POP3
                          WWW


   -----------------    ---------------       ------------------------------
   Service              Any number            All TCP and UDP connections 
                        Or, one of these:     have a port number in the IP
                          IGNORE              header. This port number denotes
                          DNS                 the Service. Common services
                          FTP                 are 'FTP', 'Telnet', 'WWW', etc.
                          FTP-DATA
                          GOPHER              The Service can be addressed
                          SMTP                by your access control rule;
                          SNMP                e.g. in order to deny (or
                          SNMP-TRAP           allow) FTP connections, set the
                          TELNET              'Service' attribute to 'FTP'.
                          TFTP                
                          NETBIOS             Use the value IGNORE if you do
                          NETBIOS-NS          not want your rule to check
                          NETBIOS-SSN         this field.
                          NNTP
                          POP2
                          POP3
                          WWW


   -----------------    ---------------       ------------------------------
   Service-List         The following         The 'Service-List' attribute
                        operators are         allows you to specify advanced
                        valid:                service port combinations - as
                                              opposed to the 'Service' attr.
                        #   - allow port
                        #:# - range           The 'Service-List' is a string,
                        <#  - less than       composed of a combination of
                        >#  - more than       port numbers and operators.
                        -#  - exclude         
                        -#:#- exclude         The following examples 
                              range.          illustrate the syntax:

                        '#' signifies a       Example 1: Match 3 often
                        port number.          used ports:

                        Names (e.g. ftp)         "telnet ftp www-http"
                        can be used in 
                        place of port         Example 2: Match ports in the
                        numbers and are       range 2000 to 4000 (both incl):
                        looked up in         
                        services.                "2000:4000"

                                              Example 3: Match ports bigger
                                              than 10500, excluding a range
                                              of ports in the 40xxx segment:

                                                 ">10500 -40000:49999"

                                              Example 4: Multiple ranges:

                                                 "20:23 57:67 150:999 "

                                              Example 5: Ftp, telnet and 
                                              ports above 1024 are matched.

                                                 "ftp telnet >1024"

                                              Refer to the sample section
                                              of this document for rules
                                              that use use this feature.


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

                                              The source IP address may be
                                              given as a host name, e.g.
                                              'www.fx.dk'.

                                              Use the keyword 'any' if the
                                              IP address should be ignored.

                                              Use the keyword 'current' when
                                              creating rules that depend on a
                                              dynamically assigned IP address.


   -----------------    ---------------       ------------------------------
   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 address            The 'Destination' IP address, 
                        or the keyword        together with the 
                        "any"                 'Destination-Netmask' denote a 
                        "current"             mask with which destination IP 
                                              addresses from the IP packets 
                                              are compared.

                                              The destination IP address may
                                              be given as a host name, e.g.
                                              'www.fx.dk'.

                                              Use the keyword 'any' if the
                                              IP address should be ignored.

                                              Use the keyword 'current' when
                                              creating rules that depend on a
                                              dynamically assigned IP address.


   -----------------    ---------------       ------------------------------
   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.


   -----------------    ---------------       ------------------------------
   Rule-Action          Allow                 This attribute specifies the
                        Deny                  action taken when the rule
                        Log                   criteria match the data stream.
                        Account
                        Alert                 'Allow' instructs the firewall
                        Portmap               to pass through data matching 
                                              the rule.

                                              'Deny' instructs the firewall
                                              to block any data matching 
                                              the rule.

                                              'Log' instructs the firewall
                                              to log any data matching 
                                              the rule. Read on for other 
                                              logging attributes.

                                              'Account' instructs the
                                              firewall to perform accouting
                                              for data matching the rule.
                                              Read on for other accounting
                                              attributes.

                                              'Alert' instructs the firewall
                                              to give an alert when the rule
                                              is matched, respecting the
                                              value of the 'Alert-Type' 
                                              attribute.

                                              'Portmap' instructs the firewall
                                              to map a connection to another
                                              IP address and Port when the rule
                                              is matched.


   -----------------    ---------------       ------------------------------
   Alert-Type           Alert-Off             To track hacking attempts or
                        Alert-Audio           other firewall exploits, use
                        Alert-Autostart       the 'Alert' feature. Alerts
                                              will be issued when the owner-
                                              rule is matched.
                                              
                                              'Alert-Off' to disable alerts.

                                              'Alert-Audio' to give a short
                                              high-pitched tone.

                                              'Alert-Autostart' to run the
                                              command specified in the
                                              'Alert-Info' field.


   -----------------    ---------------       ------------------------------
   Alert-Info           A string              This field specifies additional
                                              info for the Alert feature.

                                              With the attribute 'Alert-Type' 
                                              set to the value of 'Alert-
                                              Autostart', this field must
                                              contain the actual command you
                                              wish to pass to the Operating
                                              System, once the alert occurs.


   -----------------    ---------------       ------------------------------
   Log-Control          Disabled              Specifies whether logging
                        Enabled               is enabled for the rule
                                              in question.

                                              Logging can be enabled for
                                              rules with the attribute 
                                              'Rule-Action' set to value:

                                                 'Log'
                                                 'Allow'
                                                 'Deny'
                                                 'Portmap'
                                              
                                              
   -----------------    ---------------       ------------------------------
   Log-Mask             String composed       This attribute allows you to
                        from the following    select the information level
                        case-sensitive,       of the logging output.
                        whitespace-
                        separated
                        keywords:             Below is a descriptive list of
                                              the various flags.
                          "rule"              
                          "date"              "rule"   - rule name
                          "time"              "date"   - today's date
                          "msg"               "time"   - current time
                          "prot"              "msg"    - descriptive text (if 
                          "source"                       provided by the
                          "dest"                         application)
                          "service"           "prot"   - Protocol
                          "dump"              "source" - source IP
                                              "dest"   - dest IP
                                              "service"- service / port#
                                              "dump"   - dump offending IP
                                                         packets


   -----------------    ---------------       ------------------------------
   Log-File             A string              Name of the log-file attached
                                              to this rule.
                                              

   -----------------    ---------------       ------------------------------
   Log-Size             Any number            CURRENTLY NOT SUPPORTED
                        

   -----------------    ---------------       ------------------------------
   Account-Control      Disabled              Use this setting to turn 
                        Enabled               accounting ON/OFF for a rule.

                                              Accounting can be enabled only
                                              for rules with the attribute 
                                              'Rule-Action' set to the value
                                              'Account'.


   -----------------    ---------------       ------------------------------
   Account-File         A string              Name of the account-file 
                                              attached to this rule.

                                              The file-name can include
                                              a full path, but should NOT
                                              include an extension.

                                              The extension is determined
                                              by the Firewall. Refer to the
                                              Accounting section.


   -----------------    ---------------       ------------------------------
   Account-Type         Service               This setting determines the
                        Source-IP             type of accounting information
                        Destination-IP        that is generated for the
                        Both-IP               rule.

                                              Accounting can be per service-
                                              usage (e.g. FTP, WWW usage) or
                                              accounting can be per source,
                                              destination or both IP 
                                              addresses.

                                              Refer to the accounting section.


   -----------------    ---------------       ------------------------------
   Mapping-Dest-IP      An IP address         This setting determines the
                        or the keyword        destination IP address for
                        "any"                 a port and IP address
                                              redirection.
                        
                                              Use the keyword 'any' if the 
                                              IP address should be left 
                                              unaltered.

                                              Refer to the "Port and Address
                                              Redirection" section.


   -----------------    ---------------       ------------------------------
   Mapping-Dest-Port    Any number            When redirecting, this setting
                        Or, one of these:     determines the new service-port
                          IGNORE              number.
                          DNS                 
                          FTP                 Use the value IGNORE if you do
                          FTP-DATA            not wish for your rule to alter
                          GOPHER              the service port.
                          SMTP
                          SNMP                Refer to the "Port and Address
                          SNMP-TRAP           Redirection" section.
                          TELNET
                          TFTP
                          NETBIOS
                          NETBIOS-NS
                          NETBIOS-SSN
                          NNTP
                          POP2
                          POP3
                          WWW




==========================================================================
 8. N E T W O R K  A D D R E S S  T R A N S L A T I O N
==========================================================================



   The Firewall supports two Network Address Translation (NAT)
   features: IP Masquerading and Port & Address Redirection.

   IP Masquerading, which is one feature of NAT, can hide internal IP
   addresses from the external network. This adds another, optional level
   of firewall protection by enabling one legal Internet IP address to
   serve as the gateway for all outbound traffic from internal networks.
   Return connections are re-mapped by the Firewall to the correct 
   client machine based on port number.

   Making many internal hosts look like one very busy external host has
   several advantages: 

      o From a security standpoint, it denies outsiders information
        about the shape and configuration of the internal network. It
        also makes it more difficult to derive individual usage patterns.

      o From a network management standpoint, it enables internal or
        trusted networks to use RFC 1918 private IP addresses that are
        invalid on the Internet. This frees up "real" IP addresses for
        better purposes.

      o From an administrative standpoint, it allows companies to
        change their Internet Service Provider without needing to
        renumber internal IP addresses.

   Port and Address Redirection, another feature of NAT, allows internal 
   hosts with unregistered IP addresses to function as Internet-reachable 
   servers. The Firewall redirects IP packets to a masqueraded host 
   behind it based on the original destination port number. 

   For example, using SMTP port forwarding, the Firewall allows 
   administrators to maintain a public e-mail server with an invalid 
   Internet IP address behind the Firewall and publish the IP
   address of the Firewall as its mail server. Whenever the Firewall
   receives a TCP/IP packet on SMTP's registered service port of 25, 
   the firewall will forward the packet to the masqueraded SMTP server
   for processing.

   Almost all TCP/IP applications will work through NAT. The following
   list of applications lists some of the applications that work flawlessly
   with NAT:

   - Netscape, MS Internet Explore, or any other web browser
   - Any FTP client
   - Any mail client (PMMail, MR/2 ICE, etc)
   - News readers (Agent, NR/2, etc)
   - IPSec (VPN protocol)
   - IRC (including DCC CHAT/DCC SEND/IDENTD)
   - ICQ
   - Tracerte
   - Ping
   - Cuseeme
   - Telnet
   - 3270 emulation
   - Netbios over IP
   - Gopher
   - RealPlayer 5.0
   - Quake II
   - many more....

   These applications will NOT run:

   - Programs not running TCP or UDP protocol (except ping/tracerte).
   - various multimedia applications, of which MS Netmeeting is the most
     noteable.

   Read more about the NAT feature in the "Port and Address Redirection"
   section.



==========================================================================
 9. P O R T   A N D   A D D R E S S   R E D I R E C T I O N
==========================================================================



   IP Port and Address Redirection allows you to configure the Firewall 
   to give external Internet users access to specific computer resources on 
   your internal LAN. Normally, the Firewall blocks incoming access to 
   all internal LAN computer resources.

   IP Port Forwarding allows you to redirect requests to Internet services 
   like Web (HTTP), mail servers (SMTP and POP3), Telnet, FTP, etc, to 
   computers on your local LAN.

   Remember that all firewall openings are one-way, so you need to create
   two seperate rules to redirect connections to an internal host
   successfully. One rule defines the incoming redirection and another rule
   defines the outgoing redirection.


   o Creating Port Mapping Rules

   To create an incoming port forwarding rule, you must define the following
   parameters:

	- Network IP Address of the firewall
	- Service Port
	- Local Service Port (on internal host)
	- local Network IP Address (on internal host)

   Example:
   To define an IP and Port Forwarding rule to redirect incoming Telnet 
   requests to a telnet server with the IP Address "192.168.1.20" on your 
   internal network, create a rule like the one below:

	PORTMAP-TELNET-IN	Comment = "Map incoming Telnet to internal PC",
				Source = "any",
				Destination = "firewall.company.com",
				Service = TELNET,
				Rule-Action = Portmap,
				Mapping-Dest-IP = "192.168.1.20",
				Mapping-Dest-Port = TELNET

   To complete the port mapping, you must define an extra rule to define and
   permit redirection in the outgoing direction. In this example, the reversed
   rule looks like this:

	PORTMAP-TELNET-OUT	Comment = "Map outgoing Telnet back",
				Source = "192.168.1.20",
				Destination = "any",
				Source-Port = TELNET,
				Rule-Action = Portmap,
				Mapping-Dest-Port = TELNET

   This rule defines that the host "192.168.1.20" on our internal LAN
   will get Telnet connections.

   If you are out on the internet and steer your telnet client to 
   the address "firewall.company.com", then you will think that 
   you are accessing a server running on "firewall.company.com". Actually,
   "firewall.company.com" is just passing off traffic to the real 
   server at "192.168.1.20".


   o Security Concerns

   IP Port Forwarding can give anyone on the Internet access to 
   a computer resource you specify on your LAN.

   Always think carefully about the implications of enabling any feature
   that allows outside users to access resources on your LAN from the
   Internet. If in doubt, you should hire a qualified Internet security
   consultant to help you understand the risks involved.



==========================================================================
 10. P A C K E T   F I L T E R I N G
==========================================================================


   (Please refer to FILTER.TXT).

   Packet Filtering is provided by a separate plugin.

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

   The Packet Filter Plugin allows ALL attributes in a IP-packet to be 
   used as a filtering trigger to discard selected packets when presented.
   The following packet attributes can be examined by the filter process:

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

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

   For further information on the F/X Packet Filter Plugin, please refer 
   to the seperate Filter documentation found in the file FILTER.TXT.




==========================================================================
 11. A C C O U N T I N G
==========================================================================



   Accounting information provides a powerful tool to get a statistical
   overview of you network usage. Not only will accounting show you how
   your bandwidth is utilized, it will also help you diagnose problems,
   outside hacker attacks and even junk e-mail ("spam").

   First, accounting needs some kind of granularity. The Firewall provides 
   statistics with an hour by hour granularity organized into human readable
   files of monthly granularity. That is, if you perform accounting for a
   full year, then you will have 12 files each named with a 3 letter monthly 
   suffix, like:

	account.jan
	account.feb
	account.mar
	.
	.
	account.dec

   Each file will contain accounting information organized per day
   of the month (each day with an hour by hour granularity). At the end 
   of each file you will find a monthly total.

   Two different types of native accounting-information are available

	* Accounting Per Service-Usage
	* Accounting Per IP-Usage

   As a firewall administrator, you would want information about the
   services that are in use and when. With the 'accounting per service'
   option you have easy access to this information all the way down to
   a specific hour.

   Lets take a look at the sample service-usage accounting report:


      [DATE: 15.07.1998]

                     | Time of day
                     +------------------+------------------ 
      SERVICE        | 00:00            | 01:00             
      ---------------+------------------+------------------ 
      PORT           | inbytes/outbytes | inbytes/outbytes  
      ---------------+------------------+------------------ 
      ftp     |T|21  | 4444/342         | 0/0               ......
      ftp-data|T|20  | 33422/8998       | 0/0               ......
      pop3    |T|110 | 5665/4332        | 789/999           ......
      domain  |U|53  | 233/299          | 44/4446               
      other          | 0/0              | 345/789               
      ---------------+------------------+------------------ 
      total          | 437630/13971     | 1178/6234               


   On the X direction (horizontally) you have the time of day, divided
   into 24 hours, ending with a total (not shown). 

   On the Y direction (vertically) you have the different services that 
   pop up as they have been used. The services are resolved into names,
   using a cached copy of the 'services' file found in your /mptn/etc 
   directory.

   The total number of bytes per hour is summarized vertically along
   the Y axis. The total number of bytes per service is summarized along
   the X axis. Total bytes per day and total bytes per service are found
   all the way to the right (not shown).

   As a firewall administrator, you also need accounting reports showing
   which IP addresses on your system are responsible for the bandwidth
   utilization.

   The 'Accounting Per IP Address' report provides just this information:

      DATE: 15.07.1998]

                     | Time of day
                     +------------------+------------------
      HOST           | 00:00            | 01:00
      ---------------+------------------+------------------
      IP-ADDRESS     | inbytes/outbytes | inbytes/outbytes
      ---------------+------------------+------------------
      194.239.180.26 | 4444/342         | 0/0
      195.97.161.40  | 33422/8998       | 0/0               ......
      194.239.134.166| 5665/4332        | 789/999           ......
      193.162.146.9  | 233/299          | 44/4446           ......
      other          | 0/0              | 345/789
      ---------------+------------------+------------------
      total          | 437630/13971     | 1178/6234               


   The above report should be easily understood, so let's move on and
   see what options that are available to customize your accounting
   reports. A typical request is to generate accounting for (say) three
   different IP segments.

   Generating accounting information for almost any combination of networks,
   segments and services is a great challenge that requires a very flexible 
   and easy understandable administration scheme.

   This administration scheme is available first hand in the form of special 
   rules. So far, you have seen the typical rules that 'allow' or 'deny' 
   access to a certain network resource, but the rule concept can easily 
   be expanded to define accounting masks. So, accounting rules are no 
   different from ordinary firewall rules. You simply define the rule, which
   serves as a mask, and then provide an accounting filename in which the 
   information is stored and summarized. Keep in mind that for optimal 
   flexibility, several accounting rules can in fact address/update the 
   same file.

   Refer to the 'Access Control' section to learn more about rules.



==========================================================================
 12. L O G G I N G
==========================================================================



   o Understanding Logging

   Logging is an indispensable tool for the firewall administrator. It
   helps you:

	* discover errors and misconfigurations
	* verify access control rules
	* monitor data packets for hacker attacks
	* keep track of visitors
	* trace failing connections
        * and more.

   The firewall has two distinct types of logging. One type is strictly 
   bound to reporting errors in the firewall configuration/operation and 
   the other type is rule based logging. 


   o Firewall Error Log

   The firewall error log provides a convenient way to discover all
   types of misconfigurations and/or firewall malfunctions before they 
   turn into serious security issues.

   The firewall errors are stored in the file:

      "FIREWALL.ERR"

   This file is stored in your host application base directory. Note that this
   file is only created if an error occurs, so it may not exist on your system.

   When errors are written to this file it requires your full attention.
   The problem could be anything from a complete firewall "meltdown" to
   a simple misconfigured rule.

   The Firewall is put into operation even if simple errors are reported,
   so be sure to check this file to make sure the Firewall is operating the
   way you expect.


   o Rule Based Logging

   Rule based logging allows the firewall administrator to precisely
   define what is to be logged.

   Logging can be attached to any access control rule, which means that 
   whenever the rule is matched, a log-entry is generated. The log-entry 
   is immediately written to the log-file that you have specified by the 
   rule in question.

   Not only rules that deny or allow access can have logging "attached". 
   In fact, it is possible to create rules that does nothing but log 
   whenever they are matched. Please refer to the sample section for
   examples of this.

   Log-files can be specified with a full path, so you can organize them
   into sub-directories by relevance. Note that one log-file can be shared
   by several rules, so you have maximum freedom to define your desired 
   output of the firewall.

   Refer to the following attributes in the "Access Control Attributes"
   section for more information on how to configure the logging:

	* Log-Control
	* Log-Mask
	* Log-File
	* Log-Size
                        


==========================================================================
 13. E R R O R S
==========================================================================



   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
   FIREWALL.ERR, located in the working directory of the host application.



==========================================================================
 14. S A M P L E   C O N F I G U R A T I O N S
==========================================================================



   o General Firewall Options

     This example shows you the contents of the default 'FIREWALL.CNF'
     file. 

     As you can see, logging is enabled, incoming connections are
     accepted if they are allowed by rule or accepted by the Network Address
     Translation. All outgoing connections are allowed. The Account-Interval
     specifies that the accounting is flushed to the harddisk every 5 minutes.

	SETTINGS	Logging-Control = Enabled,
			Permit-Incoming = YES,
			Permit-Outgoing = YES,
			Account-Interval = 300


   o Transparent Access Rule Sample

     The following example provides full and transparent access to a
     workstation on the LAN. The workstation has its own IP address
     and domain name.

     Notice how two rules are needed; one rule for incoming data and one
     rule for outgoing data. You may also notice that logging is turned
     on for both rules.

	NT-SERVER_OUT	Comment = "NT Server ---> Internet",
			Source = "ntserver.com",
			Destination = "any",
			Rule-Action = Allow,
			Log-Control = Log-Enabled,
			Log-File = "firewall\nt.com"


	NT-SERVER_IN	Comment = "Internet ---> NT Server",
			Source = "any",
			Destination = "ntserver.com",
			Rule-Action = Allow,
			Log-Control = Log-Enabled,
			Log-File = "firewall\nt.com"


   o Specifying a Range of Ports

     The samples below demonstrate the available options for matching
     a selection of ports, using a combination of pre-defined operators
     and actual port numbers (or resolvable service names).

     Notice, when using NAT to provide services for internal LAN clients,
     ports above 10000 must generally be left open at the Firewall PC.

     The first example demonstrates how to deny 3 specific services 
     (ftp smtp and pop3). The Service names are looked up in the 
     %etc/services file (typically located in the mptn/etc directory):

	PORT-RANGE1	Comment = "Deny 3 ports",
			Source = "any",
			Destination = "fx.dk",
			Service-List = "ftp smtp pop3",
			Rule-Action = Deny


     This example demonstrates how to disable all ports below 10000:

	PORT-RANGE2	Comment = "Deny ports below 10000",
			Source = "any",
			Destination = "fx.dk",
			Service-List = "<10000",
			Rule-Action = Deny


     To define a range of ports, use the ':' operator. Both port 23
     and port 80 are inclusive:

	PORT-RANGE3	Comment = "Allow range of ports",
			Source = "any",
			Destination = "fx.dk",
			Service-List = "23:80",
			Rule-Action = Allow


     To define multiple ranges of ports, the following syntax is
     used:

	MULTIPLE-RANGES	Comment = "Allow multiple ranges of ports",
			Source = "any",
			Destination = "fx.dk",
			Service-List = "ftp:telnet 57:67 150:999",
			Rule-Action = Allow


     This example disables all ports (using the ':' operator), except the
     www-http port (using the '-' operator). Notice a rule like this
     for the firewall PC will effectively disable NAT for the LAN clients.

	DISABLE-ALL	Comment = "Deny all ports, except 80",
			Source = "any",
			Destination = "fx.dk",
			Service-List = "0:65535 -www-http",
			Rule-Action = Deny


     The following example allows all ports in the range 1024 to 4000,
     except those in the range from 3000 to 3500, which remain blocked
     (using the combination of the '-' and the ':' operator).
  
	PORT-HOLE	Comment = "Allow range of ports",
			Source = "any",
			Destination = "cyberspace.dk",
			Service-List = ">1024 <4000 -3000:3500",
			Rule-Action = Allow


   o IP Address Redirection

     The following example shows how to redirect incoming Telnet requests 
     to a Telnet server on the internal network with the IP Address 
     "192.168.1.20":

	PORTMAP-TELNET-IN	Comment = "Map incoming Telnet to internal server",
				Source = "any",
				Destination = "firewall.company.com",
				Service = TELNET,
				Rule-Action = Portmap,
				Mapping-Dest-IP = "192.168.1.20",
				Mapping-Dest-Port = TELNET


     To complete the port mapping, an extra rule must be defined to permit 
     redirection in the outgoing direction:

	PORTMAP-TELNET-OUT	Comment = "Map outgoing Telnet",
				Source = "192.168.1.20",
				Destination = "any",
				Source-Port = TELNET,
				Rule-Action = Portmap,
				Mapping-Dest-Port = TELNET


   o Port Mapping

     The following example shows a combination of port and IP address
     redirection. Incoming Web requests are mapped to port 8080 on the
     internal network. The IP address of internal PC is "192.168.1.20":

	PORTMAP-WEB-IN	Comment = "Map incoming Web to port 8080",
			Source = "any",
			Destination = "firewall.company.com",
			Service = WWW,
			Rule-Action = Portmap,
			Mapping-Dest-IP = "192.168.1.20",
			Mapping-Dest-Port = 8080


     To complete the port mapping, an extra rule must be defined to permit 
     redirection in the outgoing direction:

	PORTMAP-WEB-OUT	Comment = "Map outgoing Web back to port 80",
			Source = "192.168.1.20",
			Destination = "any",
			Source-Port = 8080,
			Rule-Action = Portmap,
			Mapping-Dest-Port = WWW


   o Accounting

     Accounting rules must be dedicated to the purpose, i.e. you cannot
     apply the accounting attributes to any type of rule, but only to
     rules with the 'Rule-Action' attribute set to the value 'Account'.

     The below rule defines accounting for services on ALL IP-addresses.

	ACCOUNT-SERVICE  	Comment = "Service Accounting (ftp, web, etc)",
				Source = "any",
				Destination = "any",
				Rule-Action = Account,
		                Account-Control = Enabled,
				Account-Type = Service,
				Account-File = "firewall\acc\service"


     The below rules define accounting per source and destination Network
     IP Address for all workstations on the 192.168.1.* segment. Two rules
     are used to update the same file. The first rule provides accounting for
     packets coming from the internal network and the second rule provides 
     accounting for packets coming into the internal network.

	ACCOUNT-IP-OUT		Comment = "Accounting per Source-IP",
				Source = "192.168.1.0",
				Destination = "any",
				Rule-Action = Account,
        		        Account-Control = Enabled,
				Account-Type = Source-IP,
				Account-File = "firewall\acc\ip-usage"

	ACCOUNT-IP-IN		Comment = "Accounting per Destination-IP",
				Destination = "192.168.1.0",
                	        Destination-Netmask = "255.255.255.0",
				Source = "any",
				Rule-Action = Account,
        		        Account-Control = Enabled,
				Account-Type = Destination-IP,
				Account-File = "firewall\acc\ip-usage"

     When two rules are updating the same file, it is crusial that they
     are of the same type. The two possible types are IP based accounting
     and accounting per Service. 

   o Logging

     Logging can be enabled in two possible ways. One way is to set the
     'Log-Control' attribute to the value 'Log-Enabled' in 'allow' or
     'deny' rules. The other way is by creating a rule with the sole
     purpose of logging. This can be done by setting the 'Rule-Action'
     attribute to the value 'Log' as in the below example:

	LOG-FX		Comment = "Log all references to fx.dk",
			Source = "any",
			Destination = "fx.dk",
			Rule-Action = Log,
			Log-Control = Enabled,
			Log-File = "firewall\fx.dk",
			Log-Mask = "rule date time msg prot source dest dump"


   o Alerting

     This sample shows you how to execute a command whenever a certain
     domain is addressed.

	FX-ALERT	Comment = "beep at fx.dk visits",
			Source = "any",
			Destination = "www.fx.dk",
			Rule-Action = Alert,
                        Alert-Type = Alert-Autostart,
			Alert-Info = "play.cmd dong.wav"


   o More samples

     Additional firewall sample rules are available in 'FIREWALL/SAMPLES.TXT'
     and 'FIREWALL/FIRERULE.CNF'.



==========================================================================
 15. O N   T H E   F L Y   U P D A T E S
==========================================================================



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

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

	1. Update the firewall 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 -firewall".

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





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

