path: root/dhcpctl/omshell.1

.\"	$Id: omshell.1,v 1.1.2.6 2006/07/13 00:53:55 dhankins Exp $
.\"
.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2001-2003 by Internet Software Consortium
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"   Internet Systems Consortium, Inc.
.\"   950 Charter Street
.\"   Redwood City, CA 94063
.\"   <info@isc.org>
.\"   http://www.isc.org/
.\"
.\" This software has been written for Internet Systems Consortium
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
.\" To learn more about Internet Systems Consortium, see
.\" ``http://www.isc.org/''.  To learn more about Vixie Enterprises,
.\" see ``http://www.vix.com''.   To learn more about Nominum, Inc., see
.\" ``http://www.nominum.com''.
.TH omshell 1
.SH NAME
omshell - OMAPI Command Shell
.SH SYNOPSIS
.B omshell
.SH DESCRIPTION
The OMAPI Command Shell, omshell, provides an interactive way to connect to,
query, and possibly change, the ISC DHCP Server's state via OMAPI, the Object
Management API.  By using OMAPI and omshell, you do not have to stop, make
changes, and then restart the DHCP server, but can make the changes
while the server is running.   Omshell provides a way of accessing
OMAPI.
.PP
OMAPI is simply a communications mechanism that allows you to
manipulate objects.   In order to actually \fIuse\fR omshell, you
.I must
understand what objects are available and how to use them.
Documentation for OMAPI objects can be found in the documentation for
the server that provides them - for example, in the \fBdhcpd(1)\fR
manual page and the \fBdhclient(1)\fR manual page.
.SH CONTRIBUTIONS
.PP
This software is free software.  At various times its development has
been underwritten by various organizations, including the ISC and
Vixie Enterprises.  The development of 3.0 has been funded almost
entirely by Nominum, Inc.
.PP
At this point development is being shepherded by Ted Lemon, and hosted
by the ISC, but the future of this project depends on you.  If you
have features you want, please consider implementing them.
.SH LOCAL AND REMOTE OBJECTS
.PP
Throughout this document, there are references to local and remote objects.
Local objects are ones created in omshell with the \fBnew\fR command.  Remote
objects are ones on the server: leases, hosts, and groups that the DHCP
server knows about.  Local and remote objects are associated together to
enable viewing and modification of object attributes.  Also, new remote
objects can be created to match local objects.
.SH OPENING A CONNECTION
.PP
omshell is started from the command line.  Once omshell is started, there are
several commands that can be issued:
.PP
.B server \fIaddress\fR
.RS 0.5i
where address is the IP address of the DHCP server to connect to.  If this is
not specified, the default server is 127.0.0.1 (localhost).
.RE
.PP
.B port \fInumber\fR
.RS 0.5i
where number is the port that OMAPI listens on.  By default, this is 7911.
.RE
.PP
.B key \fIname secret\fR
.RS 0.5i
This specifies the TSIG key to use to authenticate the OMAPI transactions.
\fIname\fR is the name of a key defined in \fIdhcpd.conf\fR with the
\fBomapi-key\fR statement.  The \fIsecret\fR is the secret key generated from
\fBdnssec-keygen\fR or another key generation program.
.RE
.PP
.B connect
.RS 0.5i
This starts the OMAPI connection to the server as specified by the \fIserver\fR
statement.
.SH CREATING LOCAL OBJECTS
.PP
Any object defined in OMAPI can be created, queried, and/or modified.  The
object types available to OMAPI are defined in \fBdhcpd(8)\fR and
\fBdhclient(8)\fR.  When using omshell, objects are first defined locally,
manipulated as desired, and then associated with an object on the server.
Only one object can be manipulated at a time.  To create a local object, use
.PP
.B new \fIobject-type\fR
.RS 0.5i
\fIobject-type\fR is one of group, host, or lease.
.RE
.PP
At this point, you now have an object that you can set properties on.  For
example, if a new lease object was created with \fInew lease\fR, any of a
lease's attributes can be set as follows:
.PP
.B set \fIattribute-name = value\fR
.RS 0.5i
\fBAttribute\fR names are defined in \fBdhcpd(8)\fR and \fBdhclient(8)\fR.
Values should be quoted if they are strings.  So, to set a lease's IP address,
you would do the following:
\fB set ip-address = 192.168.4.50\fR
.SH ASSOCIATING LOCAL AND REMOTE OBJECTS
.PP
At this point, you can query the server for information about this lease, by
.PP
.B open
.PP
Now, the local lease object you created and set the IP address for is associated
with the corresponding lease object on the DHCP server.  All of the lease
attributes from the DHCP server are now also the attributes on the local
object, and will be shown in omshell.
.SH VIEWING A REMOTE OBJECT
.PP
To query a lease of address 192.168.4.50, and find out its attributes, after
connecting to the server, take the following steps:
.PP
.B new "lease"
.PP
This creates a new local lease object.
.PP
.B set ip-address = 192.168.4.50
.PP
This sets the \fIlocal\fR object's IP address to be 192.168.4.50
.PP
.B open
.PP
Now, if a lease with that IP address exists, you will see all the information
the DHCP server has about that particular lease.  Any data that isn't readily
printable text will show up in colon-separated hexadecimal values.  In this
example, output back from the server for the entire transaction might look
like this:
.nf
.sp 1
> new "lease"
obj: lease
> set ip-address = 192.168.4.50
obj: lease
ip-address = c0:a8:04:32
> open
obj: lease
ip-address = c0:a8:04:32
state = 00:00:00:02
dhcp-client-identifier = 01:00:10:a4:b2:36:2c
client-hostname = "wendelina"
subnet = 00:00:00:06
pool = 00:00:00:07
hardware-address = 00:10:a4:b2:36:2c
hardware-type = 00:00:00:01
ends = dc:d9:0d:3b
starts = 5c:9f:04:3b
tstp = 00:00:00:00
tsfp = 00:00:00:00
cltt = 00:00:00:00
.fi
.PP
As you can see here, the IP address is represented in hexadecimal, as are the
starting and ending times of the lease.
.SH MODIFYING A REMOTE OBJECT
.PP
Attributes of remote objects are updated by using the \fBset\fR command as
before, and then issuing an \fBupdate\fR command.  The \fBset\fR command sets
the attributes on the current local object, and the \fBupdate\fR command
pushes those changes out to the server.
.PP
Continuing with the previous example, if a \fBset client-hostname =
"something-else"\fR was issued, followed by an \fBupdate\fR command, the
output would look about like this:
.nf
.sp 1
> set client-hostname = "something-else"
obj: lease
ip-address = c0:a8:04:32
state = 00:00:00:02
dhcp-client-identifier = 01:00:10:a4:b2:36:2c
client-hostname = "something-else"
subnet = 00:00:00:06
pool = 00:00:00:07
hardware-address = 00:10:a4:b2:36:2c
hardware-type = 00:00:00:01
ends = dc:d9:0d:3b
starts = 5c:9f:04:3b
tstp = 00:00:00:00
tsfp = 00:00:00:00
cltt = 00:00:00:00
> update
obj: lease
ip-address = c0:a8:04:32
state = 00:00:00:02
dhcp-client-identifier = 01:00:10:a4:b2:36:2c
client-hostname = "something-else"
subnet = 00:00:00:06
pool = 00:00:00:07
hardware-address = 00:10:a4:b2:36:2c
hardware-type = 00:00:00:01
ends = dc:d9:0d:3b
starts = 5c:9f:04:3b
tstp = 00:00:00:00
tsfp = 00:00:00:00
cltt = 00:00:00:00
.fi
.SH NEW REMOTE OBJECTS
.PP
New remote objects are created much in the same way that existing server
objects are modified.  Create a local object using \fBnew\fR, set the
attributes as you'd wish them to be, and then create the remote object with
the same properties by using
.PP
.B create
.PP
Now a new object exists on the DHCP server which matches the properties that
you gave your local object.  Objects created via OMAPI are saved into the
dhcpd.leases file.
.PP
For example, if a new host with the IP address of 192.168.4.40 needs to be
created it would be done as follows:
.nf
.sp 1
> new host
obj: host
> set name = "some-host"
obj: host
name = "some-host"
> set hardware-address = 00:80:c7:84:b1:94
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
> set hardware-type = 1
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 1
> set ip-address = 192.168.4.40
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 1
ip-address = c0:a8:04:28
> create
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = c0:a8:04:28
> 
.fi
.PP
Your dhcpd.leases file would then have an entry like this in it:
.nf
.sp 1
host some-host {
  dynamic;
  hardware ethernet 00:80:c7:84:b1:94;
  fixed-address 192.168.4.40;
}
.fi
.PP
The \fIdynamic;\fR line is to denote that this host entry did not come from
dhcpd.conf, but was created dynamically via OMAPI.  
.SH RESETTING ATTRIBUTES
.PP
If you want to remove an attribute from an object, you can do this with the
\fBunset\fR command.   Once you have unset an attribute, you must use the
\fBupdate\fR command to update the remote object.  So, if the host "some-host"
from the previous example will not have a static IP address anymore, the
commands in omshell would look like this:
.nf
.sp 1
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = c0:a8:04:28
> unset ip-address
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = <null>
> 
.fi
.SH REFRESHING OBJECTS
.PP
A local object may be refreshed with the current remote object properties
using the \fBrefresh\fR command.  This is useful for object that change
periodically, like leases, to see if they have been updated.  This isn't
particularly useful for hosts.
.SH DELETING OBJECTS
.PP
Any remote object that can be created can also be destroyed.  This is done by
creating a new local object, setting attributes, associating the local and
remote object using \fBopen\fR, and then using the \fBremove\fR command. 
If the host "some-host" from before was created in error, this could be
corrected as follows:
.nf
.sp 1
obj: host
name = "some-host"
hardware-address = 00:80:c7:84:b1:94
hardware-type = 00:00:00:01
ip-address = c0:a8:04:28
> remove
obj: <null>
> 
.fi
.SH HELP
.PP
The \fBhelp\fR command will print out all of the commands available in
omshell, with some syntax pointers.
.SH SEE ALSO
dhcpctl(3), omapi(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
.SH AUTHOR
.B omshell
was written by Ted Lemon of Nominum, Inc.  Information about Nominum
can be found at
.B http://www.nominum.com.
This preliminary documentation was written by Wendy Verschoor of Nominum,
Inc., while she was testing omshell.