1: .\" $Id: omshell.1,v 1.1 2012/02/21 22:30:18 misho Exp $
2: .\"
3: .\" Copyright (c) 2004,2009 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: .\" https://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: .\" ``https://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 key 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(8)\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\fR 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\fR, 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: can be found at
332: .B http://www.nominum.com.
333: This preliminary documentation was written by Wendy Verschoor of Nominum,
334: Inc., while she was testing omshell.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to omshell.1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / dhcpctl