[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.0 The oasis implementation

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] [ ? ]

1.0.1 How oasis is designed

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:

  1. The access server "probes" the user by sending a "probe" that the user has to respond to. This "probe" will most likely be some sort of ping. To make the system flexible, 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.

  2. The second mode of operation is to use 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] [ ? ]

1.0.2 Format of the requests

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'
LOGIN USER=username\rPASS=password\rDOMAIN=domain\rIP=ip-address\rMAC=mac-address\r\n

`LOGOUT'
LOGOUT\rUSER=username\rDOMAIN=domain\r\n

`STATS'
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] [ ? ]

1.0.3 Compiling oasis

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] [ ? ]

1.0.4 Configuring oasis

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
Time between consecutive probe scans of the users. Each scan consists of probe-max-users probes.

probe-max-users
Maximum number of users to probe in each scan.

max-missed-probes
Maximum number of probes a user can miss before the user is considered away and logged out by the system

probe-timeout
Timeout, in seconds, before a probe is considered failed and is cancelled. Must be less than probe-interval.

socket-path
Path to the UNIX socket. Default is /tmp/oasis.

socket-owner
Owner and group to set for the socket. Owner and group are separated by a dot, as in root.nobody.

socket-mode
The permissions to set for the socket. Both the syntax used by 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
What facility to use when loggin to syslog. The following arguments are recognised:

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
Timeout, in seconds, before the execution of a firewall control program is considered failed and a SIGTERM is sent to shutdown the process. Default is 15 seconds.

firewall-hard-timeout
Timeout, in seconds, before the shutdown of a firewall control program is considered failed and a SIGKILL is sent to the process. Default is 5 seconds.

backlog
Specifies how many pending requests should be put in the queue of incoming requests before a "Connection refused" error message is sent to the client. Default is 50.

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
Defines the maximum number of users allowed to be logged in concurrently. If the value specified is -1, no limit is enforced, which also is the default.

max-same-users
The maximum number a user can connect to the same account from different machines (different MAC addresses). Default is 1. The special value -1 means no limit (except the max-users limit above).

firewall-program
The program to run when controlling the firewall. The firewall control program is called with the following parameters:

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
Instead of running a local script to control the firewall, connect to this host (which must be running fwcd, the firewall control daemon).

fwcd-port
Remote port used when connecting to the firewall control daemon (using the firewall-host option above). The default port is 1717.

port
This is the port used to listen for connection from fwcd, when fwcd decides to logout a user.

certificate-file
This is the certificate used when identifying to fwcd. Default is `/usr/local/etc/oasis.cert'.

key-file
The private key used when identifying to fwcd. Default is `/usr/local/etc/oasis.key'.

fwcd-certificate-file
This is the certificate that will be expected from fwcd. Default is `/usr/local/etc/fwcd.cert'.

pam-service
What PAM service to use to authenticate user on this domain. The PAM service name is also the name of the file in `/etc/pam.d/' directory. This directive is mandatory.

probe-library
The plugin library to use to probe users. If no library or an empty string is specified, no probing will be performed.

probe-interface
Specifies what interface to use to probe users. The ARP probe plugin uses this when constructing the ARP packet.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.0.5 Starting Oasis

Options are specified by the usual GNU command line syntax, with long options starting with two dashes (--).

Usage: oasis [options]

Options:

`-f'
`--fg'
Run in foreground, don't fork. When in foreground the log messages are sent directly to the console instead of to syslog.

`-r `FILE''
`--rcfile=`FILE''
Read configuration file `FILE' instead of the default one in `/usr/local/etc/oasis.conf'.

`-d'
`--debug'
Show debug messages.

`-F'
`--force'
Continue even if the socket already exists (it will be overwritten). Make sure no other oasis process is running.

`-h'
`--help'
Show a short help message describing the syntax.

`-V'
`--version'
Show the version number.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.0.6 PAM

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] [ ? ]

1.0.7 The firewall control program

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] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About this document

This document was generated by Oden Eriksson on November, 10 2004 using texi2html

The buttons in the navigation panels have the following meaning:

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  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated by Oden Eriksson on November, 10 2004 using texi2html