Provided by: dhcp3-common_3.1.3-2ubuntu3_i386 bug

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

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
            (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 the omapi-key  statement.   The  secret  is  the  secret  key
            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(8).  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
       hexadecimal  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  =
       "something-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
       anymore, 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
       properties 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
       command.   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  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)