In this document, we use the system configuration as follows. The network connecting terminals is called "lower-side network" and the network having servers is called "upper-side network".
upper-side network:192.168.0.0/24, 2001:db8:1:2:3/64 |
Opengate recognizes both IPv4 and IPv6 addresses, and controls both firewalls. It can be used for IPv4 control only if the FreeBSD environment is not set up for IPv6.
The following steps are necessary to complete the installation of
Opengate.
Items marked with '*' are mandatory.
The Opengate support page can be consulted at:
http://www.cc.saga-u.ac.jp/opengate/index-e.html |
Use FreeBSD4.x or later. FreeBSD6.1 or later is preferred.
Choose distribution "Developer (Full sources, binaries and doc)" or "all"
because we have to compile a custom kernel.
Add the following line to "/etc/rc.conf", to enable the gateway function:
|
Preparing the kernel to include IPFW functionality.
*As the recent kernel includes ipfw in default, reconstruction is not needed. Skip following reconstruction and start from setting of /etc/rc.conf.
Make a new kernel configuration file:MYKERNEL
# cd /usr/src/sys/i386/conf |
Following is the content of the file: MYKERNEL
include GENERIC |
Compile and install the new kernel (incl. added support for IPFW and IP6FW).
#cd /usr/src |
It might be failed in old FreeBSD. In the case, execute the following.
# config MYKERNEL |
"make clean" might be requested before "make depend".
Add the following lines to "/etc/rc.conf":
a. FreeBSD6.0 or earlier
firewall_enable="YES" |
b. FreeBSD6.1 or later
firewall_enable="YES" |
When enabling IPFW (and IP6FW), make sure to also set the firewall_type
to 'OPEN', to prevent unpredictable system behavior during installation.
To enable NAT, set natd_enable to 'YES' and define the natd interface
(Upper-side interface).
Connect a client pc to the lower-side network and check the IPv4
behavior.
Since DHCP is not yet set up, the client's network settings must be
configured manually.
If you need IPv4 only, this section can be skipped.
Though explanation is omitted, many parameters, like the ones used in the
following sample, can be set in /etc/rc.conf.
It is advised to read up on IPv6 and carefully set up its parameters.
##ENABLE IPv6 |
Connect a client pc to the lower-side network and check the behavior of
IPv6.
On a Windows pc, the command "ipv6 install" might be needed to activate
IPv6.
You can ignore DNS settings, if you control with IP address base or use existing DNS servers.
* Instead of BIND, it is recommended to use Unbound included in the recent FreeBSD versions.
Installing BIND9 from ports:
Note: The "sysinstall" command can also be used. If /usr/sbin/named
exists, configure files in /etc/namedb.
# cd /usr/ports/dns/bind9/ |
During installation the directory "/etc/namedb (/var/named/etc/namedb)" is created.
Use the "rndc" command to further secure BIND9.
Create the rndc key as follows:
# cd /etc/namebd/ |
This will generate the "rndc.conf" file.
# Start of rndc.conf |
After installation, look for the "/etc/namedb/named.conf" file and copy the last half of the "rndc.conf" file to it, making sure to remove comments, and add IPv6 configuration where/if required.
# Use with the following in named.conf, adjusting the allow list as needed: |
For security reasons, it is better to write the "key" directive in the other file.
Edit the "options" directive in "named.conf":
options { |
Create the corresponding "pid" directory.
Edit the "zone" directives in "named.conf".
zone "og.saga-u.ac.jp" { type master; file "og.saga-u.ac.jp"; }; |
Make a "zone" file for the domain "og.saga-u.ac.jp".
The domain name and IPv4/6 addresses should be modified properly. If you
don't need IPv6, remove the line containing "AAAA ....".
$TTL 3600 $ORIGIN og.saga-u.ac.jp. @ IN SOA ns.og.saga-u.ac.jp. postmaster ( 2005051702 ; 3600 1200 2419200 86400 ) IN NS ns.og.saga-u.ac.jp. IN A 192.168.1.1 IN MX 10 opengate.og.saga-u.ac.jp. ns IN A 192.168.1.1 opengate IN A 192.168.1.1 IN AAAA 2001:db8:5:6:7::1 |
Confirm starting of "named" after completings its configuration.
# /usr/local/sbin/named -u bind -c /etc/namedb/named.conf |
If "named" starts without problems, add the following lines to "/etc/rc.conf" to allow it to automatically start on boot up.
named_enable="YES" |
Because the management of a DNS server can be complicated, it is strongly advised to carefully read the BIND9 manual, and/or consult other documentation.
If many client PCs are going to be connected, using the DHCP service might be a desirable solution for assigning IP addresses to these clients.
Installing isc-dhcp3 from ports:
Note: the "sysinstall" command can also be used.
# cd /usr/ports/net/isc-dhcp3-server |
The"/usr/local/etc/dhcpd.conf.sample" configuration file is created
during installation.
Copy "dhcpd.conf.sample" to "dhcpd.conf" and edit the file.
The following is an example setup:
The lease time must be greater than the maximum usage duration
(Duration/Max in opengatesrv.conf).
The domain name and IP addresses should be modified.
option domain-name "og.saga-u.ac.jp"; |
Add the following lines to "/etc/rc.conf" to allow it to automatically start on boot up.
dhcpd_enable="YES" |
In this example, the value of "dhcpd_ifaces" is the interface providing
the DHCP service
(to the lower-side network).
When using IPv6, Opengate needs Apache2 to support IPv6.
By default, Apache2 supports SSL which is preferred for secure
authentication.
Installing Apache2 from ports:
Note: The "sysinstall" command can also be used.
# cd /usr/ports/www/apache22 |
It is better to obtain a formal key from some CA. But we will show you how to create a self-signed private key and certificate.
Creating a private key:
# cd /usr/local/etc/apache22 |
Making a certificate from the created key:
# /usr/bin/openssl req -new -x509 -days 365 \ |
Edit "/usr/local/etc/apache22/extra/httpd-ssl.conf" as shown in the following example:
ssl.conf |
<VirtualHost _default_:443> |
Since Apache2 has many settings, familiarize yourself with the Apache2 configuration options for adequate control.
Edit "/usr/local/etc/apache22/httpd.conf" as follows:
Opengate should send back the authentication page in response to any kind
of HTTP request.
To do so, add the following line to httpd.conf:
(the top page will be sent back on an HTTP_ERROR 404 [file not found]
error).
ErrorDocument 404 / |
Add "ExecCGI" to allow executing CGI programs in the cgi-bin directory.
<Directory "/usr/local/www/cgi-bin"> |
Remove the comment mark ("#") to enable the following setting:
AddHandler cgi-script .cgi |
Add "index.html.var" to DirectoryIndex:
DirectoryIndex index.html.var index.html |
Include ssl conf file:
Include etc/apache22/extra/httpd-ssl.conf |
Set ServerName:
ServerName opengate.og.saga-u.ac.jp |
Start Apache2 with "apachectl start" and check for errors.
If no errors are displayed, add the following lines to "/etc/rc.conf" to
allow Apache to start on boot up:
apache22_enable="YES" |
If the system shows "Failed to enable the 'httpready' Accept Filter", add the following to /boot/loader.conf :
accf_http_load="YES" |
Should the certificate require a PASSPHRASE, Apache will ask for it
during boot up.
If you do not enter the passphrase (reboot due to power outage, remote
reboot, ,...), this will prevent
the server from starting Apache normally, i.e. leaving you with a possible
"crippled" server.
Easy fix:
1. create a simple script containing the following:
#!/bin/sh
echo "<passphrase goes here>"
2. add the following to httpd.conf:
SSLPassPhraseDialog exec:/path/to/above/script
Download archive file from SQLite site(www.sqlite.org). Install it as follows. Note: The "sysinstall" command and ports can also be used.
# tar xzvf sqlite-amalgamation-3.xx.xx.tar.gz |
Check the normal execution.
# sqlite3 |
Unpack the Opengate compressed file:
# tar xzvf opengatexxxx.tar.gz |
It contains the following directories:
doc: Documentation |
Check the settings in "opengatesrv/Makefile" and modify if needed:
HTMLTOP = /usr/local/www/apache22 |
Compile and Install in opengatesrv directory:
# make clean |
Copy the sample configuration file "/etc/opengate/opengatesrv.conf.sample" to "/etc/opengate/opengatesrv.conf" and modify it.
cd /etc/opengate |
The following settings must be changed:
<OpengateServerName>opengate.og.saga-u.ac.jp</OpengateServerName> |
In <OpengateServerName>, set the HOSTNAME(FQDN) or IP address of the opengate gateway server. If you want to use IPv6, you need to set the FQDN corresponding to both IPv4 and IPv6 addresses.
In <AuthServer>, set the information for the authentication server.
Opengate supports various authentication protocols. See the config file
for details.
To differentiate between erorrs caused by authentication server or those
caused by the opengate server, try the following setting first. This means
that any userid and password combination is accepted.
****Do not use this setting in real service**** |
The config file is XML. "#" marks in the file do not represent the start
of a comment.
Use XML-formatted comments like <!-- Comment String --> to disable a
description.
Opengate can pass authentication settings in the form of "userid@extid".
See the config file for more details.
By using this function, you can use different authentication servers for
many sections or guests.
When the primary authentication server does not reply, Opengate can resend the request to other authentication servers. See the config file for more details.
Caution: Do not delete the IPv6 related settings in the config file!
The IPv6 access is executed when the FQDN for IPv6 is prepared.
Write IPFW rules for Opengate.
Both IPv4 and IPv6 packets are controlled by IPFW.
A sample rule set for IPFW can be found in "/etc/opengate/rc.firewall.sample"
Copy the script and modify to fit your needs.
If you are not familiar with Ipv6, set IPv6 addresses as localhost
(*net6="0", *ip6="::1").
# cd /etc/opengate |
Modify the firewall settings in /etc/rc.conf as follows:
Be careful not to lock yourself out of the system after reloading the
firewall.
firewall_enable="YES" |
Familiarise yourself with the "ipfw" command.
The Opengate software sends out ipfw add/delete commands.
The directory /etc/opengate includes another file: 'ipfwctrl.pl.sample'. The file is an ipfw control perl script but is not used in default setting.
Edit /etc/syslog.conf to save log entries for Opengate.
| * Separated by TAB code V local1.* /var/log/opengate.log |
Make the log file as follows:
Consider using log rotation to control the size of this log file.
# touch /var/log/opengate.log |
Reboot the PC to enable setting and connect a PC to the lower-side
network and try to access a site in the upper-side network.
If it does not work properly, consult doc/progflow.html and
doc/protocol.txt to better understand the procedure. Also check the log
files for Opengate, httpd, system and others. To dump more information
from Opengate, set the <Debug> switch to "2" in opengatesrv.conf.
Also check the functions of related software. The error checking document
(errcheck.html) and Q&A documents (qa.html, recentqa.html on the web)
can be used for problem solving.
If you want to modify the contents of the web pages, edit the html files in the Opengate directories. The relative path cannot be used in httpkeep.html. Use the full URL description. The descriptions such as %%XXX%% are variables replaced by their proper values during CGI runtime.
Opengate uses the SQLite3 database to hold session information. The path of the database file is indicated with <SqliteDb> in opengatesrv.conf. It is recommended to change the default value to the proper directory. WWW sholud have write permission for the directory.
Example: |
The file and database table are created automatically.
As the file size incleases steadily, you should periodically trim or remove the file with cron (or manually). Following is a sample script to delete 3 day old records.
#!/bin/sh |
This section is optional.
If you want to graphically monitor the state of Opengate, MRTG can be used
but is not required.
MRTG (Multi Router Traffic Grapher) is a system to monitor network traffic. MRTG produces graphic images and HTML files.
You can install MRTG on the gateway server or another server. If you need to monitor multiple Opengate systems, it is advised to install MRTG on a separate server.
# cd /usr/ports/net-mgmt/mrtg/ |
MRTG creates "/usr/local/etc/mrtg/mrtg.cfg.sample" as the sample configuration file during installation. Copy mrtg.cfg.sample to opengate.cfg and edit the file:
################################################## |
Be sure to actually create the directory which you appointed in "WorkDir". MRTG creates its graphic images and HTML files in "WorkDir"
"Target[opengate]" contains the path to the program that hands its data
to MRTG.
(details explained below)
Create the shell script "/usr/home/user/bin/input.sh" with the following contents:
#!/bin/sh |
Run this shell script as standalone and confirm that you can acquire the following data:
5 |
Create the shell script "/usr/home/user/bin/input.sh" on a separate server.
#!/bin/sh |
Create the shell script "/usr/local/apache2/cgi-bin/output.sh" on the Opengate (gateway) server, and set the URL to $url, as explained above.
#!/bin/sh |
Run "input.sh" on another server and confirm that you can acquire the following data:
5 |
Use the following command to confirm MRTG is working with your config:
# /usr/local/bin/mrtg /usr/local/etc/mrtg/opengate.cfg |
Various WARNING messages are output the first
and second time, this is normal behavior
(as explained in the MRTG documentation)!
Some files are created in "WorkDir".
> ls -l |
Add the following line to "/etc/crontab":
*/5 * * * * root /usr/local/bin/mrtg /usr/local/etc/mrtg/opengate.cfg |
This section is optional.
When the Opengate process is not exited normally, superfluous rules might
be left behind.
Though it is very rare, the tools/rulechk script is made to handle such
situations. This script compares the Opengate process list and the
firewall rule list, and deletes the obsolete rules.
This script is compatible with Opengate Ver1.3.1 or above.