OpengateMd - MAC address check and firewall control daemon

Summary

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.

• The firewall on the gateway is closed by default.
• An user starts the network use with a terminal.
• Daemon captures the packet and refers to the database. If the sender's MAC address is confirmed, the daemon add a pass rule to the firewall.
• When no packet from the terminal is detected for a while, the pass rule is removed.
  
• It records usage log with the user ID at adding and removing the rule.
  
• As the database access takes large cost, address cache is hold in hand.
  

Installation

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:
   gateway_enable="YES"
   
   
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.
   net.link.ether.ipfw=1
   
   
6. If you replace the packeage from 0.7.X to 0.8.X,  do the following
   
   • Remove the old opengatemd.db (The primary key is changed.  New file is created automatically).
   • Add IPFW Layer2 all-pass rule at the bottom of rule list (Sample set is rc.firewall.sample in the archive).
     
   • Confirm that Layer2 check passes through OpengateMd rules[10000-50000] (Do not enter all-pass rule before rule 10000).
     
   
   
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.
   
   
   • Edit "/usr/local/etc/apache22/httpd.conf" as follows:
     
     Reply DocumentRoot when no document found.
     ErrorDocument 404  /
     
     Allow executing CGI program
     <Directory '/usr/local/www/cgi-bin'>
     Options ExecCGI
     </Directory>
     
     Remove the comment mark to enable the following settings:
     AddHandler cgi-script  .cgi
     AddHandler  tyep-map  .var
     
     Add "index.html.var" to DirectoryIndex.
     DirectoryIndex  index.html.var  index.html
     
     Include SSL conf file.  (SSL is not essential but recommended. (Refer other site or Opengate site for the setting of SSL).
     Include etc/apache22/extra/httpd-ssl.conf
     
     Set server name
     ServerName opengate.og.saga-u.ac.jp
     
     
   • Edit "etc/rc.conf" to start Apache.
     apache22_enable="YES"
     apache22ssl_enable="YES"
     
     
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.
    
    /usr/local/bin/opengatemd
    /etc/opengate/opengatemd.conf.sample
    /et/rc.d/opengatemd
    
    
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.
    firewall_enable="YES"
    firewall_script="/etc/opengate/rc.firewall"
    natd_enable="YES"
    natd_interface="fxp1"
    
    
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
              V
    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.
    
    opengatemd_enable="YES"
    
    
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
    

Usage

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

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

• FreeBSD/Ipfw = OS and firewall
• Libpcap = Packet capture library
• SqLite3 = temporal work database on each gateway
• MySQL = management database on a database server
  

Databases

• MySQL: opengatem R/W (management DB)
  
• SqLite3:opengatemd.db R/W (work DB for OpengateMd)
  
• SqLite3:opengate.db R (work DB for Opengate)

Program Logic

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.