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 hosted by the ISC, but the future of  this
33       project depends on you.  If you have features you want, please consider
34       implementing them.
35

LOCAL AND REMOTE OBJECTS

37       Throughout this document, there are references to local and remote  ob‐
38       jects.  Local objects are ones created in omshell with the new command.
39       Remote objects are ones on the server: leases, hosts, and  groups  that
40       the  DHCP  server knows about.  Local and remote objects are associated
41       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.   The
62            key  algorithm is assumed to be HMAC-MD5 key. If a different algo‐
63            rithm was specified in dhcpd.conf file for the key, then  it  must
64            be specified via the key-algorithm statement.
65
66       key-algorithm algorithm
67            This  specifies  the cryptographic algorithm for the key used when
68            authenticating OMAPI transactions. Supported values for  algorithm
69            are:
70                    HMAC-MD5
71                    HMAC-SHA1
72                    HMAC-SHA224
73                    HMAC-SHA256
74                    HMAC-SHA384
75                    HMAC-SHA512
76            The default is HMAC-MD5. (Value is not case sensitive).
77
78       connect
79            This starts the OMAPI connection to the server as specified by the
80            server statement.
81

CREATING LOCAL OBJECTS

83       Any object defined in OMAPI can be created, queried,  and/or  modified.
84       The  object  types  available  to  OMAPI  are  defined  in dhcpd(8) and
85       dhclient(8).  When using omshell, objects are  first  defined  locally,
86       manipulated  as  desired,  and  then  associated  with an object on the
87       server.  Only one object can be manipulated at a time.  To create a lo‐
88       cal object, use
89
90       new object-type
91            object-type is one of group, host, or lease.
92
93       At  this  point, you now have an object that you can set properties on.
94       For example, if a new lease object was created with new lease, any of a
95       lease's attributes can be set as follows:
96
97       set attribute-name = value
98            Attribute  names  are defined in dhcpd(8) and dhclient(8).  Values
99            should be quoted if they are strings.  So, to set a lease's IP ad‐
100            dress, you would do the following:
101             set ip-address = 192.168.4.50
102

ASSOCIATING LOCAL AND REMOTE OBJECTS

104       At  this  point,  you  can  query the server for information about this
105       lease, by
106
107       open
108
109       Now, the local lease object you created and set the IP address  for  is
110       associated with the corresponding lease object on the DHCP server.  All
111       of the lease attributes from the DHCP  server  are  now  also  the  at‐
112       tributes on the local object, and will be shown in omshell.
113

VIEWING A REMOTE OBJECT

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

MODIFYING A REMOTE OBJECT

159       Attributes  of  remote  objects are updated by using the set command as
160       before, and then issuing an update command.  The set command  sets  the
161       attributes  on  the current local object, and the update command pushes
162       those changes out to the server.
163
164       Continuing with the previous example, if a set client-hostname = "some‐
165       thing-else" was issued, followed by an update command, the output would
166       look about like this:
167
168       > set client-hostname = "something-else"
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       > update
184       obj: lease
185       ip-address = c0:a8:04:32
186       state = 00:00:00:02
187       dhcp-client-identifier = 01:00:10:a4:b2:36:2c
188       client-hostname = "something-else"
189       subnet = 00:00:00:06
190       pool = 00:00:00:07
191       hardware-address = 00:10:a4:b2:36:2c
192       hardware-type = 00:00:00:01
193       ends = dc:d9:0d:3b
194       starts = 5c:9f:04:3b
195       tstp = 00:00:00:00
196       tsfp = 00:00:00:00
197       cltt = 00:00:00:00
198

NEW REMOTE OBJECTS

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

RESETTING ATTRIBUTES

254       If you want to remove an attribute from an object, you can do this with
255       the unset command.  Once you have unset an attribute, you must use  the
256       update  command  to  update  the remote object.  So, if the host "some-
257       host" from the previous example will not have a static IP address  any‐
258       more, the commands in omshell would look like this:
259
260       obj: host
261       name = "some-host"
262       hardware-address = 00:80:c7:84:b1:94
263       hardware-type = 00:00:00:01
264       ip-address = c0:a8:04:28
265       > unset ip-address
266       obj: host
267       name = "some-host"
268       hardware-address = 00:80:c7:84:b1:94
269       hardware-type = 00:00:00:01
270       ip-address = <null>
271       >
272

REFRESHING OBJECTS

274       A  local object may be refreshed with the current remote object proper‐
275       ties using the refresh command.  This is useful for object that  change
276       periodically,  like  leases,  to  see  if they have been updated.  This
277       isn't particularly useful for hosts.
278

DELETING OBJECTS

280       Any remote object that can be created can also be destroyed.   This  is
281       done  by  creating  a new local object, setting attributes, associating
282       the local and remote object using open, and then using the remove  com‐
283       mand.   If  the host "some-host" from before was created in error, this
284       could be corrected as follows:
285
286       obj: host
287       name = "some-host"
288       hardware-address = 00:80:c7:84:b1:94
289       hardware-type = 00:00:00:01
290       ip-address = c0:a8:04:28
291       > remove
292       obj: <null>
293       >
294

HELP

296       The help command will print  out  all  of  the  commands  available  in
297       omshell, with some syntax pointers.
298

SEE ALSO

300       dhcpctl(3),    omapi(3),    dhcpd(8),    dhclient(8),    dhcpd.conf(5),
301       dhclient.conf(5).
302

AUTHOR

304       omshell is maintained by ISC.  To learn  more  about  Internet  Systems
305       Consortium, see https://www.isc.org
306
307
308
309                                                                    omshell(1)
Impressum