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 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
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.
62 connect
64 This starts the OMAPI connection to the server as specified by the
65 server statement.
66
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 new object-type
76 object-type is one of group, host, or lease.
77 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 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
89 At this point, you can query the server for information about this
90 lease, by
91 open
93 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
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 new lease
104 This creates a new local lease object.
106 set ip-address = 192.168.4.50
108 This sets the local object's IP address to be 192.168.4.50
110 open
112 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 > 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 As you can see here, the IP address is represented in hexadecimal, as
141 are the starting and ending times of the lease.
142
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 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 > 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
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 create
191 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 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 > 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 Your dhcpd.leases file would then have an entry like this in it:
228 host some-host {
230 dynamic;
231 hardware ethernet 00:80:c7:84:b1:94;
232 fixed-address 192.168.4.40;
233 }
234 The dynamic; line is to denote that this host entry did not come from
236 dhcpd.conf, but was created dynamically via OMAPI.
237
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 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
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
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 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
281 The help command will print out all of the commands available in
282 omshell, with some syntax pointers.
283
285 dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5),
286 dhclient.conf(5).
287
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 omshell(1)