• Share
  • Dark

Sending a Server Shutdown Message Via OMAPI

  • Updated on 24 Mar 2017
  • 2 minutes to read
  • Contributors 

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 netmask {    range;}

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/nullserver localhostport 7911key omapi_key Ofakekeyfakekeyfakekey==connectnew controlopenset state=2updateEND_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."

© 2001-2018 Internet Systems Consortium For assistance with problems and questions for which you have not been able to find an answer in our Knowledge Base, we recommend searching our community mailing list archives and/or posting your question there (you will need to register there first for your posts to be accepted). The bind-users and the dhcp-users lists particularly have a long-standing and active membership. ISC relies on the financial support of the community to fund the development of its open source software products. If you would like to support future product evolution and maintenance as well having peace of mind knowing that our team of experts are poised to provide you with individual technical assistance whenever you call upon them, then please consider our Professional Subscription Support services - details can be found on our main website.

Problems with this site? Email us at marketing@isc.org