


omshell(1)                                             omshell(1)


NNAAMMEE
       omshell - OMAPI Command Shell

SSYYNNOOPPSSIISS
       oommsshheellll

DDEESSCCRRIIPPTTIIOONN
       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  pro-
       vides a way of accessing OMAPI.

       OMAPI is simply a communications mechanism that allows you
       to manipulate objects.   In order to actually _u_s_e omshell,
       you  _m_u_s_t 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 ddhhccppdd((11)) manual page and  the  ddhhcclliieenntt((11))
       manual page.

CCOONNTTRRIIBBUUTTIIOONNSS
       This  software  is  free  software.   At various times its
       development has been  underwritten  by  various  organiza-
       tions,  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  pro-
       ject  depends  on  you.   If  you  have features you want,
       please consider implementing them.

LLOOCCAALL AANNDD RREEMMOOTTEE OOBBJJEECCTTSS
       Throughout this document, there are  references  to  local
       and  remote  objects.   Local  objects are ones created in
       omshell with the nneeww 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.

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

       sseerrvveerr _a_d_d_r_e_s_s
            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).




                                                                1





omshell(1)                                             omshell(1)


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

       kkeeyy _n_a_m_e _s_e_c_r_e_t
            This  specifies  the  TSIG key to use to authenticate
            the OMAPI transactions.  _n_a_m_e is the name  of  a  key
            defined  in  _d_h_c_p_d_._c_o_n_f with the oommaappii--kkeeyy statement.
            The _s_e_c_r_e_t is the secret key generated  from  ddnnsssseecc--
            kkeeyyggeenn or another key generation program.

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

CCRREEAATTIINNGG LLOOCCAALL OOBBJJEECCTTSS
       Any object defined  in  OMAPI  can  be  created,  queried,
       and/or  modified.  The object types available to OMAPI are
       defined in ddhhccppdd((88)) and ddhhcclliieenntt((88)).  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

       nneeww _o_b_j_e_c_t_-_t_y_p_e
            _o_b_j_e_c_t_-_t_y_p_e 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 _n_e_w _l_e_a_s_e, any of a lease's attributes can be
       set as follows:

       sseett _a_t_t_r_i_b_u_t_e_-_n_a_m_e _= _v_a_l_u_e
            AAttttrriibbuuttee   names   are   defined   in  ddhhccppdd((88))  and
            ddhhcclliieenntt((88)).  Values should be  quoted  if  they  are
            strings.   So, to set a lease's IP address, you would
            do the following:
             sseett iipp--aaddddrreessss == 119922..116688..44..5500

AASSSSOOCCIIAATTIINNGG LLOOCCAALL AANNDD RREEMMOOTTEE OOBBJJEECCTTSS
       At this point, you can query the  server  for  information
       about this lease, by

       ooppeenn

       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.

VVIIEEWWIINNGG AA RREEMMOOTTEE OOBBJJEECCTT
       To query a lease of address 192.168.4.50, and find out its
       attributes, after  connecting  to  the  server,  take  the



                                                                2





omshell(1)                                             omshell(1)


       following steps:

       nneeww lleeaassee

       This creates a new local lease object.

       sseett iipp--aaddddrreessss == 119922..116688..44..5500

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

       ooppeenn

       Now, if a lease with that IP address exists, you will  see
       all the information the DHCP server has about that partic-
       ular 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 hex-
       adecimal, as are the starting  and  ending  times  of  the
       lease.

MMOODDIIFFYYIINNGG AA RREEMMOOTTEE OOBBJJEECCTT
       Attributes  of remote objects are updated by using the sseett
       command as before, and then  issuing  an  uuppddaattee  command.
       The  sseett  command sets the attributes on the current local
       object, and the uuppddaattee command pushes those changes out to
       the server.

       Continuing  with  the  previous  example, if a sseett cclliieenntt--
       hhoossttnnaammee == ""ssoommeetthhiinngg--eellssee"" was  issued,  followed  by  an
       uuppddaattee command, the output would look about like this:



                                                                3





omshell(1)                                             omshell(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

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

       ccrreeaattee

       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  fol-
       lows:

       > new host
       obj: host
       > set name = "some-host"
       obj: host
       name = "some-host"
       > set hardware-address = 00:80:c7:84:b1:94



                                                                4





omshell(1)                                             omshell(1)


       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 _d_y_n_a_m_i_c_; line is to denote that this  host  entry  did
       not  come from dhcpd.conf, but was created dynamically via
       OMAPI.

RREESSEETTTTIINNGG AATTTTRRIIBBUUTTEESS
       If you want to remove an attribute from an object, you can
       do  this  with the uunnsseett command.   Once you have unset an
       attribute, you must use the uuppddaattee command to  update  the
       remote  object.  So, if the host "some-host" from the pre-
       vious 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>



                                                                5





omshell(1)                                             omshell(1)


       >

RREEFFRREESSHHIINNGG OOBBJJEECCTTSS
       A  local  object  may be refreshed with the current remote
       object properties using the rreeffrreesshh command.  This is use-
       ful  for  object that change periodically, like leases, to
       see if they have been updated.   This  isn't  particularly
       useful for hosts.

DDEELLEETTIINNGG OOBBJJEECCTTSS
       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 ooppeenn, and then using the rreemmoovvee 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>
       >

HHEELLPP
       The hheellpp command will print out all of the commands avail-
       able in omshell, with some syntax pointers.

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

AAUUTTHHOORR
       oommsshheellll was written by Ted Lemon of Nominum, Inc.   Infor-
       mation     about     Nominum     can     be    found    at
       hhttttpp::////wwwwww..nnoommiinnuumm..ccoomm..   This  preliminary  documentation
       was written by Wendy Verschoor of Nominum, Inc., while she
       was testing omshell.

















                                                                6


