MAN page from RedHat 7.X dhcp-3.0.2-6.pp-rh73.i386.rpm

omshell

Section: User Commands (1)
Index

NAME

omshell - OMAPI Command Shell

SYNOPSIS

omshell

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 ObjectManagement API. By using OMAPI and omshell, you do not have to stop, makechanges, and then restart the DHCP server, but can make the changeswhile the server is running. Omshell provides a way of accessingOMAPI.

OMAPI is simply a communications mechanism that allows you tomanipulate objects. In order to actually use omshell, youmustunderstand what objects are available and how to use them.Documentation for OMAPI objects can be found in the documentation forthe server that provides them - for example, in the dhcpd(1)manual page and the dhclient(1) manual page.

CONTRIBUTIONS

This software is free software. At various times its development hasbeen underwritten by various organizations, including the ISC andVixie Enterprises. The development of 3.0 has been funded almostentirely by Nominum, Inc.

At this point development is being shepherded by Ted Lemon, and hostedby the ISC, but the future of this project depends on you. If youhave features you want, please consider implementing them.

LOCAL AND REMOTE OBJECTS

Throughout this document, there are references to local and remote objects.Local objects are ones created in omshell with the new command. Remoteobjects are ones on the server: leases, hosts, and groups that the DHCPserver knows about. Local and remote objects are associated together toenable viewing and modification of object attributes. Also, new remoteobjects can be created to match local objects.

OPENING A CONNECTION

omshell is started from the command line. Once omshell is started, there areseveral commands that can be issued:

server address

: where address is the IP address of the DHCP server to connect to. If this isnot specified, the default server is 127.0.0.1 (localhost).

port number

: where number is the port that OMAPI listens on. By default, this is 7911.

key name secret

: This specifies the TSIG key to use to authenticate the OMAPI transactions.name is the name of a key defined in dhcpd.conf with theomapi-key statement. The secret is the secret generated fromdnssec-keygen or another key generation program.

connect

: This starts the OMAPI connection to the server as specified by the serverstatement.

CREATING LOCAL OBJECTS

Any object defined in OMAPI can be created, queried, and/or modified. Theobject types available to OMAPI are defined in dhcpd(8) anddhclient. 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

new object-type

: object-type is one of group, host, or lease.

At this point, you now have an object that you can set properties on. Forexample, if a new lease object was created with new lease, any of alease's attributes can be set as follows:

set attribute-name = value

: Attribute names are defined in dhcpd(8) and dhclient(8).Values should be quoted if they are strings. So, to set a lease's IP address,you would do the following: set ip-address = 192.168.4.50

ASSOCIATING LOCAL AND REMOTE OBJECTS

At this point, you can query the server for information about this lease, by

open

Now, the local lease object you created and set the IP address for is associatedwith the corresponding lease object on the DHCP server. All of the leaseattributes from the DHCP server are now also the attributes on the localobject, and will be shown in omshell.

VIEWING A REMOTE OBJECT

To query a lease of address 192.168.4.50, and find out its attributes, afterconnecting to the server, take the following steps:

new lease

This creates a new local lease object.

set ip-address = 192.168.4.50

This sets the local object's IP address to be 192.168.4.50

open

Now, if a lease with that IP address exists, you will see all the informationthe DHCP server has about that particular lease. Any data that isn't readilyprintable text will show up in colon-separated hexadecimal values. In thisexample, output back from the server for the entire transaction might looklike this:

> new "lease"obj: lease> set ip-address = 192.168.4.50obj: leaseip-address = c0:a8:04:32> openobj: leaseip-address = c0:a8:04:32state = 00:00:00:02dhcp-client-identifier = 01:00:10:a4:b2:36:2cclient-hostname = "wendelina"subnet = 00:00:00:06pool = 00:00:00:07hardware-address = 00:10:a4:b2:36:2chardware-type = 00:00:00:01ends = dc:d9:0d:3bstarts = 5c:9f:04:3btstp = 00:00:00:00tsfp = 00:00:00:00cltt = 00:00:00:00

As you can see here, the IP address is represented in hexadecimal, as are thestarting and ending times of the lease.

MODIFYING A REMOTE OBJECT

Attributes of remote objects are updated by using the set command asbefore, and then issuing an update command. The set command setsthe attributes on the current local object, and the update commandpushes those changes out to the server.

Continuing with the previous example, if a set client-hostname ="something-else" was issued, followed by an update command, theoutput would look about like this:

> set client-hostname = "something-else"obj: leaseip-address = c0:a8:04:32state = 00:00:00:02dhcp-client-identifier = 01:00:10:a4:b2:36:2cclient-hostname = "something-else"subnet = 00:00:00:06pool = 00:00:00:07hardware-address = 00:10:a4:b2:36:2chardware-type = 00:00:00:01ends = dc:d9:0d:3bstarts = 5c:9f:04:3btstp = 00:00:00:00tsfp = 00:00:00:00cltt = 00:00:00:00> updateobj: leaseip-address = c0:a8:04:32state = 00:00:00:02dhcp-client-identifier = 01:00:10:a4:b2:36:2cclient-hostname = "something-else"subnet = 00:00:00:06pool = 00:00:00:07hardware-address = 00:10:a4:b2:36:2chardware-type = 00:00:00:01ends = dc:d9:0d:3bstarts = 5c:9f:04:3btstp = 00:00:00:00tsfp = 00:00:00:00cltt = 00:00:00:00

NEW REMOTE OBJECTS

New remote objects are created much in the same way that existing serverobjects are modified. Create a local object using new, set theattributes as you'd wish them to be, and then create the remote object withthe same properties by using

create

Now a new object exists on the DHCP server which matches the properties thatyou gave your local object. Objects created via OMAPI are saved into thedhcpd.leases file.

For example, if a new host with the IP address of 192.168.4.40 needs to becreated it would be done as follows:

> new hostobj: host> set name = "some-host"obj: hostname = "some-host"> set hardware-address = 00:80:c7:84:b1:94obj: hostname = "some-host"hardware-address = 00:80:c7:84:b1:94> set hardware-type = 1obj: hostname = "some-host"hardware-address = 00:80:c7:84:b1:94hardware-type = 1> set ip-address = 192.168.4.40obj: hostname = "some-host"hardware-address = 00:80:c7:84:b1:94hardware-type = 1ip-address = c0:a8:04:28> createobj: hostname = "some-host"hardware-address = 00:80:c7:84:b1:94hardware-type = 00:00:00:01ip-address = c0:a8:04:28>

Your dhcpd.leases file would then have an entry like this in it:

host some-host {  dynamic;  hardware ethernet 00:80:c7:84:b1:94;  fixed-address 192.168.4.40;}

The dynamic; line is to denote that this host entry did not come fromdhcpd.conf, but was created dynamically via OMAPI.

RESETTING ATTRIBUTES

If you want to remove an attribute from an object, you can do this with theunset command. Once you have unset an attribute, you must use theupdate command to update the remote object. So, if the host "some-host"from the previous example will not have a static IP address anymore, thecommands in omshell would look like this:

obj: hostname = "some-host"hardware-address = 00:80:c7:84:b1:94hardware-type = 00:00:00:01ip-address = c0:a8:04:28> unset ip-addressobj: hostname = "some-host"hardware-address = 00:80:c7:84:b1:94hardware-type = 00:00:00:01ip-address = <null>>

REFRESHING OBJECTS

A local object may be refreshed with the current remote object propertiesusing the refresh command. This is useful for object that changeperiodically, like leases, to see if they have been updated. This isn'tparticularly useful for hosts.

DELETING OBJECTS

Any remote object that can be created can also be destroyed. This is done bycreating a new local object, setting attributes, associating the local andremote object using open, and then using the remove command. If the host "some-host" from before was created in error, this could becorrected as follows:

obj: hostname = "some-host"hardware-address = 00:80:c7:84:b1:94hardware-type = 00:00:00:01ip-address = c0:a8:04:28> removeobj: <null>>

HELP

The help command will print out all of the commands available inomshell, with some syntax pointers.

AUTHOR

omshellwas written by Ted Lemon of Nominum, Inc. Information about Nominumand support contracts for DHCP and BIND can be found athttp://www.nominum.com. This preliminary documentation waswritten by Wendy Verschoor of Nominum, Inc., while she was testingomshell.

Index

NAME
SYNOPSIS
DESCRIPTION
CONTRIBUTIONS
LOCAL AND REMOTE OBJECTS
OPENING A CONNECTION
CREATING LOCAL OBJECTS
ASSOCIATING LOCAL AND REMOTE OBJECTS
VIEWING A REMOTE OBJECT
MODIFYING A REMOTE OBJECT
NEW REMOTE OBJECTS
RESETTING ATTRIBUTES
REFRESHING OBJECTS
DELETING OBJECTS
HELP
SEE ALSO
AUTHOR

This document was created byman2html,using the manual pages.