1omshell(1)                  General Commands Manual                 omshell(1)
2
3
4

NAME

6       omshell - OMAPI Command Shell
7

SYNOPSIS

9       omshell
10

DESCRIPTION

12       The  OMAPI  Command Shell, omshell, provides an interactive way to con‐
13       nect to, query, and possibly change, the ISC DHCP  Server's  state  via
14       OMAPI,  the  Object Management API.  By using OMAPI and omshell, you do
15       not have to stop, make changes, and then restart the DHCP  server,  but
16       can  make  the changes while the server is running.  Omshell provides a
17       way of accessing OMAPI.
18
19       OMAPI is simply a communications mechanism that allows you  to  manipu‐
20       late  objects.   In  order to actually use omshell, you must understand
21       what objects are available and how  to  use  them.   Documentation  for
22       OMAPI  objects  can  be  found in the documentation for the server that
23       provides them - for example,  in  the  dhcpd(1)  manual  page  and  the
24       dhclient(1) manual page.
25

CONTRIBUTIONS

27       This  software  is free software.  At various times its development has
28       been underwritten by various organizations, including the ISC and Vixie
29       Enterprises.  The development of 3.0 has been funded almost entirely by
30       Nominum, Inc.
31
32       At this point development is being shepherded by Ted Lemon, and  hosted
33       by the ISC, but the future of this project depends on you.  If you have
34       features you want, please consider implementing them.
35

LOCAL AND REMOTE OBJECTS

37       Throughout this document, there are  references  to  local  and  remote
38       objects.   Local  objects are ones created in omshell with the new com‐
39       mand.  Remote objects are ones on the server: leases, hosts, and groups
40       that the DHCP server knows about.  Local and remote objects are associ‐
41       ated together to enable viewing and modification of object  attributes.
42       Also, new remote objects can be created to match local objects.
43

OPENING A CONNECTION

45       omshell  is  started  from  the command line.  Once omshell is started,
46       there are several commands that can be issued:
47
48       server address
49            where address is the IP address of the DHCP server to connect  to.
50            If  this is not specified, the default server is 127.0.0.1 (local‐
51            host).
52
53       port number
54            where number is the port that OMAPI listens on.  By default,  this
55            is 7911.
56
57       key name secret
58            This  specifies  the  TSIG  key  to  use to authenticate the OMAPI
59            transactions.  name is the name of a  key  defined  in  dhcpd.conf
60            with the omapi-key statement.  The secret is the secret key gener‐
61            ated from dnssec-keygen or another key generation program.
62
63       connect
64            This starts the OMAPI connection to the server as specified by the
65            server statement.
66

CREATING LOCAL OBJECTS

68       Any  object  defined in OMAPI can be created, queried, and/or modified.
69       The object types  available  to  OMAPI  are  defined  in  dhcpd(8)  and
70       dhclient(8).   When  using  omshell, objects are first defined locally,
71       manipulated as desired, and then  associated  with  an  object  on  the
72       server.   Only  one  object  can be manipulated at a time.  To create a
73       local object, use
74
75       new object-type
76            object-type is one of group, host, or lease.
77
78       At this point, you now have an object that you can set  properties  on.
79       For example, if a new lease object was created with new lease, any of a
80       lease's attributes can be set as follows:
81
82       set attribute-name = value
83            Attribute names are defined in dhcpd(8) and  dhclient(8).   Values
84            should  be  quoted  if  they are strings.  So, to set a lease's IP
85            address, you would do the following:
86             set ip-address = 192.168.4.50
87

ASSOCIATING LOCAL AND REMOTE OBJECTS

89       At this point, you can query the  server  for  information  about  this
90       lease, by
91
92       open
93
94       Now,  the  local lease object you created and set the IP address for is
95       associated with the corresponding lease object on the DHCP server.  All
96       of  the  lease  attributes  from  the  DHCP  server  are  now  also the
97       attributes on the local object, and will be shown in omshell.
98

VIEWING A REMOTE OBJECT

100       To query a lease of address 192.168.4.50, and find out its  attributes,
101       after connecting to the server, take the following steps:
102
103       new lease
104
105       This creates a new local lease object.
106
107       set ip-address = 192.168.4.50
108
109       This sets the local object's IP address to be 192.168.4.50
110
111       open
112
113       Now,  if  a  lease  with  that  IP address exists, you will see all the
114       information the DHCP server has about that particular lease.  Any  data
115       that isn't readily printable text will show up in colon-separated hexa‐
116       decimal values.  In this example, output back from the server  for  the
117       entire transaction might look like this:
118
119       > new "lease"
120       obj: lease
121       > set ip-address = 192.168.4.50
122       obj: lease
123       ip-address = c0:a8:04:32
124       > open
125       obj: lease
126       ip-address = c0:a8:04:32
127       state = 00:00:00:02
128       dhcp-client-identifier = 01:00:10:a4:b2:36:2c
129       client-hostname = "wendelina"
130       subnet = 00:00:00:06
131       pool = 00:00:00:07
132       hardware-address = 00:10:a4:b2:36:2c
133       hardware-type = 00:00:00:01
134       ends = dc:d9:0d:3b
135       starts = 5c:9f:04:3b
136       tstp = 00:00:00:00
137       tsfp = 00:00:00:00
138       cltt = 00:00:00:00
139
140       As  you  can see here, the IP address is represented in hexadecimal, as
141       are the starting and ending times of the lease.
142

MODIFYING A REMOTE OBJECT

144       Attributes of remote objects are updated by using the  set  command  as
145       before,  and  then issuing an update command.  The set command sets the
146       attributes on the current local object, and the update  command  pushes
147       those changes out to the server.
148
149       Continuing with the previous example, if a set client-hostname = "some‐
150       thing-else" was issued, followed by an update command, the output would
151       look about like this:
152
153       > set client-hostname = "something-else"
154       obj: lease
155       ip-address = c0:a8:04:32
156       state = 00:00:00:02
157       dhcp-client-identifier = 01:00:10:a4:b2:36:2c
158       client-hostname = "something-else"
159       subnet = 00:00:00:06
160       pool = 00:00:00:07
161       hardware-address = 00:10:a4:b2:36:2c
162       hardware-type = 00:00:00:01
163       ends = dc:d9:0d:3b
164       starts = 5c:9f:04:3b
165       tstp = 00:00:00:00
166       tsfp = 00:00:00:00
167       cltt = 00:00:00:00
168       > update
169       obj: lease
170       ip-address = c0:a8:04:32
171       state = 00:00:00:02
172       dhcp-client-identifier = 01:00:10:a4:b2:36:2c
173       client-hostname = "something-else"
174       subnet = 00:00:00:06
175       pool = 00:00:00:07
176       hardware-address = 00:10:a4:b2:36:2c
177       hardware-type = 00:00:00:01
178       ends = dc:d9:0d:3b
179       starts = 5c:9f:04:3b
180       tstp = 00:00:00:00
181       tsfp = 00:00:00:00
182       cltt = 00:00:00:00
183

NEW REMOTE OBJECTS

185       New  remote  objects  are  created  much  in the same way that existing
186       server objects are modified.  Create a local object using new, set  the
187       attributes  as you'd wish them to be, and then create the remote object
188       with the same properties by using
189
190       create
191
192       Now a new object exists on the DHCP server which matches the properties
193       that  you  gave your local object.  Objects created via OMAPI are saved
194       into the dhcpd.leases file.
195
196       For example, if a new host with the IP address of 192.168.4.40 needs to
197       be created it would be done as follows:
198
199       > new host
200       obj: host
201       > set name = "some-host"
202       obj: host
203       name = "some-host"
204       > set hardware-address = 00:80:c7:84:b1:94
205       obj: host
206       name = "some-host"
207       hardware-address = 00:80:c7:84:b1:94
208       > set hardware-type = 1
209       obj: host
210       name = "some-host"
211       hardware-address = 00:80:c7:84:b1:94
212       hardware-type = 1
213       > set ip-address = 192.168.4.40
214       obj: host
215       name = "some-host"
216       hardware-address = 00:80:c7:84:b1:94
217       hardware-type = 1
218       ip-address = c0:a8:04:28
219       > create
220       obj: host
221       name = "some-host"
222       hardware-address = 00:80:c7:84:b1:94
223       hardware-type = 00:00:00:01
224       ip-address = c0:a8:04:28
225       >
226
227       Your dhcpd.leases file would then have an entry like this in it:
228
229       host some-host {
230         dynamic;
231         hardware ethernet 00:80:c7:84:b1:94;
232         fixed-address 192.168.4.40;
233       }
234
235       The  dynamic;  line is to denote that this host entry did not come from
236       dhcpd.conf, but was created dynamically via OMAPI.
237

RESETTING ATTRIBUTES

239       If you want to remove an attribute from an object, you can do this with
240       the  unset command.  Once you have unset an attribute, you must use the
241       update command to update the remote object.  So,  if  the  host  "some-
242       host"  from the previous example will not have a static IP address any‐
243       more, the commands in omshell would look like this:
244
245       obj: host
246       name = "some-host"
247       hardware-address = 00:80:c7:84:b1:94
248       hardware-type = 00:00:00:01
249       ip-address = c0:a8:04:28
250       > unset ip-address
251       obj: host
252       name = "some-host"
253       hardware-address = 00:80:c7:84:b1:94
254       hardware-type = 00:00:00:01
255       ip-address = <null>
256       >
257

REFRESHING OBJECTS

259       A local object may be refreshed with the current remote object  proper‐
260       ties  using the refresh command.  This is useful for object that change
261       periodically, like leases, to see if  they  have  been  updated.   This
262       isn't particularly useful for hosts.
263

DELETING OBJECTS

265       Any  remote  object that can be created can also be destroyed.  This is
266       done by creating a new local object,  setting  attributes,  associating
267       the  local and remote object using open, and then using the remove com‐
268       mand.  If the host "some-host" from before was created in  error,  this
269       could be corrected as follows:
270
271       obj: host
272       name = "some-host"
273       hardware-address = 00:80:c7:84:b1:94
274       hardware-type = 00:00:00:01
275       ip-address = c0:a8:04:28
276       > remove
277       obj: <null>
278       >
279

HELP

281       The  help  command  will  print  out  all  of the commands available in
282       omshell, with some syntax pointers.
283

SEE ALSO

285       dhcpctl(3),    omapi(3),    dhcpd(8),    dhclient(8),    dhcpd.conf(5),
286       dhclient.conf(5).
287

AUTHOR

289       omshell  was  written  by Ted Lemon of Nominum, Inc.  Information about
290       Nominum can be found at http://www.nominum.com.  This preliminary docu‐
291       mentation  was  written  by Wendy Verschoor of Nominum, Inc., while she
292       was testing omshell.
293
294
295
296                                                                    omshell(1)
Impressum