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
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
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 fi
77 The default is HMAC-MD5. (Value is not case sensitive).
78 connect
80 This starts the OMAPI connection to the server as specified by the server
81 statement.
82
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 new object-type
92 object-type is one of group, host, or lease.
93 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 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
105 At this point, you can query the server for information about this
106 lease, by
107 open
109 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
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 new lease
120 This creates a new local lease object.
122 set ip-address = 192.168.4.50
124 This sets the local object's IP address to be 192.168.4.50
126 open
128 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 > 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 As you can see here, the IP address is represented in hexadecimal, as
157 are the starting and ending times of the lease.
158
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 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 > 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
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 create
207 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 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 > 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 Your dhcpd.leases file would then have an entry like this in it:
244 host some-host {
246 dynamic;
247 hardware ethernet 00:80:c7:84:b1:94;
248 fixed-address 192.168.4.40;
249 }
250 The dynamic; line is to denote that this host entry did not come from
252 dhcpd.conf, but was created dynamically via OMAPI.
253
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 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
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
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 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
297 The help command will print out all of the commands available in
298 omshell, with some syntax pointers.
299
301 dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5),
302 dhclient.conf(5).
303
305 omshell is maintained by ISC. To learn more about Internet Systems
306 Consortium, see https://www.isc.org
307 omshell(1)