From c2db20f10d74afb27a6b9772a092af249e829906 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Fri, 22 Sep 2017 12:23:10 +0200 Subject: [PATCH] [5310] Applied minor changes to Shared Networks sections in User's Guide. As a result of review. --- doc/guide/dhcp4-srv.xml | 74 ++++++++++++++++++++--------------------- doc/guide/dhcp6-srv.xml | 62 +++++++++++++++++----------------- 2 files changed, 66 insertions(+), 70 deletions(-) diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index e161dbde44..c05576a44e 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -3288,33 +3288,30 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> blurred. Sometimes it is useful to have more than one logical IP subnet being deployed on the same physical link. The need to understand that two or more subnets are used on the same link requires additional logic - in the DHCP server. This capability has been added in Kea 1.3. - - The ability to use more than one subnet is called shared networks in - Kea and ISC DHCP projects. This feature is often called shared - subnets. Microsoft nomenclature tends to call it 'multinet'. - - + in the DHCP server. This capability has been added in Kea 1.3.0. It is + called "shared networks" in Kea and ISC DHCP projects. It is sometimes also + called "shared subnets". In Microsoft's nomenclature it is called "multinet". + There are many use cases where the feature is useful. This paragraph - explains just a handful of more common ones. The first and by far the most + explains just a handful of the most common ones. The first and by far the most common use case is an existing network that has grown and is running out of - available address space. Instead of migrating all devices to a new, larger - subnet, it is easier to simple configure additional subnet on top of + available address space. Rather than migrating all devices to a new, larger + subnet, it is easier to simply configure additional subnet on top of the existing one. Sometimes, due to address space fragmentation (e.g. only many disjoint /24s are available) this is the only choice. Also, configuring - additional subnet has the advantage of not distrupting existing - devices. + additional subnet has the advantage of not distrupting the operation of + existing devices. - Another very frequent use case are cable networks. There are two types + Another very frequent use case comes from cable networks. There are two types of devices in cable networks: cable modems and the end user devices behind them. It is a common practice to use different subnet for cable modems to prevent users from tinkering with their cable modems. In this case, the - distinction is based on the type of device, rather than coming out of - running out address space. + distinction is based on the type of device, rather than address space + exhaustion. - Kea 1.3 introduced support for shared networks. To define a shared - network, an additional scope is now honored: + In order to define a shared network an additional configuration scope + is introduced: { "Dhcp4": { @@ -3345,8 +3342,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> // This is regular subnet. It's not part of any shared-network. "subnet4": [ { - "pools": [ { "pool": "192.0.3.1 - 192.0.3.200" } ], - "subnet": "192.0.3.0/24" + "subnet": "192.0.3.0/24", + "pools": [ { "pool": "192.0.3.1 - 192.0.3.200" } ] } ] @@ -3363,14 +3360,15 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> consist of two or more subnets. However, for testing purposes it is allowed to define a shared network with just one subnet or even an empty one. This is not a recommended practice in production networks, as the shared network - logic requires additional processing and thus lowers performace. In general, - usage of shared networks is somewhat discouraged, unless they are really - needed. + logic requires additional processing and thus lowers server's performace. + To avoid unnecessary peformance degradation the shared subnets should only + be defined when required by the deployment. + - Shared networks provide an ability to specify many parameters on + Shared networks provide an ability to specify many parameters in the shared network scope that will apply to all subnets within it. If necessary, you can specify a parameter on the shared network scope and then - override its value on the subnet scope. For example: + override its value in the subnet scope. For example: "shared-networks": [ { @@ -3416,28 +3414,28 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> "data": "192.0.2.1" } ] } - ], + ] } ] In this example, there is a log-servers option defined that is available to clients in both subnets in this shared network. Also, a valid lifetime is - set to 10 minutes. However, the first subnet overrides some of the values + set to 10 minutes (600s). However, the first subnet overrides some of the values (valid lifetime is 20 minutes, different IP address for log-servers), but also adds its own option (router address). Assuming a client asking for router and log servers options is assigned a lease from this subnet, he will get a lease for 20 minutes and log-servers and routers value of 10.0.0.254. - If the same client is assigned to the second subnet, he will gett a 10 - minutes lease, log-servers value of 1.2.3.4 and routers set to 192.0.2.1. + If the same client is assigned to the second subnet, he will get a 10 + minutes long lease, log-servers value of 1.2.3.4 and routers set to 192.0.2.1.
Local and relayed traffic in shared networks - It is possible to specify interface name on shared network scope to + It is possible to specify interface name in the shared network scope to tell the server that this specific shared network is reachable directly (not via relays) using local network interface. It is sufficient to specify it once on the shared network level. As all subnets in a shared network are expected to be used on the same physical link, it is a configuration error - to attempt to make a shared network out of subnets that are reachable over + to attempt to define a shared network using subnets that are reachable over different interfaces. It is allowed to specify interface parameter on each subnet, although its value must be the same for each subnet. Thus it's usually more convenient to specify it once on the shared network level. @@ -3464,7 +3462,7 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> // error: // "interface": "eth1" } - ], + ] } ] @@ -3512,9 +3510,9 @@ as long as it is valid IPv4 address. Client classification in shared networks Sometimes it is desired to segregate clients into specific subnets. -A case of cable network where modems should use one subnet and everything else -should use another is a good example. For that reason Kea allows restricting -access to specific subnets based on client classification. See for details on how to define client classes. The following example defines two classes of devices. The decision is made @@ -3552,10 +3550,10 @@ based on option 93 values. } In this example each class has its own restriction. Only clients that belong to -class a-devices will be able to use subnet 192.0.2.0/26 and only clients +class "a-devices" will be able to use subnet 192.0.2.0/26 and only clients belonging to b-devices will be able to use subnet 10.0.0.0/24. Care should be taken to not define too restrictive classification rules, as clients that are -not able to use any subnets will be refused service. Although, this may be +not able to use any subnets will be refused service. Although, this may be a desired outcome if one desires to service only clients of known properties (e.g. only VoIP phones allowed on a given link). @@ -3609,10 +3607,10 @@ one of the reasons why defining a shared network may impact performance. If there is a reservation for a client in any subnet, that particular subnet will be picked for the client. Although it's technically not an error, it is considered a bad practice to define reservations for the same host in multiple -subnets belonging to the same client. +subnets belonging to the same shared network. While not strictly mandatory, it is strongly recommended to use explicit -ID values for subnets if you plan to use database storage for host +"id" values for subnets if you plan to use database storage for host reservations. If ID is not specified, the values for it be autogenerated, i.e. it will assign increasing integer values starting from 1.
diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index d50dcff277..9a53e561fd 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -3003,22 +3003,19 @@ If not specified, the default value is: blurred. Sometimes it is useful to have more than one logical IP subnet being deployed on the same physical link. The need to understand that two or more subnets are used on the same link requires additional logic - in the DHCP server. This capability has been added in Kea 1.3. - - The ability to use more than one subnet is called shared networks in - Kea and ISC DHCP projects. This feature is often called shared - subnets. Microsoft nomenclature tends to call it - 'multinet'. - - There are many use cases where the feature is useful. While the most - typical example of a subnet growing and running out of addresses is most - common in IPv4, there are several scenarios where it may be useful in IPv6 - as well. It is very unlikely any reasonably managed IPv6 network to ever run - out of addresses. However, it may run out of address space when handling - IPv6 prefixes. Another IPv6 specific example is an experiment with - addressing scheme. With the advent of IPv6 deployment and vast address - space, many organizations split the address space into subnets, then - deploy it and after a while discover that they want to split it + in the DHCP server. This capability has been added in Kea 1.3.0. It is + called "shared networks" in Kea and ISC DHCP projects. It is sometimes also + called "shared subnets". In Microsoft's nomenclature it is called "multinet". + + + There are many use cases where the feature is useful. The most common + example in the IPv4 case is when the server is running out of available + addresses in a subnet. This is less common in IPv6, but the shared networks + are still useful in IPv6. One of the use cases is an exhaustion of IPv6 + delegated prefixes within a subnet. Another IPv6 specific example + is an experiment with addressing scheme. With the advent of IPv6 deployment + and vast address space, many organizations split the address space into + subnets, then deploy it and after a while discover that they want to split it differently. In the transition period they want both old and new addressing to be available. Thus the need for more than one subnet on the same physical link. @@ -3030,8 +3027,8 @@ If not specified, the default value is: modems. In this case, the distinction is based on the type of device, rather than coming out of running out address space. - Kea 1.3 introduced support for shared networks. To define a shared - network, an additional scope is now honored: + In order to define a shared network an additional configuration scope + is introduced: { "Dhcp6": { @@ -3080,13 +3077,14 @@ If not specified, the default value is: consist of two or more subnets. However, for testing purposes it is allowed to define a shared network with just one subnet or even an empty one. This is not a recommended practice in production networks, as the shared network - logic requires additional processing and thus lowers performace. In general, - usage of shared networks is somewhat discouraged, unless they are really - needed. + logic requires additional processing and thus lowers server's performace. + To avoid unnecessary peformance degradation the shared subnets should only + be defined when required by the deployment. + - Shared networks provide an ability to specify many parameters on + Shared networks provide an ability to specify many parameters in the shared network scope that will apply to all subnets within it. If - necessary, you can specify a parameter on the shared network scope and then + necessary, you can specify a parameter in the shared network scope and then override its value on the subnet scope. For example: "shared-networks": [ @@ -3138,23 +3136,23 @@ If not specified, the default value is: In this example, there is a dns-servers option defined that is available to clients in both subnets in this shared network. Also, a valid lifetime is - set to 10 minutes. However, the first subnet overrides some of the values + set to 10 minutes (600s). However, the first subnet overrides some of the values (valid lifetime is 20 minutes, different IP address for dns-servers), but also adds its own option (unicast address). Assuming a client asking for a server unicast and dns servers options is assigned a lease from this subnet, he will get a lease for 20 minutes and dns-servers and be allowed to use server unicast at address 2001:abcd::1. If the same client is assigned to - the second subnet, he will get a 10 minutes lease, dns-servers value of + the second subnet, he will get a 10 minutes long lease, dns-servers value of 2001:db8:cafe::1 and no server unicast.
Local and relayed traffic in shared networks - It is possible to specify interface name on shared network scope to + It is possible to specify interface name in the shared network scope to tell the server that this specific shared network is reachable directly (not via relays) using local network interface. It is sufficient to specify - it once on the shared network level. As all subnets in a shared network are + it once in the shared network level. As all subnets in a shared network are expected to be used on the same physical link, it is a configuration error to attempt to make a shared network out of subnets that are reachable over different interfaces. It is allowed to specify interface parameter on each @@ -3231,9 +3229,9 @@ as long as it is valid IPv6 address. Client classification in shared networks Sometimes it is desired to segregate clients into specific subnets. -A case of cable network where modems should use one subnet and everything else -should use another is a good example. For that reason Kea allows restricting -access to specific subnets based on client classification. See for details on how to define client classes. The following example defines two classes of devices. The decision is made @@ -3328,10 +3326,10 @@ one of the reasons why defining a shared network may impact performance. If there is a reservation for a client in any subnet, that particular subnet will be picked for the client. Although it's technically not an error, it is considered a bad practice to define reservations for the same host in multiple -subnets belonging to the same client. +subnets belonging to the same shared network. While not strictly mandatory, it is strongly recommended to use explicit -ID values for subnets if you plan to use database storage for host +"id" values for subnets if you plan to use database storage for host reservations. If ID is not specified, the values for it be autogenerated, i.e. it will assign increasing integer values starting from 1.
-- 2.47.2