342 lines
12 KiB
Groff
342 lines
12 KiB
Groff
.\" omshell.1
|
|
.\"
|
|
.\" Copyright (c) 2001-2002 Internet Software Consortium.
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of The Internet Software Consortium nor the names
|
|
.\" of its contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
|
|
.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
|
|
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
|
|
.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
|
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" This software has been written for the Internet Software Consortium
|
|
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
|
|
.\" To learn more about the Internet Software 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 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\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 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\fI, 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
|
|
and support contracts for DHCP and BIND 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.
|