OMAPI is simply a communications mechanism that allows you to manipulate objects. In order to actually _u_s_e 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 ddhhccppdd((11)) manual page and the ddhhcclliieenntt((11)) manual page.
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 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 consider implementing them.
Throughout this document, there are references to local and remote objects. Local objects are ones created in omshell with the nneeww 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.
omshell is started from the command line. Once omshell is started, there are several commands that can be issued:
server _a_d_d_r_e_s_s 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 _n_u_m_b_e_r where number is the port that OMAPI listens on. By default, this is 7911.
key _n_a_m_e _s_e_c_r_e_t This specifies the TSIG key to use to authenticate the OMAPI transactions. _n_a_m_e is the name of a key defined in _d_h_c_p_d_._c_o_n_f with the oommaappii--kkeeyy statement. The _s_e_c_r_e_t is the secret generated from ddnnsssseecc--kkeeyyggeenn or another key generation program.
connect This starts the OMAPI connection to the server as specified by the _s_e_r_v_e_r statement.
Any object defined in OMAPI can be created, queried, and/or modified. The object types available to OMAPI are defined in ddhhccppdd((88)) and ddhhcclliieenntt. 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 _o_b_j_e_c_t_-_t_y_p_e _o_b_j_e_c_t_-_t_y_p_e 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 _n_e_w _l_e_a_s_e, any of a lease's attributes can be set as follows:
set _a_t_t_r_i_b_u_t_e_-_n_a_m_e _= _v_a_l_u_e AAttttrriibbuuttee nnaammeess aarree ddeeffiinneedd iinn ddhhccppdd((88)) and ddhhcclliieenntt((88)). Values should be quoted if they are strings. So, to set a lease's IP address, you would do the following: sseett iipp--aaddddrreessss == 119922..116688..44..5500
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.
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 _l_o_c_a_l 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.
Attributes of remote objects are updated by using the sseett command as before, and then issuing an uuppddaattee command. The sseett command sets the attributes on the current local object, and the uuppddaattee command pushes those changes out to the server.
Continuing with the previous example, if a sseett cclliieenntt--hhoossttnnaammee ==
""ssoommeetthhiinngg--eellssee"" was issued, followed by an uuppddaattee 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 are created much in the same way that existing server objects are modified. Create a local object using nneeww, 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 _d_y_n_a_m_i_c_; line is to denote that this host entry did not come from dhcpd.conf, but was created dynamically via OMAPI.
If you want to remove an attribute from an object, you can do this with the
uunnsseett command. Once you have unset an attribute, you must use the
uuppddaattee 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 =>
A local object may be refreshed with the current remote object properties using the rreeffrreesshh 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.
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 ooppeenn_, _a_n_d _t_h_e_n _u_s_i_n_g _t_h_e rreemmoovvee 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:>
The hheellpp command will print out all of the commands available in omshell, with some syntax pointers.