Annotation of embedaddon/dhcp/dhcpctl/omshell.1, revision 1.1
1.1 ! misho 1: .\" $Id: omshell.1,v 1.4.690.2 2009-07-24 22:04:52 sar 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