| blob | 63797c3eff1a02ec1ffb46c3b9bfc0c08bf34596 |
1 .\" $NetBSD: omshell.1,v 1.1.1.3 2014/07/12 11:57:52 spz Exp $
2 .\"
3 .\" Id: omshell.1,v 1.6 2009/11/24 02:06:56 sar Exp
4 .\"
5 .\" Copyright (c) 2012,2014 by Internet Systems Consortium, Inc. ("ISC")
6 .\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC")
7 .\" Copyright (c) 2001-2003 by Internet Software Consortium
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software for any
10 .\" purpose with or without fee is hereby granted, provided that the above
11 .\" copyright notice and this permission notice appear in all copies.
12 .\"
13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
19 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 .\"
21 .\" Internet Systems Consortium, Inc.
22 .\" 950 Charter Street
23 .\" Redwood City, CA 94063
24 .\" <info@isc.org>
25 .\" https://www.isc.org/
26 .\"
27 .TH omshell 1
28 .SH NAME
29 omshell - OMAPI Command Shell
30 .SH SYNOPSIS
31 .B omshell
32 .SH DESCRIPTION
33 The OMAPI Command Shell, omshell, provides an interactive way to connect to,
34 query, and possibly change, the ISC DHCP Server's state via OMAPI, the Object
35 Management API. By using OMAPI and omshell, you do not have to stop, make
36 changes, and then restart the DHCP server, but can make the changes
37 while the server is running. Omshell provides a way of accessing
38 OMAPI.
39 .PP
40 OMAPI is simply a communications mechanism that allows you to
41 manipulate objects. In order to actually \fIuse\fR omshell, you
42 .I must
43 understand what objects are available and how to use them.
44 Documentation for OMAPI objects can be found in the documentation for
45 the server that provides them - for example, in the \fBdhcpd(1)\fR
46 manual page and the \fBdhclient(1)\fR manual page.
47 .SH CONTRIBUTIONS
48 .PP
49 This software is free software. At various times its development has
50 been underwritten by various organizations, including the ISC and
51 Vixie Enterprises. The development of 3.0 has been funded almost
52 entirely by Nominum, Inc.
53 .PP
54 At this point development is hosted by the ISC, but the future of
55 this project depends on you. If you have features you want, please
56 consider implementing them.
57 .SH LOCAL AND REMOTE OBJECTS
58 .PP
59 Throughout this document, there are references to local and remote objects.
60 Local objects are ones created in omshell with the \fBnew\fR command. Remote
61 objects are ones on the server: leases, hosts, and groups that the DHCP
62 server knows about. Local and remote objects are associated together to
63 enable viewing and modification of object attributes. Also, new remote
64 objects can be created to match local objects.
65 .SH OPENING A CONNECTION
66 .PP
67 omshell is started from the command line. Once omshell is started, there are
68 several commands that can be issued:
69 .PP
70 .B server \fIaddress\fR
71 .RS 0.5i
72 where address is the IP address of the DHCP server to connect to. If this is
73 not specified, the default server is 127.0.0.1 (localhost).
74 .RE
75 .PP
76 .B port \fInumber\fR
77 .RS 0.5i
78 where number is the port that OMAPI listens on. By default, this is 7911.
79 .RE
80 .PP
81 .B key \fIname secret\fR
82 .RS 0.5i
83 This specifies the TSIG key to use to authenticate the OMAPI transactions.
84 \fIname\fR is the name of a key defined in \fIdhcpd.conf\fR with the
85 \fBomapi-key\fR statement. The \fIsecret\fR is the secret key generated from
86 \fBdnssec-keygen\fR or another key generation program.
87 .RE
88 .PP
89 .B connect
90 .RS 0.5i
91 This starts the OMAPI connection to the server as specified by the \fIserver\fR
92 statement.
93 .SH CREATING LOCAL OBJECTS
94 .PP
95 Any object defined in OMAPI can be created, queried, and/or modified. The
96 object types available to OMAPI are defined in \fBdhcpd(8)\fR and
97 \fBdhclient(8)\fR. When using omshell, objects are first defined locally,
98 manipulated as desired, and then associated with an object on the server.
99 Only one object can be manipulated at a time. To create a local object, use
100 .PP
101 .B new \fIobject-type\fR
102 .RS 0.5i
103 \fIobject-type\fR is one of group, host, or lease.
104 .RE
105 .PP
106 At this point, you now have an object that you can set properties on. For
107 example, if a new lease object was created with \fInew lease\fR, any of a
108 lease's attributes can be set as follows:
109 .PP
110 .B set \fIattribute-name = value\fR
111 .RS 0.5i
112 \fBAttribute\fR names are defined in \fBdhcpd(8)\fR and \fBdhclient(8)\fR.
113 Values should be quoted if they are strings. So, to set a lease's IP address,
114 you would do the following:
115 \fB set ip-address = 192.168.4.50\fR
116 .SH ASSOCIATING LOCAL AND REMOTE OBJECTS
117 .PP
118 At this point, you can query the server for information about this lease, by
119 .PP
120 .B open
121 .PP
122 Now, the local lease object you created and set the IP address for is associated
123 with the corresponding lease object on the DHCP server. All of the lease
124 attributes from the DHCP server are now also the attributes on the local
125 object, and will be shown in omshell.
126 .SH VIEWING A REMOTE OBJECT
127 .PP
128 To query a lease of address 192.168.4.50, and find out its attributes, after
129 connecting to the server, take the following steps:
130 .PP
131 .B new "lease"
132 .PP
133 This creates a new local lease object.
134 .PP
135 .B set ip-address = 192.168.4.50
136 .PP
137 This sets the \fIlocal\fR object's IP address to be 192.168.4.50
138 .PP
139 .B open
140 .PP
141 Now, if a lease with that IP address exists, you will see all the information
142 the DHCP server has about that particular lease. Any data that isn't readily
143 printable text will show up in colon-separated hexadecimal values. In this
144 example, output back from the server for the entire transaction might look
145 like this:
146 .nf
147 .sp 1
148 > new "lease"
149 obj: lease
150 > set ip-address = 192.168.4.50
151 obj: lease
152 ip-address = c0:a8:04:32
153 > open
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 = "wendelina"
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 .fi
169 .PP
170 As you can see here, the IP address is represented in hexadecimal, as are the
171 starting and ending times of the lease.
172 .SH MODIFYING A REMOTE OBJECT
173 .PP
174 Attributes of remote objects are updated by using the \fBset\fR command as
175 before, and then issuing an \fBupdate\fR command. The \fBset\fR command sets
176 the attributes on the current local object, and the \fBupdate\fR command
177 pushes those changes out to the server.
178 .PP
179 Continuing with the previous example, if a \fBset client-hostname =
180 "something-else"\fR was issued, followed by an \fBupdate\fR command, the
181 output would look about like this:
182 .nf
183 .sp 1
184 > set client-hostname = "something-else"
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 > update
200 obj: lease
201 ip-address = c0:a8:04:32
202 state = 00:00:00:02
203 dhcp-client-identifier = 01:00:10:a4:b2:36:2c
204 client-hostname = "something-else"
205 subnet = 00:00:00:06
206 pool = 00:00:00:07
207 hardware-address = 00:10:a4:b2:36:2c
208 hardware-type = 00:00:00:01
209 ends = dc:d9:0d:3b
210 starts = 5c:9f:04:3b
211 tstp = 00:00:00:00
212 tsfp = 00:00:00:00
213 cltt = 00:00:00:00
214 .fi
215 .SH NEW REMOTE OBJECTS
216 .PP
217 New remote objects are created much in the same way that existing server
218 objects are modified. Create a local object using \fBnew\fR, set the
219 attributes as you'd wish them to be, and then create the remote object with
220 the same properties by using
221 .PP
222 .B create
223 .PP
224 Now a new object exists on the DHCP server which matches the properties that
225 you gave your local object. Objects created via OMAPI are saved into the
226 dhcpd.leases file.
227 .PP
228 For example, if a new host with the IP address of 192.168.4.40 needs to be
229 created it would be done as follows:
230 .nf
231 .sp 1
232 > new host
233 obj: host
234 > set name = "some-host"
235 obj: host
236 name = "some-host"
237 > set hardware-address = 00:80:c7:84:b1:94
238 obj: host
239 name = "some-host"
240 hardware-address = 00:80:c7:84:b1:94
241 > set hardware-type = 1
242 obj: host
243 name = "some-host"
244 hardware-address = 00:80:c7:84:b1:94
245 hardware-type = 1
246 > set ip-address = 192.168.4.40
247 obj: host
248 name = "some-host"
249 hardware-address = 00:80:c7:84:b1:94
250 hardware-type = 1
251 ip-address = c0:a8:04:28
252 > create
253 obj: host
254 name = "some-host"
255 hardware-address = 00:80:c7:84:b1:94
256 hardware-type = 00:00:00:01
257 ip-address = c0:a8:04:28
258 >
259 .fi
260 .PP
261 Your dhcpd.leases file would then have an entry like this in it:
262 .nf
263 .sp 1
264 host some-host {
265 dynamic;
266 hardware ethernet 00:80:c7:84:b1:94;
267 fixed-address 192.168.4.40;
268 }
269 .fi
270 .PP
271 The \fIdynamic;\fR line is to denote that this host entry did not come from
272 dhcpd.conf, but was created dynamically via OMAPI.
273 .SH RESETTING ATTRIBUTES
274 .PP
275 If you want to remove an attribute from an object, you can do this with the
276 \fBunset\fR command. Once you have unset an attribute, you must use the
277 \fBupdate\fR command to update the remote object. So, if the host "some-host"
278 from the previous example will not have a static IP address anymore, the
279 commands in omshell would look like this:
280 .nf
281 .sp 1
282 obj: host
283 name = "some-host"
284 hardware-address = 00:80:c7:84:b1:94
285 hardware-type = 00:00:00:01
286 ip-address = c0:a8:04:28
287 > unset ip-address
288 obj: host
289 name = "some-host"
290 hardware-address = 00:80:c7:84:b1:94
291 hardware-type = 00:00:00:01
292 ip-address = <null>
293 >
294 .fi
295 .SH REFRESHING OBJECTS
296 .PP
297 A local object may be refreshed with the current remote object properties
298 using the \fBrefresh\fR command. This is useful for object that change
299 periodically, like leases, to see if they have been updated. This isn't
300 particularly useful for hosts.
301 .SH DELETING OBJECTS
302 .PP
303 Any remote object that can be created can also be destroyed. This is done by
304 creating a new local object, setting attributes, associating the local and
305 remote object using \fBopen\fR, and then using the \fBremove\fR command.
306 If the host "some-host" from before was created in error, this could be
307 corrected as follows:
308 .nf
309 .sp 1
310 obj: host
311 name = "some-host"
312 hardware-address = 00:80:c7:84:b1:94
313 hardware-type = 00:00:00:01
314 ip-address = c0:a8:04:28
315 > remove
316 obj: <null>
317 >
318 .fi
319 .SH HELP
320 .PP
321 The \fBhelp\fR command will print out all of the commands available in
322 omshell, with some syntax pointers.
323 .SH SEE ALSO
324 dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
325 .SH AUTHOR
326 .B omshell
327 is maintained by ISC. To learn more about Internet Systems Consortium,
328 see
329 .B https://www.isc.org