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);

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.