The BOOTP relay agent is a modified version of ISCs dhcrelay version 3.0. The relay agent has been modified to instead of sending a recieved DHCP message to one or more servers it now sends the DHCP message to only one server based on the MAC address of the requesting client. This is achieved by looking up the MAC address in a database consisting of mappings between MAC addresses and providers. The database is a PostgreSQL and is accessed trough libpq.

The database has the following definitions:

@verbatim CREATE TABLE T_provider ( provider_id SERIAL, provider_name text, provider_dhcp inet, provider_auth_url text, provider_net inet, provider_netmask inet, primary key (provider_id));

CREATE TABLE T_macbind ( mac_addr macaddr, provider_id bigint, mac_reg_date timestamp, primary key (mac_addr));

CREATE VIEW V_mapping AS SELECT M.mac_addr, P.provider_dhcp, P.provider_net, P.provider_netmask, P.provider_auth_url FROM T_macbind AS M,T_provider AS P WHERE M.provider_id = P.provider_id;

GRANT ALL ON T_provider TO macbind; GRANT ALL ON T_macbind TO macbind; GRANT ALL ON V_mapping TO macbind;

In the table T_provider:

`provider_id': A serialnumber identifying the provider that is used to bind mac addresses to it.
`provider_name': The name of the provider and is also displayed to the users when choosing provider.
`provider_dhcp': The IP address of the dhcpserver of the provider.
`provider_auth_url': The URL to the providers authentication page.
`provider_net': The IP address of the network that the dhcpserver should hand to a client.
`provider_netmask': The netmask for `provider_net'.

In T_provider there has to exist one entry with `provider_name' = "default" to be used as default when a (MAC address, provider) binding is not available.

In the table T_macbind:

`mac_addr': The macaddress of the client.
`provider_id': Referes to the table T_provider
`mac_reg_date': A timestamp of when this MAC address last received a DHCP lease. This is used to delete old entries in the database.

The view V_mapping is just a way to ease up the queries to the database so that the client only has to make one query to get the (MAC address, provider) binding.

2.1.1 Compiling the relay agent

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.1.1 Compiling the relay agent

Unpack the DHCP sources and apply the patch:

tar zxf dhcp-3.0.tar.gz cd dhcp-3.0 patch -p0 < ../dhcp.patch

Now configure and make DHCP:

./configure make make install

The relay agent does not need any configuration. All neccessary information is retrieved from the MAC database.

For more instructions, see the included documentation in the original ISC DHCP sources.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.2 The registration services

The registration service lets users choose the provider to use. It is a web page that records the users choice in the MAC database.

When the user wants to authenticate to the network, he enters the registration page. This page looks up the MAC address of the requesting client in the MAC database and redirects the user to the real authentication webpage of the chosen ISP. The registration page also makes it possible for the user to change ISP.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3 Setting up the MAC database

PostgreSQL is used for the MAC database.

Install PostgreSQL
PostgreSQL is available as convenient packages for many GNU/Linux distributions, including RedHat (+ clones) and Debian.
Alternatively, one can download and compile PostgreSQL from source. The sources are available from http://www.postgresql.org/. Instructions for compiling PostgreSQL are included in the sources.
Create the database
createdb macbind
Create a user
createuser -P macbind
The -P option will ask you for a password to protect the macbind database. In the current version of the system, this password is hardcoded as macbind_qwerty into the access and DHCP relay sources. This really has to be fixed.

Initialize the database

psql -U macbind -f init-macbind.sql macbind

Configure access permissions
Edit the PostgreSQL access configuration file to allow connections to the macbind database with a password. Add the following line to /etc/postgresql/pg_hba.conf:
local macbind password

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4 The oasis implementation

This chapter describes the oasis implementation.

2.4.1 How oasis is designed    How it works

2.4.2 Format of the requests

2.4.3 Compiling oasis    Compiling the sources

2.4.4 Configuring oasis

2.4.5 Starting Oasis    Starting oasis

2.4.6 PAM

2.4.7 The firewall control program    Controlling the firewall

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.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 2.4.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:

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.
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]

[ ? ]

2.4.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]

[ ? ]

2.4.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]

[ ? ]

2.4.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]

[ ? ]

2.4.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]

[ ? ]

2.4.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]

[ ? ]

2.4.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.5 The firewall control daemon

fwcd is a daemon that runs on the firewall. This requires that the firewall is an ordinary computer and not a dedicated router (such as a Cisco router). It communicates with Oasis, who sends requests to fwcd to login a user. The firewall control daemon will then start to listen on the traffic to decide if the user is logged in or not. When the user is inactive (but still connected), fwcd starts to ping the user until he is active again.

This solves the problem of too much probing, since the firewall doesn't need to actively probe all the time.

2.5.1 Starting fwcd

2.5.2 Configuring fwcd

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.5.1 Starting fwcd

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

Usage: fwcd [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/fwcd.conf'.
`-d'
`--debug': Show debug messages.
`-h'
`--help': Show a short help message describing the syntax.
`-V'
`--version': Show the version number.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.5.2 Configuring fwcd

The configuration file is by default installed as `/usr/local/etc/fwcd.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 an 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 directives are:

probe-interval

Time between consecutive checks of the users' traffic.

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

max-missed-probes

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

firewall-soft-timeout

Timeout, in seconds, before the execution of the firewall program is considered failed and a SIGTERM is sent to shutdown the process.

firewall-hard-timeout

Timeout, in seconds, before the shutdown of the firewall program is considered failed and a SIGKILL is sent to the process.

firewall-program

The program to run when controlling the firewall. The firewall 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).

port

What port to use when listening for the connection from oasis.

probe-interface

What interface to use when listening for traffic and probing users.

oasis-host

The host oasis is running on.

oasis-port

The port oasis listens on for the connection from fwcd.

probe-library

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

certificate-file

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

key-file

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

oasis-certificate-file

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

network

This is the network and mask we're listening on. Can be specified either on the format "192.168.1.0/24" or "192.168.1.0 mask 255.255.255.0".

promiscuous

Integer specifying whether to sniff packets in promiscuous mode or not. Generally, setting promiscuous to 0 is a better choice since the firewall only needs to listen on traffic to be routed through that machine.

[ << ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

This document was generated by Martin Hedenfalk on May, 2 2002 using texi2html