From: Tomek Mrugalski Date: Fri, 15 Feb 2019 16:29:04 +0000 (+0100) Subject: [#464,!238] User's guide updated X-Git-Tag: 397-cb-implement-mysqlconfigbackenddhcpv6_base~54 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=11851e4de67d5bf1db156019c09e0aa0f47924a7;p=thirdparty%2Fkea.git [#464,!238] User's guide updated --- diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index acc46e66b1..d96ba4d003 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -1145,7 +1145,7 @@ temporarily override a list of interface names and listen on all interfaces. address) and the last (typically broadcast address) address from that pool. In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and 192.0.3.255 addresses may be assigned as well. This may be invalid in some - network configurations. If you want to avoid this, please use the "min-max" + network configurations. If you want to avoid this, please use the "min-max" notation. @@ -2078,6 +2078,109 @@ It is merely echoed by the server } + + Another popular option that is often somewhat imprecisely called vendor + option is option 125. It's proper name is vendor-independent + vendor-specific information option or vivso. The idea behind those + options is that each vendor has its own unique set of options with their + own custom formats. The vendor is identified by a 32 unsigned integer + called enterprise-id or vendor-id. For example, vivso with vendor-id + 4491 repesents DOCSIS options and you are likely to see many of them + when dealing with cable modems. + + + + In Kea each vendor is represented by its own vendor space. Since there + are hundreds of vendors and sometimes they use different option + definitions for different hardware, it's impossible for Kea to support + them all out of the box. Fortunately, it's easy to define support for + new vendor options. Let's take an example of Genexis home gateway. This + device requires sending vivso 125 option with a suboption 2 that + contains a string with TFTP server URL. To support such a device, three + steps are needed. First, we need to define option definitions that will + explain how the option is supposed to be formed. Second, we will need to + define option values. Third, we will need to tell Kea when to send + those specific options. This last step will be done with client + classification. + + + + An example snippet of a configuration could look similar to the + following: + + +{ + // First, we need to define that suboption 2 in vivso option for + // vendor-id 25167 has specific format (it's a plain string in this example). + // After this definition, we can specify values for option tftp. + "option-def": [ + { + // We define a short name, so the option could be referenced by name. + // The option has code 2 and resides with vendor space 25167. + // Its data is a plain string. + "name": "tftp", + "code": 2, + "space": "vendor-25167", + "type": "string" + } ], + + "client-classes": [ + { + // We now need to tell Kea how to recognize when to use vendor space 25167. + // Usually we can use simple expression such as checking if the device + // sent a vivso option with specific vendor-id, e.g. "vendor[4491].exists" + // Unfortunately, Genexis is a bit unusual in this aspect, because it + // doesn't send vivso. In this case we need to look into vendor class + // (option code 60) and see if there's specific string that identifies + // the device. + "name": "cpe_genexis", + "test": "substring(option[60].hex,0,7) == 'HMC1000'", + + // Once the device is recognized, we want to send two options: + // the VIVSO option with vendor-id set to 25167 and a suboption 2. + "option-data": [ + { + "name": "vivso-suboptions", + "data": "25167", + "encapsulate": "vendor-25167" + }, + + // The suboption 2 value is defined as any other option. However, + // we want to send this suboption 2, even when the client didn't + // explicitly requested it (often there is no way to do that for + // vendor options). Therefore we use always-send to force Kea + // to always send this option when 25167 vendor space is involved. + { + "name": "tftp", + "space": "vendor-25167", + "data": "tftp://192.0.2.1/genexis/HMC1000.v1.3.0-R.img", + "always-send": true + } + ] + } ] +} + + + + One aspect requires a bit broader comment. By default Kea sends back + only those options that are requested by a client, unless there are + protocol rules that tell DHCP server to always send an option. This + approach works nicely for most cases and avoids problems with clients + refusing responses with options they don't understand. Unfortunately, + this is more blurry when we consider vendor options. Some vendors (such + as docsis, identified by vendor options 4491) have a mechanism to + request specific vendor options and Kea is able to honor that. + Unfortunately, for many other vendors, such as Genexis (25167) discussed + here, Kea does not have such a mechanism, so it can't sent any + suboptions on its own. To solve this issue, we came up with a concept of + persistent options. Kea can be told to always send options, even if + client didn't request them. This can be achieved by adding + "always-send": true to your option definition. Note that in this + particular case an option is defined in a vendor space 25167. With the + "always-send" enabled, the option will be sent every time there is a + need to deal with vendor space 25167. + + Another possibility, since Kea 1.3, is to redefine the option, see .