File:  [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / server / dhcpd.leases.5
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Oct 9 09:06:55 2012 UTC (11 years, 8 months ago) by misho
Branches: dhcp, MAIN
CVS tags: v4_1_R7p0, v4_1_R7, v4_1_R4, HEAD
dhcp 4.1 r7

    1: .\"	dhcpd.leases.5
    2: .\"
    3: .\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC")
    4: .\" Copyright (c) 1996-2003 by Internet Software Consortium
    5: .\"
    6: .\" Permission to use, copy, modify, and distribute this software for any
    7: .\" purpose with or without fee is hereby granted, provided that the above
    8: .\" copyright notice and this permission notice appear in all copies.
    9: .\"
   10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
   11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   12: .\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
   13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
   14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
   15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
   16: .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
   17: .\"
   18: .\"   Internet Systems Consortium, Inc.
   19: .\"   950 Charter Street
   20: .\"   Redwood City, CA 94063
   21: .\"   <info@isc.org>
   22: .\"   https://www.isc.org/
   23: .\"
   24: .\" This software has been written for Internet Systems Consortium
   25: .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
   26: .\" To learn more about Internet Systems Consortium, see
   27: .\" ``https://www.isc.org/''.  To learn more about Vixie Enterprises,
   28: .\" see ``http://www.vix.com''.   To learn more about Nominum, Inc., see
   29: .\" ``http://www.nominum.com''.
   30: .\"
   31: .\" $Id: dhcpd.leases.5,v 1.1.1.1 2012/10/09 09:06:55 misho Exp $
   32: .\"
   33: .TH dhcpd.leases 5
   34: .SH NAME
   35: dhcpd.leases - DHCP client lease database
   36: .SH DESCRIPTION
   37: The Internet Systems Consortium DHCP Server keeps a persistent
   38: database of leases that it has assigned.  This database is a free-form
   39: ASCII file containing a series of lease declarations.  Every time a
   40: lease is acquired, renewed or released, its new value is recorded at
   41: the end of the lease file.  So if more than one declaration appears
   42: for a given lease, the last one in the file is the current one.
   43: .PP
   44: When dhcpd is first installed, there is no lease database.   However,
   45: dhcpd requires that a lease database be present before it will start.
   46: To make the initial lease database, just create an empty file called
   47: DBDIR/dhcpd.leases.   You can do this with:
   48: .PP
   49: .nf
   50: 	touch DBDIR/dhcpd.leases
   51: .fi
   52: .PP
   53: In order to prevent the lease database from growing without bound, the
   54: file is rewritten from time to time.   First, a temporary lease
   55: database is created and all known leases are dumped to it.   Then, the
   56: old lease database is renamed DBDIR/dhcpd.leases~.   Finally, the
   57: newly written lease database is moved into place.
   58: .SH FORMAT
   59: Lease descriptions are stored in a format that is parsed by the same
   60: recursive descent parser used to read the
   61: .B dhcpd.conf(5)
   62: and
   63: .B dhclient.conf(5)
   64: files.  Lease files can contain lease declarations, and also group and
   65: subgroup declarations, host declarations and failover state
   66: declarations.  Group, subgroup and host declarations are used to
   67: record objects created using the OMAPI protocol.
   68: .PP
   69: The lease file is a log-structured file - whenever a lease changes,
   70: the contents of that lease are written to the end of the file.   This
   71: means that it is entirely possible and quite reasonable for there to
   72: be two or more declarations of the same lease in the lease file at the
   73: same time.   In that case, the instance of that particular lease that
   74: appears last in the file is the one that is in effect.
   75: .PP
   76: Group, subgroup and host declarations in the lease file are handled in
   77: the same manner, except that if any of these objects are deleted, a
   78: \fIrubout\fR is written to the lease file.   This is just the same
   79: declaration, with \fB{ deleted; }\fR in the scope of the
   80: declaration.   When the lease file is rewritten, any such rubouts that
   81: can be eliminated are eliminated.   It is possible to delete a
   82: declaration in the \fBdhcpd.conf\fR file; in this case, the rubout
   83: can never be eliminated from the \fBdhcpd.leases\fR file.
   84: .SH THE LEASE DECLARATION
   85: .PP
   86: .B lease \fIip-address\fB { \fIstatements...\fB }
   87: .PP
   88: Each lease declaration includes the single IP address that has been
   89: leased to the client.   The statements within the braces define the
   90: duration of the lease and to whom it is assigned.
   91: .PP
   92: .nf
   93: .B starts \fIdate\fB;\fR
   94: .B ends \fIdate\fB;\fR
   95: .B tstp \fIdate\fB;\fR
   96: .B tsfp \fIdate\fB;\fR
   97: .B atsfp \fIdate\fB;\fR
   98: .B cltt \fIdate\fB;\fR
   99: .fi
  100: .PP
  101: The start and end time of a lease are recorded using the \fBstarts\fR
  102: and \fBends\fR statements.   The \fBtstp\fR statement is specified if
  103: the failover protocol is being used, and indicates what time the peer
  104: has been told the lease expires.   The \fBtsfp\fR statement is
  105: also specified if the failover protocol is being used, and indicates
  106: the lease expiry time that the peer has acknowledged.
  107: The \fBatsfp\fR statement is the actual time sent from the failover
  108: partner.
  109: The \fBcltt\fR statement is the client's last transaction time.
  110: .PP
  111: The \fIdate\fR is specified in two ways, depending on the configuration
  112: value for the \fBdb-time-format\fR parameter.  If it was set to \fIdefault\fR,
  113: then the \fIdate\fR fields appear as follows:
  114: .PP
  115: .I weekday year\fB/\fImonth\fB/\fIday hour\fB:\fIminute\fB:\fIsecond\fR
  116: .PP
  117: The weekday is present to make it easy for a human to tell when a
  118: lease expires - it's specified as a number from zero to six, with zero
  119: being Sunday.  The day of week is ignored on input.  The year is
  120: specified with the century, so it should generally be four digits
  121: except for really long leases.  The month is specified as a number
  122: starting with 1 for January.  The day of the month is likewise
  123: specified starting with 1.  The hour is a number between 0 and 23, the
  124: minute a number between 0 and 59, and the second also a number between
  125: 0 and 59.
  126: .PP
  127: Lease times are specified in Universal Coordinated Time (UTC), not in
  128: the local time zone.  There is probably nowhere in the world where the
  129: times recorded on a lease are always the same as wall clock times.  On
  130: most unix machines, you can display the current time in UTC by typing
  131: \fBdate -u\fR.
  132: .PP
  133: If the \fBdb-time-format\fR was configured to \fIlocal\fR, then
  134: the \fIdate\fR fields appear as follows:
  135: .PP
  136:  \fBepoch\fR \fI<seconds-since-epoch>\fR\fB; #\fR \fI<day-name> <month-name>
  137: <day-number> <hours>\fR\fB:\fR\fI<minutes>\fR\fB:\fR\fI<seconds> <year>\fR
  138: .PP
  139: The \fIseconds-since-epoch\fR is as according to the system's local clock (often
  140: referred to as "unix time").  The \fB#\fR symbol supplies a comment that
  141: describes what actual time this is as according to the system's configured
  142: timezone, at the time the value was written.  It is provided only for human
  143: inspection.
  144: .PP
  145: If a lease will never expire, \fIdate\fR is \fBnever\fR instead of an
  146: actual date.
  147: .PP
  148: .B hardware \fIhardware-type mac-address\fB;\fR
  149: .PP
  150: The hardware statement records the MAC address of the network
  151: interface on which the lease will be used.   It is specified as a
  152: series of hexadecimal octets, separated by colons.
  153: .PP
  154: .B uid \fIclient-identifier\fB;\fR
  155: .PP
  156: The \fBuid\fR statement records the client identifier used by the
  157: client to acquire the lease.   Clients are not required to send client
  158: identifiers, and this statement only appears if the client did in fact
  159: send one.   Client identifiers are normally an ARP type (1 for
  160: ethernet) followed by the MAC address, just like in the \fBhardware\fI
  161: statement, but this is not required.
  162: .PP
  163: The client identifier is recorded as a colon-separated hexadecimal
  164: list or as a quoted string.   If it is recorded as a quoted string and
  165: it contains one or more non-printable characters, those characters are
  166: represented as octal escapes - a backslash character followed by three
  167: octal digits.
  168: .PP
  169: .B client-hostname "\fIhostname\fB";\fR
  170: .PP
  171: Most DHCP clients will send their hostname in the \fIhost-name\fR
  172: option.  If a client sends its hostname in this way, the hostname is
  173: recorded on the lease with a \fBclient-hostname\fR statement.   This
  174: is not required by the protocol, however, so many specialized DHCP
  175: clients do not send a host-name option.
  176: .PP
  177: .B abandoned;
  178: .PP
  179: The \fBabandoned\fR statement indicates that the DHCP server has
  180: abandoned the lease.   In that case, the \fBabandoned\fR statement
  181: will be used to indicate that the lease should not be reassigned.
  182: Please see the \fBdhcpd.conf(5)\fR manual page for information about
  183: abandoned leases.
  184: .PP
  185: .B binding state \fIstate\fB;
  186: .B next binding state \fIstate\fB;
  187: .PP
  188: The \fBbinding state\fR statement declares the lease's binding state.
  189: When the DHCP server is not configured to use the failover protocol, a
  190: lease's binding state will be either \fBactive\fR or \fBfree\fR.   The
  191: failover protocol adds some additional transitional states, as well as
  192: the \fBbackup\fR state, which indicates that the lease is available
  193: for allocation by the failover secondary.
  194: .PP
  195: The \fBnext binding state\fR statement indicates what state the lease
  196: will move to when the current state expires.   The time when the
  197: current state expires is specified in the \fIends\fR statement.
  198: .PP
  199: .B option agent.circuit-id \fIstring\fR;
  200: .B option agent.remote-id \fIstring\fR;
  201: .PP
  202: The \fBoption agent.circuit-id\fR and \fBoption agent.remote-id\fR
  203: statements are used to record the circuit ID and remote ID options
  204: send by the relay agent, if the relay agent uses the \fIrelay agent
  205: information option\fR.   This allows these options to be used
  206: consistently in conditional evaluations even when the client is
  207: contacting the server directly rather than through its relay agent.
  208: .PP
  209: .B set \fIvariable\fB = \fIvalue\fB;
  210: .PP
  211: The \fBset\fR statement sets the value of a variable on the lease.
  212: For general information on variables, see the \fBdhcp-eval(5)\fR
  213: manual page.
  214: .PP
  215: .B The \fIddns-text\fB variable
  216: .PP
  217: The \fIddns-text\fR variable is used to record the value of the
  218: client's TXT identification record when the interim ddns update
  219: style has been used to update the DNS for a particular lease.
  220: .PP
  221: .B The \fIddns-fwd-name\fB variable
  222: .PP
  223: The \fIddns-fwd-name\fB variable records the value of the name used in
  224: updating the client's A record if a DDNS update has been successfully
  225: done by the server.   The server may also have used this name to
  226: update the client's PTR record.
  227: .PP
  228: .B The \fIddns-client-fqdn\fB variable
  229: .PP
  230: If the server is configured to use the interim ddns update style, and
  231: is also configured to allow clients to update their own fqdns, and the
  232: client did in fact update its own fqdn, then the
  233: \fIddns-client-fqdn\fR variable records the name that the client has
  234: indicated it is using.   This is the name that the server will have
  235: used to update the client's PTR record in this case.
  236: .PP
  237: .B The \fIddns-rev-name\fB variable
  238: .PP
  239: If the server successfully updates the client's PTR record, this
  240: variable will record the name that the DHCP server used for the PTR
  241: record.   The name to which the PTR record points will be either the
  242: \fIddns-fwd-name\fR or the \fIddns-client-fqdn\fR.
  243: .PP
  244: .B The \fIvendor-class-identifier\fB variable
  245: .PP
  246: The server retains the client-supplied Vendor Class Identifier option
  247: for informational purposes, and to render them in DHCPLEASEQUERY responses.
  248: .PP
  249: .B on \fIevents\fB { \fIstatements...\fB }
  250: The \fBon\fI statement records a list of statements to execute if a
  251: certain event occurs.   The possible events that can occur for an
  252: active lease are \fBrelease\fR and \fBexpiry\fR.   More than one event
  253: can be specified - if so, the events are separated by '|' characters.
  254: .PP
  255: .B bootp;
  256: .B reserved;
  257: These two statements are effectively flags.  If present, they indicate that
  258: the BOOTP and RESERVED failover flags, respectively, should be set.  BOOTP
  259: and RESERVED dynamic leases are treated differently than normal dynamic leases,
  260: as they may only be used by the client to which they are currently allocated.
  261: .RE
  262: .SH THE FAILOVER PEER STATE DECLARATION
  263: The state of any failover peering arrangements is also recorded in the
  264: lease file, using the \fBfailover peer\fR statement:
  265: .PP
  266: .nf
  267: .B failover peer "\fIname\fB" state {
  268: .B   my   state \fIstate\fB at \fIdate\fB;
  269: .B   peer state \fIstate\fB at \fIdate\fB;
  270: .B }
  271: .fi
  272: .PP
  273: The states of the peer named \fIname\fR is being recorded.   Both the
  274: state of the running server (\fBmy state\fR) and the other failover
  275: partner (\fIpeer state\fR) are recorded.   The following states are
  276: possible: \fBunknown-state\fR, \fBpartner-down\fR, \fBnormal\fR,
  277: \fBcommunications-interrupted\fR, \fBresolution-interrupted\fR,
  278: \fBpotential-conflict\fR, \fBrecover\fR, \fBrecover-done\fR,
  279: \fBshutdown\fR, \fBpaused\fR, and \fBstartup\fR.
  280: .RE
  281: .SH FILES
  282: .B DBDIR/dhcpd.leases DBDIR/dhcpd.leases~
  283: .SH SEE ALSO
  284: dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5), RFC2132, RFC2131.
  285: .SH AUTHOR
  286: .B dhcpd(8)
  287: was written by Ted Lemon
  288: under a contract with Vixie Labs.   Funding
  289: for this project was provided by Internet Systems Consortium.
  290: Information about Internet Systems Consortium can be found at:
  291: .B https://www.isc.org/

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>