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