FreeBSD Man Pages

omshell(1)

NAME

       omshell - OMAPI Command Shell

SYNOPSIS

       omshell

DESCRIPTION

       The  OMAPI  Command Shell, omshell, provides an interactive way to con-
       nect 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.

       OMAPI is simply a communications mechanism that allows you  to  manipu-
       late  objects.	 In order to actually use omshell, you 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  dhcpd(1)	manual	page  and  the
       dhclient(1) manual page.

CONTRIBUTIONS

       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.

       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.

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 com-
       mand.  Remote objects are ones on the server: leases, hosts, and groups
       that the DHCP server knows about.  Local and remote objects are associ-
       ated together to enable viewing and modification of object  attributes.
       Also, new remote objects can be created to match local objects.

OPENING A CONNECTION

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

       server address
	    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 (local-
	    host).

       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
       Any  object  defined in OMAPI can be created, queried, and/or modified.
       The object types  available  to	OMAPI  are  defined  in  dhcpd(8)  and
       dhclient.   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.
       For example, if a new lease object was created with new lease, any of a
       lease'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
       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.

VIEWING A REMOTE OBJECT

       To query a lease of address 192.168.4.50, and find out its  attributes,
       after connecting 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
       information the DHCP server has about that particular lease.  Any  data
       that isn't readily printable text will show up in colon-separated hexa-
       decimal values.	In this example, output back from the server  for  the
       entire transaction might look like this:

       > new "lease"
       obj: lease
       > set ip-address = 192.168.4.50
       obj: lease
       ip-address = c0:a8:04:32
       > open
       obj: lease
       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

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

MODIFYING A REMOTE OBJECT

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

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

       > 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

NEW REMOTE OBJECTS

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

       create

       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
       >

       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 from
       dhcpd.conf, but was created dynamically via OMAPI.

RESETTING ATTRIBUTES

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

       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>
       >

       done by creating a new local object,  setting  attributes,  associating
       the  local and remote object using open, and then using the remove com-
       mand.  If the host "some-host" from before was created in  error,  this
       could be corrected as follows:

       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>
       >

HELP

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

SEE ALSO

       dhcpctl(3),    omapi(3),    dhcpd(8),	dhclient(8),	dhcpd.conf(5),
       dhclient.conf(5).

AUTHOR

       omshell	was  written  by Ted Lemon of Nominum, Inc.  Information about
       Nominum and support contracts  for  DHCP  and  BIND  can  be  found  at
       http://www.nominum.com.	This  preliminary documentation was written by
       Wendy Verschoor of Nominum, Inc., while she was testing omshell.

								    omshell(1)

SPONSORED LINKS