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
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.   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            fi
77            The default is HMAC-MD5. (Value is not case sensitive).
78
79       connect
80            This starts the OMAPI connection to the server as specified by the server
81            statement.
82

CREATING LOCAL OBJECTS

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

ASSOCIATING LOCAL AND REMOTE OBJECTS

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

VIEWING A REMOTE OBJECT

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

MODIFYING A REMOTE OBJECT

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

NEW REMOTE OBJECTS

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

RESETTING ATTRIBUTES

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

REFRESHING OBJECTS

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

DELETING OBJECTS

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

HELP

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

SEE ALSO

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

AUTHOR

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