Cloning the module in the FreeRADIUS source tree

For the FreeRADIUS 3.0 build system you'll have to clone this repository as a submodule in the FreeRADIUS source tree at src/modules/rlm_omapi, as such:

$ cd ~/src/freeradius
$ git clone ... src/modules/rlm_omapi
$ cd !$

(If you're using a FreeRADIUS version prior to 3.0, check out the Git tag pre-3.0 in this repository.)

Preparing rlm_omapi

The rlm_omapi module needs several libraries from ISC's DHCP daemon. Included in this repository is a script, bootstrap.sh, that will do all of this automatically for you:

$ ./bootstrap.sh
$ ./bootstrap.sh 4.2.0  # If you prefer a different version

Once you're done, skip to the section "Compiling rlm_omapi". If you want to do the steps manually, proceed as follows: Get the latest source tarball from https://www.isc.org/downloads/ and extract it to a subdirectory isc-dhcp/, e.g.:

$ wget -O isc-dhcp.tar.gz http://www.isc.org/downloads/file/dhcp-4-3-0b1/\?version=tar.gz
$ tar xfv isc-dhcp.tar.gz
$ ln -s dhcp-4.3.0 isc-dhcp

Then, compile the necessary libraries. Be sure to export the CFLAGS or make the library code relocatable in another way!

$ cd isc-dhcp/
$ export CFLAGS="-fPIC"
$ ./configure
$ make

Compiling rlm_omapi

Now, you can compile the module. Change to the top-level directory of FreeRADIUS and simply type make:

$ make
CC src/modules/rlm_omapi/rlm_omapi.c
LINK build/lib/rlm_omapi.la

Configuring the module

There is no configuration per se:

$ cat ~/server/etc/mods-enabled/omapi
omapi {
}

But you will need to define the attributes that will be used by this module in a dictionary somewhere. You could simply include the dictionary.example somewhere in your global dictionary:

$ grep omapi etc/dictionary
$INCLUDE        ../share/freeradius/dictionary.zedat.omapi

Of course, you are free to edit the number of the attributes as you wish. If you change the names, don't forget to also make the change in the rlm_omapi.c file, accordingly.

Configuring the DHCP server

Read the dhcpd.conf man page on how to create a suitable key. In practice, it works to just create some random secret (e.g. use pwgen 60) and then put the base64-encoded version of this secret here, while using the original secret in the rlm_omapi module!

omapi-port 4327;
key "radius-key" {
    algorithm hmac-md5;
    secret "base-64 of your secret here";
}
omapi-key radius-key;

Ad-hoc configuration of the module

The module can be configured "ad hoc" using "unlang" or for example a Perl module. This is done by simply filling information into "virtual attributes" that must be defined in a dictionary -- see the file dictionary.example for an example.

These attributes are are about the connection to the server:

Attribute name	Content	Example value
Zedat-Omapi-Host	DHCP server host name	dhcp.example.com
Zedat-Omapi-Port	DHCP server port	4327
Zedat-Omapi-Key	Secret key (no base64)	abcde12345
Zedat-Omapi-Key-Name	Key's name from dhcpd.conf	radius-key

These attributes decide which record will be entered in the server:

Attribute name	Content	Example value
Zedat-Omapi-User-Mac	Device's MAC address	3c:d9:2b:4b:f7:b8, note you must use colons!
Zedat-Omapi-User-IP	Device's IPv4 address	93.184.216.119
Zedat-Omapi-User-Host	Device's hostname	rather arbitrary, use e.g. IP address

The rlm_omapi module will then do the following steps:

1. Query the server if there is a lease with this MAC address. If yes, then compare the assigned IP addresses: in case they match, no update is needed; the module returns. In case they differ, this lease will be deleted on the server

2. Delete leases matching the wanted hostname, if any

3. Insert a lease of the following form:

   host <Zedat-Omapi-User-Host> {
     dynamic;
     hardware ethernet <Zedat-Omapi-User-Mac>;
     fixed-address <Zedat-Omapi-User-IP>;
   }
   

vim:set et sw=2 ts=2 ft=markdown: