====== DHCP server scripts ======

I run ISC's dhcpd on my own networks.

A friend also asked me to set up a Raspberry Pi as a VPN router for a motor caravan (which already had an ethernet / wireless router with a SIM card in it for mobile data access), and when I set up the DHCP server for the VPN, I decided it would be nice to have some alerting of when devices acquired or lost their DHCP leases.

This turned out to be a combination of easy and difficult.

The easy part is that the [[https://kb.isc.org/docs/isc-dhcp-41-manual-pages-dhcpdconf|DHCP server documentation]] tells you that you can set up an **on commit** event which can run a script when a lease is granted (either for the first time, or on renewal - I haven't found a way to tell the difference, which seems unfortunate).  You can also create events for **on release** and **on expiry**.

The difficult part is finding out what variables you can pass to the script which you might want to use when sending out a notification, for example.  The most obvious ones I can think of are the MAC address of the client requesting the lease, its hostname, and the IP address it gets assigned.

I managed to find [[https://jpmens.net/2011/07/06/execute-a-script-when-isc-dhcp-hands-out-a-new-lease/|an article]] which seemed very promising, but when I tried it, I got the IP address and the MAC address, but no hostname.

It took me **ages** to find out what you can use as parameters in these event triggers - the documentation for this could be described as atrocious, however I don't know whether something which doesn't exist can be described as atrocious - but I eventually ended up with the following, which did what I wanted:

<code>  on commit {
    set clip = binary-to-ascii(10, 8, ".", leased-address);
    set clra = binary-to-ascii(10, 8, ".", option dhcp-requested-address);
    set clhw = binary-to-ascii(16, 8, ":", substring(hardware, 1, 6));
    set clhn = option host-name;
    execute("/usr/local/bin/dhcpevent", "commit", clip, clhw, clhn);
  }

  on release {
    set clip = binary-to-ascii(10, 8, ".", leased-address);
    set clhw = binary-to-ascii(16, 8, ":", substring(hardware, 1, 6));
    set clhn = option host-name;
    execute("/usr/local/bin/dhcpevent", "release", clip, clhw, clhn);
  }

  on expiry {
    set clip = binary-to-ascii(10, 8, ".", leased-address);
    set clhw = binary-to-ascii(16, 8, ":", substring(hardware, 1, 6));
    execute("/usr/local/bin/dhcpevent", "expiry", clip, clhw);
  }</code>

The magic part was **set clhn = option host-name;**.  I found a list of all the option names at https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcp-options

Note that there are some paramteters you don't get access to - for example, you can't find out the hostname of the client which had an address which has now expired (hence there is no **clhn** in the **on expiry** section above).  I'm not certain about the **on release** section yet, although I suspect the same rule applies.

Note about getting the first lease and renewing it later:

I thought the option dhcp-message-type (documented in the last link shown above) might let me identify a DHCPdiscover separately from a DHCPrequest, but alas it always contains code 3 for DHCPrequest.  I suspect the reason for this is that the **on commit** event only occurs after the client has sent a Request, so nothing gets triggered before that.

I hope this is of some use to anyone trying to do the same thing.

----
[[.:|Go up]]\\
Return to [[:|main index]].