1 .\" $Id: omshell.1,v 1.1.1.1 2005/12/07 10:50:32 sonic_amiga Exp $
3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (c) 2001-2003 by Internet Software Consortium
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
16 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .\" Internet Systems Consortium, Inc.
19 .\" 950 Charter Street
20 .\" Redwood City, CA 94063
22 .\" http://www.isc.org/
24 .\" This software has been written for Internet Systems Consortium
25 .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
26 .\" To learn more about Internet Systems Consortium, see
27 .\" ``http://www.isc.org/''. To learn more about Vixie Enterprises,
28 .\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
29 .\" ``http://www.nominum.com''.
32 omshell - OMAPI Command Shell
36 The OMAPI Command Shell, omshell, provides an interactive way to connect to,
37 query, and possibly change, the ISC DHCP Server's state via OMAPI, the Object
38 Management API. By using OMAPI and omshell, you do not have to stop, make
39 changes, and then restart the DHCP server, but can make the changes
40 while the server is running. Omshell provides a way of accessing
43 OMAPI is simply a communications mechanism that allows you to
44 manipulate objects. In order to actually \fIuse\fR omshell, you
46 understand what objects are available and how to use them.
47 Documentation for OMAPI objects can be found in the documentation for
48 the server that provides them - for example, in the \fBdhcpd(1)\fR
49 manual page and the \fBdhclient(1)\fR manual page.
52 This software is free software. At various times its development has
53 been underwritten by various organizations, including the ISC and
54 Vixie Enterprises. The development of 3.0 has been funded almost
55 entirely by Nominum, Inc.
57 At this point development is being shepherded by Ted Lemon, and hosted
58 by the ISC, but the future of this project depends on you. If you
59 have features you want, please consider implementing them.
60 .SH LOCAL AND REMOTE OBJECTS
62 Throughout this document, there are references to local and remote objects.
63 Local objects are ones created in omshell with the \fBnew\fR command. Remote
64 objects are ones on the server: leases, hosts, and groups that the DHCP
65 server knows about. Local and remote objects are associated together to
66 enable viewing and modification of object attributes. Also, new remote
67 objects can be created to match local objects.
68 .SH OPENING A CONNECTION
70 omshell is started from the command line. Once omshell is started, there are
71 several commands that can be issued:
73 .B server \fIaddress\fR
75 where address is the IP address of the DHCP server to connect to. If this is
76 not specified, the default server is 127.0.0.1 (localhost).
81 where number is the port that OMAPI listens on. By default, this is 7911.
84 .B key \fIname secret\fR
86 This specifies the TSIG key to use to authenticate the OMAPI transactions.
87 \fIname\fR is the name of a key defined in \fIdhcpd.conf\fR with the
88 \fBomapi-key\fR statement. The \fIsecret\fR is the secret generated from
89 \fBdnssec-keygen\fR or another key generation program.
94 This starts the OMAPI connection to the server as specified by the \fIserver\fR
96 .SH CREATING LOCAL OBJECTS
98 Any object defined in OMAPI can be created, queried, and/or modified. The
99 object types available to OMAPI are defined in \fBdhcpd(8)\fR and
100 \fBdhclient\fR. When using omshell, objects are first defined locally,
101 manipulated as desired, and then associated with an object on the server.
102 Only one object can be manipulated at a time. To create a local object, use
104 .B new \fIobject-type\fR
106 \fIobject-type\fR is one of group, host, or lease.
109 At this point, you now have an object that you can set properties on. For
110 example, if a new lease object was created with \fInew lease\fR, any of a
111 lease's attributes can be set as follows:
113 .B set \fIattribute-name = value\fR
115 \fBAttribute names are defined in \fBdhcpd(8)\fR and \fBdhclient(8)\fR.
116 Values should be quoted if they are strings. So, to set a lease's IP address,
117 you would do the following:
118 \fB set ip-address = 192.168.4.50\fR
119 .SH ASSOCIATING LOCAL AND REMOTE OBJECTS
121 At this point, you can query the server for information about this lease, by
125 Now, the local lease object you created and set the IP address for is associated
126 with the corresponding lease object on the DHCP server. All of the lease
127 attributes from the DHCP server are now also the attributes on the local
128 object, and will be shown in omshell.
129 .SH VIEWING A REMOTE OBJECT
131 To query a lease of address 192.168.4.50, and find out its attributes, after
132 connecting to the server, take the following steps:
136 This creates a new local lease object.
138 .B set ip-address = 192.168.4.50
140 This sets the \fIlocal\fR object's IP address to be 192.168.4.50
144 Now, if a lease with that IP address exists, you will see all the information
145 the DHCP server has about that particular lease. Any data that isn't readily
146 printable text will show up in colon-separated hexadecimal values. In this
147 example, output back from the server for the entire transaction might look
153 > set ip-address = 192.168.4.50
155 ip-address = c0:a8:04:32
158 ip-address = c0:a8:04:32
160 dhcp-client-identifier = 01:00:10:a4:b2:36:2c
161 client-hostname = "wendelina"
164 hardware-address = 00:10:a4:b2:36:2c
165 hardware-type = 00:00:00:01
173 As you can see here, the IP address is represented in hexadecimal, as are the
174 starting and ending times of the lease.
175 .SH MODIFYING A REMOTE OBJECT
177 Attributes of remote objects are updated by using the \fBset\fR command as
178 before, and then issuing an \fBupdate\fR command. The \fBset\fR command sets
179 the attributes on the current local object, and the \fBupdate\fR command
180 pushes those changes out to the server.
182 Continuing with the previous example, if a \fBset client-hostname =
183 "something-else"\fR was issued, followed by an \fBupdate\fR command, the
184 output would look about like this:
187 > set client-hostname = "something-else"
189 ip-address = c0:a8:04:32
191 dhcp-client-identifier = 01:00:10:a4:b2:36:2c
192 client-hostname = "something-else"
195 hardware-address = 00:10:a4:b2:36:2c
196 hardware-type = 00:00:00:01
204 ip-address = c0:a8:04:32
206 dhcp-client-identifier = 01:00:10:a4:b2:36:2c
207 client-hostname = "something-else"
210 hardware-address = 00:10:a4:b2:36:2c
211 hardware-type = 00:00:00:01
218 .SH NEW REMOTE OBJECTS
220 New remote objects are created much in the same way that existing server
221 objects are modified. Create a local object using \fBnew\fR, set the
222 attributes as you'd wish them to be, and then create the remote object with
223 the same properties by using
227 Now a new object exists on the DHCP server which matches the properties that
228 you gave your local object. Objects created via OMAPI are saved into the
231 For example, if a new host with the IP address of 192.168.4.40 needs to be
232 created it would be done as follows:
237 > set name = "some-host"
240 > set hardware-address = 00:80:c7:84:b1:94
243 hardware-address = 00:80:c7:84:b1:94
244 > set hardware-type = 1
247 hardware-address = 00:80:c7:84:b1:94
249 > set ip-address = 192.168.4.40
252 hardware-address = 00:80:c7:84:b1:94
254 ip-address = c0:a8:04:28
258 hardware-address = 00:80:c7:84:b1:94
259 hardware-type = 00:00:00:01
260 ip-address = c0:a8:04:28
264 Your dhcpd.leases file would then have an entry like this in it:
269 hardware ethernet 00:80:c7:84:b1:94;
270 fixed-address 192.168.4.40;
274 The \fIdynamic;\fR line is to denote that this host entry did not come from
275 dhcpd.conf, but was created dynamically via OMAPI.
276 .SH RESETTING ATTRIBUTES
278 If you want to remove an attribute from an object, you can do this with the
279 \fBunset\fR command. Once you have unset an attribute, you must use the
280 \fBupdate\fR command to update the remote object. So, if the host "some-host"
281 from the previous example will not have a static IP address anymore, the
282 commands in omshell would look like this:
287 hardware-address = 00:80:c7:84:b1:94
288 hardware-type = 00:00:00:01
289 ip-address = c0:a8:04:28
293 hardware-address = 00:80:c7:84:b1:94
294 hardware-type = 00:00:00:01
298 .SH REFRESHING OBJECTS
300 A local object may be refreshed with the current remote object properties
301 using the \fBrefresh\fR command. This is useful for object that change
302 periodically, like leases, to see if they have been updated. This isn't
303 particularly useful for hosts.
306 Any remote object that can be created can also be destroyed. This is done by
307 creating a new local object, setting attributes, associating the local and
308 remote object using \fBopen\fI, and then using the \fBremove\fR command.
309 If the host "some-host" from before was created in error, this could be
310 corrected as follows:
315 hardware-address = 00:80:c7:84:b1:94
316 hardware-type = 00:00:00:01
317 ip-address = c0:a8:04:28
324 The \fBhelp\fR command will print out all of the commands available in
325 omshell, with some syntax pointers.
327 dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
330 was written by Ted Lemon of Nominum, Inc. Information about Nominum
331 and support contracts for DHCP and BIND can be found at
332 .B http://www.nominum.com. This preliminary documentation was
333 written by Wendy Verschoor of Nominum, Inc., while she was testing