dhcp4-srv.xml 137 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
  4. <!ENTITY mdash "&#x2014;" >
  5. ]>
  6. <chapter id="dhcp4">
  7. <title>The DHCPv4 Server</title>
  8. <section id="dhcp4-start-stop">
  9. <title>Starting and Stopping the DHCPv4 Server</title>
  10. <!-- @todo Rewrite this section once #3422 is done -->
  11. <para>
  12. It is recommended that the Kea DHCPv4 server be started and stopped
  13. using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
  14. However, it is also possible to run the server directly: it accepts
  15. the following command-line switches:
  16. </para>
  17. <itemizedlist>
  18. <listitem>
  19. <simpara>
  20. <command>-c <replaceable>file</replaceable></command> -
  21. specifies the configuration file. This is the only mandatory
  22. switch.</simpara>
  23. </listitem>
  24. <listitem>
  25. <simpara>
  26. <command>-d</command> - specifies whether the server
  27. logging should be switched to debug/verbose mode. In verbose mode,
  28. the logging severity and debuglevel specified in the configuration
  29. file are ignored and "debug" severity and the maximum debuglevel
  30. (99) are assumed. The flag is convenient, for temporarily
  31. switching the server into maximum verbosity, e.g. when
  32. debugging.</simpara>
  33. </listitem>
  34. <listitem>
  35. <simpara>
  36. <command>-p <replaceable>port</replaceable></command> -
  37. specifies UDP port the server will listen on. This is only
  38. useful during testing, as the DHCPv4 server listening on
  39. ports other than default DHCPv4 ports will not be able to
  40. handle regular DHCPv4 queries.</simpara>
  41. </listitem>
  42. <listitem>
  43. <simpara>
  44. <command>-v</command> - prints out Kea version and exits.
  45. </simpara>
  46. </listitem>
  47. <listitem>
  48. <simpara>
  49. <command>-V</command> - prints out Kea extended version with
  50. additional parameters and exits.
  51. </simpara>
  52. </listitem>
  53. <listitem>
  54. <simpara>
  55. <command>-W</command> - prints out Kea configuration report
  56. and exits.
  57. </simpara>
  58. </listitem>
  59. </itemizedlist>
  60. <para>
  61. The <command>-V</command> command returns the versions of the
  62. external libraries dynamically linked.
  63. </para>
  64. <para>
  65. The <command>-W</command> command describes the environment used
  66. to build Kea. This command displays a copy of the
  67. <filename>config.report</filename> file produced by
  68. <userinput>./configure</userinput> that is embedded in the
  69. executable binary.
  70. </para>
  71. <para>
  72. The <filename>config.report</filename> may also be accessed more
  73. directly. The following command may be used to extract this
  74. information. The binary <userinput>path</userinput> may be found
  75. in the install directory or in the <filename>.libs</filename>
  76. subdirectory in the source treee. For example
  77. <filename>kea/src/bin/dhcp4/.libs/kea-dhcp4</filename>.
  78. <screen>
  79. strings <userinput>path</userinput>/kea-dhcp4 | sed -n 's/;;;; //p'
  80. </screen>
  81. </para>
  82. <para>
  83. When running in a console, the server can be shut down by
  84. pressing ctrl-c. It detects the key combination and shuts
  85. down gracefully.
  86. </para>
  87. <para>
  88. On start-up, the server will detect available network interfaces
  89. and will attempt to open UDP sockets on all interfaces
  90. mentioned in the configuration file.
  91. </para>
  92. <para>
  93. Since the DHCPv4 server opens privileged ports, it requires root
  94. access. Make sure you run this daemon as root.
  95. </para>
  96. </section>
  97. <section id="dhcp4-configuration">
  98. <title>DHCPv4 Server Configuration</title>
  99. <section>
  100. <title>Introduction</title>
  101. <para>
  102. This section explains how to configure the DHCPv4 server using the
  103. Kea configuration backend. (Kea configuration using any other
  104. backends is outside of scope of this document.) Before DHCPv4
  105. is started, its configuration file has to be created. The
  106. basic configuration is as follows:
  107. <screen>
  108. {
  109. # DHCPv4 configuration starts in this line
  110. "Dhcp4": {
  111. # First we set up global values
  112. "valid-lifetime": 4000,
  113. "renew-timer": 1000,
  114. "rebind-timer": 2000,
  115. # Next we setup the interfaces to be used by the server.
  116. "interfaces-config": {
  117. "interfaces": [ "eth0" ]
  118. },
  119. # And we specify the type of lease database
  120. "lease-database": {
  121. "type": "memfile",
  122. "persist": true,
  123. "name": "/var/kea/dhcp4.leases"
  124. },
  125. # Finally, we list the subnets from which we will be leasing addresses.
  126. "subnet4": [
  127. {
  128. "subnet": "192.0.2.0/24",
  129. "pools": [
  130. { "pool": "192.0.2.1 - 192.0.2.200" }
  131. ]
  132. }
  133. ]
  134. # DHCPv4 configuration ends with this line
  135. }
  136. } </screen>
  137. </para>
  138. <para>The following paragraphs provide a brief overview of the parameters in
  139. the above example and
  140. their format. Subsequent sections of this chapter go into much greater detail
  141. for these and other parameters.</para>
  142. <para>The lines starting with a hash (#) are comments and are ignored by
  143. the server; they do not impact its
  144. operation in any way.</para>
  145. <para>The configuration starts in the first line with the initial
  146. opening curly bracket (or brace). Each configuration consists of
  147. one or more objects. In this specific example, we have only one
  148. object called Dhcp4. This is a simplified configuration, as usually
  149. there will be additional objects, like <command>Logging</command> or
  150. <command>DhcpDns</command>, but we omit them now for clarity. The Dhcp4
  151. configuration starts with the <command>"Dhcp4": {</command> line
  152. and ends with the corresponding closing brace (in the above example,
  153. the brace after the last comment). Everything defined between those
  154. lines is considered to be the Dhcp4 configuration.</para>
  155. <para>In the general case, the order in which those parameters appear does not
  156. matter. There are two caveats here though. The first one is to remember that
  157. the configuration file must be well formed JSON. That means that the parameters
  158. for any given scope must be separated by a comma and there must not be a comma
  159. after the last parameter. When reordering a configuration file, keep in mind that
  160. moving a parameter to or from the last position in a given scope may also require
  161. moving the comma. The second caveat is that it is uncommon &mdash; although
  162. legal JSON &mdash; to
  163. repeat the same parameter multiple times. If that happens, the last occurrence of a
  164. given parameter in a given scope is used while all previous instances are
  165. ignored. This is unlikely to cause any confusion as there are no real life
  166. reasons to keep multiple copies of the same parameter in your configuration
  167. file.</para>
  168. <para>Moving onto the DHCPv4 configuration elements, the very first few elements
  169. define some global parameters. <command>valid-lifetime</command> defines for how long the addresses (leases) given out by the
  170. server are valid. If nothing changes, a client that got an address is allowed to
  171. use it for 4000 seconds. (Note that integer numbers are specified as is,
  172. without any quotes around them.) <command>renew-timer</command> and
  173. <command>rebind-timer</command> are values that
  174. define T1 and T2 timers that govern when the client will begin the renewal and
  175. rebind procedures. Note that <command>renew-timer</command> and
  176. <command>rebind-timer</command> are optional. If they are not specified the
  177. client will select values for T1 and T2 timers according to the
  178. <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>.</para>
  179. <para>The <command>interfaces-config</command> map specifies the server
  180. configuration concerning the network interfaces, on which the server should
  181. listen to the DHCP messages. The <command>interfaces</command> parameter
  182. specifies a list of network interfaces on which the server should listen.
  183. Lists are opened and closed with square brackets, with elements separated
  184. by commas. Had we wanted to listen on two interfaces, the
  185. <command>interfaces-config</command> would look like this:
  186. <screen>
  187. "interfaces-config": {
  188. "interfaces": [ "eth0", "eth1" ]
  189. },
  190. </screen>
  191. </para>
  192. <para>The next couple of lines define the lease database, the place where the server
  193. stores its lease information. This particular example tells the server to use
  194. <command>memfile</command>, which is the simplest (and fastest) database
  195. backend. It uses an in-memory database and stores leases on disk in a CSV
  196. file. This is a very simple configuration. Usually, lease database configuration
  197. is more extensive and contains additional parameters. Note that
  198. <command>lease-database</command>
  199. is an object and opens up a new scope, using an opening brace.
  200. Its parameters (just one in this example -- <command>type</command>)
  201. follow. Had there been more than one, they would be separated by commas. This
  202. scope is closed with a closing brace. As more parameters follow, a trailing
  203. comma is present.</para>
  204. <para>Finally, we need to define a list of IPv4 subnets. This is the
  205. most important DHCPv4 configuration structure as the server uses that
  206. information to process clients' requests. It defines all subnets from
  207. which the server is expected to receive DHCP requests. The subnets are
  208. specified with the <command>subnet4</command> parameter. It is a list,
  209. so it starts and ends with square brackets. Each subnet definition in
  210. the list has several attributes associated with it, so it is a structure
  211. and is opened and closed with braces. At a minimum, a subnet definition
  212. has to have at least two parameters: <command>subnet</command> (that
  213. defines the whole subnet) and <command>pools</command> (which is a list of
  214. dynamically allocated pools that are governed by the DHCP server).</para>
  215. <para>The example contains a single subnet. Had more than one been defined,
  216. additional elements
  217. in the <command>subnet4</command> parameter would be specified and
  218. separated by commas. For example, to define three subnets, the following
  219. syntax would be used:
  220. <screen>
  221. "subnet4": [
  222. {
  223. "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
  224. "subnet": "192.0.2.0/24"
  225. },
  226. {
  227. "pools": [ { "pool": "192.0.3.100 - 192.0.3.200" } ],
  228. "subnet": "192.0.3.0/24"
  229. },
  230. {
  231. "pools": [ { "pool": "192.0.4.1 - 192.0.4.254" } ],
  232. "subnet": "192.0.4.0/24"
  233. }
  234. ]
  235. </screen>
  236. </para>
  237. <para>After all parameters are specified, we have two contexts open:
  238. global and Dhcp4, hence we need two closing curly brackets to close them.
  239. In a real life configuration file there most likely would be additional
  240. components defined such as Logging or DhcpDdns, so the closing brace would
  241. be followed by a comma and another object definition.</para>
  242. </section>
  243. <section>
  244. <title>Lease Storage</title>
  245. <para>All leases issued by the server are stored in the lease database.
  246. Currently there are three database backends available:
  247. memfile (which is the default backend), MySQL and PostgreSQL.</para>
  248. <section>
  249. <title>Memfile, Basic Storage for Leases</title>
  250. <para>The server is able to store lease data in different repositories. Larger
  251. deployments may elect to store leases in a database. <xref
  252. linkend="database-configuration4"/> describes this option. In typical
  253. smaller deployments though, the server will use a CSV file rather than a database to
  254. store lease information. As well as requiring less administration, an
  255. advantage of using a file for storage is that it
  256. eliminates a dependency on third-party database software.</para>
  257. <para>The configuration of the file backend (Memfile) is controlled through
  258. the Dhcp4/lease-database parameters. The <command>type</command> parameter
  259. is mandatory and it specifies which storage for leases the server should use.
  260. The value of <userinput>"memfile"</userinput> indicates that the file should
  261. be used as the storage. The following list presents the remaining, not mandatory
  262. parameters, which can be used to configure the Memfile backend.
  263. <itemizedlist>
  264. <listitem>
  265. <simpara><command>persist</command>: controls whether the new leases and
  266. updates to existing leases are written to the file. It is strongly
  267. recommended that the value of this parameter is set to
  268. <userinput>true</userinput> at all times, during the server's normal
  269. operation. Not writing leases to disk will mean that if a server is restarted
  270. (e.g. after a power failure), it will not know what addresses have been
  271. assigned. As a result, it may hand out addresses to new clients that are
  272. already in use. The value of <userinput>false</userinput> is mostly useful
  273. for performance testing purposes. The default value of the
  274. <command>persist</command> parameter is <userinput>true</userinput>,
  275. which enables writing lease updates
  276. to the lease file.
  277. </simpara>
  278. </listitem>
  279. <listitem>
  280. <simpara><command>name</command>: specifies an absolute location of the lease
  281. file in which new leases and lease updates will be recorded. The default value
  282. for this parameter is <userinput>"[kea-install-dir]/var/kea/kea-leases4.csv"
  283. </userinput>.</simpara>
  284. </listitem>
  285. <listitem>
  286. <simpara><command>lfc-interval</command>: specifies the interval in seconds, at
  287. which the server (Memfile backend) will perform a lease file cleanup (LFC),
  288. which removes the redundant (historical) information from the lease file
  289. and effectively reduces the lease file size. The cleanup process is described
  290. in more detailed fashion further in this section. The default value of the
  291. <command>lfc-interval</command> is <userinput>0</userinput>, which disables
  292. the LFC.</simpara>
  293. </listitem>
  294. </itemizedlist>
  295. </para>
  296. <para>The example configuration of the Memfile backend is presented below:
  297. <screen>
  298. "Dhcp4": {
  299. "lease-database": {
  300. <userinput>"type": "memfile"</userinput>,
  301. <userinput>"persist": true</userinput>,
  302. <userinput>"name": "/tmp/kea-leases4.csv",</userinput>
  303. <userinput>"lfc-interval": 1800</userinput>
  304. }
  305. }
  306. </screen>
  307. This configuration selects the <filename>/tmp/kea-leases4.csv</filename> as
  308. the storage for lease information and enables persistence (writing lease updates
  309. to this file). It also configures the backend perform the periodic cleanup
  310. of the lease files, executed every 30 minutes.
  311. </para>
  312. <para>It is important to know how the lease file contents are organized
  313. to understand why the periodic lease file cleanup is needed. Every time when
  314. the server updates a lease or creates a new lease for the client, the new
  315. lease information must be recorded in the lease file. For performance reasons,
  316. the server does not supersede the existing client's lease, as it would require
  317. the lookup of the specific lease entry, but simply appends the new lease
  318. information at the end of the lease file. The previous lease entries for the
  319. client are not removed. When the server loads leases from the lease file, e.g.
  320. at the server startup, it assumes that the latest lease entry for the client
  321. is the valid one. The previous entries are discarded. This means that the
  322. server can re-construct the accurate information about the leases even though
  323. there may be many lease entries for each client. However, storing many entries
  324. for each client results in bloated lease file and impairs the performance of
  325. the server's startup and reconfiguration, as it needs to process larger number
  326. of lease entries.
  327. </para>
  328. <para>The lease file cleanup removes all previous entries for each client and
  329. leaves only the latest ones. The interval at which the cleanup is performed
  330. is configurable, and it should be selected according to the frequency of lease
  331. renewals initiated by the clients. The more frequent renewals are, the lesser
  332. value of the <command>lfc-interval</command> should be. Note however, that the
  333. LFC takes time and thus it is possible (although unlikely) that new cleanup
  334. is started while the previous cleanup instance is still running, if the
  335. <command>lfc-interval</command> is too short. The server would recover from
  336. this by skipping the new cleanup when it detects that the previous cleanup
  337. is still in progress. But, this implies that the actual cleanups will be
  338. triggered more rarely than configured. Moreover, triggering a new cleanup
  339. adds an overhead to the server, which will not be able to respond to new
  340. requests for a short period of time when the new cleanup process is spawned.
  341. Therefore, it is recommended that the <command>lfc-interval</command> value
  342. is selected in a way that would allow for completing the cleanup before the
  343. new cleanup is triggered.
  344. </para>
  345. <para>The LFC is performed by a separate process (in background) to avoid
  346. performance impact on the server process. In order to avoid the conflicts
  347. between the two processes both using the same lease files, the LFC process
  348. operates on the copy of the original lease file, rather than on the lease
  349. file used by the server to record lease updates. There are also other files
  350. being created as a side effect of the lease file cleanup. The detailed
  351. description of the LFC is located on the Kea wiki:
  352. <ulink url="http://kea.isc.org/wiki/LFCDesign"/>.
  353. </para>
  354. </section>
  355. <section id="database-configuration4">
  356. <title>Database Configuration</title>
  357. <note>
  358. <para>Database access information must be configured for the DHCPv4 server,
  359. even if it has already been configured for the DHCPv6 server. The servers
  360. store their information independently, so each server can use a separate
  361. database or both servers can use the same database.</para>
  362. </note>
  363. <para>Database configuration is controlled through the Dhcp4/lease-database
  364. parameters. The type of the database must be set to "mysql" or "postgresql",
  365. e.g.
  366. <screen>
  367. "Dhcp4": { "lease-database": { <userinput>"type": "mysql"</userinput>, ... }, ... }
  368. </screen>
  369. Next, the name of the database to hold the leases must be set: this is the
  370. name used when the lease database was created (see <xref linkend="mysql-database-create"/>
  371. or <xref linkend="pgsql-database-create"/>).
  372. <screen>
  373. "Dhcp4": { "lease-database": { <userinput>"name": "<replaceable>database-name</replaceable>" </userinput>, ... }, ... }
  374. </screen>
  375. If the database is located on a different system to the DHCPv4 server, the
  376. database host name must also be specified (although it should be noted that this
  377. configuration may have a severe impact on server performance):
  378. <screen>
  379. "Dhcp4": { "lease-database": { <userinput>"host": <replaceable>remote-host-name</replaceable></userinput>, ... }, ... }
  380. </screen>
  381. The usual state of affairs will be to have the database on the same machine as
  382. the DHCPv4 server. In this case, set the value to the empty string:
  383. <screen>
  384. "Dhcp4": { "lease-database": { <userinput>"host" : ""</userinput>, ... }, ... }
  385. </screen>
  386. </para>
  387. <para>Finally, the credentials of the account under which the server will
  388. access the database should be set:
  389. <screen>
  390. "Dhcp4": { "lease-database": { <userinput>"user": "<replaceable>user-name</replaceable>"</userinput>,
  391. <userinput>"password": "<replaceable>password</replaceable>"</userinput>,
  392. ... },
  393. ... }
  394. </screen>
  395. If there is no password to the account, set the password to the empty string
  396. "". (This is also the default.)</para>
  397. </section>
  398. </section>
  399. <section id="dhcp4-interface-configuration">
  400. <title>Interface configuration</title>
  401. <para>The DHCPv4 server has to be configured to listen on specific network
  402. interfaces. The simplest network interface configuration tells the server to
  403. listen on all available interfaces:
  404. <screen>
  405. "Dhcp4": {
  406. "interfaces-config": {
  407. "interfaces": [ <userinput>"*"</userinput> ]
  408. }
  409. ...
  410. },
  411. </screen>
  412. The asterisk plays the role of a wildcard and means "listen on all interfaces".
  413. However, it is usually a good idea to explicitly specify interface names:
  414. <screen>
  415. "Dhcp4": {
  416. "interfaces-config": {
  417. "interfaces": [ <userinput>"eth1", "eth3"</userinput> ]
  418. },
  419. ...
  420. }
  421. </screen>
  422. </para>
  423. <para>It is possible to use wildcard interface name (asterisk) concurrently
  424. with explicit interface names:
  425. <screen>
  426. "Dhcp4": {
  427. "interfaces-config": {
  428. "interfaces": [ <userinput>"eth1", "eth3", "*"</userinput> ]
  429. },
  430. ...
  431. }
  432. </screen>
  433. It is anticipated that this form of usage will only be used when it is desired to
  434. temporarily override a list of interface names and listen on all interfaces.
  435. </para>
  436. <para>Some deployments of the DHCP servers require that the servers listen
  437. on the interfaces with multiple IPv4 addresses configured. In these situations,
  438. the address to use can be selected by appending an IPv4 address to the interface
  439. name in the following manner:
  440. <screen>
  441. "Dhcp4": {
  442. "interfaces-config": {
  443. "interfaces": [ <userinput>"eth1/10.0.0.1", "eth3/192.0.2.3"</userinput> ]
  444. },
  445. ...
  446. }
  447. </screen>
  448. </para>
  449. <para>If it is desired that the server listens on multiple IPv4 addresses assigned
  450. to the same interface, multiple addresses can be specified for this interface
  451. as in the example below:
  452. <screen>
  453. "Dhcp4": {
  454. "interfaces-config": {
  455. "interfaces": [ <userinput>"eth1/10.0.0.1", "eth1/10.0.0.2"</userinput> ]
  456. },
  457. ...
  458. }
  459. </screen>
  460. </para>
  461. <para>Alternatively, if the server should listen on all addresses for the particular
  462. interface, an interface name without any address should be specified.</para>
  463. <para>Kea supports responding to directly connected clients which don't have
  464. an address configured on the interface yet. This requires that the server
  465. injects the hardware address of the destination into the data link layer
  466. of the packet being sent to the client. The DHCPv4 server utilizes the
  467. raw sockets to achieve this, and builds the entire IP/UDP stack for the
  468. outgoing packets. The down side of raw socket use, however, is that incoming
  469. and outgoing packets bypass the firewalls (e.g. iptables). It is also
  470. troublesome to handle traffic on multiple IPv4 addresses assigned to the
  471. same interface, as raw sockets are bound to the interface and advanced
  472. packet filtering techniques (e.g. using the BPF) have to be used to
  473. receive unicast traffic on the desired addresses assigned to the interface,
  474. rather than capturing whole traffic reaching the interface to which the raw
  475. socket is bound. Therefore, in the deployments where the server doesn't
  476. have to provision the directly connected clients and only receives the
  477. unicast packets from the relay agents, it is desired to configure the
  478. DHCP server to utilize the IP/UDP datagram sockets, instead of raw sockets.
  479. The following configuration demonstrates how this can be achieved:
  480. <screen>
  481. "Dhcp4": {
  482. "interfaces-config": {
  483. "interfaces": [ <userinput>"eth1", "eth3"</userinput> ],
  484. "dhcp-socket-type": "udp"
  485. },
  486. ...
  487. }
  488. </screen>
  489. The <command>dhcp-socket-type</command> specifies that the IP/UDP sockets will
  490. be opened on all interfaces on which the server listens, i.e. "eth1" and
  491. "eth3" in our case. If the <command>dhcp-socket-type</command> is set to
  492. <userinput>raw</userinput>, it configures the server to use raw sockets
  493. instead. If the <command>dhcp-socket-type</command> value is not specified, the
  494. default value <userinput>raw</userinput> is used.
  495. </para>
  496. <para>Using UDP sockets automatically disables the reception of brodcast
  497. packets from directly connected clients. This effectively means that the
  498. UDP sockets can be used for relayed traffic only. When using the raw sockets,
  499. both the traffic from the directly connected clients and the relayed traffic
  500. will be handled. Caution should be taken when configuring the server to open
  501. multiple raw sockets on the interface with several IPv4 addresses assigned.
  502. If the directly connected client sends the message to the brodcast address
  503. all sockets on this link will receive this message and multiple responses
  504. will be sent to the client. Hence, the configuration with multiple IPv4
  505. addresses assigned to the interface should not be used when the directly
  506. connected clients are operating on that link. To use a single address on
  507. such interface, the "interface-name/address" notation should be used.
  508. </para>
  509. <note>
  510. <para>Specifying the value <userinput>raw</userinput> as the socket type,
  511. doesn't guarantee that the raw sockets will be used! The use of raw sockets
  512. to handle the traffic from the directly connected clients is currently
  513. supported on Linux and BSD systems only. If the raw sockets are not
  514. supported on the particular OS, the server will issue a warning and
  515. fall back to use the IP/UDP sockets.</para>
  516. </note>
  517. </section>
  518. <section id="ipv4-subnet-id">
  519. <title>IPv4 Subnet Identifier</title>
  520. <para>
  521. The subnet identifier is a unique number associated with a particular subnet.
  522. In principle, it is used to associate clients' leases with their respective subnets.
  523. When a subnet identifier is not specified for a subnet being configured, it will
  524. be automatically assigned by the configuration mechanism. The identifiers
  525. are assigned from 1 and are monotonically increased for each subsequent
  526. subnet: 1, 2, 3 ....
  527. </para>
  528. <para>
  529. If there are multiple subnets configured with auto-generated identifiers and
  530. one of them is removed, the subnet identifiers may be renumbered. For example:
  531. if there are four subnets and the third is removed the last subnet will be assigned
  532. the identifier that the third subnet had before removal. As a result, the leases
  533. stored in the lease database for subnet 3 are now associated with
  534. subnet 4, something that may have unexpected consequences. It is planned
  535. to implement a mechanism to preserve auto-generated subnet ids in a
  536. future version of Kea. However, the only remedy for this issue
  537. at present is to
  538. manually specify a unique identifier for each subnet.
  539. </para>
  540. <para>
  541. The following configuration will assign the specified subnet
  542. identifier to the newly configured subnet:
  543. <screen>
  544. "Dhcp4": {
  545. "subnet4": [
  546. {
  547. "subnet": "192.0.2.0/24",
  548. <userinput>"id": 1024</userinput>,
  549. ...
  550. }
  551. ]
  552. }
  553. </screen>
  554. This identifier will not change for this subnet unless the "id" parameter is
  555. removed or set to 0. The value of 0 forces auto-generation of the subnet
  556. identifier.
  557. </para>
  558. <!-- @todo: describe whether database needs to be updated after changing
  559. id -->
  560. </section>
  561. <section id="dhcp4-address-config">
  562. <title>Configuration of IPv4 Address Pools</title>
  563. <para>
  564. The essential role of DHCPv4 server is address assignment. The server has to
  565. be configured with at least one subnet and one pool of dynamic addresses to
  566. be managed. For example, assume that the server is connected to a network
  567. segment that uses the 192.0.2.0/24 prefix. The Administrator of that network
  568. has decided that addresses from range 192.0.2.10 to 192.0.2.20 are going to
  569. be managed by the Dhcp4 server. Such a configuration can be achieved in the
  570. following way:
  571. <screen>
  572. "Dhcp4": {
  573. <userinput>"subnet4": [
  574. {
  575. "subnet": "192.0.2.0/24",
  576. "pools": [
  577. { "pool": "192.0.2.10 - 192.0.2.20" }
  578. ],
  579. ...
  580. }
  581. ]</userinput>
  582. }</screen>
  583. Note that subnet is defined as a simple string, but the <command>pools</command> parameter is
  584. actually a list of pools: for this reason, the pools definition is enclosed
  585. in square brackets, even though only one range of addresses is
  586. specified in this example.</para>
  587. <para>Each pool is a structure that contains the parameters
  588. that describe a single pool. Currently there is only one parameter,
  589. <command>pool</command>, which gives the range of addresses
  590. in the pool. Additional parameters will be added in future
  591. releases of Kea.</para>
  592. <para>It is possible to define more than one pool in a subnet: continuing
  593. the previous example, further assume that 192.0.2.64/26 should be also be
  594. managed by the server. It could be written as 192.0.2.64 to
  595. 192.0.2.127. Alternatively, it can be expressed more simply as
  596. 192.0.2.64/26. Both formats are supported by Dhcp4 and can be mixed in the
  597. pool list. For example, one could define the following pools:
  598. <screen>
  599. "Dhcp4": {
  600. "subnet4": [
  601. {
  602. "subnet": "192.0.2.0/24",
  603. <userinput>"pools": [
  604. { "pool": "192.0.2.10-192.0.2.20" },
  605. { "pool": "192.0.2.64/26" }
  606. ]</userinput>,
  607. ...
  608. }
  609. ],
  610. ...
  611. }
  612. </screen>
  613. The number of pools is not limited, but for performance reasons it is recommended to
  614. use as few as possible. White space in pool definitions is ignored, so
  615. spaces before and after the hyphen are optional. They can be used to improve readability.
  616. </para>
  617. <para>
  618. The server may be configured to serve more than one subnet:
  619. <screen>
  620. "Dhcp4": {
  621. "subnet4": [
  622. {
  623. "subnet": "192.0.2.0/24",
  624. "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
  625. ...
  626. },
  627. {
  628. "subnet": "192.0.3.0/24",
  629. "pools": [ { "pool": "192.0.3.100 - 192.0.3.200" } ],
  630. ...
  631. },
  632. {
  633. "subnet": "192.0.4.0/24",
  634. "pools": [ { "pool": "192.0.4.1 - 192.0.4.254" } ],
  635. ...
  636. }
  637. ]
  638. }
  639. </screen>
  640. </para>
  641. <para>
  642. When configuring a DHCPv4 server using prefix/length notation, please pay
  643. attention to the boundary values. When specifying that the server can use
  644. a given pool, it will also be able to allocate the first (typically network
  645. address) and the last (typically broadcast address) address from that pool.
  646. In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and
  647. 192.0.3.255 addresses may be assigned as well. This may be invalid in some
  648. network configurations. If you want to avoid this, please use the "min-max" notation.
  649. </para>
  650. </section>
  651. <section id="dhcp4-std-options">
  652. <title>Standard DHCPv4 options</title>
  653. <para>
  654. One of the major features of the DHCPv4 server is to provide configuration
  655. options to clients. Although there are several options that require
  656. special behavior, most options are sent by the server only if the client
  657. explicitly requests them using the Parameter Request List option.
  658. The last column of the <xref linkend="dhcp4-std-options-list"/> specifies
  659. which options can be sent by the server even when they are not
  660. requested in the Parameter Request List option, and which are sent only
  661. when explicitly requested. These options are marked with the 'true'
  662. and 'false' values respectively. One group of options which are
  663. sent by the server even when they are not requested are those that
  664. require special processing, e.g. Client FQDN option returned if the
  665. client has sent Client FQDN option to the server. Another group comprises
  666. options with the fixed values specified in the server configuration,
  667. e.g. 'domain-name-servers'.
  668. </para>
  669. <para>
  670. The following example shows how to configure the addresses of DNS
  671. servers, which is one of the most frequently used options. Options
  672. specified in this way are considered global and apply to all
  673. configured subnets.
  674. <screen>
  675. "Dhcp4": {
  676. "option-data": [
  677. {
  678. <userinput>"name": "domain-name-servers",
  679. "code": 6,
  680. "space": "dhcp4",
  681. "csv-format": true,
  682. "data": "192.0.2.1, 192.0.2.2"</userinput>
  683. },
  684. ...
  685. ]
  686. }
  687. </screen>
  688. </para>
  689. <para>
  690. The <command>name</command> parameter specifies the
  691. option name. For a complete list of currently supported names,
  692. see <xref linkend="dhcp4-std-options-list"/> below.
  693. The <command>code</command> parameter specifies the option code, which must match one of the
  694. values from that list. The next line specifies the option space, which must always
  695. be set to "dhcp4" as these are standard DHCPv4 options. For
  696. other option spaces, including custom option spaces, see <xref
  697. linkend="dhcp4-option-spaces"/>. The next line specifies the format in
  698. which the data will be entered: use of CSV (comma
  699. separated values) is recommended. The sixth line gives the actual value to
  700. be sent to clients. Data is specified as normal text, with
  701. values separated by commas if more than one value is
  702. allowed.
  703. </para>
  704. <para>
  705. Options can also be configured as hexadecimal values. If
  706. <command>csv-format</command> is
  707. set to false, option data must be specified as a hexadecimal string. The
  708. following commands configure the domain-name-servers option for all
  709. subnets with the following addresses: 192.0.3.1 and 192.0.3.2.
  710. Note that <command>csv-format</command> is set to false.
  711. <screen>
  712. "Dhcp4": {
  713. "option-data": [
  714. {
  715. <userinput>"name": "domain-name-servers",
  716. "code": 6,
  717. "space": "dhcp4",
  718. "csv-format": false,
  719. "data": "C0 00 03 01 C0 00 03 02"</userinput>
  720. },
  721. ...
  722. ],
  723. ...
  724. }</screen>
  725. </para>
  726. <para>
  727. Most of the parameters in the "option-data" structure are optional and
  728. can be omitted in some circumstances as discussed in the
  729. <xref linkend="dhcp4-option-data-defaults"/>.
  730. </para>
  731. <para>
  732. It is possible to specify or override options on a per-subnet basis. If
  733. clients connected to most of your subnets are expected to get the
  734. same values of a given option, you should use global options: you
  735. can then override specific values for a small number of subnets.
  736. On the other hand, if you use different values in each subnet,
  737. it does not make sense to specify global option values
  738. (Dhcp4/option-data), rather you should set only subnet-specific values
  739. (Dhcp4/subnet[X]/option-data[Y]).
  740. </para>
  741. <para>
  742. The following commands override the global
  743. DNS servers option for a particular subnet, setting a single DNS
  744. server with address 192.0.2.3.
  745. <screen>
  746. "Dhcp4": {
  747. "subnet4": [
  748. {
  749. <userinput>"option-data": [
  750. {
  751. "name": "domain-name-servers",
  752. "code": 6,
  753. "space": "dhcp4",
  754. "csv-format": true,
  755. "data": "192.0.2.3"
  756. },
  757. ...
  758. ]</userinput>,
  759. ...
  760. },
  761. ...
  762. ],
  763. ...
  764. }
  765. </screen>
  766. </para>
  767. <para>
  768. The currently supported standard DHCPv4 options are
  769. listed in <xref linkend="dhcp4-std-options-list"/>
  770. and <xref linkend="dhcp4-std-options-list-part2"/>.
  771. The "Name" and "Code"
  772. are the values that should be used as a name in the option-data
  773. structures. "Type" designates the format of the data: the meanings of
  774. the various types is given in <xref linkend="dhcp-types"/>.
  775. </para>
  776. <para>
  777. Some options are designated as arrays, which means that more than one
  778. value is allowed in such an option. For example the option time-servers
  779. allows the specification of more than one IPv4 address, so allowing
  780. clients to obtain the addresses of multiple NTP servers.
  781. </para>
  782. <!-- @todo: describe record types -->
  783. <para>
  784. The <xref linkend="dhcp4-custom-options"/> describes the configuration
  785. syntax to create custom option definitions (formats). It is generally not
  786. allowed to create custom definitions for standard options, even if the
  787. definition being created matches the actual option format defined in the
  788. RFCs. There is an exception from this rule for standard options for which
  789. Kea does not provide a definition yet. In order to use such options,
  790. a server administrator must create a definition as described in
  791. <xref linkend="dhcp4-custom-options"/> in the 'dhcp4' option space. This
  792. definition should match the option format described in the relevant
  793. RFC but the configuration mechanism will allow any option format as it has
  794. no means to validate the format at the moment.
  795. </para>
  796. <para>
  797. <table frame="all" id="dhcp4-std-options-list">
  798. <title>List of standard DHCPv4 options</title>
  799. <tgroup cols='5'>
  800. <colspec colname='name'/>
  801. <colspec colname='code' align='center'/>
  802. <colspec colname='type' align='center'/>
  803. <colspec colname='array' align='center'/>
  804. <colspec colname='always-returned' align='center'/>
  805. <thead>
  806. <row>
  807. <entry>Name</entry>
  808. <entry>Code</entry>
  809. <entry>Type</entry>
  810. <entry>Array?</entry>
  811. <entry>Returned if not requested?</entry>
  812. </row>
  813. </thead>
  814. <tbody>
  815. <row><entry>subnet-mask</entry><entry>1</entry><entry>ipv4-address</entry><entry>false</entry><entry>true</entry></row>
  816. <row><entry>time-offset</entry><entry>2</entry><entry>int32</entry><entry>false</entry><entry>false</entry></row>
  817. <row><entry>routers</entry><entry>3</entry><entry>ipv4-address</entry><entry>true</entry><entry>true</entry></row>
  818. <row><entry>time-servers</entry><entry>4</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  819. <row><entry>name-servers</entry><entry>5</entry><entry>ipv4-address</entry><entry>false</entry><entry>false</entry></row>
  820. <row><entry>domain-name-servers</entry><entry>6</entry><entry>ipv4-address</entry><entry>true</entry><entry>true</entry></row>
  821. <row><entry>log-servers</entry><entry>7</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  822. <row><entry>cookie-servers</entry><entry>8</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  823. <row><entry>lpr-servers</entry><entry>9</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  824. <row><entry>impress-servers</entry><entry>10</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  825. <row><entry>resource-location-servers</entry><entry>11</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  826. <row><entry>host-name</entry><entry>12</entry><entry>string</entry><entry>false</entry><entry>true</entry></row>
  827. <row><entry>boot-size</entry><entry>13</entry><entry>uint16</entry><entry>false</entry><entry>false</entry></row>
  828. <row><entry>merit-dump</entry><entry>14</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  829. <row><entry>domain-name</entry><entry>15</entry><entry>fqdn</entry><entry>false</entry><entry>true</entry></row>
  830. <row><entry>swap-server</entry><entry>16</entry><entry>ipv4-address</entry><entry>false</entry><entry>false</entry></row>
  831. <row><entry>root-path</entry><entry>17</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  832. <row><entry>extensions-path</entry><entry>18</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  833. <row><entry>ip-forwarding</entry><entry>19</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  834. <row><entry>non-local-source-routing</entry><entry>20</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  835. <row><entry>policy-filter</entry><entry>21</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  836. <row><entry>max-dgram-reassembly</entry><entry>22</entry><entry>uint16</entry><entry>false</entry><entry>false</entry></row>
  837. <row><entry>default-ip-ttl</entry><entry>23</entry><entry>uint8</entry><entry>false</entry><entry>false</entry></row>
  838. <row><entry>path-mtu-aging-timeout</entry><entry>24</entry><entry>uint32</entry><entry>false</entry><entry>false</entry></row>
  839. <row><entry>path-mtu-plateau-table</entry><entry>25</entry><entry>uint16</entry><entry>true</entry><entry>false</entry></row>
  840. <row><entry>interface-mtu</entry><entry>26</entry><entry>uint16</entry><entry>false</entry><entry>false</entry></row>
  841. <row><entry>all-subnets-local</entry><entry>27</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  842. <row><entry>broadcast-address</entry><entry>28</entry><entry>ipv4-address</entry><entry>false</entry><entry>false</entry></row>
  843. <row><entry>perform-mask-discovery</entry><entry>29</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  844. <row><entry>mask-supplier</entry><entry>30</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  845. <row><entry>router-discovery</entry><entry>31</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  846. <row><entry>router-solicitation-address</entry><entry>32</entry><entry>ipv4-address</entry><entry>false</entry><entry>false</entry></row>
  847. <row><entry>static-routes</entry><entry>33</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  848. <row><entry>trailer-encapsulation</entry><entry>34</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  849. <row><entry>arp-cache-timeout</entry><entry>35</entry><entry>uint32</entry><entry>false</entry><entry>false</entry></row>
  850. <row><entry>ieee802-3-encapsulation</entry><entry>36</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  851. <row><entry>default-tcp-ttl</entry><entry>37</entry><entry>uint8</entry><entry>false</entry><entry>false</entry></row>
  852. <row><entry>tcp-keepalive-interval</entry><entry>38</entry><entry>uint32</entry><entry>false</entry><entry>false</entry></row>
  853. <row><entry>tcp-keepalive-garbage</entry><entry>39</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
  854. </tbody>
  855. </tgroup>
  856. </table>
  857. </para>
  858. <para>
  859. <table frame="all" id="dhcp4-std-options-list-part2">
  860. <title>List of standard DHCPv4 options (continued)</title>
  861. <tgroup cols='5'>
  862. <colspec colname='name'/>
  863. <colspec colname='code'/>
  864. <colspec colname='type'/>
  865. <colspec colname='array'/>
  866. <colspec colname='always-returned' align='center'/>
  867. <thead>
  868. <row>
  869. <entry>Name</entry>
  870. <entry>Code</entry>
  871. <entry>Type</entry>
  872. <entry>Array?</entry>
  873. <entry>Returned if not requested?</entry>
  874. </row>
  875. </thead>
  876. <tbody>
  877. <row><entry>nis-domain</entry><entry>40</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  878. <row><entry>nis-servers</entry><entry>41</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  879. <row><entry>ntp-servers</entry><entry>42</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  880. <row><entry>vendor-encapsulated-options</entry><entry>43</entry><entry>empty</entry><entry>false</entry><entry>false</entry></row>
  881. <row><entry>netbios-name-servers</entry><entry>44</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  882. <row><entry>netbios-dd-server</entry><entry>45</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  883. <row><entry>netbios-node-type</entry><entry>46</entry><entry>uint8</entry><entry>false</entry><entry>false</entry></row>
  884. <row><entry>netbios-scope</entry><entry>47</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  885. <row><entry>font-servers</entry><entry>48</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  886. <row><entry>x-display-manager</entry><entry>49</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  887. <!-- Lease time and requested address should not be configured by a user.
  888. <row><entry>dhcp-requested-address</entry><entry>50</entry><entry>ipv4-address</entry><entry>false</entry><entry>true</entry></row>
  889. <row><entry>dhcp-lease-time</entry><entry>51</entry><entry>uint32</entry><entry>false</entry><entry>true</entry></row>
  890. -->
  891. <row><entry>dhcp-option-overload</entry><entry>52</entry><entry>uint8</entry><entry>false</entry><entry>false</entry></row>
  892. <!-- Message Type, Server Identifier and Parameter Request List should not be configured by a user.
  893. <row><entry>dhcp-message-type</entry><entry>53</entry><entry>uint8</entry><entry>false</entry><entry>false</entry></row>
  894. <row><entry>dhcp-server-identifier</entry><entry>54</entry><entry>ipv4-address</entry><entry>false</entry><entry>true</entry></row>
  895. <row><entry>dhcp-parameter-request-list</entry><entry>55</entry><entry>uint8</entry><entry>true</entry><entry>true</entry></row>
  896. -->
  897. <row><entry>dhcp-message</entry><entry>56</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  898. <row><entry>dhcp-max-message-size</entry><entry>57</entry><entry>uint16</entry><entry>false</entry><entry>false</entry></row>
  899. <!-- Renewal and rebinding time should not be configured by a user.
  900. <row><entry>dhcp-renewal-time</entry><entry>58</entry><entry>uint32</entry><entry>false</entry><entry>true</entry></row>
  901. <row><entry>dhcp-rebinding-time</entry><entry>59</entry><entry>uint32</entry><entry>false</entry><entry>true</entry></row>
  902. -->
  903. <row><entry>vendor-class-identifier</entry><entry>60</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
  904. <!-- Client identifier should not be configured by a user.
  905. <row><entry>dhcp-client-identifier</entry><entry>61</entry><entry>binary</entry><entry>false</entry><entry>true</entry></row>
  906. -->
  907. <row><entry>nwip-domain-name</entry><entry>62</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  908. <row><entry>nwip-suboptions</entry><entry>63</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
  909. <row><entry>tftp-server-name</entry><entry>66</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  910. <row><entry>boot-file-name</entry><entry>67</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
  911. <row><entry>user-class</entry><entry>77</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
  912. <row><entry>fqdn</entry><entry>81</entry><entry>record</entry><entry>false</entry><entry>true</entry></row>
  913. <!-- Relay Agent Information is not configured by the user.
  914. It is merely echoed by the server
  915. <row><entry>dhcp-agent-options</entry><entry>82</entry><entry>empty</entry><entry>false</entry><entry>false</entry></row>
  916. -->
  917. <row><entry>authenticate</entry><entry>90</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
  918. <row><entry>client-last-transaction-time</entry><entry>91</entry><entry>uint32</entry><entry>false</entry><entry>false</entry></row>
  919. <row><entry>associated-ip</entry><entry>92</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
  920. <row><entry>subnet-selection</entry><entry>118</entry><entry>ipv4-address</entry><entry>false</entry><entry>false</entry></row>
  921. <row><entry>domain-search</entry><entry>119</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
  922. <row><entry>vivco-suboptions</entry><entry>124</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
  923. <row><entry>vivso-suboptions</entry><entry>125</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
  924. </tbody>
  925. </tgroup>
  926. </table>
  927. </para>
  928. <para>
  929. <table frame="all" id="dhcp-types">
  930. <title>List of standard DHCP option types</title>
  931. <tgroup cols='2'>
  932. <colspec colname='name'/>
  933. <colspec colname='meaning'/>
  934. <thead>
  935. <row><entry>Name</entry><entry>Meaning</entry></row>
  936. </thead>
  937. <tbody>
  938. <row><entry>binary</entry><entry>An arbitrary string of bytes, specified as a set of hexadecimal digits.</entry></row>
  939. <row><entry>boolean</entry><entry>Boolean value with allowed values true or false</entry></row>
  940. <row><entry>empty</entry><entry>No value, data is carried in suboptions</entry></row>
  941. <row><entry>fqdn</entry><entry>Fully qualified domain name (e.g. www.example.com)</entry></row>
  942. <row><entry>ipv4-address</entry><entry>IPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)</entry></row>
  943. <row><entry>ipv6-address</entry><entry>IPv6 address in the usual colon notation (e.g. 2001:db8::1)</entry></row>
  944. <row><entry>record</entry><entry>Structured data that may comprise any types (except "record" and "empty")</entry></row>
  945. <row><entry>string</entry><entry>Any text</entry></row>
  946. <row><entry>uint8</entry><entry>8 bit unsigned integer with allowed values 0 to 255</entry></row>
  947. <row><entry>uint16</entry><entry>16 bit unsigned integer with allowed values 0 to 65535</entry></row>
  948. <row><entry>uint32</entry><entry>32 bit unsigned integer with allowed values 0 to 4294967295</entry></row>
  949. </tbody>
  950. </tgroup>
  951. </table>
  952. </para>
  953. </section>
  954. <section id="dhcp4-custom-options">
  955. <title>Custom DHCPv4 options</title>
  956. <para>Kea supports custom (non-standard) DHCPv4 options. Assume
  957. that we want to define a new DHCPv4 option called "foo" which
  958. will have code 222 and will convey a single unsigned 32 bit
  959. integer value. We can define such an option by using the
  960. following entry in the configuration file:
  961. <screen>
  962. "Dhcp4": {
  963. "option-def": [
  964. {
  965. <userinput>"name": "foo",
  966. "code": 222,
  967. "type": "uint32",
  968. "array": false,
  969. "record-types": "",
  970. "space": "dhcp4",
  971. "encapsulate": ""</userinput>
  972. }, ...
  973. ],
  974. ...
  975. }
  976. </screen>
  977. The <command>false</command> value of the <command>array</command>
  978. parameter determines that the option does NOT comprise an array of
  979. "uint32" values but rather a single value. Two other parameters have been
  980. left blank: <command>record-types</command> and
  981. <command>encapsulate</command>. The former specifies the comma separated
  982. list of option data fields if the option comprises a record of data
  983. fields. This should be non-empty if the <command>type</command> is set to
  984. "record". Otherwise it must be left blank. The latter parameter specifies
  985. the name of the option space being encapsulated by the particular
  986. option. If the particular option does not encapsulate any option space it
  987. should be left blank. Note that the above set of comments define the
  988. format of the new option and do not set its values.
  989. </para>
  990. <note>
  991. <para>
  992. In the current release the default values are not propagated to the
  993. parser when the new configuration is being set. Therefore, all
  994. parameters must be specified at all times, even if their values are
  995. left blank.
  996. </para>
  997. </note>
  998. <para>Once the new option format is defined, its value is set
  999. in the same way as for a standard option. For example the following
  1000. commands set a global value that applies to all subnets.
  1001. <screen>
  1002. "Dhcp4": {
  1003. "option-data": [
  1004. {
  1005. <userinput>"name": "foo",
  1006. "code": 222,
  1007. "space": "dhcp4",
  1008. "csv-format": true,
  1009. "data": "12345"</userinput>
  1010. }, ...
  1011. ],
  1012. ...
  1013. }
  1014. </screen>
  1015. </para>
  1016. <para>New options can take more complex forms than simple use of
  1017. primitives (uint8, string, ipv4-address etc): it is possible to
  1018. define an option comprising a number of existing primitives.
  1019. Assume we want to define a new option that will consist of
  1020. an IPv4 address, followed by an unsigned 16 bit integer, followed by
  1021. a boolean value, followed by a text string. Such an option could
  1022. be defined in the following way:
  1023. <screen>
  1024. "Dhcp4": {
  1025. "option-def": [
  1026. {
  1027. <userinput>"name": "bar",
  1028. "code": 223,
  1029. "space": "dhcp4",
  1030. "type": "record",
  1031. "array": false,
  1032. "record-types": "ipv4-address, uint16, boolean, string",
  1033. "encapsulate": ""</userinput>
  1034. }, ...
  1035. ],
  1036. ...
  1037. }
  1038. </screen>
  1039. The <command>type</command> is set to "record" to indicate that the option contains
  1040. multiple values of different types. These types are given as a comma-separated
  1041. list in the <command>record-types</command> field and should be those listed in <xref linkend="dhcp-types"/>.
  1042. </para>
  1043. <para>
  1044. The values of the option are set as follows:
  1045. <screen>
  1046. "Dhcp4": {
  1047. "option-data": [
  1048. {
  1049. <userinput>"name": "bar",
  1050. "space": "dhcp4",
  1051. "code": 223,
  1052. "csv-format": true,
  1053. "data": "192.0.2.100, 123, true, Hello World"</userinput>
  1054. }
  1055. ],
  1056. ...
  1057. }</screen>
  1058. <command>csv-format</command> is set to <command>true</command> to indicate
  1059. that the <command>data</command> field comprises a command-separated list
  1060. of values. The values in the <command>data</command> must correspond to
  1061. the types set in the <command>record-types</command> field of the option
  1062. definition.
  1063. </para>
  1064. <note>
  1065. <para>In the general case, boolean values are specified as <command>true</command> or
  1066. <command>false</command>, without quotes. Some specific boolean parameters may
  1067. accept also <command>"true"</command>, <command>"false"</command>,
  1068. <command>0</command>, <command>1</command>, <command>"0"</command> and
  1069. <command>"1"</command>. Future Kea versions will accept all those values
  1070. for all boolean parameters.</para>
  1071. </note>
  1072. </section>
  1073. <section id="dhcp4-vendor-opts">
  1074. <title>DHCPv4 Vendor Specific Options</title>
  1075. <para>
  1076. Currently there are three option spaces defined: "dhcp4" (used by the DHCPv4 daemon)
  1077. and "dhcp6" (for the DHCPv6 daemon); there is also "vendor-encapsulated-options-space",
  1078. which is empty by default, but options
  1079. can be defined in it. Those options are called vendor-specific
  1080. information options. The following examples show how to define
  1081. an option "foo" with code 1 that consists of an IPv4 address, an
  1082. unsigned 16 bit integer and a string. The "foo" option is conveyed
  1083. in a vendor specific information option.
  1084. </para>
  1085. <para>
  1086. The first step is to define the format of the option:
  1087. <screen>
  1088. "Dhcp4": {
  1089. "option-def": [
  1090. {
  1091. <userinput>"name": "foo",
  1092. "code": 1,
  1093. "space": "vendor-encapsulated-options-space",
  1094. "type": "record",
  1095. "array": false,
  1096. "record-types": "ipv4-address, uint16, string",
  1097. "encapsulates": ""</userinput>
  1098. }
  1099. ],
  1100. ...
  1101. }</screen>
  1102. (Note that the option space is set to "vendor-encapsulated-options-space".)
  1103. Once the option format is defined, the next step is to define actual values
  1104. for that option:
  1105. <screen>
  1106. "Dhcp4": {
  1107. "option-data": [
  1108. {
  1109. <userinput>"name": "foo",
  1110. "space": "vendor-encapsulated-options-space",
  1111. "code": 1,
  1112. "csv-format": true,
  1113. "data": "192.0.2.3, 123, Hello World"</userinput>
  1114. }
  1115. ],
  1116. ...
  1117. }</screen>
  1118. We also set up a dummy value for "vendor-encapsulated-options", the option that conveys our sub-option "foo".
  1119. This is required else the option will not be included in messages sent to the client.
  1120. <screen>
  1121. "Dhcp4": {
  1122. "option-data": [
  1123. {
  1124. <userinput>"name": "vendor-encapsulated-options",
  1125. "space": "dhcp4",
  1126. "code": 43,
  1127. "csv-format": false,
  1128. "data": ""</userinput>
  1129. }
  1130. ],
  1131. ...
  1132. }</screen>
  1133. </para>
  1134. <note>
  1135. <para>
  1136. With this version of Kea, the "vendor-encapsulated-options" option
  1137. must be specified in the configuration although it has no configurable
  1138. parameters. If it is not specified, the server will assume that it is
  1139. not configured and will not send it to a client. In the future there
  1140. will be no need to include this option in the configuration.
  1141. </para>
  1142. </note>
  1143. </section>
  1144. <section id="dhcp4-option-spaces">
  1145. <title>Nested DHCPv4 Options (Custom Option Spaces)</title>
  1146. <para>It is sometimes useful to define completely new option
  1147. space. This is the case when user creates new option in the
  1148. standard option space ("dhcp4 or "dhcp6") and wants this option
  1149. to convey sub-options. Since they are in a separate space,
  1150. sub-option codes will have a separate numbering scheme and may
  1151. overlap with the codes of standard options.
  1152. </para>
  1153. <para>Note that creation of a new option space when defining
  1154. sub-options for a standard option is not required, because it is
  1155. created by default if the standard option is meant to convey any
  1156. sub-options (see <xref linkend="dhcp4-vendor-opts"/>).
  1157. </para>
  1158. <para>
  1159. Assume that we want to have a DHCPv4 option called "container" with
  1160. code 222 that conveys two sub-options with codes 1 and 2.
  1161. First we need to define the new sub-options:
  1162. <screen>
  1163. "Dhcp4": {
  1164. "option-def": [
  1165. {
  1166. <userinput>"name": "subopt1",
  1167. "code": 1,
  1168. "space": "isc",
  1169. "type": "ipv4-address",
  1170. "record-types": "",
  1171. "array": false,
  1172. "encapsulate ""
  1173. },
  1174. {
  1175. "name": "subopt2",
  1176. "code": 2,
  1177. "space": "isc",
  1178. "type": "string",
  1179. "record-types": "",
  1180. "array": false,
  1181. "encapsulate": ""</userinput>
  1182. }
  1183. ],
  1184. ...
  1185. }</screen>
  1186. Note that we have defined the options to belong to a new option space
  1187. (in this case, "isc").
  1188. </para>
  1189. <para>
  1190. The next step is to define a regular DHCPv4 option with our desired
  1191. code and specify that it should include options from the new option space:
  1192. <screen>
  1193. "Dhcp4": {
  1194. "option-def": [
  1195. ...,
  1196. {
  1197. <userinput>"name": "container",
  1198. "code": 222,
  1199. "space": "dhcp4",
  1200. "type": "empty",
  1201. "array": false,
  1202. "record-types": "",
  1203. "encapsulate": "isc"</userinput>
  1204. }
  1205. ],
  1206. ...
  1207. }</screen>
  1208. The name of the option space in which the sub-options are defined
  1209. is set in the "encapsulate" field. The "type" field is set to "empty"
  1210. to indicate that this option does not carry any data other than
  1211. sub-options.
  1212. </para>
  1213. <para>
  1214. Finally, we can set values for the new options:
  1215. <screen>
  1216. "Dhcp4": {
  1217. "option-data": [
  1218. {
  1219. <userinput>"name": "subopt1",
  1220. "space": "isc",
  1221. "code": 1,
  1222. "csv-format": true,
  1223. "data": "192.0.2.3"</userinput>
  1224. },
  1225. }
  1226. <userinput>"name": "subopt2",
  1227. "space": "isc",
  1228. "code": 2,
  1229. "csv-format": true,
  1230. "data": "Hello world"</userinput>
  1231. },
  1232. {
  1233. <userinput>"name": "container",
  1234. "space": "dhcp4",
  1235. "code": 222,
  1236. "csv-format": true,
  1237. "data": ""</userinput>
  1238. }
  1239. ],
  1240. ...
  1241. }
  1242. </screen>
  1243. Even though the "container" option does not carry any data except
  1244. sub-options, the "data" field must be explicitly set to an empty value.
  1245. This is required because in the current version of Kea, the
  1246. default configuration values are not propagated to the configuration parsers:
  1247. if the "data" is not set the parser will assume that this
  1248. parameter is not specified and an error will be reported.
  1249. </para>
  1250. <para>Note that it is possible to create an option which carries some data
  1251. in addition to the sub-options defined in the encapsulated option space. For example,
  1252. if the "container" option from the previous example was required to carry an uint16
  1253. value as well as the sub-options, the "type" value would have to be set to "uint16" in
  1254. the option definition. (Such an option would then have the following
  1255. data structure: DHCP header, uint16 value, sub-options.) The value specified
  1256. with the "data" parameter &mdash; which should be a valid integer enclosed in quotes,
  1257. e.g. "123" &mdash; would then be assigned to the uint16 field in the "container" option.
  1258. </para>
  1259. </section>
  1260. <section id="dhcp4-option-data-defaults">
  1261. <title>Unspecified parameters for DHCPv4 option configuration</title>
  1262. <para>In many cases it is not required to specify all parameters for
  1263. an option configuration and the default values may be used. However, it is
  1264. important to understand the implications of not specifing some of them
  1265. as it may result in configuration errors. The list below explains
  1266. the behavior of the server when a particular parameter is not explicitly
  1267. specified:
  1268. <itemizedlist>
  1269. <listitem>
  1270. <simpara><command>name</command> - the server requires an option name or
  1271. option code to identify an option. If this parameter is unspecified, the
  1272. option code must be specified.
  1273. </simpara>
  1274. </listitem>
  1275. <listitem>
  1276. <simpara><command>code</command> - the server requires an option name or
  1277. option code to identify an option. This parameter may be left unspecified if
  1278. the <command>name</command> parameter is specified. However, this also
  1279. requires that the particular option has its definition (it is either a
  1280. standard option or an administrator created a definition for the option
  1281. using an 'option-def' structure), as the option definition associates an
  1282. option with a particular name. It is possible to configure an option
  1283. for which there is no definition (unspecified option format).
  1284. Configuration of such options requires the use of option code.
  1285. </simpara>
  1286. </listitem>
  1287. <listitem>
  1288. <simpara><command>space</command> - if the option space is unspecified it
  1289. will default to 'dhcp4' which is an option space holding DHCPv4 standard
  1290. options.
  1291. </simpara>
  1292. </listitem>
  1293. <listitem>
  1294. <simpara><command>data</command> - if the option data is unspecified it
  1295. defaults to an empty value. The empty value is mostly used for the
  1296. options which have no payload (boolean options), but it is legal to specify
  1297. empty values for some options which carry variable length data and which
  1298. spec allows for the length of 0. For such options, the data parameter
  1299. may be omitted in the configuration.</simpara>
  1300. </listitem>
  1301. <listitem>
  1302. <simpara><command>csv-format</command> - if this value is not specified
  1303. and the definition for the particular option exists, the server will assume
  1304. that the option data is specified as a list of comma separated values to be
  1305. assigned to individual fields of the DHCP option. If the definition
  1306. does not exist for this option, the server will assume that the data
  1307. parameter contains the option payload in the binary format (represented
  1308. as a string of hexadecimal digits). Note that not specifying this
  1309. parameter doesn't imply that it defaults to a fixed value, but
  1310. the configuration data interpretation also depends on the presence
  1311. of the option definition. An administrator must be aware if the
  1312. definition for the particular option exists when this parameter
  1313. is not specified. It is generally recommended to not specify this
  1314. parameter only for the options for which the definition exists, e.g.
  1315. standard options. Setting <command>csv-format</command> to an explicit
  1316. value will cause the server to strictly check the format of the option
  1317. data specified.
  1318. </simpara>
  1319. </listitem>
  1320. </itemizedlist>
  1321. </para>
  1322. </section>
  1323. <section id="dhcp4-stateless-configuration">
  1324. <title>Stateless Configuration of DHCPv4 clients</title>
  1325. <para>The DHCPv4 server supports the stateless client configuration whereby the
  1326. client has an IP address configured (e.g. using manual configuration) and only
  1327. contacts the server to obtain other configuration parameters, e.g. DNS servers' addresses.
  1328. In order to obtain the stateless configuration parameters the client sends the
  1329. DHCPINFORM message to the server with the "ciaddr" set to the address that the
  1330. client is currently using. The server unicasts the DHCPACK message to the
  1331. client that includes the stateless configuration ("yiaddr" not set).
  1332. </para>
  1333. <para>The server will respond to the DHCPINFORM when the client is associated
  1334. with the particular subnet defined in the server's configuration. The example
  1335. subnet configuration will look like this:
  1336. <screen>
  1337. "Dhcp4": {
  1338. "subnet4": [
  1339. {
  1340. "subnet": "192.0.2.0/24"
  1341. "option-data": [ {
  1342. "name": "domain-name-servers",
  1343. "code": 6,
  1344. "data": "192.0.2.200,192.0.2.201",
  1345. "csv-format": true,
  1346. "space": "dhcp4"
  1347. } ]
  1348. }
  1349. ]
  1350. }</screen>
  1351. </para>
  1352. <para>This subnet specifies the single option which will be included in
  1353. the DHCPACK message to the client in response to DHCPINFORM. Note that
  1354. the subnet definition does not require the address pool configuration
  1355. if it will be used solely for the stateless configuration.
  1356. </para>
  1357. <para>This server will associate the subnet with the client if one of
  1358. the following conditions is met:
  1359. <itemizedlist>
  1360. <listitem>
  1361. <simpara>The DHCPINFORM is relayed and the giaddr matches the
  1362. configured subnet.</simpara>
  1363. </listitem>
  1364. <listitem>
  1365. <simpara>The DHCPINFORM is unicast from the client and the ciaddr
  1366. matches the configured subnet.</simpara>
  1367. </listitem>
  1368. <listitem>
  1369. <simpara>The DHCPINFORM is unicast from the client, the ciaddr is
  1370. not set but the source address of the IP packet matches the
  1371. configured subnet.</simpara>
  1372. </listitem>
  1373. <listitem>
  1374. <simpara>The DHCPINFORM is not relayed and the IP address on the
  1375. interface on which the message is received matches the configured
  1376. subnet.</simpara>
  1377. </listitem>
  1378. </itemizedlist>
  1379. </para>
  1380. </section>
  1381. <section id="dhcp4-client-classifier">
  1382. <title>Client Classification in DHCPv4</title>
  1383. <note>
  1384. <para>
  1385. The DHCPv4 server has been extended to support limited client classification.
  1386. Although the current capability is modest, it is expected to be expanded
  1387. in the future. However, it is envisaged that the majority of client classification
  1388. extensions will be using hooks extensions.
  1389. </para>
  1390. </note>
  1391. <para>In certain cases it is useful to differentiate between different
  1392. types of clients and treat them differently. The process of doing
  1393. classification is conducted in two steps. The first step is to assess an
  1394. incoming packet and assign it to zero or more classes. This classification
  1395. is currently simple, but is expected to grow in capability soon. Currently
  1396. the server checks whether an incoming packet includes the vendor class identifier
  1397. option (60). If it does, the content of that option is prepended with
  1398. &quot;VENDOR_CLASS_&quot; then it is interpreted as a class. For example,
  1399. modern cable modems will send this option with value &quot;docsis3.0&quot;
  1400. and as a result the packet will belong to class &quot;VENDOR_CLASS_docsis3.0&quot;.
  1401. </para>
  1402. <para>It is envisaged that the client classification will be used for changing the
  1403. behavior of almost any part of the DHCP message processing, including assigning
  1404. leases from different pools, assigning different options (or different values of
  1405. the same options) etc. For now, there are only two mechanisms that are taking
  1406. advantage of client classification: specific processing for cable modems and
  1407. subnet selection.</para>
  1408. <para>
  1409. For clients that belong to the VENDOR_CLASS_docsis3.0 class, the siaddr
  1410. field is set to the value of next-server (if specified in a subnet). If
  1411. there is a boot-file-name option specified, its value is also set in the
  1412. file field in the DHCPv4 packet. For eRouter1.0 class, the siaddr is
  1413. always set to 0.0.0.0. That capability is expected to be moved to
  1414. an external hook library that will be dedicated to cable modems.
  1415. </para>
  1416. <para>
  1417. Kea can be instructed to limit access to given subnets based on class information.
  1418. This is particularly useful for cases where two types of devices share the
  1419. same link and are expected to be served from two different subnets. The
  1420. primary use case for such a scenario is cable networks. There are two
  1421. classes of devices: the cable modem itself, which should be handed a lease
  1422. from subnet A and all other devices behind the modem that should get a lease
  1423. from subnet B. That segregation is essential to prevent overly curious
  1424. users from playing with their cable modems. For details on how to set up
  1425. class restrictions on subnets, see <xref linkend="dhcp4-subnet-class"/>.
  1426. </para>
  1427. <section id="dhcp4-subnet-class">
  1428. <title>Limiting Access to IPv4 Subnet to Certain Classes</title>
  1429. <para>
  1430. In certain cases it beneficial to restrict access to certain subnets
  1431. only to clients that belong to a given subnet. For details on client
  1432. classes, see <xref linkend="dhcp4-client-classifier"/>. This is an
  1433. extension of a previous example from <xref linkend="dhcp4-address-config"/>.
  1434. Let's assume that the server is connected to a network segment that uses
  1435. the 192.0.2.0/24 prefix. The Administrator of that network has decided
  1436. that addresses from range 192.0.2.10 to 192.0.2.20 are going to be
  1437. managed by the Dhcp4 server. Only clients belonging to client class
  1438. VENDOR_CLASS_docsis3.0 are allowed to use this subnet. Such a
  1439. configuration can be achieved in the following way:
  1440. <screen>
  1441. "Dhcp4": {
  1442. "subnet4": [
  1443. {
  1444. <userinput>"subnet": "192.0.2.0/24",
  1445. "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
  1446. "client-class": "VENDOR_CLASS_docsis3.0"</userinput>
  1447. }
  1448. ],
  1449. ...
  1450. }</screen>
  1451. </para>
  1452. <para>
  1453. Care should be taken with client classification as it is easy for
  1454. clients that do not meet class criteria to be denied any service altogether.
  1455. </para>
  1456. </section>
  1457. </section>
  1458. <section id="dhcp4-ddns-config">
  1459. <title>Configuring DHCPv4 for DDNS</title>
  1460. <para>
  1461. As mentioned earlier, kea-dhcp4 can be configured to generate requests to the
  1462. DHCP-DDNS server (referred to here as "D2" ) to update DNS entries. These requests are known as
  1463. NameChangeRequests or NCRs. Each NCR contains the following information:
  1464. <orderedlist>
  1465. <listitem><para>
  1466. Whether it is a request to add (update) or remove DNS entries
  1467. </para></listitem>
  1468. <listitem><para>
  1469. Whether the change requests forward DNS updates (A records), reverse
  1470. DNS updates (PTR records), or both.
  1471. </para></listitem>
  1472. <listitem><para>
  1473. The FQDN, lease address, and DHCID
  1474. </para></listitem>
  1475. </orderedlist>
  1476. The parameters for controlling the generation of NCRs for submission to D2
  1477. are contained in the <command>dhcp-ddns</command> section of the kea-dhcp4 server
  1478. configuration. The mandatory parameters for the DHCP DDNS configuration
  1479. are <command>enable-updates</command> which is unconditionally
  1480. required, and <command>qualifying-suffix</command> which has no
  1481. default value and is required when <command>enable-updates</command>
  1482. is set to <command>true</command>.
  1483. The two (disabled and enabled) minimal DHCP DDNS configurations are:
  1484. <screen>
  1485. "Dhcp4": {
  1486. "dhcp-ddns": {
  1487. <userinput>"enable-updates": false</userinput>
  1488. },
  1489. ...
  1490. }
  1491. </screen>
  1492. and for example:
  1493. <screen>
  1494. "Dhcp4": {
  1495. "dhcp-ddns": {
  1496. <userinput>"enable-updates": true,
  1497. "qualifying-suffix": "example."</userinput>
  1498. },
  1499. ...
  1500. }
  1501. </screen>
  1502. The default values for the "dhcp-ddns" section are as follows:
  1503. <itemizedlist>
  1504. <listitem><simpara>
  1505. <command>"server-ip": "127.0.0.1"</command>
  1506. </simpara></listitem>
  1507. <listitem><simpara>
  1508. <command>"server-port": 53001</command>
  1509. </simpara></listitem>
  1510. <listitem><simpara>
  1511. <command>"sender-ip": ""</command>
  1512. </simpara></listitem>
  1513. <listitem><simpara>
  1514. <command>"sender-port": 0</command>
  1515. </simpara></listitem>
  1516. <listitem><simpara>
  1517. <command>"max-queue-size": 1024</command>
  1518. </simpara></listitem>
  1519. <listitem><simpara>
  1520. <command>"ncr-protocol": "UDP"</command>
  1521. </simpara></listitem>
  1522. <listitem><simpara>
  1523. <command>"ncr-format": "JSON"</command>
  1524. </simpara></listitem>
  1525. <listitem><simpara>
  1526. <command>"override-no-update": false</command>
  1527. </simpara></listitem>
  1528. <listitem><simpara>
  1529. <command>"override-client-update": false</command>
  1530. </simpara></listitem>
  1531. <listitem><simpara>
  1532. <command>"replace-client-name": false</command>
  1533. </simpara></listitem>
  1534. <listitem><simpara>
  1535. <command>"generated-prefix": "myhost"</command>
  1536. </simpara></listitem>
  1537. </itemizedlist>
  1538. </para>
  1539. <section id="dhcpv4-d2-io-config">
  1540. <title>DHCP-DDNS Server Connectivity</title>
  1541. <para>
  1542. In order for NCRs to reach the D2 server, kea-dhcp4 must be able
  1543. to communicate with it. kea-dhcp4 uses the following configuration
  1544. parameters to control how it communications with D2:
  1545. <itemizedlist>
  1546. <listitem><simpara>
  1547. <command>enable-updates</command> - determines whether or not kea-dhcp4 will
  1548. generate NCRs. By default, this value is false hence DDNS updates are
  1549. disabled. To enable DDNS updates set this value to true:
  1550. </simpara></listitem>
  1551. <listitem><simpara>
  1552. <command>server-ip</command> - IP address on which D2 listens for requests. The default is
  1553. the local loopback interface at address 127.0.0.1. You may specify
  1554. either an IPv4 or IPv6 address.
  1555. </simpara></listitem>
  1556. <listitem><simpara>
  1557. <command>server-port</command> - port on which D2 listens for requests. The default value
  1558. is 53001.
  1559. </simpara></listitem>
  1560. <listitem><simpara>
  1561. <command>sender-ip</command> - IP address which kea-dhcp4 should use to send requests to D2.
  1562. The default value is blank which instructs kea-dhcp4 to select a suitable
  1563. address.
  1564. </simpara></listitem>
  1565. <listitem><simpara>
  1566. <command>sender-port</command> - port which kea-dhcp4 should use to send requests to D2. The
  1567. default value of 0 instructs kea-dhcp4 to select a suitable port.
  1568. </simpara></listitem>
  1569. <listitem><simpara>
  1570. <command>max-queue-size</command> - maximum number of requests allowed to queue waiting to
  1571. be sent to D2. This value guards against requests accumulating
  1572. uncontrollably if they are being generated faster than they can be
  1573. delivered. If the number of requests queued for transmission reaches
  1574. this value, DDNS updating will be turned off until the queue backlog has
  1575. been sufficiently reduced. The intention is to allow the kea-dhcp4 server to
  1576. continue lease operations without running the risk that its memory usage
  1577. grows without limit. The default value is 1024.
  1578. </simpara></listitem>
  1579. <listitem><simpara>
  1580. <command>ncr-format</command> - socket protocol use when sending requests to D2. Currently
  1581. only UDP is supported. TCP may be available in an upcoming release.
  1582. </simpara></listitem>
  1583. <listitem><simpara>
  1584. <command>ncr-protocol</command> - packet format to use when sending requests to D2.
  1585. Currently only JSON format is supported. Other formats may be available
  1586. in future releases.
  1587. </simpara></listitem>
  1588. </itemizedlist>
  1589. By default, kea-dhcp-ddns is assumed to be running on the same machine as kea-dhcp4, and
  1590. all of the default values mentioned above should be sufficient.
  1591. If, however, D2 has been configured to listen on a different address or
  1592. port, these values must be altered accordingly. For example, if D2 has been
  1593. configured to listen on 192.168.1.10 port 900, the following configuration
  1594. would be required:
  1595. <screen>
  1596. "Dhcp4": {
  1597. "dhcp-ddns": {
  1598. <userinput>"server-ip": "192.168.1.10",
  1599. "server-port": 900</userinput>,
  1600. ...
  1601. },
  1602. ...
  1603. }
  1604. </screen>
  1605. </para>
  1606. </section>
  1607. <section id="dhcpv4-d2-rules-config">
  1608. <title>When Does the kea-dhcp4 Server Generate DDNS Requests?</title>
  1609. <para>kea-dhcp4 follows the behavior prescribed for DHCP servers in
  1610. <ulink url="http://tools.ietf.org/html/rfc4702">RFC 4702</ulink>.
  1611. It is important to keep in mind that kea-dhcp4 provides the initial decision
  1612. making of when and what to update and forwards that information to D2 in
  1613. the form of NCRs. Carrying out the actual DNS updates and dealing with
  1614. such things as conflict resolution are within the purview of D2 itself (<xref linkend="dhcp-ddns-server"/>).
  1615. This section describes when kea-dhcp4 will generate NCRs and the
  1616. configuration parameters that can be used to influence this decision.
  1617. It assumes that the "enable-updates" parameter is true.
  1618. </para>
  1619. <para>
  1620. In general, kea-dhcp4 will generate DDNS update requests when:
  1621. <orderedlist>
  1622. <listitem><para>
  1623. A new lease is granted in response to a DHCP REQUEST
  1624. </para></listitem>
  1625. <listitem><para>
  1626. An existing lease is renewed but the FQDN associated with it has
  1627. changed.
  1628. </para></listitem>
  1629. <listitem><para>
  1630. An existing lease is released in response to a DHCP RELEASE
  1631. </para></listitem>
  1632. </orderedlist>
  1633. In the second case, lease renewal, two DDNS requests will be issued: one
  1634. request to remove entries for the previous FQDN and a second request to
  1635. add entries for the new FQDN. In the last case, a lease release, a
  1636. single DDNS request to remove its entries will be made. The decision
  1637. making involved when granting a new lease (the first case) is more
  1638. involved and is discussed next.
  1639. </para>
  1640. <para>
  1641. When a new lease is granted, kea-dhcp4 will generate a DDNS
  1642. update request if the DHCP REQUEST contains either the FQDN option
  1643. (code 81) or the Host Name option (code 12). If both are present,
  1644. the server will use the FQDN option. By default kea-dhcp4
  1645. will respect the FQDN N and S flags specified by the client as shown
  1646. in the following table:
  1647. </para>
  1648. <table id="fqdn-flag-table">
  1649. <title>Default FQDN Flag Behavior</title>
  1650. <tgroup cols='4' align='left'>
  1651. <colspec colname='cflags'/>
  1652. <colspec colname='meaning'/>
  1653. <colspec colname='response'/>
  1654. <colspec colname='sflags'/>
  1655. <thead>
  1656. <row>
  1657. <entry>Client Flags:N-S</entry>
  1658. <entry>Client Intent</entry>
  1659. <entry>Server Response</entry>
  1660. <entry>Server Flags:N-S-O</entry>
  1661. </row>
  1662. </thead>
  1663. <tbody>
  1664. <row>
  1665. <entry>0-0</entry>
  1666. <entry>
  1667. Client wants to do forward updates, server should do reverse updates
  1668. </entry>
  1669. <entry>Server generates reverse-only request</entry>
  1670. <entry>1-0-0</entry>
  1671. </row>
  1672. <row>
  1673. <entry>0-1</entry>
  1674. <entry>Server should do both forward and reverse updates</entry>
  1675. <entry>Server generates request to update both directions</entry>
  1676. <entry>0-1-0</entry>
  1677. </row>
  1678. <row>
  1679. <entry>1-0</entry>
  1680. <entry>Client wants no updates done</entry>
  1681. <entry>Server does not generate a request</entry>
  1682. <entry>1-0-0</entry>
  1683. </row>
  1684. </tbody>
  1685. </tgroup>
  1686. </table>
  1687. <para>
  1688. The first row in the table above represents "client delegation". Here
  1689. the DHCP client states that it intends to do the forward DNS updates and
  1690. the server should do the reverse updates. By default, kea-dhcp4 will honor
  1691. the client's wishes and generate a DDNS request to the DHCP-DDNS server to update only
  1692. reverse DNS data. The parameter <command>override-client-update</command> can be used
  1693. to instruct the server to override client delegation requests. When
  1694. this parameter is true, kea-dhcp4 will disregard requests for client
  1695. delegation and generate a DDNS request to update both forward and
  1696. reverse DNS data. In this case, the N-S-O flags in the server's
  1697. response to the client will be 0-1-1 respectively.
  1698. </para>
  1699. <para>
  1700. (Note that the flag combination N=1, S=1 is prohibited according to
  1701. <ulink url="http://tools.ietf.org/html/rfc4702">RFC 4702</ulink>. If such a combination is received from the client, the packet
  1702. will be dropped by kea-dhcp4.)
  1703. </para>
  1704. <para>
  1705. To override client delegation, set the following values in your configuration
  1706. file:
  1707. </para>
  1708. <screen>
  1709. "Dhcp4": {
  1710. "dhcp-ddns": {
  1711. <userinput>"override-client-update": true</userinput>,
  1712. ...
  1713. },
  1714. ...
  1715. }
  1716. </screen>
  1717. <para>
  1718. The third row in the table above describes the case in which the client
  1719. requests that no DNS updates be done. The parameter, <command>override-no-update</command>,
  1720. can be used to instruct the server to disregard the client's wishes. When
  1721. this parameter is true, kea-dhcp4 will generate a DDNS update request to kea-dhcp-ddns
  1722. even if the client requests that no updates be done. The N-S-O flags in the
  1723. server's response to the client will be 0-1-1.
  1724. </para>
  1725. <para>
  1726. To override client delegation, the following values should be set in your configuration:
  1727. </para>
  1728. <screen>
  1729. "Dhcp4": {
  1730. "dhcp-ddns": {
  1731. <userinput>"override-no-update": true</userinput>,
  1732. ...
  1733. },
  1734. ...
  1735. }
  1736. </screen>
  1737. <para>
  1738. kea-dhcp4 will always generate DDNS update requests if the client request
  1739. only contains the Host Name option. In addition it will include an FQDN
  1740. option in the response to the client with the FQDN N-S-O flags set to
  1741. 0-1-0 respectively. The domain name portion of the FQDN option will be
  1742. the name submitted to D2 in the DDNS update request.
  1743. </para>
  1744. </section>
  1745. <section id="dhcpv4-fqdn-name-generation">
  1746. <title>kea-dhcp4 name generation for DDNS update requests</title>
  1747. <para>Each NameChangeRequest must of course include the fully qualified domain
  1748. name whose DNS entries are to be affected. kea-dhcp4 can be configured to
  1749. supply a portion or all of that name based upon what it receives from
  1750. the client in the DHCP REQUEST.</para>
  1751. <para>
  1752. The rules for determining the FQDN option are as follows:
  1753. <orderedlist>
  1754. <listitem><para>
  1755. If configured to do, so ignore the DHCPREQUEST contents and generate a
  1756. FQDN using a configurable prefix and suffix.
  1757. </para></listitem>
  1758. <listitem><para>
  1759. If the DHCPREQUEST contains the client FQDN option, the candidate
  1760. name is taken from there, otherwise it is taken from the Host Name option.
  1761. The candidate name may then be modified:
  1762. <orderedlist>
  1763. <listitem><para>
  1764. If the candidate name is a fully qualified domain name, use it.
  1765. </para></listitem>
  1766. <listitem><para>
  1767. If the candidate name is a partial (i.e. unqualified) name then
  1768. add a configurable suffix to the name and use the result as the FQDN.
  1769. </para></listitem>
  1770. <listitem><para>
  1771. If the candidate name is a empty, generate a FQDN using a
  1772. configurable prefix and suffix.
  1773. </para></listitem>
  1774. </orderedlist>
  1775. </para></listitem>
  1776. </orderedlist>
  1777. To instruct kea-dhcp4 to always generate the FQDN for a client, set the
  1778. parameter <command>replace-client-name</command> to true as follows:
  1779. </para>
  1780. <screen>
  1781. "Dhcp4": {
  1782. "dhcp-ddns": {
  1783. <userinput>"replace-client-name": true</userinput>,
  1784. ...
  1785. },
  1786. ...
  1787. }
  1788. </screen>
  1789. <para>
  1790. The prefix used in the generation of a FQDN is specified by the
  1791. <command>generated-prefix</command> parameter. The default value is "myhost". To alter
  1792. its value simply set it to the desired string:
  1793. </para>
  1794. <screen>
  1795. "Dhcp4": {
  1796. "dhcp-ddns": {
  1797. <userinput>"generated-prefix": "another.host"</userinput>,
  1798. ...
  1799. },
  1800. ...
  1801. }
  1802. </screen>
  1803. <para>
  1804. The suffix used when generating a FQDN or when qualifying a
  1805. partial name is specified by
  1806. the <command>qualifying-suffix</command> parameter. This
  1807. parameter has no default value, thus it is mandatory when
  1808. DDNS updates are enabled.
  1809. To set its value simply set it to the desired string:
  1810. </para>
  1811. <screen>
  1812. "Dhcp4": {
  1813. "dhcp-ddns": {
  1814. <userinput>"qualifying-suffix": "foo.example.org"</userinput>,
  1815. ...
  1816. },
  1817. ...
  1818. }
  1819. </screen>
  1820. </section>
  1821. <para>
  1822. When generating a name, kea-dhcp4 will construct name of the format:
  1823. </para>
  1824. <para>
  1825. [generated-prefix]-[address-text].[qualifying-suffix].
  1826. </para>
  1827. <para>
  1828. where address-text is simply the lease IP address converted to a
  1829. hyphenated string. For example, if the lease address is 172.16.1.10,
  1830. the qualifying suffix "example.com", and the default value is used for
  1831. <command>generated-prefix</command>, the generated FQDN would be:
  1832. </para>
  1833. <para>
  1834. myhost-172-16-1-10.example.com.
  1835. </para>
  1836. </section>
  1837. <section id="dhcp4-next-server">
  1838. <title>Next Server (siaddr)</title>
  1839. <para>In some cases, clients want to obtain configuration from the TFTP server.
  1840. Although there is a dedicated option for it, some devices may use the siaddr field
  1841. in the DHCPv4 packet for that purpose. That specific field can be configured
  1842. using <command>next-server</command> directive. It is possible to define it in the global scope or
  1843. for a given subnet only. If both are defined, the subnet value takes precedence.
  1844. The value in subnet can be set to 0.0.0.0, which means that <command>next-server</command> should
  1845. not be sent. It may also be set to an empty string, which means the same as if
  1846. it was not defined at all, i.e. use the global value.
  1847. </para>
  1848. <screen>
  1849. "Dhcp4": {
  1850. <userinput>"next-server": "192.0.2.123"</userinput>,
  1851. ...,
  1852. "subnet4": [
  1853. {
  1854. <userinput>"next-server": "192.0.2.234"</userinput>,
  1855. ...
  1856. }
  1857. ]
  1858. }
  1859. </screen>
  1860. </section>
  1861. <section id="dhcp4-echo-client-id">
  1862. <title>Echoing Client-ID (RFC 6842)</title>
  1863. <para>The original DHCPv4 specification
  1864. (<ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>)
  1865. states that the DHCPv4
  1866. server must not send back client-id options when responding to
  1867. clients. However, in some cases that confused clients that did
  1868. not have MAC address or client-id; see
  1869. <ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>.
  1870. for details. That
  1871. behavior has changed with the publication of
  1872. <ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>.
  1873. which updated
  1874. <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>.
  1875. That update now states that the server must
  1876. send client-id if the client sent it. That is the default behaviour
  1877. that Kea offers. However, in some cases older devices that do
  1878. not support
  1879. <ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>.
  1880. may refuse to accept responses that include the
  1881. client-id option. To enable backward compatibility, an optional
  1882. configuration parameter has been introduced. To configure it,
  1883. use the following configuration statement:</para>
  1884. <screen>
  1885. "Dhcp4": {
  1886. <userinput>"echo-client-id": false</userinput>,
  1887. ...
  1888. }
  1889. </screen>
  1890. </section>
  1891. <section id="dhcp4-match-client-id">
  1892. <title>Using Client Identifier and Hardware Address</title>
  1893. <para>DHCP server must be able to identify the client (distinguish it from
  1894. other clients) from which it receives the message. There are many reasons
  1895. why this identification is required and the most important ones are listed
  1896. below.
  1897. <itemizedlist>
  1898. <listitem><simpara>When the client contacts the server to allocate a new
  1899. lease, the server must store the client identification information in
  1900. the lease database as a search key.</simpara></listitem>
  1901. <listitem><simpara>When the client is trying to renew or release the existing
  1902. lease, the server must be able to find the existing lease entry in the
  1903. database for this client, using the client identification information as a
  1904. search key.</simpara></listitem>
  1905. <listitem><simpara>Some configurations use static reservations for the IP
  1906. addreses and other configuration information. The server's administrator
  1907. uses client identification information to create these static assignments.
  1908. </simpara></listitem>
  1909. <listitem><simpara>In the dual stack networks there is often a need to
  1910. correlate the lease information stored in DHCPv4 and DHCPv6 server for
  1911. a particular host. Using common identification information by the DHCPv4
  1912. and DHCPv6 client allows the network administrator to achieve this
  1913. correlation and better administer the network.</simpara></listitem>
  1914. </itemizedlist>
  1915. </para>
  1916. <para>DHCPv4 makes use of two distinct identifiers which are placed
  1917. by the client in the queries sent to the server and copied by the server
  1918. to its responses to the client: 'chaddr' and 'client identifier'. The
  1919. former was introduced as a part of the BOOTP specification and it is also
  1920. used by DHCP to carry the hardware address of the interface used to send
  1921. the query to the server (MAC address for the Ethernet). The latter is
  1922. carried in the Client-identifier option, introduced in the
  1923. <ulink url="http://tools.ietf.org/html/rfc2132">RFC 2132</ulink>.
  1924. </para>
  1925. <para>The <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>
  1926. indicates that the server may use both of these identifiers to identify
  1927. the client but the 'client identifier', if present, takes precedence
  1928. over 'chaddr'. One of the reasons for this is that 'client identifier'
  1929. is independent from the hardware used by the client to communicate with
  1930. the server. For example, if the client obtained the lease using one
  1931. network card and then the network card is moved to another host, the
  1932. server will wrongly identify this host is the one which has obtained
  1933. the lease. Moreover, the
  1934. <ulink url="https://tools.ietf.org/html/rfc4361">RFC 4361</ulink> gives
  1935. the recommendation to use DUID
  1936. (see <ulink url="https://tools.ietf.org/html/rfc3315">DHCPv6 specification</ulink>)
  1937. carried as 'client identifier' when dual stack networks are in use,
  1938. to provide consistent identification information of the client, regardless
  1939. of the protocol type it is using. Kea adheres to these specifications and
  1940. the 'client identifier' by default takes precedence over the value carried
  1941. in 'chaddr' field when the server searches, creates, updates or removes
  1942. the client's lease.
  1943. </para>
  1944. <para>When the server receives a DHCPDISCOVER or DHCPREQUEST message from the
  1945. client, it will try to find out if the client already has a lease in the
  1946. database and will hand out the existing lease rather than allocate
  1947. a new one. Each lease in the lease database is associated with the
  1948. 'client identifier' and/or 'chaddr'. The server will first use the
  1949. 'client identifer' (if present) to search the lease. If the lease is
  1950. found, the server will treat this lease as belonging to the client
  1951. even if the current 'chaddr' and the 'chaddr' associated with
  1952. the lease do not match. This facilitates the scenario when the network card
  1953. on the client system has been replaced and thus the new MAC address
  1954. appears in the messages sent by the DHCP client. If the server fails
  1955. to find the lease using the 'client identifier' it will perform another lookup
  1956. using the 'chaddr'. If this lookup returns no result, the client is
  1957. considered as not having a lease and the new lease will be created.
  1958. </para>
  1959. <para>A common problem reported by network operators is that bogus
  1960. client implementations do not use stable client identifiers such as
  1961. generating a new 'client identifier' each time the client connects
  1962. to the network. Another well known case is when the client changes its
  1963. 'client identifier' during the multi-stage boot process (PXE). In such
  1964. cases, the MAC address of the client's interface remains stable and
  1965. using 'chaddr' field to identify the client guarantees that the
  1966. particular system is considered to be the same client, even though its
  1967. 'client identifier' changes.
  1968. </para>
  1969. <para>To address this problem, Kea includes a configuration option
  1970. which enables client identification using 'chaddr' only by instructing
  1971. the server to disregard server to "ignore" the 'client identifier' during
  1972. lease lookups and allocations for a particular subnet. Consider the following
  1973. simplified server configuration:</para>
  1974. <screen>
  1975. "Dhcp4": {
  1976. ...
  1977. <userinput>"match-client-id": true,</userinput>
  1978. ...
  1979. "subnet4": [
  1980. {
  1981. "subnet": "192.0.10.0/24",
  1982. "pools": [ { "pool": "192.0.2.23-192.0.2.87" } ],
  1983. <userinput>"match-client-id": false</userinput>
  1984. },
  1985. {
  1986. "subnet": "10.0.0.0/8",
  1987. "pools": [ { "pool": "10.0.0.23-10.0.2.99" } ],
  1988. }
  1989. ]
  1990. }
  1991. </screen>
  1992. <para>The <command>match-client-id</command> is a boolean value which
  1993. controls this behavior. The default value of <userinput>true</userinput>
  1994. indicates that the server will use the 'client identifier' for lease
  1995. lookups and 'chaddr' if the first lookup returns no results. The
  1996. <command>false</command> means that the server will only
  1997. use the 'chaddr' to search for client's lease. Whether the DHCID for
  1998. DNS updates is generated from the 'client identifier' or 'chaddr' is
  1999. controlled through the same parameter accordingly.</para>
  2000. <para>The <command>match-client-id</command> parameter may appear
  2001. both in the global configuration scope and/or under any subnet
  2002. declaration. In the example shown above, the effective value of the
  2003. <command>match-client-id</command> will be <userinput>false</userinput>
  2004. for the subnet 192.0.10.0/24, because the subnet specific setting
  2005. of the parameter overrides the global value of the parameter. The
  2006. effective value of the <command>match-client-id</command> for the subnet
  2007. 10.0.0.0/8 will be set to <userinput>true</userinput> because the
  2008. subnet declaration lacks this parameter and the global setting is
  2009. by default used for this subnet. In fact, the global entry for this
  2010. parameter could be omitted in this case, because
  2011. <userinput>true</userinput> is the default value.
  2012. </para>
  2013. <para>It is important to explain what happens when the client obtains
  2014. its lease for one setting of the <command>match-client-id</command>
  2015. and then renews when the setting has been changed. Let's first consider
  2016. the case when the client obtains the lease when the
  2017. <command>match-client-id</command> is set to <userinput>true</userinput>.
  2018. The server will store the lease information including 'client identifier'
  2019. (if supplied) and 'chaddr' in the lease database. When the setting is
  2020. changed and the client renews the lease the server will determine that
  2021. it should use the 'chaddr' to search for the existing lease. If the
  2022. client hasn't changed its MAC address the server should successfully
  2023. find the existing lease. The 'client identifier' associated with the
  2024. returned lease is ignored and the client is allowed to use this lease.
  2025. When the lease is renewed only the 'chaddr' is recorded for this
  2026. lease according to the new server setting.
  2027. </para>
  2028. <para>In the second case the client has the lease with only a 'chaddr'
  2029. value recorded. When the setting is changed to
  2030. <command>match-client-id</command> set to <userinput>true</userinput>
  2031. the server will first try to use the 'client identifier' to find the
  2032. existing client's lease. This will return no results because the
  2033. 'client identifier' was not recorded for this lease. The server will
  2034. then use the 'chaddr' and the lease will be found. If the lease appears
  2035. to have no 'client identifier' recorded, the server will assume that
  2036. this lease belongs to the client and that it was created with the previous
  2037. setting of the <command>match-client-id</command>.
  2038. However, if the lease contains 'client identifier' which is different
  2039. from the 'client identifier' used by the client the lease will be
  2040. assumed to belong to another client and the new lease will be
  2041. allocated.
  2042. </para>
  2043. </section>
  2044. </section> <!-- end of configuring kea-dhcp4 server section with many subsections -->
  2045. <!-- Host reservation is a large topic. There will be many subsections,
  2046. so it should be a section on its own. -->
  2047. <section id="host-reservation-v4">
  2048. <title>Host reservation in DHCPv4</title>
  2049. <para>There are many cases where it is useful to provide a configuration on
  2050. a per host basis. The most obvious one is to reserve specific, static
  2051. address for exclusive use by a given client (host) &dash; returning client will
  2052. receive the same address from the server every time, and other clients will
  2053. generally not receive that address. Note that there may be cases when the
  2054. new reservation has been made for the client for the address being currently
  2055. in use by another client. We call this situation a "conflict". The conflicts
  2056. get resolved automatically over time as described in the subsequent sections.
  2057. Once conflict is resolved,the client will keep receiving the reserved
  2058. configuration when it renews.</para>
  2059. <para>Another example when the host reservations are applicable is when a host
  2060. that has specific requirements, e.g. a printer that needs additional DHCP options.
  2061. Yet another possible use case is to define unique names for hosts. Although not all
  2062. of the presented use cases are implemented yet, Kea software will support them in the
  2063. near future.</para>
  2064. <para>Hosts reservations are defined as parameters for each subnet. Each host
  2065. has to be identified by its hardware/MAC address. There is an optional
  2066. <command>reservations</command> array in the <command>Subnet4</command>
  2067. element. Each element in that array is a structure, that holds information
  2068. about reservrations for a single host. In particular, such a structure has
  2069. to have an indentifer that uniquely identifies a host. In DHCPv4 context, such an
  2070. identifier is a hardware or MAC address. In most cases, also an address
  2071. will be specified. It is possible to specify a hostname. Additional
  2072. capabilities are planned.</para>
  2073. <para>The following example shows how to reserve addresses for specific
  2074. hosts:
  2075. <screen>
  2076. "subnet4": [
  2077. {
  2078. "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
  2079. "subnet": "192.0.2.0/24",
  2080. "interface": "eth0",
  2081. <userinput>"reservations": [
  2082. {
  2083. "hw-address": "1a:1b:1c:1d:1e:1f",
  2084. "ip-address": "192.0.2.202"
  2085. },
  2086. {
  2087. "hw-address": "0a:0b:0c:0d:0e:0f",
  2088. "ip-address": "192.0.2.100",
  2089. "hostname": "alice-laptop"
  2090. }
  2091. ]</userinput>
  2092. }
  2093. ]
  2094. </screen>
  2095. The first entry reserves the 192.0.2.202 address for the client that uses
  2096. MAC adress of 1a:1b:1c:1d:1e:1f. The second entry reserves the address
  2097. 192.0.2.100 and the hostname of alice-laptop for client using MAC
  2098. address 0a:0b:0c:0d:0e:0f. Note that if you plan to do DNS updates, it
  2099. is strongly recommended for the hostnames to be unique.
  2100. </para>
  2101. <para>Making a reservation for a mobile host that may visit multiple subnets
  2102. requires a separate host definition in each subnet it is expected to visit.
  2103. It is not allowed to define multiple host definitions with the same hardware
  2104. address in a single subnet. It is a valid configuration, if such definitions
  2105. are specified in different subnets, though.
  2106. </para>
  2107. <para>Adding host reservation incurs a performance penalty. In principle,
  2108. when the server that does not support host reservation responds to a query,
  2109. it needs to check whether there is a lease for a given address being
  2110. considered for allocation or renewal. The server that also supports host
  2111. reservation, has to perform additional checks: not only if the address is
  2112. currently used (if there is a lease for it), but also whether the address
  2113. could be used by someone else (if there is a reservation for it). That
  2114. additional check incurs performance penalty.</para>
  2115. <section id="reservation4-types">
  2116. <title>Address reservation types</title>
  2117. <para>In a typical scenario there is an IPv4 subnet defined,
  2118. e.g. 192.0.2.0/24, with certain part of it dedicated for dynamic allocation
  2119. by the DHCPv4 server. That dynamic part is referred to as a dynamic pool or
  2120. simply a pool. In principle, the host reservation can reserve any address
  2121. that belongs to the subnet. The reservations that specify addresses that
  2122. belong to configured pools are called <command>in-pool reservations</command>.
  2123. In contrast, those that do not belong to dynamic pools are called
  2124. <command>out-of-pool reservations</command>. There is no formal difference
  2125. in the reservation syntax. As of 0.9.1, both reservation types are
  2126. handled uniformly. However, upcoming releases may offer improved performance
  2127. if there are only out-of-pool reservations as the server will be able
  2128. to skip reservation checks when dealing with existing leases. Therefore,
  2129. system administrators are encouraged to use out-of-pool reservations, if
  2130. possible.</para>
  2131. </section>
  2132. <section id="reservation4-conflict">
  2133. <title>Conflicts in DHCPv4 reservations</title>
  2134. <para>As the reservations and lease information are stored separately,
  2135. conflicts may arise. Consider the following series of events. The server
  2136. has configured the dynamic pool of addresses from the range of 192.0.2.10 to
  2137. 192.0.2.20. The Host A requests an address and gets 19.0.2.10. Now the system
  2138. administrator decides to reserve the address for the Host B. He decides to
  2139. reserve 192.0.2.10 for that purpose. In general, reserving an address that
  2140. is currently assigned to someone else is not recommended, but there are
  2141. valid use cases where such an operation is warranted.</para>
  2142. <para>The server now has a conflict to resolve. Let's analyze the
  2143. situation here. If the Host B boots up and requests an address, the server is
  2144. not able to assign the reserved address 192.0.2.10 for the Host B. A naive
  2145. approach would to be immediately remove the existing lease for the Host A
  2146. and create a new one for the Host B. That would not solve the problem,
  2147. though, because as soon as the Host B gets the address, it will detect
  2148. that the address is already in use by the Host A and would send
  2149. the DHCPDECLINE message. Therefore, in this situation, the server has
  2150. to temporarily assign a different address (not matching what has been
  2151. reserved) to the Host B.</para>
  2152. <!-- let's keep this text around. It describes how that is working in v6
  2153. <para>When the Host A renews its address, the server will discover that
  2154. the address being renewed is now reserved for someone else (host
  2155. B). Therefore the server will remove the lease and will inform the Host A
  2156. that it is no longer allowed to use it by sending DHCPNAK message. Host A
  2157. will then revert to server discovery and will eventually get a different
  2158. address. The address 192.0.2.10 is now no longer used. When host B tries
  2159. to renew its temporarily assigned address, the server will detect that
  2160. it has a valid lease, but there is a reservation for a different address.
  2161. The server will send DHCPNAK to inform host B that its address is no
  2162. longer usable. The server will also remove its temporary lease. It will
  2163. revert to the server discovery phase and will eventually send a
  2164. DHCPREQUEST message. This time the server will find out that there is a
  2165. reservation for that host and the reserved address 192.0.2.10 is not used,
  2166. so it will be granted.</para> -->
  2167. <para>When the Host A renews its address, the server will discover that
  2168. the address being renewed is now reserved for another host - the Host
  2169. B. Therefore the server will inform the Host A that it is no longer
  2170. allowed to use it by sending DHCPNAK message. The server will not remove the
  2171. lease, though, as there's small chance that the DHCPNAK may be lost if the
  2172. network is lossy. If that happens, the client will not receive any
  2173. responses, so it will retransmit its DHCPREQUEST packet. Once the
  2174. DHCPNAK is received by the Host A, it will then revert to the server
  2175. discovery and will eventually get a different address. Besides
  2176. allocating a new lease, the server will also remove the old one. As
  2177. a result, the address 192.0.2.10 will be no longer used. When Host B
  2178. tries to renew its temporarily assigned address, the server will detect
  2179. that it has a valid lease, but there is a reservation for a different
  2180. address. The server will send DHCPNAK to inform Host B that its address
  2181. is no longer usable, but will keep its lease (again, the DHCPNAK may be
  2182. lost, so the server will keep it, until the client returns for a new
  2183. address). The Host B will revert to the server discovery phase and will
  2184. eventually send a DHCPREQUEST message. This time the server will find
  2185. out that there is a reservation for that host and the reserved address
  2186. 192.0.2.10 is not used, so it will be granted. It will also remove the
  2187. lease for the temporarily assigned address that the Host B previously
  2188. obtained.</para>
  2189. <para>This recovery will succeed, even if other hosts will attempt to get
  2190. the reserved address. Had the Host C requested address 192.0.2.10 after
  2191. the reservation was made, the server will either offer a different
  2192. address (when responding to DHCPDISCOVER) or would send DHCPNAK
  2193. (when responding to DHCPREQUEST).</para>
  2194. <para>This recovery mechanism allows the server to fully recover from a
  2195. case where reservations conflict with the existing leases. This procedure
  2196. takes time and will roughly take as long as renew-timer value specified.
  2197. The best way to avoid such recovery is to not define new reservations that
  2198. conflict with existing leases. Another recommendation is to use
  2199. out-of-pool reservations. If the reserved address does not belong to a
  2200. pool, there is no way that other clients could get this address (note that
  2201. having multiple reservations for the same address is not allowed).
  2202. </para>
  2203. </section>
  2204. <section id="reservation4-hostname">
  2205. <title>Reserving a hostname</title>
  2206. <para>When the reservation for the client includes the <command>hostname
  2207. </command>, the server will assign this hostname to the client and send
  2208. it back in the Client FQDN or Hostname option, depending on which of them
  2209. the client has sent to the server. The reserved hostname always takes
  2210. precedence over the hostname supplied by the client or the autogenerated
  2211. (from the IPv4 address) hostname.</para>
  2212. <para>The server qualifies the reserved hostname with the value
  2213. of the <command>qualifying-suffix</command> parameter. For example, the
  2214. following subnet configuration:
  2215. <screen>
  2216. {
  2217. "subnet4": [ {
  2218. "subnet": "10.0.0.0/24",
  2219. "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ],
  2220. "reservations": [
  2221. {
  2222. "hw-address": "aa:bb:cc:dd:ee:ff",
  2223. "hostname": "alice-laptop"
  2224. }
  2225. ]
  2226. }],
  2227. "dhcp-ddns": {
  2228. "enable-updates": true,
  2229. "qualifying-suffix": "example.isc.org."
  2230. }
  2231. }
  2232. </screen>
  2233. will result in assigning the "alice-laptop.example.isc.org." hostname to the
  2234. client using the MAC address "aa:bb:cc:dd:ee:ff". If the <command>qualifying-suffix
  2235. </command> is not specified, the default (empty) value will be used, and
  2236. in this case the value specified as a <command>hostname</command> will
  2237. be treated as fully qualified name. Thus, by leaving the
  2238. <command>qualifying-suffix</command> empty it is possible to qualify
  2239. hostnames for the different clients with different domain names:
  2240. <screen>
  2241. {
  2242. "subnet4": [ {
  2243. "subnet": "10.0.0.0/24",
  2244. "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ],
  2245. "reservations": [
  2246. {
  2247. "hw-address": "aa:bb:cc:dd:ee:ff",
  2248. "hostname": "alice-laptop.isc.org."
  2249. },
  2250. {
  2251. "hw-address": "12:34:56:78:99:AA",
  2252. "hostname": "mark-desktop.example.org."
  2253. }
  2254. ]
  2255. }],
  2256. "dhcp-ddns": {
  2257. "enable-updates": true,
  2258. }
  2259. }
  2260. </screen>
  2261. </para>
  2262. </section>
  2263. <section id="reservation4-options">
  2264. <title>Reserving specific options</title>
  2265. <!-- @todo: replace this with the actual text once #3572 is implemented -->
  2266. <para>Currently it is not possible to specify options in host
  2267. reservation. Such a feature will be added in the upcoming Kea
  2268. releases.</para>
  2269. </section>
  2270. <section id="reservation4-mode">
  2271. <title>Fine Tuning IPv4 Host Reservation</title>
  2272. <note>
  2273. <para><command>reservation-mode</command> configuration parameter in DHCPv4
  2274. server is accepted, but not used in the Kea 0.9.1 beta. Full implementation
  2275. will be available in the upcoming releases.</para>
  2276. </note>
  2277. <para>Host reservation capability introduces additional restrictions for the
  2278. allocation engine during lease selection and renewal. In particular, three
  2279. major checks are necessary. First, when selecting a new lease, it is not
  2280. sufficient for a candidate lease to be not used by another DHCP client. It
  2281. also must not be reserved for another client. Second, when renewing a lease,
  2282. additional check must be performed whether the address being renewed is not
  2283. reserved for another client. Finally, when a host renews an address, the server
  2284. has to check whether there's a reservation for this host, so the exisiting
  2285. (dynamically allocated) address should be revoked and the reserved one be
  2286. used instead.
  2287. </para>
  2288. <para>Some of those checks may be unnecessary in certain deployments. Not
  2289. performing them may improve performance. The Kea server provides the
  2290. <command>reservation-mode</command> configuration parameter to select the
  2291. types of reservations allowed for the particular subnet. Each reservation
  2292. type has different constraints for the checks to be performed by the
  2293. server when allocating or renewing a lease for the client.
  2294. Allowed values are:
  2295. <itemizedlist>
  2296. <listitem><simpara> <command>all</command> - enables all host reservation
  2297. types. This is the default value. This setting is the safest and the most
  2298. flexible. It allows in-pool and out-of-pool reservations. As all checks
  2299. are conducted, it is also the slowest.
  2300. </simpara></listitem>
  2301. <listitem><simpara> <command>out-of-pool</command> - allows only out of
  2302. pool host reservations. With this setting in place, the server may assume
  2303. that all host reservations are for addresses that do not belong to the
  2304. dynamic pool. Therefore it can skip the reservation checks when dealing
  2305. with in-pool addresses, thus improving performance. Do not use this mode
  2306. if any of your reservations use in-pool address. Caution is advised when
  2307. using this setting. Kea 0.9.1 does not sanity check the reservations against
  2308. <command>reservation-mode</command>. Misconfiguration may cause problems.
  2309. </simpara></listitem>
  2310. <listitem><simpara>
  2311. <command>disabled</command> - host reservation support is disabled. As there
  2312. are no reservations, the server will skip all checks. Any reservations defined
  2313. will be completely ignored. As the checks are skipped, the server may
  2314. operate faster in this mode.
  2315. </simpara></listitem>
  2316. </itemizedlist>
  2317. </para>
  2318. <para>
  2319. An example configuration that disables reservation looks like follows:
  2320. <screen>
  2321. "Dhcp4": {
  2322. "subnet4": [
  2323. {
  2324. "subnet": "192.0.2.0/24",
  2325. <userinput>"reservation-mode": "disabled"</userinput>,
  2326. ...
  2327. }
  2328. ]
  2329. }
  2330. </screen>
  2331. </para>
  2332. </section>
  2333. </section>
  2334. <!-- end of host reservations section -->
  2335. <section id="dhcp4-serverid">
  2336. <title>Server Identifier in DHCPv4</title>
  2337. <para>
  2338. The DHCPv4 protocol uses a "server identifier" to allow clients
  2339. to discriminate between several servers present on the same link: this
  2340. value is an IPv4 address of the server. The server chooses the IPv4 address
  2341. of the interface on which the message from the client (or relay) has been
  2342. received. A single server instance will use multiple server identifiers
  2343. if it is receiving queries on multiple interfaces.
  2344. </para>
  2345. <para>
  2346. Currently there is no mechanism to override the default server identifiers
  2347. by an administrator. In the future, the configuration mechanism will be used
  2348. to specify the custom server identifier.
  2349. </para>
  2350. </section>
  2351. <section id="dhcp4-subnet-selection">
  2352. <title>How the DHCPv4 Server Selects a Subnet for the Client</title>
  2353. <para>
  2354. The DHCPv4 server differentiates between the directly connected clients,
  2355. clients trying to renew leases and clients sending their messages through
  2356. relays. For the directly connected clients the server will check the
  2357. configuration for the interface on which the message has been received, and
  2358. if the server configuration doesn't match any configured subnet the
  2359. message is discarded.</para>
  2360. <para>Assuming that the server's interface is configured with the
  2361. IPv4 address 192.0.2.3, the server will only process messages received through
  2362. this interface from a directly connected client if there is a subnet
  2363. configured to which this IPv4 address belongs, e.g. 192.0.2.0/24.
  2364. The server will use this subnet to assign IPv4 address for the client.
  2365. </para>
  2366. <para>
  2367. The rule above does not apply when the client unicasts its message, i.e.
  2368. is trying to renew its lease. Such a message is accepted through any
  2369. interface. The renewing client sets ciaddr to the currently used IPv4
  2370. address. The server uses this address to select the subnet for the client
  2371. (in particular, to extend the lease using this address).
  2372. </para>
  2373. <para>
  2374. If the message is relayed it is accepted through any interface. The giaddr
  2375. set by the relay agent is used to select the subnet for the client.
  2376. </para>
  2377. <para>
  2378. It is also possible to specify a relay IPv4 address for a given subnet. It
  2379. can be used to match incoming packets into a subnet in uncommon configurations,
  2380. e.g. shared subnets. See <xref linkend="dhcp4-relay-override"/> for details.
  2381. </para>
  2382. <note>
  2383. <para>The subnet selection mechanism described in this section is based
  2384. on the assumption that client classification is not used. The classification
  2385. mechanism alters the way in which a subnet is selected for the client,
  2386. depending on the classes to which the client belongs.</para>
  2387. </note>
  2388. <section id="dhcp4-relay-override">
  2389. <title>Using a Specific Relay Agent for a Subnet</title>
  2390. <para>
  2391. The relay has to have an interface connected to the link on which
  2392. the clients are being configured. Typically the relay has an IPv4
  2393. address configured on that interface that belongs to the subnet from which
  2394. the server will assign addresses. In the typical case, the
  2395. server is able to use the IPv4 address inserted by the relay (in the giaddr
  2396. field of the DHCPv4 packet) to select the appropriate subnet.
  2397. </para>
  2398. <para>
  2399. However, that is not always the case. In certain uncommon &mdash;
  2400. valid &mdash; deployments, the relay address may not match the subnet. This
  2401. usually means that there is more than one subnet allocated for a given
  2402. link. The two most common examples where this is the case are long lasting
  2403. network renumbering (where both old and new address space is still being
  2404. used) and a cable network. In a cable network both cable modems and the
  2405. devices behind them are physically connected to the same link, yet
  2406. they use distinct addressing. In such a case, the DHCPv4 server needs
  2407. additional information (the IPv4 address of the relay) to properly select
  2408. an appropriate subnet.
  2409. </para>
  2410. <para>
  2411. The following example assumes that there is a subnet 192.0.2.0/24
  2412. that is accessible via a relay that uses 10.0.0.1 as its IPv4 address.
  2413. The server will be able to select this subnet for any incoming packets
  2414. that came from a relay that has an address in 192.0.2.0/24 subnet.
  2415. It will also select that subnet for a relay with address 10.0.0.1.
  2416. <screen>
  2417. "Dhcp4": {
  2418. "subnet4": [
  2419. {
  2420. "subnet": "192.0.2.0/24",
  2421. "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
  2422. <userinput>"relay": {
  2423. "ip-address": "10.0.0.1"
  2424. }</userinput>,
  2425. ...
  2426. }
  2427. ],
  2428. ...
  2429. }
  2430. </screen>
  2431. </para>
  2432. </section>
  2433. <section id="dhcp4-srv-example-client-class-relay">
  2434. <title>Segregating IPv4 Clients in a Cable Network</title>
  2435. <para>
  2436. In certain cases, it is useful to mix relay address information,
  2437. introduced in <xref linkend="dhcp4-relay-override"/> with client
  2438. classification, explained in <xref linkend="dhcp4-subnet-class"/>.
  2439. One specific example is cable network, where typically modems
  2440. get addresses from a different subnet than all devices connected
  2441. behind them.
  2442. </para>
  2443. <para>
  2444. Let's assume that there is one CMTS (Cable Modem Termination System)
  2445. with one CM MAC (a physical link that modems are connected to).
  2446. We want the modems to get addresses from the 10.1.1.0/24 subnet, while
  2447. everything connected behind modems should get addresses from another
  2448. subnet (192.0.2.0/24). The CMTS that acts as a relay uses address
  2449. 10.1.1.1. The following configuration can serve that configuration:
  2450. <screen>
  2451. "Dhcp4": {
  2452. "subnet4": [
  2453. {
  2454. "subnet": "10.1.1.0/24",
  2455. "pools": [ { "pool": "10.1.1.2 - 10.1.1.20" } ],
  2456. <userinput>"client-class" "docsis3.0",
  2457. "relay": {
  2458. "ip-address": "10.1.1.1"
  2459. }</userinput>
  2460. },
  2461. {
  2462. "subnet": "192.0.2.0/24",
  2463. "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
  2464. <userinput>"relay": {
  2465. "ip-address": "10.1.1.1"
  2466. }</userinput>
  2467. }
  2468. ],
  2469. ...
  2470. }
  2471. </screen>
  2472. </para>
  2473. </section>
  2474. </section>
  2475. <section id="dhcp4-stats">
  2476. <title>Statistics in DHCPv4 server</title>
  2477. <note>
  2478. <para>This section describes DHCPv4-specific statistics. For a general
  2479. overview and usage of statistics, see <xref linkend="stats" />.</para>
  2480. </note>
  2481. <para>
  2482. The DHCPv4 server supports the following statistics:
  2483. </para>
  2484. <table frame="all" id="dhcp4-statistics">
  2485. <title>DHCPv4 Statistics</title>
  2486. <tgroup cols='3'>
  2487. <colspec colname='statistic' align='center'/>
  2488. <colspec colname='type' align='center'/>
  2489. <colspec colname='description' align='left'/>
  2490. <thead>
  2491. <row>
  2492. <entry>Statistic</entry>
  2493. <entry>Data Type</entry>
  2494. <entry>Description</entry>
  2495. </row>
  2496. </thead>
  2497. <tbody>
  2498. <row>
  2499. <entry>pkt4-received</entry>
  2500. <entry>integer</entry>
  2501. <entry>
  2502. Number of DHCPv4 packets received. This includes all packets: valid,
  2503. bogus, corrupted, rejected etc. This statistic is expected to grow
  2504. rapidly.
  2505. </entry>
  2506. </row>
  2507. <row>
  2508. <entry>pkt4-discover-received</entry>
  2509. <entry>integer</entry>
  2510. <entry>
  2511. Number of DHCPDISCOVER packets received. This statistic is expected to grow.
  2512. Its increase means that clients that just booted started their configuration process
  2513. and their initial packets reached your server.
  2514. </entry>
  2515. </row>
  2516. <row>
  2517. <entry>pkt4-offer-received</entry>
  2518. <entry>integer</entry>
  2519. <entry>
  2520. Number of DHCPOFFER packets received. This statistic
  2521. is expected to remain zero at all times, as DHCPOFFER packets are sent
  2522. by the server and the server is never expected to receive them. Non-zero
  2523. value indicates an error. One likely cause would be a misbehaving relay
  2524. agent that incorrectly forwards DHCPOFFER messages towards the server,
  2525. rather back to the clients.
  2526. </entry>
  2527. </row>
  2528. <row>
  2529. <entry>pkt4-request-received</entry>
  2530. <entry>integer</entry>
  2531. <entry>
  2532. Number of DHCPREQUEST packets received. This statistic
  2533. is expected to grow. Its increase means that clients that just booted
  2534. received server's response (DHCPOFFER), accepted it and now requesting
  2535. an address (DHCPREQUEST).
  2536. </entry>
  2537. </row>
  2538. <row>
  2539. <entry>pkt4-ack-received</entry>
  2540. <entry>integer</entry>
  2541. <entry>
  2542. Number of DHCPACK packets received. This statistic
  2543. is expected to remain zero at all times, as DHCPACK packets are sent
  2544. by the server and the server is never expected to receive them. Non-zero
  2545. value indicates an error. One likely cause would be a misbehaving relay
  2546. agent that incorrectly forwards DHCPACK messages towards the server,
  2547. rather back to the clients.
  2548. </entry>
  2549. </row>
  2550. <row>
  2551. <entry>pkt4-nak-received</entry>
  2552. <entry>integer</entry>
  2553. <entry>
  2554. Number of DHCPNAK packets received. This statistic
  2555. is expected to remain zero at all times, as DHCPNAK packets are sent
  2556. by the server and the server is never expected to receive them. Non-zero
  2557. value indicates an error. One likely cause would be a misbehaving relay
  2558. agent that incorrectly forwards DHCPNAK messages towards the server,
  2559. rather back to the clients.
  2560. </entry>
  2561. </row>
  2562. <row>
  2563. <entry>pkt4-release-received</entry>
  2564. <entry>integer</entry>
  2565. <entry>
  2566. Number of DHCPRELEASE packets received. This statistic
  2567. is expected to grow. Its increase means that clients that had an address
  2568. are shutting down or stop using their addresses.
  2569. </entry>
  2570. </row>
  2571. <row>
  2572. <entry>pkt4-decline-received</entry>
  2573. <entry>integer</entry>
  2574. <entry>
  2575. Number of DHCPDECLINE packets received. This statistic
  2576. is expected to remain close to zero. Its increase means that a client
  2577. that leased an address, but discovered that the address is currently
  2578. used by an unknown device in your network.
  2579. </entry>
  2580. </row>
  2581. <row>
  2582. <entry>pkt4-inform-received</entry>
  2583. <entry>integer</entry>
  2584. <entry>
  2585. Number of DHCPINFORM packets received. This statistic
  2586. is expected to grow. Its increase means that there are clients that
  2587. either do not need an address or already have an address and are
  2588. interested only in getting additional configuration parameters.
  2589. </entry>
  2590. </row>
  2591. <row>
  2592. <entry>pkt4-unknown-received</entry>
  2593. <entry>integer</entry>
  2594. <entry>
  2595. Number of packets received of an unknown type. Non-zero
  2596. value of this statistic indicates that the server received a packet
  2597. that it wasn't able to recognize: either with unsupported type
  2598. or possibly malformed (without message type option).
  2599. </entry>
  2600. </row>
  2601. <row>
  2602. <entry>pkt4-sent</entry>
  2603. <entry>integer</entry>
  2604. <entry>
  2605. Number of DHCPv4 packets sent. This statistic is expected to grow
  2606. every time the server transmits a packet. In general, it should
  2607. roughly match pkt4-received, as most incoming packets cause
  2608. server to respond. There are exceptions (e.g. DHCPRELEASE), so
  2609. do not worry, if it is lesser than pkt4-received.
  2610. </entry>
  2611. </row>
  2612. <row>
  2613. <entry>pkt4-offer-sent</entry>
  2614. <entry>integer</entry>
  2615. <entry>
  2616. Number of DHCPOFFER packets sent. This statistic is expected to
  2617. grow in most cases after a DHCPDISCOVER is processed. There are
  2618. certain uncommon, but valid cases where incoming DHCPDISCOVER is
  2619. dropped, but in general this statistic is expected to be close to
  2620. pkt4-discover-received.
  2621. </entry>
  2622. </row>
  2623. <row>
  2624. <entry>pkt4-ack-sent</entry>
  2625. <entry>integer</entry>
  2626. <entry>
  2627. Number of DHCPACK packets sent. This statistic is expected to
  2628. grow in most cases after a DHCPREQUEST is processed. There are
  2629. certain cases where DHCPNAK is sent instead. In general, the sum of
  2630. pkt4-ack-sent and pkt4-nak-sent should be close to
  2631. pkt4-request-received.
  2632. </entry>
  2633. </row>
  2634. <row>
  2635. <entry>pkt4-nak-sent</entry>
  2636. <entry>integer</entry>
  2637. <entry>
  2638. Number of DHCPNAK packets sent. This statistic is expected to
  2639. grow when the server choses to not honor the address requested by a
  2640. client. In general, the sum of pkt4-ack-sent and pkt4-nak-sent
  2641. should be close to pkt4-request-received.
  2642. </entry>
  2643. </row>
  2644. <row>
  2645. <entry>pkt4-parse-failed</entry>
  2646. <entry>integer</entry>
  2647. <entry>
  2648. Number of incoming packets that could not be parsed. Non-zero value of
  2649. this statistic indicates that the server received malformed or truncated packet.
  2650. This may indicate problems in your network, faulty clients or server code bug.
  2651. </entry>
  2652. </row>
  2653. <row>
  2654. <entry>pkt4-receive-drop</entry>
  2655. <entry>integer</entry>
  2656. <entry>
  2657. Number of incoming packets that were dropped.
  2658. Exact reason for dropping packets is logged, but the most common
  2659. reasons may be: an unacceptable packet type, direct responses are
  2660. forbidden, or the server-id sent by the client does not match
  2661. the server's server-id.
  2662. </entry>
  2663. </row>
  2664. <row>
  2665. <entry>subnet[id].total-addresses</entry>
  2666. <entry>integer</entry>
  2667. <entry>The total number of addresses available for the DHCPv4
  2668. management. In other words, this is the sum of all addresses in
  2669. all configured pools. This statistic changes only during
  2670. configuration changes. Note it does not take into account any
  2671. addresses that may be reserved due to host reservation. The
  2672. <emphasis>id</emphasis> is the subnet-id of a given subnet. This
  2673. statistic is exposed for each subnet separately. This statistic is
  2674. reset during reconfiguration event.</entry>
  2675. </row>
  2676. <row>
  2677. <entry>subnet[id].assigned-addresses</entry>
  2678. <entry>integer</entry>
  2679. <entry>This statistic shows the number of assigned addresses in a
  2680. given subnet. This statistic increases every time a new lease is
  2681. allocated (as a result of receiving a DHCPREQUEST message) and is
  2682. decreased every time a lease is released (a DHCPRELEASE message is
  2683. received). When lease expiration is implemented (planned for Kea
  2684. 1.0), it will also decrease when a lease is expired. The
  2685. <emphasis>id</emphasis> is the subnet-id of a given subnet. This
  2686. statistic is exposed for each subnet separately. This statistic is
  2687. reset during reconfiguration event.</entry>
  2688. </row>
  2689. </tbody>
  2690. </tgroup>
  2691. </table>
  2692. </section>
  2693. <section id="dhcp4-ctrl-channel">
  2694. <title>Management API for the DHCPv4 server</title>
  2695. <para>
  2696. Management API has been introduced in Kea 0.9.2-beta. It allows issuing specific
  2697. management commands, like statistics retrieval, reconfiguration or shutdown.
  2698. For more details, see <xref linkend="ctrl-channel" />. Currently the only
  2699. supported communication channel type is UNIX stream socket. By default there
  2700. are no sockets open. To instruct Kea to open a socket, the following entry
  2701. in the configuration file can be used:
  2702. <screen>
  2703. "Dhcp4": {
  2704. "control-socket": {
  2705. "socket-type": "unix",
  2706. "socket-name": <userinput>"/path/to/the/unix/socket"</userinput>
  2707. },
  2708. "subnet4": [
  2709. ...
  2710. ],
  2711. ...
  2712. }
  2713. </screen>
  2714. </para>
  2715. <para>
  2716. Communication over control channel is conducted using JSON structures.
  2717. See the Control Channel section in the Kea Developer's Guide for more details.
  2718. </para>
  2719. <para>DHCPv4 server supports <command>statistic-get</command>,
  2720. <command>statistic-reset</command>, <command>statistic-remove</command>,
  2721. <command>statistic-get-all</command>, <command>statistic-reset-all</command>
  2722. and <command>statistic-remove-all</command>, specified in
  2723. <xref linkend="command-stats"/>. It also supports
  2724. <command>list-commands</command> and <command>shutdown</command>,
  2725. specified in <xref linkend="command-list-commands" /> and
  2726. <xref linkend="command-shutdown" />, respectively.</para>
  2727. </section>
  2728. <section id="dhcp4-std">
  2729. <title>Supported DHCP Standards</title>
  2730. <para>The following standards are currently supported:</para>
  2731. <itemizedlist>
  2732. <listitem>
  2733. <simpara><emphasis>Dynamic Host Configuration Protocol</emphasis>,
  2734. <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>:
  2735. Supported messages are DHCPDISCOVER (1), DHCPOFFER (2),
  2736. DHCPREQUEST (3), DHCPRELEASE (7), DHCPINFORM (8), DHCPACK (5), and
  2737. DHCPNAK(6).</simpara>
  2738. </listitem>
  2739. <listitem>
  2740. <simpara><emphasis>DHCP Options and BOOTP Vendor Extensions</emphasis>,
  2741. <ulink url="http://tools.ietf.org/html/rfc2132">RFC 2132</ulink>:
  2742. Supported options are: PAD (0),
  2743. END(255), Message Type(53), DHCP Server Identifier (54),
  2744. Domain Name (15), DNS Servers (6), IP Address Lease Time
  2745. (51), Subnet mask (1), and Routers (3).</simpara>
  2746. </listitem>
  2747. <listitem>
  2748. <simpara><emphasis>DHCP Relay Agent Information Option</emphasis>,
  2749. <ulink url="http://tools.ietf.org/html/rfc3046">RFC 3046</ulink>:
  2750. Relay Agent Information option is supported.</simpara>
  2751. </listitem>
  2752. <listitem>
  2753. <simpara><emphasis>Vendor-Identifying Vendor Options for
  2754. Dynamic Host Configuration Protocol version 4</emphasis>,
  2755. <ulink url="http://tools.ietf.org/html/rfc3925">RFC 3925</ulink>:
  2756. Vendor-Identifying Vendor Class and Vendor-Identifying Vendor-Specific
  2757. Information options are supported.</simpara>
  2758. </listitem>
  2759. <listitem>
  2760. <simpara><emphasis>Client Identifier Option in DHCP Server Replies</emphasis>,
  2761. <ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>:
  2762. Server by default sends back client-id option. That capability may be
  2763. disabled. See <xref linkend="dhcp4-echo-client-id"/> for details.
  2764. </simpara>
  2765. </listitem>
  2766. </itemizedlist>
  2767. </section>
  2768. <section id="dhcp4-limit">
  2769. <title>DHCPv4 Server Limitations</title>
  2770. <para>These are the current limitations of the DHCPv4 server
  2771. software. Most of them are reflections of the current stage of
  2772. development and should be treated as <quote>not implemented
  2773. yet</quote>, rather than actual limitations. However, some of them
  2774. are implications of the design choices made. Those are clearly
  2775. marked as such.</para>
  2776. <itemizedlist>
  2777. <listitem> <!-- see tickets #3234, #3281 -->
  2778. <simpara>
  2779. Removal of a subnet during server reconfiguration may cause renumbering
  2780. of auto-generated subnet identifiers, as described in section
  2781. <xref linkend="ipv4-subnet-id"/>.
  2782. </simpara>
  2783. </listitem>
  2784. <listitem>
  2785. <simpara>Host reservation (static addresses) is not supported yet.</simpara>
  2786. </listitem>
  2787. <listitem>
  2788. <simpara>Full featured client classification is not supported yet.</simpara>
  2789. </listitem>
  2790. <listitem>
  2791. <simpara>
  2792. BOOTP (<ulink url="http://tools.ietf.org/html/rfc951">RFC 951</ulink>)
  2793. is not supported. This is a design choice. BOOTP support is not planned.
  2794. </simpara>
  2795. </listitem>
  2796. <listitem>
  2797. <simpara>On Linux and BSD system families the DHCP messages are sent
  2798. and received over the raw sockets (using LPF and BPF) and all packet
  2799. headers (including data link layer, IP and UDP headers) are created and
  2800. parsed by Kea, rather than the system kernel. Currently, Kea can
  2801. only parse the data link layer headers with a format adhering to
  2802. IEEE 802.3 standard and assumes this data link layer header format
  2803. for all interfaces. Hence, Kea will fail to work on interfaces
  2804. which use different data link layer header formats (e.g. Infiniband).
  2805. </simpara>
  2806. </listitem>
  2807. <listitem>
  2808. <simpara>The DHCPv4 server does not verify that
  2809. assigned address is unused. According to <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>, the
  2810. allocating server should verify that address is not used by
  2811. sending ICMP echo request.</simpara>
  2812. </listitem>
  2813. <listitem>
  2814. <simpara>Address duplication report (DECLINE) is not supported yet.</simpara>
  2815. </listitem>
  2816. <listitem>
  2817. <simpara>
  2818. The server doesn't act upon expired leases. In particular,
  2819. when a lease expires, the server doesn't request the removal
  2820. of the DNS records associated with it. Expired leases can be
  2821. recycled.
  2822. </simpara>
  2823. </listitem>
  2824. </itemizedlist>
  2825. </section>
  2826. <!--
  2827. <section id="dhcp4-srv-examples">
  2828. <title>Kea DHCPv4 server examples</title>
  2829. <para>
  2830. This section provides easy to use example. Each example can be read
  2831. separately. It is not intended to be read sequentially as there will
  2832. be many repetitions between examples. They are expected to serve as
  2833. easy to use copy-paste solutions to many common deployments.
  2834. </para>
  2835. @todo: add simple configuration for direct clients
  2836. @todo: add configuration for relayed clients
  2837. @todo: add client classification example
  2838. </section> -->
  2839. </chapter>