`omshell`

Connect, query, and change ISC DHCP server's state

Syntax:

omshell

The omshell utility is a command shell that provides an interactive way to connect, query, and possibly change, the ISC DHCP Server's state via OMAPI, the Object Management API. By using OMAPI and omshell, you don't have to stop, make changes, and then restart the DHCP server; you can make the changes while the server is running. The omshell utility provides a way of accessing OMAPI.

OMAPI is simply a communications mechanism that lets you manipulate objects. To actually use omshell, you must understand what objects are available and how to use them.

Documentation for OMAPI objects can be found in the description for servers that provide them (e.g. in the documentation for dhcpd).

Opening a connection

The omshell utility is started from the command line with several commands that can be issued:

server address

The IP address of the DHCP server to connect to. The default server is 127.0.0.1 (localhost).

port number

The Port that OMAPI listens on. By default, this is 7911.

key name secret

This specifies the TSIG key to use to authenticate the OMAPI transactions. The argument name is the name of a key defined in dhcpd.conf.

new object-type

The object-type is one of group, host, or lease.

At this point, you now have an object that you can set properties on. For example, if a new lease object was created with new lease, any of a lease's attributes can be set as follows:

set attribute-name = value

Attribute names are defined in dhcpd. Values should be quoted if they are strings. So, to set a lease's IP address, you would do the following:

    set  ip-address = 192.168.4.50

Associating local and remote objects

You can use the open command to query the server for information about this lease.

open: Now, the local lease object you created and set the IP address for is associated with the corresponding lease object on the DHCP server. All of the lease attributes from the DHCP server are also the attributes on the local object, and are shown in omshell.

Viewing a remote object

To query a lease of address 192.168.4.50 and find out its attributes, after connecting to the server, issue these commands:

new lease

This creates a new local lease object.

set ip-address = 192.168.4.50

This sets the local object's IP address to 192.168.4.50

open

Now, if a lease with that IP address exists, you'll see all the information the DHCP server has about that particular lease. Any data that isn't readily printable text will show up in colon-separated hexadecimal values. In this example, the server's output for the entire transaction might look like this:

> new "lease"
obj: lease
> set ip-address = 192.168.4.50
obj: lease
ip-address = c0:a8:04:32
> open
obj: lease

As you can see here, the IP address is represented in hexadecimal, as are the starting and end times of the lease.

Modifying a remote object

You can update attributes of remote objects by using the set command as before, and then an update command. The set command sets the attributes on the current local object; and the update command pushes those changes out to the server.

Continuing with the previous example, if a set client-hostname = something-else is issued, followed by an update command, the output would look like this:

> set client-hostname = "something-else"      
  
obj: lease
ip-address = c0:a8:04:32
state = 00:00:00:02
dhcp-client-identifier = 01:00:10:a4:b2:36:2c
client-hostname = "something-else"
subnet = 00:00:00:06
pool = 00:00:00:07
hardware-address = 00:10:a4:b2:36:2c
hardware-type = 00:00:00:01
ends = dc:d9:0d:3b
starts = 5c:9f:04:3b
tstp = 00:00:00:00
tsfp = 00:00:00:00
cltt = 00:00:00:00
<
> update

obj: lease
ip-address = c0:a8:04:32
state = 00:00:00:02
dhcp-client-identifier = 01:00:10:a4:b2:36:2c
client-hostname = "something-else"
subnet = 00:00:00:06
pool = 00:00:00:07
hardware-address = 00:10:a4:b2:36:2c
hardware-type = 00:00:00:01
ends = dc:d9:0d:3b
starts = 5c:9f:04:3b
tstp = 00:00:00:00
tsfp = 00:00:00:00
cltt = 00:00:00:00

New remote objects

You create new objects much in the same way as you modify existing server objects. Create a local object using new, set the attributes as you wish them to be, and then create the remote object with the same properties:

create

name = "some-host"
hardware-address = 00:80:c7:84:b1:94
> set hardware-type = 1
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 1
> set ip-address = 192.168.4.40
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 1
ip-address = c0:a8:04:28
> create
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = c0:a8:04:28
>

Your dhcpd.leases file would then have an entry like this in it:

host some-host {
dynamic;
hardware ethernet 00:80:c7:84:b1:94;
fixed-address 192.168.4.40;
   }

The dynamic; line is to denote that this host entry didn't come from dhcpd.conf, but was created dynamically via OMAPI.

Resetting attributes

If you want to remove an attribute from an object, you can do this with the unset command. Once you have unset an attribute, you must use the update command to update the remote object. So, if the host somehost from the previous example wouldn't have a static IP address any more, the commands in omshell would look like this:

obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = c0:a8:04:28
> unset ip-address
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = <null>
>
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = c0:a8:04:28
> remove
obj: <null>
>

In order to use the OMAPI interface, you must have the following line in your dhcpd.conf to specify a port:

omapi-port 7911;

where 7911 is the default used by dhcpctl() library.