


omshell(1)                                             omshell(1)


NNAAMMEE
       omshell - OMAPI Command Shell

SSYYNNOOPPSSIISS
       oommsshheellll

DDEESSCCRRIIPPTTIIOONN
       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 _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 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.

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

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

       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



                                                                1





omshell(1)                                             omshell(1)


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




                                                                2





omshell(1)                                             omshell(1)


       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 hex-
       adecimal 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.

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 == ""ssoommee--
       tthhiinngg--eellssee"" was issued, followed by an uuppddaattee 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



                                                                3





omshell(1)                                             omshell(1)


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



                                                                4





omshell(1)                                             omshell(1)


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

RREEFFRREESSHHIINNGG OOBBJJEECCTTSS
       A local object may be refreshed with the current remote object  proper-
       ties  using the rreeffrreesshh 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.

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



                                                                5





omshell(1)                                             omshell(1)


       ip-address = c0:a8:04:28
       > remove
       obj: <null>
       >

HHEELLPP
       The  hheellpp  command  will  print  out  all  of the commands available 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.  Information about
       Nominum can be found at hhttttpp::////wwwwww..nnoommiinnuumm..ccoomm..  This preliminary docu-
       mentation  was  written  by Wendy Verschoor of Nominum, Inc., while she
       was testing omshell.







































                                                                6


