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
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
- As the database access takes large cost, address cache is hold in
- A document about the trial in VirtualBox is newer.
At first, refer to the document linked to the top page.
- Setup FreeBSD on a PC having two or more NICs. If you have Opengate
gateway, the installation of MySQL and OpengateMd are only needed.
- Add the following line to "/etc/rc.conf" to enable the gateway
- Install SQLite3 and the client function of MySQL. If you run
MySQL server locally, install the servar function of MySQL.
- To use the version 0.8.0 or later, set the following line in
/etc/sysctl.conf to enable ipfw Layer2 control.
- If you replace the packeage from 0.7.X to 0.8.X, do the
- 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).
- 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
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).
Set server name
- Edit "etc/rc.conf" to start Apache.
- Following settings are not essential. If you want to install
them, Refer other site or Opengate site.
Setup DHCP server.
- 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
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
sudo opengatemd <==Restart the
- An execute file, a configuration file sample, and a start script are
added to the following places in default.
- 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).
cp opengatem.conf.sample opengatem.conf
- Refer to the documentation of opengateMsql and set up the MySQL
- Add following lines to "/etc/rc.conf" to enable firewall. The
NATD setting is optional. Interface name for natd indicates the
upper network interface.
- Edit firewall script "/etc/openate/rc.firewall" to match your address
- Edit /etc/syslog.conf to save log entries for OpengateM. And
create the log file [e.g.: touch /var/log/opengate.log ].
| * Separate by
- 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.
- Add the following lines to [/etc/rc.conf] to start the daemon at
- 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
When the daemon detects the packet having indicated source MAC addresses, it
is reported via syslog (Form ver.0.9.1).
- To run as a daemon, enter [opengatemd] under the root
- To run as a console mode, enter [opengatemd -c] .
- To end service, enter [opengatemd -e]. The daemon removes
firewall rules and temporary work database records, and terminates.
- 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.
- To reload daemon, enter [opengatem -r]. The daemon sends HUP to
the old daemon, and terminates. When there is no old daemon, it
- The configuration file [/etc/opengate/opengatemd.conf] includes
<CacheTimeout> = effective time of MAC address cache (e.g., 5
<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.,
- 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.
- As usage log in MySQL and syslog are enlarged, it is necessary to
delete them periodically.
- 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
| 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.
- 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.
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
- 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.
- Timing of reporting
Detecting is reported every timeout (<CacheTimeout> in conf) of
the check cache.
- FreeBSD/Ipfw = OS and firewall
- Libpcap = Packet capture library
- SqLite3 = temporal work database on each gateway
- MySQL = management database on a database server
- MySQL: opengatem R/W (management DB)
- SqLite3:opengatemd.db R/W (work DB for OpengateMd)
- SqLite3:opengate.db R (work DB for Opengate)
The daemon repeats the following.
- With Pcap, the daemon captures a packet header and acquires the MAC/IP
- 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).
- 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
- The daemon checks whether the MAC address is found in the management
- If Valid-Addr and No-Session, the daemon starts a session (opens the
firewall and adds session info to the work database).
- If Valid-Addr and Valid-Session, the daemon updates the packet capture
time for the session.
- If No-Addr and Valid-Session, the daemon removes the session (closes
the firewall and removes the session info from work database).
- Periodically the daemon checks the packet capture time and removes
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).
- The procedure searches for the given address in the Hush table.
- 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.
- 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.
- 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.
- The procedure restores the given address to the Hash table and the
Queue, then returns FALSE.
- 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
[Terminate the unused session]
- Do nothing, if designated time does not pass from previous check.
- Update the previous check time to now.
- Finishes the session, if the detection time of the last packet is
older than a designated time.
- Compare the DB record and IPFW rule, and remove the unpaired one.
- Remove the session when it is controlled by Opengate but has no
[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
10000 count tag 123 ip from any to any MAC any 11:22:33:44:55:66
10000 count tag 123 ip from any to any MAC 11:22:33:44:55:66 any
60000 allow ip from any to any tagged 123
60010 allow ip from any to any MAC any any
60100 fwd 127.0.0.1 tcp from any to any dst-port 80
60900 deny ip from any to any
- MySQL: opengatem R/W management database
- SqLite3: opengatemd.db R/W OpengateM temporary database
- SqLite3: opengate.db R Opengate database