omshell

Runs on:

QNX Neutrino

Options:

See the subcommands below.

Description:

The OMAPI Command Shell, omshell, provides an 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 and dhclient).

Local and remote objects

Throughout this document, there are references to local and remote objects. Local objects are ones created in omshell with the new command. Remote objects are ones on the server: leases, hosts, and groups that the DHCP server knows about. Local and remote objects are associated together to enable viewing and modification of object attributes. Also, new remote objects can be created to match local objects.

Opening a connection

You start omshell from the command line. Once omshell is started, there are several commands that can be issued:

server address

Connect to the DHCP server with the given IP address. If this is not specified, the default server is 127.0.0.1 (localhost).

port number

Specify the port for OMAPI to listen on. By default, this is 7911.

key name secret

Specify the TSIG key to use to authenticate the OMAPI transactions. The name is the name of a key defined in dhcpd.conf with the omapi-key statement. The secret is the secret key generated from dnssec-keygen or another key-generation program.

connect

Start the OMAPI connection to the server as specified by the server statement.

Creating local objects

Any object defined in OMAPI can be created, queried, and/or modified. The object types available to OMAPI are defined in dhcpd and dhclient. When you're using omshell, objects are first defined locally, manipulated as desired, and then associated with an object on the server. Only one object can be manipulated at a time. To create a local object, use:

new object-type

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

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

set attribute-name = value

Attribute names are defined in dhcpd and dhclient. Values should be quoted if they're 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

At this point, you can query the server for information about this lease, by typing:

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 now also the attributes on the local object, and will be 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, take the following steps:

1. new lease

   This creates a new local lease object.

2. set ip-address = 192.168.4.50

   This sets the local object's IP address to be 192.168.4.50.

3. open

   Now, if a lease with that IP address exists, you will 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, output back from the server 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
ip-address = c0:a8:04:32
state = 00:00:00:02
dhcp-client-identifier = 01:00:10:a4:b2:36:2c
client-hostname = "wendelina"
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

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

Modifying a remote object

Attributes of remote objects are updated by using the set command as before, and then issuing 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" was issued, followed by an update command, the output would look about 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

New remote objects are created much in the same way that existing server objects are modified. Create a local object using new, set the attributes as you'd wish them to be, and then create the remote object with the same properties by using:

create

Now a new object exists on the DHCP server that matches the properties that you gave your local object. Objects created via OMAPI are saved in the dhcpd.leases file.

For example, to create a new host with the IP address of 192.168.4.40, do the following:

> new host
obj: host
> set name = "some-host"
obj: host
name = "some-host"
> set hardware-address = 00:80:c7:84:b1:94
obj: host
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 did not 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've unset an attribute, you must use the update command to update the remote object. So, if the host somehost from the previous example will not have a static IP address anymore, 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>
>

Refreshing objects

A local object may be refreshed with the current remote object properties using the refresh command. This is useful for objects that change periodically, such as leases, to see if they have been updated. This isn't particularly useful for hosts.

Deleting objects

Any remote object that can be created can also be destroyed. This is done by creating a new local object, setting attributes, associating the local and remote object using open, and then using the remove command. If the host some-host from before was created in error, this could be corrected as follows:

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
> remove
obj: <null>
>

Help

The help command displays all of the commands available in omshell, with some syntax pointers.

Contributing author:

omshell was written by Ted Lemon of Nominum, Inc (now Akamai Technologies, Inc). Information about Nominum can be found at http://www.akamai.com. This preliminary documentation was written by Wendy Verschoor of Nominum, Inc., while she was testing omshell.