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