NAME
omshell - OMAPI Command Shell
SYNOPSIS
omshell
DESCRIPTION
The OMAPI Command Shell, omshell, provides an interactive way to connect to,
query, and possibly change, the ISC DHCP Server's state via OMAPI, the Object
Management API. By using OMAPI and omshell, you do not have to stop, make
changes, and then restart the DHCP server, but can make the changes while the
server is running. Omshell provides a way of accessing OMAPI.
OMAPI is simply a communications mechanism that allows you to manipulate
objects. In order 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 documentation for the server that provides them -
for example, in the
dhcpd(1) manual page and the
dhclient(1)
manual page.
CONTRIBUTIONS
This software is free software. At various times its development has been
underwritten by various organizations, including the ISC and Vixie
Enterprises. The development of 3.0 has been funded almost entirely by
Nominum, Inc.
At this point development is hosted by the ISC, but the future of this project
depends on you. If you have features you want, please consider implementing
them.
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
omshell is started from the command line. Once omshell is started, there are
several commands that can be issued:
server address
where address is the IP address of the DHCP
server to connect to. If this is not specified, the default server is
127.0.0.1 (localhost).
port number
where number is 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. 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
This starts 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(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, use
new object-type
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(8) and dhclient(8). 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
At this point, you can query the server for information about this lease, by
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:
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, 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 which matches the properties that you
gave your local object. Objects created via OMAPI are saved into the
dhcpd.leases file.
For example, if a new host with the IP address of 192.168.4.40 needs to be
created it would be done as follows:
> 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 have unset an attribute, you must use the
update command to update the remote object. So, if the host
"some-host" 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 object that change
periodically, like 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 will print out all of the commands available in omshell,
with some syntax pointers.
SEE ALSO
dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
AUTHOR
omshell is maintained by ISC. To learn more about Internet Systems
Consortium, see
https://www.isc.org