Opengate Administration Memo
Preface
This document is a memo for Opengate administration. For
installation instructions, refer to the 'Installation Memo' page
on this site.
System Flow
When an user accesses a web server, Opengate - on the router -
catches the packet and sends back the authentication request
page. Opengate checks the userID and password, adds pass rules
to the firewall and sends an Ajax script to the user terminal.
If the TCP connection between the Ajax script and Opengate is
broken, Opengate removes the pass rules from the firewall. If
a cookie exists, the password is not needed for
re-authentication. Refer to 'the flow of the system' page on
this site.
Some Limitations
As Opengate is a web based system, it
cannot work on terminals without a web browser. When Ajax is
active, Opengate opens the network for the terminal, while an
Ajax script downloaded at authentication controls the TCP
connection. When Ajax is not active, Opengate opens the
network for a predefined period of time. In case of the
latter, the network is also closed prematurely when the
correspondence between MAC address and IP address is changed
or packets from/to the terminal are not found for a long time.
After closing the network, if the session cookie is confirmed,
Opengate can re-open the network without password. Opengate is
usable for control of network services other than web, but the
web authentication must be run first. Multiprocessing
environment is desirable for the simultaneous execution of the
Ajax page and network service processes.
Related Files
Opengate uses the following files. Refer to each file for the
details.
/usr/local/www/data/index.html.var = branching to multi language
index pages
/usr/local/www/data/opengate/* = web contents, [en/*] for English,
[ja/*] for Japanese
/usr/local/www/cgi-bin/opengate/* = CGI programs
/etc/opengate/opengatesrv.conf= Opengate configuration file
/etc/opengate/rc.firewall = ipfw initialization script
/var/log/opengate.log = log file written by syslog
/tmp/opengate.db = SQLite database (can be changed to
/home/sqlite)
/tmp/opengate.lock = file for exclusive control (can be removed)
The parameters described in this document are default values and
can be modified in opengatesrv.conf.
Working Process
Opengate starts as CGI, and one process supports one terminal. No
resident daemon process is needed. The 'ps ux' command shows the
process and related user/terminal information for Opengate. You
can 'KILL' the unnecessary process.
Firewall Control
Opengate uses the firewall 'ipfw' to open and close the network.
When an user is certified through web-based authentication, a pass
rule for the user terminal is added to the firewall. When the user
closes the web browser, the pass rule is removed. The rule numbers
10,000-40,000 are used for the pass rules. Use smaller rule
numbers to describe rules with a higher priority than the pass
rules. For example, if you want to allow access to a server
without authentication, use a rule number smaller than 10,000 for
the pass rule. On the other hand, please describe lower priority
rules with bigger rule numbers. The following is an example of
rules added, where a tag number (123) is attached to the packet
related to an IP address (10.10.10.250).
[ 10000 count tag 123 ip from 10.10.10.250 to any ]
[ 10000 count tag 123 ip from any to 10.10.10.250 ]
The description of how the tagged packets are handled by ipfw is
added at the bottom of the rule list. For example, the following
rule allows tagged packets to pass the firewall.
[ 60000 allow ip from any to any tagged 123 ]
The above rule is the default, but you can modify the rule to
further restrict access. A different tag number can be assigned to
each user group you want to treat differently. Refer to 'Specific
Setting for User Groups' in this document.
Authentication method
Opengate supports the following authentication methods.
POP3 = Judged by logging into a POP3 server.
FTP = Judged by logging into a FTP server.
RADIUS =Query to RADIUS server.
LDAP = Query to LDAP server.
PAM = Query to PAM module.
Opengate can be configured to refer to multiple authentication
methods sequentially. Opengate can be configured to separate the
certification servers for each user group.
Log file and Database
Opengate records login / logout information using 'syslog'. By
changing the syslog settings, you can transfer the information to
a file, to another server, or to a console screen (Refer to the
syslog manual). Opengate uses 'local1' as facility for syslog. In
addition, a SQLite database is employed to log the HTTP-Cookie and
related information. Since the volume of these log files increases
with time, please prepare some method to remove the old logs
(e.g., 'cron'). If a SQLite database file is not found, Opengate
creates a new file.
In SQLite DB, following table and
index are defined.
CREATE TABLE IF NOT EXISTS \
session (cookie TEXT PRIMARY KEY,\
userid TEXT, pid INTEGER, openTime TEXT, closeTime
TEXT,\
clientAddr4 TEXT, clientAddr6 TEXT, macAddr TEXT,\
ruleNumber4 INTEGER, ruleNumber6 INTEGER,duration
INTEGER,\
durationEntered INTEGER, cookieAuth INTEGER, language
TEXT, watchMode TEXT);
CREATE INDEX IF NOT EXISTS \
clientAddr4Index ON session (clientAddr4);
CREATE INDEX IF NOT EXISTS \
closeTimeIndex ON session (closeTime);
field name |
description |
cookie |
HTTP cookie for session
control, primary key (eg: '1234567890abcdef.....') |
userid |
User ID (eg:
'watanaby@guest') |
pid |
Process ID of watch process
(eg: 1234) |
openTime |
Date and time of opening
network (eg: '2012-01-02 12:34:56') |
closeTime |
Date and time of closing
network (eg: '2012-01-02 14::56:01' , set '-' before
closing) |
clientAddr4 |
IPv4 address of client (eg:
'192.168.0.100') |
clientAddr6 |
IPv6 address of client (eg:
'2001::1:2' , the address acquired first) |
macAddr |
MAC address of client (eg:
'00:11:22:33:44:55') |
ruleNumber4 |
IPFW rule number controlling
the IPv4 address (eg: 10000) |
ruleNumber6 |
IPFW rule number controlling
the IPv6 address (eg: 10000) |
duration |
Limit time length at time
watch mode (sec) (eg: 300) |
durationEntered |
Limit time length entered by
user in authentication request page (sec) (eg: 0 , set 0 at
no entry) |
cookieAuth |
Is the session started with
cookie authentication (1=auth by cookie, 0=auth by password
or other) (eg: 0) |
language |
Description language of the
web page(eg: en) |
watchMode |
Watch mode (HTTP、TIME、NONE)
(eg: 'HTTP') |
Configuration File
Various settings for Opengate are described in
/etc/opengate/opengatesrv.conf (XML format). At the very least,
you should modify Opengate server name and authentication method
as described at the beginning of the file. Other modifications are
optional. Do not put needless 'space characters' in the XML tag
description. IP address and domain name can be entered as the
server name.
<OpengateServerName>opengate.og.saga-u.ac.jp</OpengateServerName>
<AuthServer>
<Protocol>pop3s</Protocol>
<Address>192.168.0.2</Address>
</AuthServer>
Multiple Authentication Servers
Multiple authentication servers can be set as follows. In this
example, Opengate initially refers to the first server(
192.168.0.1:pop3s ) . If the response is delayed for about 10
seconds or a negative response is provided, Opengate refers to the
next server (192.168.0.2:ftp). If a positive reply is provided
from one of servers, the user is authenticated. Otherwise the user
is denied.
<AuthServer>
<Address>192.168.0.1</Address>
<Protocol>pop3s</Protocol>
<Timeout>10</Timeout>
</AuthServer>
<AuthServer>
<Address>192.168.0.2</Address>
<Protocol>ftp</Protocol>
<Timeout>10</Timeout>
</AuthServer>
Specific Setting for User Groups
When you want to modify configuration parameters for an user
group, please use the <ExtraSet> tag in the configuration
file. In the following example, the authentication server and the
ipfw tag number are overwritten for users who enter a user ID
attaching '@guest' (e.g., foobar@guest).
<ExtraSet ExtraId="guest">
<AuthServer>
<Address>192.168.0.1</Address>
<Protocol>ftp</Protocol>
</AuthServer>
<IpfwTagNumber>999</IpfwTagNumber>
</ExtraSet>
In the next example, the <ExtraSet> indicates the user
matched to 'user1' or 'user2' exactly (without ExtraId). The
UserIdPattern is the 'POSIX Extended Regular Expression'. Using
this setting, the syslog is redirected to a different destination.
<ExtraSet ExtraId="default"
UserIdPattern="^user1$|^user2$">
<Syslog>
<Enable>1</Enable>
<Facility>local2</Facility>
</Syslog>
</ExtraSet>
If the tag doesn't need to be modified, you can omit the
description. But you must describe the all tags nested. For
example, the <AuthServer> tag can be omitted, but you must
describe all tags (<Enable> and <Facility>) nested in
<Syslog>, if you include the <Syslog> tag.
Web Page Design
You can change the web page design (e.g. adding a warning message
or emblem). Please revise the HTML file in HTML document
directories. As the marks '%%XXX%%' in HTML files are variables
replaced in CGI processing, do not change or delete these! Do not
use the relative URL in 'httpkeep.html'. Instead, use the absolute
URL from the document top. The English and Japanese pages are
provided. If you want to add other language page, create your
language directory and modify some of the settings (Refer to
'Recent QA' on this site).
Bug Report
If you encounter a problem with the system, please check the
following. First, confirm the normal operation of following
services independently.
[Apache, ipfw, nat, DNS, DHCP, SQLite, syslog, and
certification servers]
Try a simple authentication method (e.g., 'allow') temporarily, to
check if the certification server is working correctly. Check the
log files for these services and the Opengate. If you change the
value of the <Debugt> tag in the Opengate configuration file
to '2', the trace of the function call is dumped to syslog. The
Opengate homepage may also provide you with a hint for a possible
solution to your problem.
In case of abnormal termination, Opengate tries to clean the
residue as much as possible. But the ipfw rule, the process, and
the log record might remain in rare cases. A script to clean the
residue is explained in 'installation memo' on this site.
Periodical rebooting is recommended. Opengate is a CGI script
(initiated by Apache), so even if a CGI terminates abnormally,
CGIs for other users should still work normally.
When you find bugs, we are happy if you report it.