OpengateMd - MAC address check and firewall control daemon


This is a daemon performing network opening and closing by checking the MAC address of the packet on the gateway.  The MAC address and the user ID to admit are registered to a MySql database beforehand.  The  registration and the update are performed by OpengateMreg and OpengateMup.

The procedure is as follows.


  1. A document about the trial in VirtualBox is newer. At first, refer to the document linked to the top page.

  2. Setup FreeBSD on a PC having two or more NICs. If you have Opengate gateway, the installation of MySQL and OpengateMd are only needed.

  3. Add the following line to "/etc/rc.conf" to enable the gateway function:

  4. Install SQLite3 and the client function of MySQL.  If you run MySQL server locally, install the servar function of MySQL.

  5. To use the version 0.8.0 or later, set the following line in /etc/sysctl.conf to enable ipfw Layer2 control.

  6. If you replace the packeage from 0.7.X to 0.8.X,  do the following

  7. If you use Web interface on the gateway, install Apache2 and configure it.  The cgi programs are added in the  installation of OpengateMreg and OpengateMown.

  8. Following settings are not essential.  If you want to install them, Refer other site or Opengate site.
    Setup DHCP server.
    Setup BIND.
    Setup IPv6.

  9. Unpack the archive linked in top page and install it from directory [mdsrc] as follows, where [0.0.0] is the version number.

    tar xzvf opengatem0.0.0.tar.gz
    cd opengatemd0.0.0/mdsrc
    sudo make install

    If opengatemd is already running, the install is failed.  At that case, do as follows.
    sudo opengatemd -s    <==Stop the daemon
    sudo make install        <==Install
    sudo opengatemd       <==Restart the daemon

  10. An execute file, a configuration file sample, and a start script are added to the following places in default.


  11. Modify the configuration file to fit to the environment. The items you need to change are MySQL setting (MySqlDb/Server,User,Password)  and Pcap capturing device (Pcap/Device).
    cd /etc/opengate
    cp opengatem.conf.sample opengatem.conf
    vi opengatem.conf

  12. Refer to the documentation of opengateMsql and set up the MySQL database.

  13. Add following lines to "/etc/rc.conf" to enable firewall.  The NATD setting is optional.  Interface name for natd indicates the upper network interface.

  14. Edit firewall script "/etc/openate/rc.firewall" to match your address and nic.

  15. Edit /etc/syslog.conf to save log entries for OpengateM.  And create the log file [e.g.:  touch /var/log/opengate.log ].

              | * Separate by TAB code
    local1.*  /var/log/opengate.log

  16. Start the daemon and try to access by a terminal.  To start daemon, enter [opengatemd] under the root user privilege.  The packets from registered terminals only pass through the gateway.

  17. Add the following lines to [/etc/rc.conf] to start the daemon at system booting.


  18. Add the following line to [/etc/crontab] to reload the deamon once in a day.  Or prepare a file to execute this command in the derectory [/etc/periodic/daily/].

    48      3       *       *       *       root    /usr/local/bin/opengatemd -r


  1. To run as a daemon, enter  [opengatemd]  under the root user privilege.

  2. To run as a console mode, enter  [opengatemd -c] .

  3. To end service, enter [opengatemd -e].  The daemon removes firewall rules and temporary work database records, and terminates.

  4. To stop service for a while, enter [opengatemd -s] (stop mode). The daemon leaves firewall rules and the database records, and terminates.  If you restart daemon, the service can continue.

  5. To reload daemon, enter [opengatem -r].  The daemon sends HUP to the old daemon, and terminates.  When there is no old daemon, it merely starts.

  6. The configuration file [/etc/opengate/opengatemd.conf] includes various settings.

    <CacheTimeout> = effective time of MAC address cache (e.g., 5 minutes):
    <UselessTimeout> = It no packet is found in this time length, daemon deletes the firewall rule (e.g., 3 hours).
    <UselessCheckInterval> = Check interval for above condition (e.g., 1 hour).

  7. To see the program trace for debugging, change the Degug value to 2 or 3 in opengatemd.conf.  The trace of function call is dumped to syslog or console.

  8. As usage log in MySQL and syslog are enlarged, it is necessary to delete them periodically.

specific addresses

When the daemon detects the packet having indicated source MAC addresses, it is reported via syslog (Form ver.0.9.1).
  1. Setting of MySQL
    Watching addresses are indicated in [watchlist] table of MySQL database. ( If the table is not exist, create it by createtablescript ). The following example indicates two addresses (Address format is 2 charactors (numeric/lowercase) separated with colon).
           | macAddress        | reporting | memo       |
           | 11:22:33:aa:bb:cc | Y         | test1      |
           | 44:55:66:dd:ee:ff | Y         | test2      |
    If [reporting] is "Y",  the detection is reported.  If the table includes a [macAddress="ALL"] record, all addresses( exist in the table and not ) are reported.

  2. Setting of syslog
    Report puts on syslog with priority=warning. The following syslog.conf example indicates to put the warning reports to the system console.
    local1.!=warning   /var/log/opengate.log
    local1.=warning   /dev/console
    Added phpsrc/sendreportmail.php which send report mail to the connection detected user. Refer the source file for the usage.
    To use this, set as follows.
    local1.=warning   | /path/sendreportmail.php

  3. Enabling the setting
    Reload the daemon to  reflect the table data to the daemon (Above table data are loaded in memory at reloading the daemon with [opengatemd -r] ).   Also, reload syslog at updating syslog.conf.

  4. Timing of reporting
    Detecting is reported every timeout (<CacheTimeout> in conf) of the check cache.

Base Systems


Program Logic

The daemon repeats the following.
  1. With Pcap, the daemon captures a packet header and acquires the MAC/IP address pair.
  2. If the MAC/IP address pair is found in cache, the daemon skips the check of the packet (It means that the address pair was checked recently).
  3. The daemon checks whether the session for the address is found in the work database (It means that the firewall for the address was already opened).
  4. The daemon checks whether the MAC address is found in the management database.
  5. If Valid-Addr and No-Session, the daemon starts a session (opens the firewall and adds session info to the work database).
  6. If Valid-Addr and Valid-Session, the daemon updates the packet capture time for the session.
  7. If No-Addr and Valid-Session, the daemon removes the session (closes the firewall and removes the session info from work database).
  8. Periodically the daemon checks the packet capture time and removes unused sessions.
[Is the given MAC/IP address pair found in cache]
The logic is implemented with a Hush table (Key=MAC/IP address pair, Value=registration time) and a Queue (FIFO list of the MAC address pair).
  1. The procedure searches for the given address in the Hush table.
  2. If the given address is found in the Hash table and the registration time is newer than a cache retention limit (Checked recently)., the procedure returns TRUE.
  3. If the given address is found in the Hash table and the registration time is older than the cache retention time (Expired)., the procedure carries out the following.
    1. Until the given address is found in the Queue, the procedure removes addresses from the Queue (FIFO order), and the same addresses from the Hash table.
    2. The procedure restores the given address to the Hash table and the Queue, then returns FALSE.
  4. If the address is not found in the Hash table (Not checked), the procedure registers the address to the Hash table and the Queue, then returns FALSE.
[Terminate the unused session]
  1. Do nothing, if designated time does not pass from previous check.
  2. Update the previous check time to now.
  3. Finishes the session, if the detection time of the last packet is older than a designated time.
  4. Compare the DB record and IPFW rule, and remove the unpaired one.
  5. Remove the session when it is controlled by Opengate but has no watching process.

[IPFW firewall control]

IPFW rule set is scanned two times (Layer2 check and layer3 check) for each packet.  In layer2 scan (rules including MAC), a tag is attached to the packets from/to the indicated MAC address. In Layer3 scan, the packets having the tag is allowed. The Web packets (not allowed) is forwarded to the localhost to show the registration page or warning page. The tag attaching rules are inserted/removed by the daemon.

10000 count tag 123 ip from any to any MAC any 11:22:33:44:55:66 keep-state
10000 count tag 123 ip from any to any MAC 11:22:33:44:55:66 any keep-state
60000 allow ip from any to any tagged 123
60010 allow ip from any to any MAC any any
60100 fwd tcp from any to any dst-port 80
60900 deny ip from any to any