omshell
(1)
Name
omshell - OMAPI Command Shell
Synopsis
omshell
Description
User Commands omshell(1)
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 devel-
opment 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 being shepherded by Ted Lemon,
and hosted by the ISC, but the future of this project
depends on you. If you have features you want, please con-
sider 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).
SunOS 5.11 Last change: 1
User Commands omshell(1)
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 spec-
ified 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 prop-
erties 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
SunOS 5.11 Last change: 2
User Commands omshell(1)
To query a lease of address 192.168.4.50, and find out its
attributes, after connecting to the server, take the follow-
ing 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 particu-
lar 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 transac-
tion 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 hexa-
decimal, 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.
SunOS 5.11 Last change: 3
User Commands omshell(1)
Continuing with the previous example, if a set client-host-
name = "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 fol-
lows:
SunOS 5.11 Last change: 4
User Commands omshell(1)
> 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 previ-
ous 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
SunOS 5.11 Last change: 5
User Commands omshell(1)
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 cor-
rected 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 avail-
able in omshell, with some syntax pointers.
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+---------------+-------------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-------------------------------+
|Availability | service/network/dhcp/isc-dhcp |
+---------------+-------------------------------+
|Stability | Uncommitted |
+---------------+-------------------------------+
SEE ALSO
dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5),
dhclient.conf(5).
SunOS 5.11 Last change: 6
User Commands omshell(1)
AUTHOR
omshell was written by Ted Lemon of Nominum, Inc. Informa-
tion about Nominum can be found at http://www.nominum.com.
This preliminary documentation was written by Wendy Ver-
schoor of Nominum, Inc., while she was testing omshell.
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from
http://ftp.isc.org/isc/dhcp/4.1-ESV-R7/dhcp-4.1-ESV-
R7.tar.gz
Further information about this software can be found on the
open source community website at http://www.isc.org/soft-
ware/dhcp/.
SunOS 5.11 Last change: 7