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:

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
Delete leases matching the wanted hostname, if any

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:

Feh/rlm_omapi