[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes the oasis
implementation.
1.0.1 How oasis is designed How it works 1.0.2 Format of the requests 1.0.3 Compiling oasis Compiling the sources 1.0.4 Configuring oasis 1.0.5 Starting Oasis Starting oasis 1.0.6 PAM 1.0.7 The firewall control program Controlling the firewall
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
oasis
is designed as a multi-threaded application. The main
thread listens on a UNIX socket for requests. Each request is
processed in order, one at a time. When a login request is received,
the user is authenticated via PAM (see 1.0.6 PAM) and, if successful,
the configured firewall control program is run to open up a rule for
that user (identified by MAC and IP address) in the corresponding
firewall.
The requests will typically be sent by the web frontend. In the www subdirectory of the source distribution there are PHP scripts that prompts for username and password, retrieves the IP and MAC addresses and sends a request to the access server.
oasis
uses PAM (Pluggable Authentication Modules) as
authentication mechanism. PAM is a highly configurable system, in
which one can plug in any authentication module. This system is used
on many UN*X systems and there exists many modules, including
Kerberos, Radius, plain passwd files and LDAP.
To prevent malicious users from using a valid user authenticated
connection after he has disconnected from the network, the rule in the
firewall must be closed when a user disconnects. oasis
has
two modes of operation to detect the presence of a user:
oasis
uses a plugin
system. Currently, there exists plugins for ARP ping and ICMP
ping. The probe plugin to use is configurable per domain.
If the user fails to answer a certain number of such "probes" the user is considered disconnected and the firewall is closed.
Each probe is run in a separate thread to simultaneously probe a (configurable) number of users. It is important to configure the number of simultaneous probes and the maximum number of users allowed in a good way. If too many users are probed simultanously this could create a flood ping. On the other hand, if too few users are probed, it will take a long time before a user is logged out.
fwcd
, the firewall
control daemon. When a user authenticates to the access server, a
request is sent to fwcd
(running on the firewall) to open up
the rule. The connection is secured using SSL. The firewall control
daemon then starts to listen on the traffic passed through it. If
packets arrive from the users MAC/IP address, he is active and no
active action is necessary. When the user is inactive (but still
connected) the firewall then starts to probe the user as described in
the previous mode until the user starts to send packets again.
This mode eases the load on the network by reducing the amount of "useless" traffic, but also requires that the firewall is able to run the daemon. This is not the case with dedicated routers.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The request is formatted as a string of ascii characters, terminated
with a linefeed - carriage return pair (\r\n). The first keyword is
the name of the command requested. Each keyword must be separated by
space. After the command keyword the arguments follow. An argument is
formatted as OPTION=VALUE
, each argument separated with a
linefeed character (\r
).
LOGIN USER=username\rPASS=password\rDOMAIN=domain\rIP=ip-address\rMAC=mac-address\r\n
LOGOUT\rUSER=username\rDOMAIN=domain\r\n
STATS\r\n
sends information about all logged in users.
STATS\rDOMAIN=domain\r\n
sends information about all logged in
users in the specified domain.
STATS\rDOMAIN=domain\rUSER=username\r\n
sends information about
the specified user in that domain.
After a request is processed, a reply is sent back. The reply is
formatted as RETURN-CODE ERROR-MESSAGE\r\n
. The return code can
be either 0 (successful) or 1 (failed). The ERROR-MESSAGE is a string
specifying the reason for failure.
See the test clients included in the source package for a more practical example of how requests are sent to the server.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
oasis
is distributed as a gzipped tarball. Type tar
zxf oasis-x.x.tar.gz
to unpack the sources (replace x.x with the
version number). This will create a directory `oasis-x.x'.
oasis
uses a configure script to adapt the sources to
different platforms. To configure the sources, simply run
./configure
in the top level directory of the source tree. The
script accepts some arguments, use ./configure --help
to see
them.
To build successfully, pthreads, libpcap and libnet are required (and their development headers). If you use a recent distribution, look for the packages libpthreads-dev[el], libpcap-dev[el] or libnet-dev[el].
The default install prefix is `/usr/local', but this can be
changed by passing the --prefix=PATH
argument to configure.
After the configuration step, simple type make
to compile the
sources. To install, type make install
as root.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The configuration file is by default installed as `/usr/local/etc/oasis.conf'. There is a template in the etc subdirectory of the source distribution that you can modify to your needs. The syntax is simple: each directive consists of a keyword, an equal sign and the argument, as in:
keyword = argument
Comments begin with #
or //
and extends to the end of
the line. Block comments can be written in C syntax, beginning with
/*
and ending in */
.
Valid global directives are:
probe-interval
probe-max-users
probes.
probe-max-users
max-missed-probes
probe-timeout
probe-interval
.
socket-path
/tmp/oasis
.
socket-owner
root.nobody
.
socket-mode
chmod
(1), as in "u=rw,g=wx,o=wr"
and octal mode can be
used. If octal mode is used, you must surround it in double quotes, as
in "0644"
.
log-facility
LOG_AUTHPRIV, LOG_DAEMON, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7, LOG_USER
firewall-soft-timeout
firewall-hard-timeout
backlog
To define a new domain, use the following syntax:
domain NAME { DIRECTIVES }
NAME
is used in the DOMAIN keyword sent in the request.
Recognized DIRECTIVES
in a domain definition are:
max-users
max-same-users
max-users
limit
above).
firewall-program
To open up a rule: <open> <IP> <MAC>
To close a rule: <close> <IP> <MAC>
To reset the firewall: <reset>
IP is a string in dotted-decimal form (xxx.xxx.xxx.xxx) and MAC is a colon-separated string of hex numbers (00:01:60:12:a7:bd).
This directive is mutually exclusive with the fwcd-host
directive.
fwcd-host
fwcd
, the firewall control
daemon).
fwcd-port
firewall-host
option above). The default port is 1717.
port
certificate-file
key-file
fwcd-certificate-file
pam-service
probe-library
probe-interface
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Options are specified by the usual GNU command line syntax, with long
options starting with two dashes (--
).
Usage: oasis [options]
Options:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A complete description of PAM (Pluggable Authentication Modules) is outside the scope of this document. More information can be found at http://www.kernel.org/pub/linux/libs/pam/.
PAM is used to do the actual authentication of a user. PAM is a general framework for authentication, accounting and password management. Only the authentication part is used in the access server. The framework uses a plug-in system where modules can be written to extend the system to support almost any kind of authentication mechanism. Today there exists modules for Kerberos, Radius, LDAP, password files and more.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If your domain is configured with firewall-program
, this option
specifies a program (a simple shell script) to be executed when
controlling the firewall. In the scripts subdirectory of the source
distribution the is a template to begin with.
The script is passed different parameters depending on what it should do. The first parameter is the action string which can be "open", "close" or "reset". The two first actions takes two more parameters, the IP and MAC address, as strings.
[Top] | [Contents] | [Index] | [ ? ] |
[Top] | [Contents] | [Index] | [ ? ] |
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ < ] | Back | previous section in reading order | 1.2.2 |
[ > ] | Forward | next section in reading order | 1.2.4 |
[ << ] | FastBack | previous or up-and-previous section | 1.1 |
[ Up ] | Up | up section | 1.2 |
[ >> ] | FastForward | next or up-and-next section | 1.3 |
[Top] | Top | cover (top) of document | |
[Contents] | Contents | table of contents | |
[Index] | Index | concept index | |
[ ? ] | About | this page |