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