1.5. omshell --- OMAPI command shell¶
1.5.1. Synopsis¶
omshell
1.5.2. Description¶
omshell provides an interactive way to connect to, query, and possibly change a DHCP server's state via OMAPI --- the Object Management API. By using OMAPI and omshell, changes can be made to the state of a DHCP server while the server is running. omshell provides a way of accessing OMAPI.
OMAPI is simply a communications mechanism that allows manipulation of objects. In order to actually use omshell, there should be an understanding of what objects are available and how to use them. Documentation for OMAPI objects can be found in the documentation for the server that provides them, in the dhcpd(8) and dhclient(8) manual pages.
1.5.3. 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 DHCP 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.
1.5.4. Opening a connection¶
omshell is started from the command line. Once omshell is started, there are several commands that can be executed:
server <address>
This command specifies the IP address of the DHCP server to connect to. If it is not specified, the default server is 127.0.0.1 (localhost).
port <number>
This command specifies the OMAPI port number of the DHCP server. By default, this is 7911.
key <name> <secret>
This command specifies the TSIG key to use to sign OMAPI transactions. <name> is the name of a key defined in dhcpd.conf(5) using the
omapi-keystatement. <secret> is the secret key generated using dnssec-keygen(1) (from the Loop DNS distribution), or using another key generation program.
connect
This command starts the OMAPI connection to the server provided by the
servercommand.
1.5.5. 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(8) and dhclient(8). When 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, the following command is used:
new <object-type>
<object-type> is one of
group,host, orlease.
At this point, a new object would have been created on which properties can be set. For example, if a new lease object was created with new lease, any of a lease's attributes can be set using the following command:
set <attribute-name> = <value>
Attribute names are defined in dhcpd(8) and dhclient(8). Values should be quoted if they are strings. So, to set a lease's IP address, the following command may be used:
> set ip-address 192.168.4.50
1.5.6. Associating local and remote objects¶
At this point, the server can be queried for information about this lease, by using the following command:
open
Now, the local lease object that was created --- and IP address set 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.
1.5.7. Viewing a remote object¶
To query a lease of address 192.168.4.50 and find out its attributes, after connecting to the server, the following commands may be used:
> 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 be 192.168.4.50.
> open
Now, if a lease with that IP address exists, all the information the DHCP server has about that particular lease is shown. Any data that isn't readily printable text will show up in colon-separated hexadecimal values. In this example, output 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 can be seen above, the IP address is represented in hexadecimal, as are the starting and ending times of the lease.
1.5.8. 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, output from the server may look as follows if the corresponding set and update commands are executed:
> 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
1.5.9. New remote objects¶
New remote objects are created much in the same way that existing server objects are modified. A local object is created using the new command, attributes are set as desired, and then the remote object is created with the same properties by using the following command:
create
Now a new object exists on the DHCP server which matches the properties that were set on the local object. Objects created via OMAPI are saved into the dhcpd.leases(5) file.
For example, the following shows how a new host with the IP address of 192.168.4.40 is created:
> 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
The dhcpd.leases(5) 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; statement is used to indicate that this host entry did
not come from dhcpd.conf(5), but was created dynamically via
OMAPI.
1.5.10. Resetting attributes¶
An attribute may be removed from an object by using the unset
command. Once an attribute has been unset, the update command must
be used to update the remote object. So, if the host "some-host"
from the previous example should not have a static IP address anymore,
the commands run 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>
Warning
Include the result of running the unset command as well in the output above.
1.5.11. Refreshing objects¶
A local object may be refreshed with the current remote object's properties using the refresh command. This is useful for objects that change periodically, like leases, to see if they have been updated. This isn't particularly useful for hosts.
1.5.12. 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 the open command, and then using the
remove command. If the host "some-host" from before was created
in error, it could be removed using the following command:
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>
1.5.13. Help¶
The help command prints out all of the commands available in omshell with some syntax pointers.
1.5.14. See also¶
dhcpctl(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5)
1.5.15. Copyright¶
Copyright (C) 2025 Banu Systems Private Limited. All rights reserved.
Copyright (c) 2012,2014 by Internet Systems Consortium, Inc. ("ISC").
Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC").
Copyright (c) 2001-2003 by Internet Software Consortium.