1omshell(1) General Commands Manual omshell(1)
2
6 omshell - OMAPI Command Shell
7
9 omshell
10
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 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
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 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
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
45 omshell is started from the command line. Once omshell is started,
46 there are several commands that can be issued:
47 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 port number
54 where number is the port that OMAPI listens on. By default, this
55 is 7911.
56 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 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 connect
79 This starts the OMAPI connection to the server as specified by the
80 server statement.
81
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 new object-type
91 object-type is one of group, host, or lease.
92 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 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
104 At this point, you can query the server for information about this
105 lease, by
106 open
108 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
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 new lease
119 This creates a new local lease object.
121 set ip-address = 192.168.4.50
123 This sets the local object's IP address to be 192.168.4.50
125 open
127 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 > 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 As you can see here, the IP address is represented in hexadecimal, as
156 are the starting and ending times of the lease.
157
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 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 > 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
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 create
206 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 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 > 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 Your dhcpd.leases file would then have an entry like this in it:
243 host some-host {
245 dynamic;
246 hardware ethernet 00:80:c7:84:b1:94;
247 fixed-address 192.168.4.40;
248 }
249 The dynamic; line is to denote that this host entry did not come from
251 dhcpd.conf, but was created dynamically via OMAPI.
252
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 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
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
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 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
296 The help command will print out all of the commands available in
297 omshell, with some syntax pointers.
298
300 dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5),
301 dhclient.conf(5).
302
304 omshell is maintained by ISC. To learn more about Internet Systems
305 Consortium, see https://www.isc.org
306 omshell(1)