Sending a Server Shutdown Message via OMAPI
  • 29 Oct 2018
  • 1 Minute to read
  • Contributors
  • Dark
    Light
  • PDF

Sending a Server Shutdown Message via OMAPI

  • Dark
    Light
  • PDF

Article Summary

OMAPI is the control channel specification for dhcpd, and you can use it to modify the config of a running server by adding host objects, subnets, etc.

You can also use it to send control messages to the server, for example to put a server in failover mode or to tell it to stop operating.

Here's a simple example of how to use the omshell utility provided with ISC dhcpd to shut down the server.

The OMAPI port must be defined in dhcpd.conf and it's a good idea to use a secure key. Keys can be generated with the dnssec-keygen utility distributed by ISC with BIND. See the dhcpd.conf man page for example syntax.

# dhcpd.conf
#
# Sample configuration file for ISC dhcpd
#

omapi-port 7911;
omapi-key omapi_key;

key omapi_key {
     algorithm hmac-md5;
     secret Ofakekeyfakekeyfakekey==;
}

# option definitions common to all supported networks...
option domain-name "example.org";

default-lease-time 600;
max-lease-time 7200;


subnet 192.168.56.0 netmask 255.255.255.0 {
    range 192.168.56.200 192.168.56.210;
}

Here's an example script that uses omshell to send commands to a DHCP server on the local machine to instruct it to shut down.

#!/bin/sh

#  uses omshell to connect to a dhcp server on the
#  local machine, create a control object, set the
#  state of the control object, and update the
#  running server to cause that server to shut down
#  gracefully.
#
#  per dhcpd man page, server shutdown can take 
#  several seconds as the server waits for close
#  on all OMAPI connections.  Watching log files 
#  for shutdown messages is recommended.

omshell << END_OF_INPUT > /dev/null 2> /dev/null
server localhost
port 7911
key omapi_key Ofakekeyfakekeyfakekey==
connect
new control
open
set state=2
update
END_OF_INPUT

echo "done sending shutdown instruction to dhcp server.."

Shutdown is not instantaneous with this method
Using this method, it can take some time to shut down dhcpd. The dhcpd man page says: "On shutdown the server will also attempt to cleanly shut down all OMAPI connections. If these connections do not go down cleanly after five seconds, they are shut down preemptively. It can take as much as 25 seconds from the beginning of the shutdown process to the time that the server actually exits."