



                            SafeFire Firewall

                               Version 1.2

              Copyright (C) 1999-2004 Link Guard Solutions Ltd.

                      CONFIGURATION GUIDE AND REFERENCE



Contents

    1. Introduction
    2. Variables and sections
    3. General considerations
    4. Known sections and variables
        4.1. [nat]      - NAT engine general parameters
        4.2. [timeouts] - NAT engine timeouts
        4.3. [cleanup]  - NAT engine cleanup parameters
        4.4. [ident]    - IDENT server configuration
        4.5. [portmap]  - Port mapper configuration
        4.6. [filter]   - Packet filter configuration
        4.7. [mfilter]  - MAC packet filter configuration
        4.8. [remote]   - Remote control configuration
        4.9. [log]      - Message logging configuration
        4.10 [dhcp]     - Interface parameters tracking
        4.11 [device]   - NDIS device driver and special flags
        4.12 [shaper]   - traffic shaper configuration
        4.13 [plugins]  - filter plugins configuration

 1. Introduction

    SafeFire Firewall is configured trough plain text configuration file.
    By default SafeFire Firewall uses file SFIRE.CFG from the current
    directory. Alternate configuration file can be specified by using
    command line parameter:

    sfire -f<file>

    Default configuration file provided in the package contains reasonable
    assumptions about configuration but you may tune it for your purposes.


 2. Variables and sections

    Each configuration file consists of few parts, called 'sections'.

    Each section starts from section name bracketed in square brackets:

        [section]

    Each section consist of several variable definitions, comments and
    empty lines. If fist non-blank character is '#' or ';' then line is
    considered comment. Empty lines and comments are ignored.
    Samples of comments:

        ; this is sample comment
        # this is comment too


    Variable definition is a construction like this:

        variable = value

    Different variables can contain different types of values.
    Set of variables is fixed. Variables can be one of two different types:
    single instantiated and multiple instantiated. Variables of first
    type can be defined only once. If it is defined more that once,
    new value replaces old one. For variables of second type, such
    as packet filter rules each occurrence in configuration file
    creates new instance of the variable.

 3. General considerations

    Configuration of SafeFire Firewall can be split into two steps:

        1. Configuration of general parameters
        2. Configuration of packet filter

    First task is described in this file. Second task is described in
    the "Packet Filter Guide and Reference" book.

    SafeFire Firewall is designed to process TCP/IP traffic going through
    one particular LAN interface. This means that SafeFire Firewall
    is unable to protect other LAN or serial interfaces and protection
    should be done with other tools.

    As a first step we recommend to use default configuration
    and make connection up and running. Then step by step
    configure packet filter and other parameters on the running copy
    of the SafeFire Firewall with Remote Control (see Administration Utility
    Guide and Reference) and then put changes into configuration file
    which will be used by SafeFire Firewall on next restart.


 4. Known sections and variables

    Following sections are recognized and used by SafeFire Firewall:

        [nat]      - NAT engine general parameters
        [timeouts] - NAT engine timeouts
        [cleanup]  - NAT engine cleanup parameters
        [ident]    - IDENT server configuration
        [portmap]  - Port mapper configuration
        [filter]   - Packet filter configuration
        [mfilter]  - MAC packet filter configuration
        [remote]   - Remote control configuration
        [log]      - Message logging configuration
        [dhcp]     - Interface parameters tracking
        [device]   - Device driver configuration

    Each variable described with its default value if any.


   4.1.  [nat]      - NAT engine general parameters

    Following variables are recognized:

        enable=yes          This variable enables NAT.
                            Disabling of NAT may be useful if only
                            packet filter is required.

        defragment=yes      This variable enables assembling packets
                            before translation.

        forward_ignored=no  This variable enables forwarding of packets
                            ignored by NAT.

        private_net=yes     This variables reduces set of internal IPs
                            which will be translated to three ranges
                            (see RFC1918):
                            10.0.0.0     ->   10.255.255.255
                            172.16.0.0   ->   172.31.255.255
                            192.168.0.0  ->   192.168.255.255

        deny_incoming=no    This variable prevents incoming connections
                            (e.g. to telnet, ftp, web servers).


   4.2.  [timeouts] - NAT engine timeouts

    Each connection in the NAT engine is presented as a link of
    particular type. Each type of link has its own idle timeout.
    When this timeout expires at the next housekeeping
    it will be removed from NAT engine. All values are in seconds.

    Following variables are recognized:

        icmp = 60           ICMP links

        udp = 60            UDP links

        tcp = 300           TCP links (initial value)

        header = 10         TCP header fragment
        fragment = 30       TCP body fragment
                            Header and body fragments are stored in the
                            NAT engine before assembling if
                            'defragment' option is turned on.

        broken = 10         TCP broken connection

        halfbroken = 90     TCP partially broken connection

        connected = 86400   TCP connected at both sides link



   4.3.  [cleanup]  - NAT engine cleanup parameters

    Cleanup is done with specified interval and at each cleanup
    only part of links is processed.

    Following variables are recognized:

        interval = 60       This variable determines time interval
                            between cleanups in seconds.

        spokes = 30         This variable determines number of table
                            rows processed during each cleanup.



   4.4.  [ident]    - IDENT server configuration

    IDENT is an Internet protocol used by some services (IRC,
    sometimes SMTP) for verifying that connection is not spoofed.
    Although this method is not very reliable but most of the IRC
    servers don't allow connection if connection is made from
    host without running IDENT service.
    Response generated by IDENT server contains name of the
    user who owns the connection.

    Following variables are recognized:

        enable=yes          This variable enables built in IDENT
                            server (IDENTD)

        user=os2user        User name returned in response to request



   4.5.  [portmap]  - Port mapper configuration

    Port mapper is a feature which enables forwarding and processing
    of incoming connections on the other host. For example:

        Local area network with private IP address space used shares
        the DSL connection to Internet. Local WEB server is installed
        on the PC with IP address 192.168.1.15 and gateway PC has
        an internal IP 192.168.1.100 and external IP (provided by ISP)
        123.45.67.123. With port mapper it is possible to allow access
        to the WEB server at 192.168.1.15 from Internet.
        Appropriate rule is:

            rule = 123.45.67.123:80,192.168.1.15:80

    NOTE: disabling of NAT will disable port mapping too, because
    each port mapping is a NAT link of special type.

    Following variables are recognized:

        rule = <rule definition>

    <rule definition> has following format:

        from_ip:from_port, to_ip:to_port [proto] [number]

    from_ip     IP address of the destination of the packet.
                If 0 is used then current IP address assigned to SafeFire
                interface is assumed.

    from_port   Port to which connection is going.

    to_ip       IP address where connection will be redirected.

    to_port     Port number to which connection will be redirected.

    proto       One of the TCP, UDP.

    number      Number of ports.
                Specifying of this number is equivalent to writing
                appropriate number of rules each of them with increased
                from_port and to_port:

                    rule = from_ip:from_port, to_ip:to_port n

                is the same as:

                    rule = from_ip:from_port, to_ip:to_port
                    rule = from_ip:from_port+1, to_ip:to_port+1
                    ...
                    rule = from_ip:from_port+(n-1), to_ip:to_port+(n-1)



   4.6.  [filter]   - Packet filter configuration

    Following variables are recognized:

        enable=no           Enable packet filter

        rule=               Packet filter rule definition.


    More details about packet filter rules are found in the "Packet Filter
    Guide and Reference" book.


   4.7.  [mfilter]   - MAC packet filter configuration

    Following variables are recognized:

        enable=no           Enable MAC packet filter

        rule=               MAC packet filter rule definition.


    More details about packet filter rules are found in the "MAC Packet Filter
    Guide and Reference" book.

   4.8.  [remote]   - Remote control configuration

    Remote control (RC) enables 'on the fly' configuration of the nearly
    all parameters of the SafeFire Firewall. For compatibility connections
    from address 127.0.0.1 are always enabled.

    Following variables are recognized:

        enable=yes          Enable remote control

        port=1021           TCP/IP port for RC server

        userid="userid"
        password="password" User login and password used for authentication
                            of the remote user.

        deny=<range>
        allow=<range>       Access control rules for Remote Control

            where:

                <range>     any|ip[{/bits|:mask}]

                    any     0.0.0.0/0   - all IP addresses

                    ip      net or host address

                    bits    number of bits for mask:
                            8  is equivalent to mask 255.0.0.0
                            16 is equivalent to mask 255.255.0.0
                            24 is equivalent to mask 255.255.255.0

                    mask    IP address mask


    Each incoming connection is checked against allow and deny rules.
    The order of these check are allow, deny. This means that IP address
    of the remote end of the connection will be checked against all 'allow'
    rules and if match will be no found then connection will be refused.
    If match will be found then that IP address will be checked against
    all 'deny' rules. If match will be found then connection will be refused.
    If match will not be found then connection will be accepted
    and RC server will authenticate user. If authentication will be successful
    then connection will be established and remote control server
    will perform commands from the user.



   4.9.  [log]      - Message logging configuration

    Logging facility of SafeFire Firewall is implemented using SYSLOG
    service. This facility has many advantages but the main advantage is
    ability to process messages from different programs in convenient and
    consistent manner.
    Please, refer to OS/2 TCP/IP documentation for information how to
    install and configure SYSLOG daemon.


    Following variables in this section are recognized:

        console=yes         Enable printing of the messages to console

        level=6             Logging level.
                            It defines how detailed messages will be.
                            Highest level is 7. In this case SafeFire Firewall
                            will log some messages which can be interesting
                            only for the troubleshooting or debugging purposes.
                            Lower levels will produce less messages.



   4.10  [dhcp]     - Interface parameters tracking

    SafeFire Firewall provides support for dynamically assigned
    IP addresses. Knowledge of IP address is important for NAT engine
    and packet filer rules with 'myip' address.

    Following variables in this section are recognized:

        interval=5          This variable defines interval in seconds
                            between checks of IP address of interface.
                            Value below or equal to 0 disables check.

        auto_pipe=off       Enable automatic detection of the assignment
                            of the IP address by DHCP and switching into
                            working mode.
        run=""              External application (including command line
                            parameters) which will be executed on each
                            IP address change. Command line may contain
                            control sequences which will be replaced with
                            following information:

                            %1 - with new IP address in usual dot-delimited form
                            %2 - with old IP address in usual dot-delimited form
                            %3 - with new IP mask in usual dot-delimited form
                            %4 - with old IP mask in usual dot-delimited form

        clear_arp=no        Enable clearing ARP cache after IP address change.
                            This option is intended for troubleshooting, when
                            gateway stops accessing external systems after IP
                            address change.

   4.11 [device]   - NDIS device driver and special flags

    This section is intended for future support of multiple interfaces
    and special switches.

        unit=0              This variable defines the SafeFire Firewall
                            driver set number to work with if the SafeFire
                            Firewall is configured to work on several
                            interfaces.

        broken_arp=no       If this variable is set to YES, it turns on
                            workaround for broken ARP ioctl's in some
                            versions of MPTN.

        filter_all=no       If this variable is set to YES, all packets
                            will be routed through the NAT engine regardless of
                            its MAC addresses.

        fastmode=no         If this variable is set to YES, it turns on
                            the fast NDIS mode, which should improve
                            performance on high speed interfaces. Default is NO.

        quedepth=8          This variable defines the size of packet queue in
                            4 Kb blocks for reading / writing packets to / from
                            net. Lowest value is 1, highest value is 15.

        dropbcast=no        Instruct SFPROT to drop broadcast Ethernet frames.
                            Use it with care - it can break ARP protocol.

        assembly=yes        Do fragmented packets assembling.

        assemblytimeout=60  Seconds to wait for packet fragments for its
                            assembling.

   4.12  [shaper]   - Traffic shaper configuration

    Following variables are recognized:

        sleep=milliseconds  Interval of sleep time within the traffic shaper loop

        pipe=               Shaper pipe definition.


    More details about shaper pipes are found in the "Traffic Shaper
    Guide and Reference" book.

   4.13  [plugins]  - Filter plugins configuration

    SafeFire Firewall provides the ability of using external plugins
    in Packet Filter or MAC Packet Filter facilities. The information of
    use plugins in these filter rules is found in corresponding filter
    reference books.

    Following variables are recognized:

        plugin=             External plugins definition.

        extvar=             External plugins parameters definition.

    More details about external plugins are found in the "External Plugins
    Guide and Reference" book.


EOF

