Knowledge Base ISC Main Website Ask a Question/Contact ISC
Sending a Server Shutdown Message Via OMAPI
Author: Michael McNally Reference Number: AA-00475 Views: 15216 Created: 2011-09-29 00:04 Last Updated: 2017-03-24 16:46 0 Rating/ Voters

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 "";

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

subnet netmask {

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.


#  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==
new control
set state=2

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.

Feedback 2
  • #
    [ Tariq]: Control Object 2014-01-01 09:20

    Need to confirm if the control object works only for standalone server ? meaning that failover object is mutually exclusive with control object ? If we are using a failover server then do we need control object.

  • #
    [Brian Conry]: Re: Control Object 2014-02-10 15:49

    The control object and the failover object handle different aspects of the server and they have their own uses.

    The control object handles the server itself, and sending a shutdown there will cause the server to exit.

    The failover object handles only the specified failover communications channel (there may be multiple, each with a different peer).

    While shutting down the server completely does implicitly impact the failover channels, shutting down the failover channels does not impact the server's behavior on other channels or for pools that aren't associated with any failover relationships.

Quick Jump Menu