


dhcp-eval(5)                                         dhcp-eval(5)


NNAAMMEE
       dhcp-eval - ISC DHCP conditional evaluation

DDEESSCCRRIIPPTTIIOONN
       The  Internet  Systems  Consortium  DHCP client and server
       both provide the ability to perform  conditional  behavior
       depending  on  the contents of packets they receive.   The
       syntax for specifying this conditional behaviour is  docu-
       mented here.

RREEFFEERREENNCCEE:: CCOONNDDIITTIIOONNAALL BBEEHHAAVVIIOOUURR
       Conditional  behaviour is specified using the if statement
       and the else or elsif statements.   A  conditional  state-
       ment  can  appear anywhere that a regular statement (e.g.,
       an option statement) can appear, and can  enclose  one  or
       more such statements.   A typical conditional statement in
       a server might be:

       if option dhcp-user-class = "accounting" {
         max-lease-time 17600;
         option domain-name "accounting.example.org";
         option domain-name-servers ns1.accounting.example.org,
                           ns2.accounting.example.org;
       } elsif option dhcp-user-class = "sales" {
         max-lease-time 17600;
         option domain-name "sales.example.org";
         option domain-name-servers ns1.sales.example.org,
                           ns2.sales.example.org;
       } elsif option dhcp-user-class = "engineering" {
         max-lease-time 17600;
         option domain-name "engineering.example.org";
         option domain-name-servers ns1.engineering.example.org,
                           ns2.engineering.example.org;
       } else {
         max-lease-time 600;
         option domain-name "misc.example.org";
         option domain-name-servers ns1.misc.example.org,
                           ns2.misc.example.org;
       }

       On the client side, an example of  conditional  evaluation
       might be:

       # example.org filters DNS at its firewall, so we have to use their DNS
       # servers when we connect to their network.   If we are not at
       # example.org, prefer our own DNS server.
       if not option domain-name = "example.org" {
         prepend domain-name-servers 127.0.0.1;
       }

       The iiff statement and the eellssiiff continuation statement both
       take boolean expressions as their  arguments.    That  is,
       they  take  expressions  that,  when  evaluated, produce a
       boolean result.   If the  expression  evaluates  to  true,



                                                                1





dhcp-eval(5)                                         dhcp-eval(5)


       then  the  statements  enclosed in braces following the iiff
       statement are executed, and all subsequent eellssiiff and  eellssee
       clauses  are  skipped.    Otherwise, each subsequent eellssiiff
       clause's expression is checked, until an elsif  clause  is
       encountered  whose  test  evaluates  to  true.   If such a
       clause is found, the statements in braces following it are
       executed,  and  then any subsequent eellssiiff and eellssee clauses
       are skipped.   If all the iiff and eellssiiff clauses are checked
       but none of their expressions evaluate true, then if there
       is an eellssee clause, the statements enclosed in braces  fol-
       lowing  the eellssee are evaluated.   Boolean expressions that
       evaluate to null are treated as false in conditionals.

BBOOOOLLEEAANN EEXXPPRREESSSSIIOONNSS
       The following is the current list of  boolean  expressions
       that are supported by the DHCP distribution.

       _d_a_t_a_-_e_x_p_r_e_s_s_i_o_n_-_1 == _d_a_t_a_-_e_x_p_r_e_s_s_i_o_n_-_2

          The  == operator compares the values of two data expres-
          sions, returning true if they are the  same,  false  if
          they  are  not.    If  either the left-hand side or the
          right-hand side are null, the result is also null.

       _b_o_o_l_e_a_n_-_e_x_p_r_e_s_s_i_o_n_-_1 aanndd _b_o_o_l_e_a_n_-_e_x_p_r_e_s_s_i_o_n_-_2

          The aanndd operator  evaluates  to  true  if  the  boolean
          expression  on  the  left-hand  side  and  the  boolean
          expression on the  right-hand  side  both  evaluate  to
          true.  Otherwise, it evaluates to false.  If either the
          expression on the left-hand side or the  expression  on
          the right-hand side are null, the result is null.

       _b_o_o_l_e_a_n_-_e_x_p_r_e_s_s_i_o_n_-_1 oorr _b_o_o_l_e_a_n_-_e_x_p_r_e_s_s_i_o_n_-_2

          The oorr operator evaluates to true if either the boolean
          expression on the left-hand side or the boolean expres-
          sion  on  the right-hand side evaluate to true.  Other-
          wise, it evaluates to false.  If either the  expression
          on  the  left-hand side or the expression on the right-
          hand side are null, the result is null.

       nnoott _b_o_o_l_e_a_n_-_e_x_p_r_e_s_s_i_o_n

          The nnoott operator evaluates to true  if  _b_o_o_l_e_a_n_-_e_x_p_r_e_s_-
          _s_i_o_n  evaluates to false, and returns false if _b_o_o_l_e_a_n_-
          _e_x_p_r_e_s_s_i_o_n evaluates to true.    If  _b_o_o_l_e_a_n_-_e_x_p_r_e_s_s_i_o_n
          evaluates to null, the result is also null.

       eexxiissttss _o_p_t_i_o_n_-_n_a_m_e

          The  eexxiissttss  expression  returns  true if the specified
          option exists in the incoming DHCP  packet  being  pro-
          cessed.



                                                                2





dhcp-eval(5)                                         dhcp-eval(5)


       kknnoowwnn

          The  kknnoowwnn  expression returns true if the client whose
          request is currently being processed is  known  -  that
          is, if there's a host declaration for it.
       ssttaattiicc

          The   ssttaattiicc  expression  returns  true  if  the  lease
          assigned to the client whose request is currently being
          processed  is derived from a static address assignment.

DDAATTAA EEXXPPRREESSSSIIOONNSS
       Several of the boolean expressions  above  depend  on  the
       results  of evaluating data expressions.   A list of these
       expressions is provided here.

       ssuubbssttrriinngg ((_d_a_t_a_-_e_x_p_r,, _o_f_f_s_e_t,, _l_e_n_g_t_h))

          The ssuubbssttrriinngg operator evaluates  the  data  expression
          and returns the substring of the result of that evalua-
          tion that starts _o_f_f_s_e_t bytes from the beginning,  con-
          tinuing  for  _l_e_n_g_t_h bytes.  _O_f_f_s_e_t and _l_e_n_g_t_h are both
          numeric expressions.  If _d_a_t_a_-_e_x_p_r,  _o_f_f_s_e_t  or  _l_e_n_g_t_h
          evaluate  to  null,  then  the result is also null.  If
          _o_f_f_s_e_t is greater than or equal to the  length  of  the
          evaluated  data,  then  a  zero-length  data  string is
          returned.  If _l_e_n_g_t_h  _i_s  _g_r_e_a_t_e_r  _t_h_e_n  _t_h_e  _r_e_m_a_i_n_i_n_g
          _l_e_n_g_t_h  _o_f _t_h_e _e_v_a_l_u_a_t_e_d _d_a_t_a _a_f_t_e_r _o_f_f_s_e_t, then a data
          string containing all data from _o_f_f_s_e_t to  the  end  of
          the evaluated data is returned.

       ssuuffffiixx ((_d_a_t_a_-_e_x_p_r,, _l_e_n_g_t_h))

          The ssuuffffiixx operator evaluates _d_a_t_a_-_e_x_p_r and returns the
          last _l_e_n_g_t_h bytes of the  result  of  that  evaluation.
          _L_e_n_g_t_h is a numeric expression.  If _d_a_t_a_-_e_x_p_r or _l_e_n_g_t_h
          evaluate to null, then the result  is  also  null.   If
          _s_u_f_f_i_x evaluates to a number greater than the length of
          the  evaluated  data,  then  the  evaluated   data   is
          returned.

       llccaassee ((_d_a_t_a_-_e_x_p_r))

          The  llccaassee  function  returns  the result of evaluating
          _d_a_t_a_-_e_x_p_r converted to lower case.   If _d_a_t_a_-_e_x_p_r eval-
          uates to null, then the result is also null.

       uuccaassee ((_d_a_t_a_-_e_x_p_r))

          The  uuccaassee  function  returns  the result of evaluating
          _d_a_t_a_-_e_x_p_r converted to upper case.   If _d_a_t_a_-_e_x_p_r eval-
          uates to null, then the result is also null.

       ooppttiioonn _o_p_t_i_o_n_-_n_a_m_e



                                                                3





dhcp-eval(5)                                         dhcp-eval(5)


          The  ooppttiioonn operator returns the contents of the speci-
          fied option in  the  packet  to  which  the  server  is
          responding.

       ccoonnffiigg--ooppttiioonn _o_p_t_i_o_n_-_n_a_m_e

          The  ccoonnffiigg--ooppttiioonn  operator  returns the value for the
          specified option that the DHCP  client  or  server  has
          been configured to send.

       hhaarrddwwaarree

          The hhaarrddwwaarree operator returns a data string whose first
          element is the type of network interface  indicated  in
          packet  being considered, and whose subsequent elements
          are client's  link-layer  address.    If  there  is  no
          packet,  or  if the RFC2131 _h_l_e_n field is invalid, then
          the result is null.   Hardware types  include  ethernet
          (1), token-ring (6), and fddi (8).   Hardware types are
          specified by the IETF, and details on how the type num-
          bers  are  defined  can be found in RFC2131 (in the ISC
          DHCP distribution, this is included in the doc/  subdi-
          rectory).

       ppaacckkeett ((_o_f_f_s_e_t,, _l_e_n_g_t_h))

          The  ppaacckkeett  operator  returns the specified portion of
          the packet being considered, or null in contexts  where
          no  packet is being considered.   _O_f_f_s_e_t and _l_e_n_g_t_h are
          applied to the contents  packet  as  in  the  ssuubbssttrriinngg
          operator.

       _s_t_r_i_n_g

          A  string,  enclosed  in  quotes, may be specified as a
          data expression,  and  returns  the  text  between  the
          quotes, encoded in ASCII.   The backslash ('\') charac-
          ter is treated specially, as  in  C  programming:  '\t'
          means  TAB, '\r' means carriage return, '\n' means new-
          line, and '\b' means bell.   Any  octal  value  can  be
          specified  with '\nnn', where nnn is any positive octal
          number less than 0400.  Any hexadecimal  value  can  be
          specified  with  '\xnn',  where nn is any positive hex-
          adecimal number less than or equal to 0xff.

       _c_o_l_o_n_-_s_e_p_a_r_a_t_e_d _h_e_x_a_d_e_c_i_m_a_l _l_i_s_t

          A  list  of  hexadecimal  octet  values,  separated  by
          colons, may be specified as a data expression.

       ccoonnccaatt ((_d_a_t_a_-_e_x_p_r_1,, ......,, _d_a_t_a_-_e_x_p_r_N))
          The  expressions are evaluated, and the results of each
          evaluation are concatenated in the  sequence  that  the
          subexpressions   are  listed.    If  any  subexpression



                                                                4





dhcp-eval(5)                                         dhcp-eval(5)


          evaluates to null, the result of the  concatenation  is
          null.

       rreevveerrssee ((_n_u_m_e_r_i_c_-_e_x_p_r_1,, _d_a_t_a_-_e_x_p_r_2))
          The  two expressions are evaluated, and then the result
          of evaluating the data expression is reversed in place,
          using  hunks  of  the  size  specified  in  the numeric
          expression.   For example, if  the  numeric  expression
          evaluates to four, and the data expression evaluates to
          twelve bytes of data, then the reverse expression  will
          evaluate  to  twelve  bytes  of data, consisting of the
          last four bytes of the the input data, followed by  the
          middle four bytes, followed by the first four bytes.

       lleeaasseedd--aaddddrreessss
          In  any context where the client whose request is being
          processed has been assigned an IP  address,  this  data
          expression  returns  that  IP  address.  In any context
          where the client whose request is being  processed  has
          not  been  assigned an ip address, if this data expres-
          sion is found in executable statements executed on that
          client's  behalf, a log message indicating "there is no
          lease associated with this client" is syslogged to  the
          debug  level  (this  is considered dhcpd.conf debugging
          information).

       bbiinnaarryy--ttoo--aasscciiii ((_n_u_m_e_r_i_c_-_e_x_p_r_1,, _n_u_m_e_r_i_c_-_e_x_p_r_2,, _d_a_t_a_-_e_x_p_r_1,,
       _d_a_t_a_-_e_x_p_r_2))
          Converts  the  result  of  evaluating data-expr2 into a
          text string containing one number for each  element  of
          the  result  of evaluating data-expr2.   Each number is
          separated from the other by the  result  of  evaluating
          data-expr1.    The  result  of evaluating numeric-expr1
          specifies the base (2 through 16) into which  the  num-
          bers  should  be  converted.   The result of evaluating
          numeric-expr2 specifies the width in bits of each  num-
          ber, which may be either 8, 16 or 32.

          As  an  example of the preceding three types of expres-
          sions, to produce the name of a PTR record for  the  IP
          address being assigned to a client, one could write the
          following expression:

               concat (binary-to-ascii (10, 8, ".",
                                        reverse (1, leased-address)),
                       ".in-addr.arpa.");


       eennccooddee--iinntt ((_n_u_m_e_r_i_c_-_e_x_p_r,, _w_i_d_t_h))
          Numeric-expr is evaluated and encoded as a data  string
          of  the  specified  width,  in network byte order (most
          significant byte first).   If  the  numeric  expression
          evaluates to the null value, the result is also null.




                                                                5





dhcp-eval(5)                                         dhcp-eval(5)


       ppiicckk--ffiirrsstt--vvaalluuee ((_d_a_t_a_-_e_x_p_r_1 [ ... _e_x_p_rn ] ))
          The  pick-first-value function takes any number of data
          expressions as  its  arguments.    Each  expression  is
          evaluated,  starting  with the first in the list, until
          an expression is found that does not evaluate to a null
          value.    That  expression is returned, and none of the
          subsequent expressions are evaluated.   If all  expres-
          sions  evaluate  to  a  null  value,  the null value is
          returned.

       hhoosstt--ddeeccll--nnaammee
          The host-decl-name function returns  the  name  of  the
          host  declaration that matched the client whose request
          is currently being processed, if any.   If no host dec-
          laration matched, the result is the null value.

NNUUMMEERRIICC EEXXPPRREESSSSIIOONNSS
       Numeric  expressions  are  expressions that evaluate to an
       integer.   In general, the maximum size of such an integer
       should not be assumed to be representable in fewer than 32
       bits, but the precision of such integers may be more  than
       32 bits.

       eexxttrraacctt--iinntt ((_d_a_t_a_-_e_x_p_r,, _w_i_d_t_h))

          The  eexxttrraacctt--iinntt  operator extracts an integer value in
          network byte order from the result  of  evaluating  the
          specified data expression.   Width is the width in bits
          of the integer to extract.  Currently,  the  only  sup-
          ported  widths are 8, 16 and 32.   If the evaluation of
          the data expression doesn't provide sufficient bits  to
          extract  an  integer  of  the  specified size, the null
          value is returned.

       lleeaassee--ttiimmee

          The duration of the current lease - that is,  the  dif-
          ference  between the current time and the time that the
          lease expires.

       _n_u_m_b_e_r

          Any number between zero and the  maximum  representable
          size may be specified as a numeric expression.

       cclliieenntt--ssttaattee

          The  current  state  of  the client instance being pro-
          cessed.   This is only useful in DHCP client configura-
          tion files.   Possible values are:

          _+_o Booting  - DHCP client is in the INIT state, and does
            not yet have an IP address.   The next message trans-
            mitted   will   be  a  DHCPDISCOVER,  which  will  be



                                                                6





dhcp-eval(5)                                         dhcp-eval(5)


            broadcast.

          _+_o Reboot - DHCP client is  in  the  INIT-REBOOT  state.
            It  has an IP address, but is not yet using it.   The
            next message to be transmitted will be a DHCPREQUEST,
            which  will  be broadcast.   If no response is heard,
            the client will bind to its address and move  to  the
            BOUND state.

          _+_o Select  -  DHCP client is in the SELECTING state - it
            has received at least one DHCPOFFER message,  but  is
            waiting to see if it may receive other DHCPOFFER mes-
            sages from other servers.   No messages are  sent  in
            the SELECTING state.

          _+_o Request - DHCP client is in the REQUESTING state - it
            has received at least one DHCPOFFER message, and  has
            chosen  which one it will request.   The next message
            to be sent will be a DHCPREQUEST message, which  will
            be broadcast.

          _+_o Bound - DHCP client is in the BOUND state - it has an
            IP address.   No messages  are  transmitted  in  this
            state.

          _+_o Renew - DHCP client is in the RENEWING state - it has
            an IP address, and is trying to contact the server to
            renew  it.    The  next  message to be sent will be a
            DHCPREQUEST message, which will be  unicast  directly
            to the server.

          _+_o Rebind  -  DHCP client is in the REBINDING state - it
            has an IP address,  and  is  trying  to  contact  any
            server  to  renew  it.    The next message to be sent
            will be a DHCPREQUEST, which will be broadcast.

RREEFFEERREENNCCEE:: AACCTTIIOONN EEXXPPRREESSSSIIOONNSS
       lloogg ((_p_r_i_o_r_i_t_y,, _d_a_t_a_-_e_x_p_r))

          Logging statements may be used to send  information  to
          the  standard  logging  channels.   A logging statement
          includes an optional priority (ffaattaall, eerrrroorr,  iinnffoo,  or
          ddeebbuugg), and a data expression.

          Logging  statements  take only a single data expression
          argument, so if you want to output multiple  data  val-
          ues,  you  will need to use the ccoonnccaatt operator to con-
          catenate them.

       eexxeeccuuttee ((_c_o_m_m_a_n_d_-_p_a_t_h [[,, _d_a_t_a_-_e_x_p_r_1,, ...... _d_a_t_a_-_e_x_p_r_N]]));;

          The eexxeeccuuttee statement runs an  external  command.   The
          first  argument is a string literal containing the name
          or path of the command to run.  The other arguments, if



                                                                7





dhcp-eval(5)                                         dhcp-eval(5)


          present,  are  either  string literals or data- expres-
          sions which evaluate to text strings, to be  passed  as
          command-line arguments to the command.

          eexxeeccuuttee  is  synchronous;  the program will block until
          the external command being run  has  finished.   Please
          note that lengthy program execution (for example, in an
          "on commit" in dhcpd.conf) may result  in  bad  perfor-
          mance  and  timeouts.   Only external applications with
          very short execution times are suitable for use.

          Passing user-supplied data to an  external  application
          might be dangerous.  Make sure the external application
          checks input buffers for validity.  Non-printable ASCII
          characters  will  be converted into dhcpd.conf language
          octal escapes ("777"), make sure your external  command
          handles them as such.

          It is possible to use the execute statement in any con-
          text, not only on events. If you put it  in  a  regular
          scope  in  the configuration file you will execute that
          command every time a scope is evaluated.

RREEFFEERREENNCCEE:: DDYYNNAAMMIICC DDNNSS UUPPDDAATTEESS
       The DHCP client and server have the ability to dynamically
       update  the  Domain Name System.  Within the configuration
       files, you can define how you want the Domain Name  System
       to  be  updated.   These updates are RFC 2136 compliant so
       any DNS server supporting  RFC  2136  should  be  able  to
       accept updates from the DHCP server.

SSEECCUURRIITTYY
       Support  for  TSIG  and DNSSEC is not yet available.  When
       you set your DNS server up to allow updates from the  DHCP
       server  or  client, you may be exposing it to unauthorized
       updates.  To avoid this, the best you can do right now  is
       to  use IP address-based packet filtering to prevent unau-
       thorized hosts from  submitting  update  requests.   Obvi-
       ously,  there  is currently no way to provide security for
       client updates - this will require TSIG or DNSSEC, neither
       of which is yet available in the DHCP distribution.

       Dynamic DNS (DDNS) updates are performed by using the ddnnss--
       uuppddaattee expression.  The ddnnss--uuppddaattee expression is a boolean
       expression that takes four parameters.  If the update suc-
       ceeds, the result is true.  If it  fails,  the  result  is
       false.   The  four  parameters  that  the are the resource
       record type (RR), the left hand side of the RR, the  right
       hand  side of the RR and the ttl that should be applied to
       the record.  The simplest example of the use of the  func-
       tion  can  be  found  in  the  reference  section  of  the
       dhcpd.conf file, where  events  are  described.   In  this
       example  several  statements  are  being  used to make the
       arguments to the ddnnss--uuppddaattee.



                                                                8





dhcp-eval(5)                                         dhcp-eval(5)


       In the example, the first  argument  to  the  first  Bdns-
       update  expression  is a data expression that evaluates to
       the A RR type.  The second argument is constructed by con-
       catenating  the  DHCP  host-name option with a text string
       containing the  local  domain,  in  this  case  "ssd.exam-
       ple.net".  The third argument is constructed by converting
       the address the client has been  assigned  from  a  32-bit
       number  into an ascii string with each byte separated by a
       ".".  The fourth argument, the TTL, specifies  the  amount
       of  time  remaining  in  the  lease  (note that this isn't
       really correct, since the DNS server will  pass  this  TTL
       out  whenever  a  request comes in, even if that is only a
       few seconds before the lease expires).

       If the first ddnnss--uuppddaattee statement succeeds, it is followed
       up  with a second update to install a PTR RR.  The instal-
       lation of a PTR record is similar to installing  an  A  RR
       except that the left hand side of the record is the leased
       address, reversed, with ".in-addr.arpa" concatenated.  The
       right  hand side is the fully qualified domain name of the
       client to which the address is being leased.

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

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

























                                                                9


