Copyright (c) 2008-2019, Hans Liss <Hans@Liss.pp.se>

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-----------------------------------
NOTICE (2017-05-27): I no longer have an environment set up for testing gluff.
Consequently, the more recent dhcp patches, while carefully checked and
test-built, have not been test run. Please let me know if you run into
problems, and I'll try to help as best I can. If you make changes to make
something broken work and want to contribute, send me a pull request, a
patch or instructions and I'll try to incorporate your changes if they make
sense to me.
-----------------------------------

Welcome to Gluff!

Gluff is the result of an idea by Magnus Törnros <magnus.tornros (at) systeamnat.se>
to collect and collate dhcp logging information from multiple DHCP servers
into a database for later retrieval, and the idea soon grew to the current
design after a number of brainstorming sessions between us.

Gluff was developed for a well-defined purpose: In an environment with
DHCP servers in a failover configuration and switches using DHCP snooping
and option 82 to imprint switch ID and switch port into passing DHCP
requests, it is used to keep track of all leases from start to end,
including the remote-id and circuit-id. It must be possible to determine
where a particular IP address is connected at any given time.

The theory is simple: Unless the failover mechanism is failing, each DHCPACK
sent out, from any DHCP server in the system, denotes an official lease or
lease extension. Thus, for every DHCPACK, our patched dhcpd logs an entry
in a "queue" table in a local sqlite3 database (chosen because it's supposed
to have high performance and be easy to use).

Another process on the DHCP server computer, gluff, regularly consumes
entries from the queue, accesses a MySQL database on a remote server shared
by all the DHCP servers, and figures out whether the entry denotes a new
lease or a lease extension. gluff updates the MySQL database accordingly,
and so the database will contain correct lease records for every distinct
lease ever granted.

This is what you need to do:

On the DB server:

In terms of Ubuntu packages, you will need mysql-server, and you will also probably want to set up
phpmyadmin, which will happily give you apache, php5-mysql and other stuff.

 * Configure mysql to listen to network interfaces - check "bind-address" in /etc/mysql/my.cnf or wherever it is.
 * Create a database (here called dhcpd_leases), and a user with permission to connect from the DHCP servers (substiture your own server addresses here):
    create database dhcpd_leases
    grant all on dhcpd_leases.* to 'dhcpd'@'192.168.10.10' identified by 'foobar'
    grant all on dhcpd_leases.* to 'dhcpd'@'192.168.11.10' identified by 'foobar'
 * Create the tables, using the commands in dhcpd_leases.sql


On the DHCP servers:

You will want at least the following: libmysqlclient15-dev, libmysqlclient15off, libsqlite3-dev
Optional are mysql-client and sqlite3
To compile stuff, you also need gcc, build-essentials and possibly more stuff, like kernel headers

 * Download and patch the version of ISC dhcp that you want to use, build, install and run it with the -ldb parameter to point out an sqlite3 database, here "/var/db/dhcpd_queue.db3"
 * Configure, build and install gluff - it will by default install into /opt/gluff
 * Run gluff with the following command
       /opt/gluff/bin/gluff -l /var/db/dhcpd_queue.db3 -h 192.168.15.10 -udhcpd -pfoobar -ddhcpd_leases -R
   where 192.168.15.10 is the address of the DB server.

gluff logs to "local2" so you can set up syslog to handle it according to your wishes.

Gluff autostart
--------------------
If you want gluff to start automatically like other system daemons, you can use the script provided in the "scripts" subdirectory:
These instructions are for Ubuntu, but there are equivalent provisions in all Linux distributions and it should be easy enough to adapt the instructions.
* Put the script in /etc/init.d
* Run the command "sudo update-rc.d gluff defaults"
* Create a file /etc/default/gluff with settings like these, adjusted to suit your environment:
  GLUFF_DBHOST=192.168.15.10
  GLUFF_DBUSER=dhcpd
  GLUFF_DBPWD=foobar
  GLUFF_DBDB=dhcpd_leases
  GLUFF_LDB=/var/db/dhcpd_queue.db3
  GLUFF_DEBUG=no

Now you can manually start gluff with the "service" command:
    service gluff start

-------------------------------------------------------------
If you are upgrading from version 1.7.3 or older:
Database changes in 1.7.4

If you are already running gluff and are upgrading to version 1.7.4, you should add the new 'id' field in the MySQL database. It's not currently used by gluff, but future additions to the system will take advantage of the new key field. Here's how to add it:

   alter table leases drop primary key,add id int auto_increment not null first, add primary key(id)

-------------------------------------------------------------
If you are upgrading from version 1.10 or older:
Database changes in 1.10

I have switched to "timestamp" fields in the database. The reason for this is that they store the time and date in UTC format and do automatic conversion between the UTC time and local time. This means that the database contains more "correct" information.

  alter table leases modify lstart timestamp not null default '0000-00-00 00:00:00';
  alter table leases modify lend timestamp not null default '0000-00-00 00:00:00';


/Hans@Liss.nu 2013-03-17