


dhcpd.leases(5)                                   dhcpd.leases(5)


NNAAMMEE
       dhcpd.leases - DHCP client lease database

DDEESSCCRRIIPPTTIIOONN
       The  Internet  Systems Consortium DHCP Server keeps a per-
       sistent database of leases that  it  has  assigned.   This
       database  is a free-form ASCII file containing a series of
       lease declarations.   Every  time  a  lease  is  acquired,
       renewed  or released, its new value is recorded at the end
       of the lease  file.   So  if  more  than  one  declaration
       appears for a given lease, the last one in the file is the
       current one.

       When dhcpd is first installed, there is no lease database.
       However,  dhcpd  requires that a lease database be present
       before it will start.  To make the initial lease database,
       just  create  an  empty  file called /var/db/dhcpd.leases.
       You can do this with:

            touch /var/db/dhcpd.leases

       In order to prevent the lease database from growing  with-
       out  bound,  the  file  is  rewritten  from  time to time.
       First, a temporary lease database is created and all known
       leases are dumped to it.   Then, the old lease database is
       renamed /var/db/dhcpd.leases~.   Finally, the newly  writ-
       ten lease database is moved into place.

FFOORRMMAATT
       Lease  descriptions  are stored in a format that is parsed
       by the same recursive descent  parser  used  to  read  the
       ddhhccppdd..ccoonnff((55)) and ddhhcclliieenntt..ccoonnff((55)) files.  Lease files can
       contain lease declarations, and also  group  and  subgroup
       declarations,  host declarations and failover state decla-
       rations.  Group, subgroup and host declarations  are  used
       to record objects created using the OMAPI protocol.

       The lease file is a log-structured file - whenever a lease
       changes, the contents of that lease are written to the end
       of the file.   This means that it is entirely possible and
       quite reasonable for there to be two or more  declarations
       of the same lease in the lease file at the same time.   In
       that case, the instance  of  that  particular  lease  that
       appears last in the file is the one that is in effect.

       Group,  subgroup  and  host declarations in the lease file
       are handled in the same manner,  except  that  if  any  of
       these  objects  are  deleted,  a  _r_u_b_o_u_t is written to the
       lease file.   This is just the same  declaration,  with  {{
       ddeelleetteedd;;  }}  in  the  scope of the declaration.   When the
       lease file is rewritten, any  such  rubouts  that  can  be
       eliminated  are  eliminated.    It is possible to delete a
       declaration in the ddhhccppdd..ccoonnff  file;  in  this  case,  the
       rubout can never be eliminated from the ddhhccppdd..lleeaasseess file.



                                                                1





dhcpd.leases(5)                                   dhcpd.leases(5)


TTHHEE LLEEAASSEE DDEECCLLAARRAATTIIOONN
       lleeaassee _i_p_-_a_d_d_r_e_s_s {{ _s_t_a_t_e_m_e_n_t_s_._._. }}

       Each lease declaration includes the single IP address that
       has been leased to the client.   The statements within the
       braces define the duration of the lease and to whom it  is
       assigned.

       ssttaarrttss _d_a_t_e;;
       eennddss _d_a_t_e;;
       ttssttpp _d_a_t_e;;
       ttssffpp _d_a_t_e;;

       The  start  and end time of a lease are recorded using the
       ssttaarrttss and eennddss statements.   The ttssttpp statement is speci-
       fied if the failover protocol is being used, and indicates
       what time the peer has been told the lease expires.    The
       ttssffpp  statement is also specified if the failover protocol
       is being used, and indicates the lease  expiry  time  that
       the peer has acknowledged.

       The  _d_a_t_e  is specified in two ways, depending on the con-
       figuration value for the ddbb--ttiimmee--ffoorrmmaatt parameter.  If  it
       was  set  to  _d_e_f_a_u_l_t, then the _d_a_t_e fields appear as fol-
       lows:

       _w_e_e_k_d_a_y _y_e_a_r//_m_o_n_t_h//_d_a_y _h_o_u_r::_m_i_n_u_t_e::_s_e_c_o_n_d

       The weekday is present to make it easy for a human to tell
       when  a  lease  expires  - it's specified as a number from
       zero to six, with zero being Sunday.  The day of  week  is
       ignored on input.  The year is specified with the century,
       so it should generally be four digits  except  for  really
       long  leases.  The month is specified as a number starting
       with 1 for January.  The day  of  the  month  is  likewise
       specified starting with 1.  The hour is a number between 0
       and 23, the minute a number between 0 and 59, and the sec-
       ond also a number between 0 and 59.

       Lease  times  are  specified in Universal Coordinated Time
       (UTC), not in the local  time  zone.   There  is  probably
       nowhere  in  the world where the times recorded on a lease
       are always the same as wall clock  times.   On  most  unix
       machines,  you can display the current time in UTC by typ-
       ing ddaattee --uu.

       If the ddbb--ttiimmee--ffoorrmmaatt was configured to  _l_o_c_a_l,  then  the
       _d_a_t_e fields appear as follows:

        eeppoocchh  _<_s_e_c_o_n_d_s_-_s_i_n_c_e_-_e_p_o_c_h_>;;  ##  _<_d_a_y_-_n_a_m_e_> _<_m_o_n_t_h_-_n_a_m_e_>
       _<_d_a_y_-_n_u_m_b_e_r_> _<_h_o_u_r_s_>::_<_m_i_n_u_t_e_s_>::_<_s_e_c_o_n_d_s_> _<_y_e_a_r_>

       The _s_e_c_o_n_d_s_-_s_i_n_c_e_-_e_p_o_c_h is as according  to  the  system's
       local  clock  (often  referred  to as "unix time").  The ##



                                                                2





dhcpd.leases(5)                                   dhcpd.leases(5)


       symbol supplies a comment that describes what actual  time
       this  is as according to the system's configured timezone,
       at the time the value was written.  It  is  provided  only
       for human inspection.

       If  a lease will never expire, _d_a_t_e is nneevveerr instead of an
       actual date.

       hhaarrddwwaarree _h_a_r_d_w_a_r_e_-_t_y_p_e _m_a_c_-_a_d_d_r_e_s_s;;

       The hardware statement records the MAC address of the net-
       work  interface  on  which the lease will be used.   It is
       specified as a series of hexadecimal octets, separated  by
       colons.

       uuiidd _c_l_i_e_n_t_-_i_d_e_n_t_i_f_i_e_r;;

       The  uuiidd  statement  records the client identifier used by
       the  client  to  acquire  the  lease.    Clients  are  not
       required  to  send  client identifiers, and this statement
       only appears if the client did in fact send one.    Client
       identifiers are normally an ARP type (1 for ethernet) fol-
       lowed by the MAC address, just like in the hhaarrddwwaarree _s_t_a_t_e_-
       _m_e_n_t_, _b_u_t _t_h_i_s _i_s _n_o_t _r_e_q_u_i_r_e_d_.

       The  client  identifier  is  recorded as a colon-separated
       hexadecimal list  or  as  a  quoted  string.    If  it  is
       recorded  as  a  quoted string and it contains one or more
       non-printable characters, those characters are represented
       as octal escapes - a backslash character followed by three
       octal digits.

       cclliieenntt--hhoossttnnaammee _h_o_s_t_n_a_m_e ;;

       Most DHCP clients will send their hostname  in  the  _h_o_s_t_-
       _n_a_m_e  option.  If a client sends its hostname in this way,
       the hostname is recorded on the lease with a  cclliieenntt--hhoosstt--
       nnaammee  statement.    This  is not required by the protocol,
       however, so many specialized DHCP clients do  not  send  a
       host-name option.

       aabbaannddoonneedd;;

       The aabbaannddoonneedd statement indicates that the DHCP server has
       abandoned the lease.   In that case, the aabbaannddoonneedd  state-
       ment will be used to indicate that the lease should not be
       reassigned.  Please see the ddhhccppdd..ccoonnff((55)) manual page  for
       information about abandoned leases.

       bbiinnddiinngg ssttaattee _s_t_a_t_e;; nneexxtt bbiinnddiinngg ssttaattee _s_t_a_t_e;;

       The  bbiinnddiinngg  ssttaattee statement declares the lease's binding
       state.  When the DHCP server is not configured to use  the
       failover  protocol, a lease's binding state will be either



                                                                3





dhcpd.leases(5)                                   dhcpd.leases(5)


       aaccttiivvee or ffrreeee.   The failover protocol  adds  some  addi-
       tional  transitional  states, as well as the bbaacckkuupp state,
       which indicates that the lease is available for allocation
       by the failover secondary.

       The  nneexxtt bbiinnddiinngg ssttaattee statement indicates what state the
       lease will move to when the current state  expires.    The
       time  when  the  current state expires is specified in the
       _e_n_d_s statement.

       ooppttiioonn  aaggeenntt..cciirrccuuiitt--iidd  _s_t_r_i_n_g;  ooppttiioonn  aaggeenntt..rreemmoottee--iidd
       _s_t_r_i_n_g;

       The  ooppttiioonn  aaggeenntt..cciirrccuuiitt--iidd  and  ooppttiioonn aaggeenntt..rreemmoottee--iidd
       statements are used to record the circuit ID and remote ID
       options  send  by the relay agent, if the relay agent uses
       the _r_e_l_a_y _a_g_e_n_t _i_n_f_o_r_m_a_t_i_o_n _o_p_t_i_o_n.    This  allows  these
       options to be used consistently in conditional evaluations
       even when the client is  contacting  the  server  directly
       rather than through its relay agent.

       sseett _v_a_r_i_a_b_l_e == _v_a_l_u_e;;

       The  sseett  statement  sets  the  value of a variable on the
       lease.  For general  information  on  variables,  see  the
       ddhhccpp--eevvaall((55)) manual page.

       TThhee _d_d_n_s_-_t_e_x_t vvaarriiaabbllee

       The  _d_d_n_s_-_t_e_x_t variable is used to record the value of the
       client's TXT identification record when the  interim  ddns
       update style has been used to update the DNS for a partic-
       ular lease.

       TThhee _d_d_n_s_-_f_w_d_-_n_a_m_e vvaarriiaabbllee

       The _d_d_n_s_-_f_w_d_-_n_a_m_e vvaarriiaabbllee rreeccoorrddss tthhee vvaalluuee ooff  tthhee  nnaammee
       uusseedd  iinn  uuppddaattiinngg  tthhee cclliieenntt''ss AA rreeccoorrdd iiff aa DDDDNNSS uuppddaattee
       hhaass bbeeeenn ssuucccceessssffuullllyy ddoonnee bbyy tthhee sseerrvveerr..   TThhee sseerrvveerr mmaayy
       aallssoo  hhaavvee  uusseedd  tthhiiss  nnaammee  ttoo  uuppddaattee  tthhee cclliieenntt''ss PPTTRR
       rreeccoorrdd..

       TThhee _d_d_n_s_-_c_l_i_e_n_t_-_f_q_d_n vvaarriiaabbllee

       If the server is configured to use the interim ddns update
       style,  and  is also configured to allow clients to update
       their own fqdns, and the client did in fact update its own
       fqdn,  then the _d_d_n_s_-_c_l_i_e_n_t_-_f_q_d_n variable records the name
       that the client has indicated it is using.   This  is  the
       name that the server will have used to update the client's
       PTR record in this case.

       TThhee _d_d_n_s_-_r_e_v_-_n_a_m_e vvaarriiaabbllee




                                                                4





dhcpd.leases(5)                                   dhcpd.leases(5)


       If  the  server  successfully  updates  the  client's  PTR
       record,  this  variable will record the name that the DHCP
       server used for the PTR record.   The name  to  which  the
       PTR  record points will be either the _d_d_n_s_-_f_w_d_-_n_a_m_e or the
       _d_d_n_s_-_c_l_i_e_n_t_-_f_q_d_n.

       oonn _e_v_e_n_t_s {{ _s_t_a_t_e_m_e_n_t_s_._._. }} The  oonn  _s_t_a_t_e_m_e_n_t  _r_e_c_o_r_d_s  _a
       _l_i_s_t  _o_f  _s_t_a_t_e_m_e_n_t_s _t_o _e_x_e_c_u_t_e _i_f _a _c_e_r_t_a_i_n _e_v_e_n_t _o_c_c_u_r_s_.
       _T_h_e _p_o_s_s_i_b_l_e _e_v_e_n_t_s _t_h_a_t _c_a_n _o_c_c_u_r _f_o_r _a_n _a_c_t_i_v_e _l_e_a_s_e _a_r_e
       rreelleeaassee and eexxppiirryy.   More than one event can be specified
       - if so, the events are separated by '|' characters.

       bboooottpp;; rreesseerrvveedd;;  These  two  statements  are  effectively
       flags.   If  present,  they  indicate  that  the BOOTP and
       RESERVED failover  flags,  respectively,  should  be  set.
       BOOTP  and RESERVED dynamic leases are treated differently
       than normal dynamic leases, as they may only  be  used  by
       the client to which they are currently allocated.

TTHHEE FFAAIILLOOVVEERR PPEEEERR SSTTAATTEE DDEECCLLAARRAATTIIOONN
       The  state  of  any  failover peering arrangements is also
       recorded in the lease file, using the ffaaiilloovveerr ppeeeerr state-
       ment:

       ffaaiilloovveerr ppeeeerr _n_a_m_e ssttaattee {{
       mmyy ssttaattee _s_t_a_t_e aatt _d_a_t_e;;
       ppeeeerr ssttaattee _s_t_a_t_e aatt _d_a_t_e;;
       }}

       The  states  of  the  peer  named  _n_a_m_e is being recorded.
       Both the state of the running server (mmyy  ssttaattee)  and  the
       other  failover  partner  (_p_e_e_r _s_t_a_t_e) are recorded.   The
       following states  are  possible:  uunnkknnoowwnn--ssttaattee,  ppaarrttnneerr--
       ddoowwnn,   nnoorrmmaall,   ccoommmmuunniiccaattiioonnss--iinntteerrrruupptteedd,  rreessoolluuttiioonn--
       iinntteerrrruupptteedd,  ppootteennttiiaall--ccoonnfflliicctt,  rreeccoovveerr,  rreeccoovveerr--ddoonnee,
       sshhuuttddoowwnn, ppaauusseedd, and ssttaarrttuupp.  //vvaarr//ddbb//ddhhccppdd..lleeaasseess

SSEEEE AALLSSOO
       dhcpd(8),  dhcp-options(5),  dhcp-eval(5),  dhcpd.conf(5),
       RFC2132, RFC2131.

AAUUTTHHOORR
       ddhhccppdd((88)) was written by Ted Lemon under  a  contract  with
       Vixie  Labs.    Funding  for  this project was provided by
       Internet Systems Consortium.  Information  about  Internet
       Systems Consortium can be found at: hhttttppss::////wwwwww..iisscc..oorrgg//











                                                                5


