omshell(1)                                                          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
            with  the omapi-key statement.  The secret is the secret generated
            from dnssec-keygen or another key generation program.

       connect
            This starts the OMAPI connection to the server as specified by the
            server statement.

CREATING LOCAL OBJECTS
       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
       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

       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

       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.

       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:

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

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

REFRESHING OBJECTS
       A local object may be refreshed with the current remote object  proper-
       ties  using the refresh 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.

DELETING OBJECTS
       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 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)
