Changes between Version 17 and Version 18 of SubnetCommands


Ignore:
Timestamp:
Jun 12, 2017, 4:14:36 PM (5 months ago)
Author:
tomek
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • SubnetCommands

    v17 v18  
    11= Subnet Commands Hook Library =
    22
    3 This page describes requirements and a design for Subnet commands ('''subnet_cmds''') hook library. That library is planned for upcoming Kea 1.3 release. For overview of the commands, see [wiki:Commands#a2.4Subnetsmanagement], Section 2.4.
     3This page describes requirements and a design for Subnet commands ('''subnet_cmds''') hook library. That library is planned a a premium hook library for upcoming Kea 1.3 release. For overview of the commands, see [wiki:Commands#a2.4Subnetsmanagement], Section 2.4.
    44
    55'''NOTE''': This document is a work in progress, it is expected to be updated in the next future.
     
    77== Use Cases ==
    88
    9 One of the potential users shared a story with us. Once in a while, they boot a new datacenter. Each datacenter has up to a 1000 of new subnets. Therefore it is desired to be able to add a significant number of subnets with as little interruptions as possible.
    10 
    11 When troubleshooting network problems, it is essential to retrieve configuration for a given subnet being debugged.
    12 
    13 When GUI/IPAM system manages a network, it must be possible to retrieve a list of subnets, details for a given subnet, and then push changes for a given subnet. It must be possible to add new subnets, edit and remove existing ones.
    14 
    15 Once shared subnets support is developed, the library should able to provide management interface for it. As the shared subnets feature is not designed yet, the details are TBD.
     91. One of the potential users shared a story with us. Once in a while, they boot up a new datacenter. Each datacenter has up to a 1000 of new subnets. Therefore it is desired to be able to add a significant number of subnets with as little interruptions as possible.
     10
     112. When troubleshooting network problems, it is essential to retrieve configuration for a given subnet being debugged.
     12
     133. When GUI/IPAM system manages a network, it must be possible to retrieve a list of subnets, details for a given subnet, and then push changes for a given subnet. It must be possible to add new subnets, edit and remove existing ones.
     14
     154. Once shared subnets support is developed, the library should able to provide management interface for it. As the shared subnets feature is not designed yet (see SharedSubnets), the details are TBD.
    1616
    1717== Commands ==
     
    2020
    2121=== subnet4-list command ===
    22 This command takes no parameters and retrieves an abbreviated list of IPv4 subnets. Each subnet is represented by a single value of subnet-id. If you need to get more information about the subnet, please use subnet4-get call. Example call:
     22This command takes no parameters and retrieves an abbreviated list of IPv4 subnets. Each subnet is represented by a single value of subnet-id. If you need to get more information about the subnet, please use subnet4-get command. Example command:
    2323
    2424{{{#!json
     
    3636}
    3737}}}
    38 This should be interpreted as: There are 7 IPv4 subnets currently configured. They are using the following subnet-ids: 1, 2, 3, 4, 5, 8 and 12. Note that subnet-ids typically start from one and grow by one, but that is not guaranteed. Deleting first subnet being configured will cause the number start from 2 for example. Sysadmin can use his own numbering scheme, so numbers starting from 100 may designate a floor 1 for example. Therefore it is essential to not assume that subnet-ids are continuous or they are strictly increasing.
    39 
    40 '''Alternative''': returning just a subnet-id for each subnet seems rather terse. It has the advantage of being able to return large number of subnets in compact way. On the other hand, retrieving more information about them would require more calls. Therefore the alternative approach would be to return subnet-id and a subnet prefix for each subnet. If this approach is chosen, the response would look like this:
     38This should be interpreted as: There are 7 IPv4 subnets currently configured. They are using the following subnet-ids: 1, 2, 3, 4, 5, 8 and 12. Note that subnet-ids typically start from one and grow by one, but that is not guaranteed. Deleting first subnet being configured will cause the number start from 2 for example. Sysadmin can use his own numbering scheme, so numbers starting from 100 may designate a floor 1 for example. Therefore it is essential to not assume that subnet-ids are continuous or that they are strictly increasing.
     39
     40'''Alternative approach''': Returning just a subnet-id for each subnet seems rather terse. It has the advantage of being able to return large number of subnets in compact way. On the other hand, retrieving more information about them would require more commands to be issued. Therefore the alternative approach would be to return subnet-id and a subnet prefix for each subnet. If this approach is chosen, the response would look like this. Note this example response corresponds to the same case as above. The size of this response is definitely bigger, but the data becomes possibly useful on its own, without any extra commands.
    4141
    4242{{{#!json
     
    8282=== subnet6-list command ===
    8383
    84 This command takes no parameters and retrieves an abbreviated list of IPv6 subnets. Each subnet is represented by a single value of subnet-id. If you need to get more information but the subnet, please use subnet4-get call. Example call:
     84This command takes no parameters and retrieves an abbreviated list of IPv6 subnets. Each subnet is represented by a single value of subnet-id. If you need to get more information but the subnet, please use subnet6-get command. Example call:
    8585
    8686{{{#!json
     
    146146=== subnet4-get command ===
    147147
    148 This command retrieves information about a single subnet. There are several ways how such a subnet could be identified: by subnet-id, or by using CIDR (subnet/length) notation. Those two parameter sets are mutually exclusive.
     148This command retrieves information about a single subnet. There are several ways how such a subnet could be identified. In the initial implementation we expect to implement two of them: by subnet-id, or by using CIDR (subnet/length) notation. Those two parameter sets are mutually exclusive.
    149149
    150150Example call for query by subnet-id:
     
    203203=== subnet6-get command ===
    204204
    205 This command retrieves information about a single subnet. There are several ways how such a subnet could be identified: by subnet-id, or by using CIDR (subnet/length) notation. Those two parameter sets are mutually exclusive.
     205This command retrieves information about a single IPv6 subnet. There are several ways how such a subnet could be identified. The initial implementation will provide support for two of them: by subnet-id, or by using CIDR (subnet/length) notation. Those two parameter sets are mutually exclusive.
    206206
    207207Example call for query by subnet-id:
     
    263263=== subnet4-add command ===
    264264
    265 This command adds a new IPv4 subnet to the current configuration. It is worth noting that several sanity checks are conducted before the subnet is actually added. In particular, there's a check whether the subnet does not overlap with existing subnets. Also, this updates the currently running configuration and the change will be lost if the server is shut down. To retain this information, please use '''config-get''' to retrieve full configuration or '''config-write''' to write it to disk.
    266 
    267 In general, any parameters allowed in subnet4 scope in the configuration file are allowed as part of this command. Specifying subnet-id ("id" parameter) is not mandatory, but recommended. If not specified, the server will assign unique-id on its own.
     265This command adds a new IPv4 subnet to the current configuration. Several sanity checks are conducted before the subnet is actually added. In particular, there's a check whether the subnet does not overlap with existing subnets, whether the parameters are correct and the subnet-id is not currently used. Also, this updates the currently running configuration. The change will be lost if the server is shut down. To retain this information, please use '''config-get''' to retrieve full configuration or '''config-write''' to write it to disk.
     266
     267In general, any parameters allowed in subnet4 scope in the configuration file are allowed as part of this command. Specifying subnet-id ("id" parameter) is not mandatory, but recommended. If not specified, the server will assign unique-id on its own. The actual value is reported in the response.
    268268
    269269A example usage of this command could look like this:
     
    312312
    313313=== subnet6-add command ===
    314 This command adds a new IPv6 subnet to the current configuration. It is worth noting that several sanity checks are conducted before the subnet is actually added. In particular, there's a check whether the subnet does not overlap with existing subnets. Also, this updates the currently running configuration and the change will be lost if the server is shut down. To retain this information, please use '''config-get''' to retrieve full configuration or '''config-write''' to write it to disk.
    315 
    316 In general, any parameters allowed in subnet4 scope in the configuration file are allowed as part of this command. Specifying subnet-id ("id" parameter) is not mandatory, but recommended. If not specified, the server will assign unique-id on its own.
     314This command adds a new IPv6 subnet to the current configuration. Several sanity checks are conducted before the subnet is actually added. In particular, there's a check whether the subnet does not overlap with existing subnets. Also, this updates the currently running configuration. The change will be lost if the server is shut down. To retain this information, please use '''config-get''' to retrieve full configuration or '''config-write''' to write it to disk.
     315
     316In general, any parameters allowed in subnet6 scope in the configuration file are allowed as part of this command. Specifying subnet-id ("id" parameter) is not mandatory, but recommended. If not specified, the server will assign unique-id on its own.
    317317
    318318A example usage of this command could look like this:
     
    363363=== subnet4-del ===
    364364
    365 This command attempts to delete an IPv4 subnet. The initial implementation takes two optional parameters that specify whether to also delete the leases and the reservations in this subnet or not. In the future there will be more flexibility in the operation.
     365This command attempts to delete an IPv4 subnet. The initial implementation takes two optional parameters that specify whether to also delete the leases and the reservations in this subnet or not. In the future additional actions will be implemented.
    366366
    367367An example use of this command looks like this:
     
    377377}}}
    378378
    379 The plan for initial implementation is to support two values for *-action: delete (which means that either leases or host reservations associated with a given subnet are deleted) and keep (which means that either leases or host reservations are kept).
    380 
    381 The default is "keep". If leases-action is not specified, the leases are not deleted. If reservations-action is not specified, the reservations are not deleted.
    382 
    383 In the future, we may implement additional actions. In particular, we may implement "expire", which would keep the leases until the client tries to renew them and such a request would be NAKed, forcing client to restart its state machine. Another possible action here would be "reconfigure", i.e. to tell Kea to use DHCP reconfigure mechanism.
     379The plan for initial implementation is to support two values for leases-action and reservations-action: '''delete''' (which means that either leases or host reservations associated with a given subnet are deleted) and '''keep''' (which means that either leases or host reservations are kept).
     380
     381The default is '''keep'''. If leases-action is not specified, the leases are not deleted. If reservations-action is not specified, the reservations are not deleted.
     382
     383In the future, we may implement additional actions. In particular, we may implement '''expire''', which would keep the leases until the client tries to renew them and such a request would be NAKed, forcing client to restart its state machine. Another possible action here would be '''reconfigure''', i.e. to tell Kea to use DHCP reconfigure mechanism.
    384384
    385385NOTE: When leases-delete is set to true, the leases are permanently deleted in lease database. The devices (DHCP clients) are not informed about this removal and will continue using the addresses until the assigned lease lifetime elapses.
     
    410410}}}
    411411
    412 The plan for initial implementation is to support two values for *-action: delete (which means that either leases or host reservations associated with a given subnet are deleted) and keep (which means that either leases or host reservations are kept).
    413 
    414 The default is "keep". If leases-action is not specified, the leases are not deleted. If reservations-action is not specified, the reservations are not deleted.
    415 
    416 In the future, we may implement additional actions. In particular, we may implement "expire", which would keep the leases until the client tries to renew them and such a request would be rejected, forcing client to restart its state machine or send a Request message. Another possible action here would be "reconfigure", i.e. to tell Kea to use DHCP reconfigure mechanism.
     412The plan for initial implementation is to support two values for leases-action and reservations-action: '''delete''' (which means that either leases or host reservations associated with a given subnet are deleted) and '''keep''' (which means that either leases or host reservations are kept).
     413
     414The default is '''keep'''. If leases-action is not specified, the leases are not deleted. If reservations-action is not specified, the reservations are not deleted.
     415
     416In the future, we may implement additional actions. In particular, we may implement '''expire''', which would keep the leases until the client tries to renew them and such a request would be rejected, forcing client to restart its state machine or send a Request message. Another possible action here would be '''reconfigure''', i.e. to tell Kea to use DHCP reconfigure mechanism.
    417417
    418418NOTE: When leases-delete is set to true, the leases are permanently deleted in lease database. The devices (DHCP clients) are not informed about this removal and will continue using the addresses until the assigned lease lifetime elapses.
     
    428428== Design ==
    429429
    430 This functionality is planned as a [wiki:Hooks hooks library]. It is to be determined whether this library will be part of open source of premium offering.
     430This functionality is planned as a [wiki:Hooks hooks library]. The design is expected to be completed as part of #5322 ticket.
    431431
    432432With the increasing complexity of the configuration it becomes less and less viable to operate on complete list of all subnets. This will become more and more problematic once the configurations grow to many thousands of networks (it already does for many deployments). While there has to be a way to retrieve all subnets, this should not be the default access pattern and should be discouraged in general. Therefore the subnet4-list and subnet6-list returns the absolute minimum of information (i.e. the subnet-id values).