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.