Opened 7 years ago

Closed 7 years ago

#2233 closed task (fixed)

Option Definition Design - V6 Options

Reported by: stephen Owned by: marcin
Priority: medium Milestone: Sprint-DHCP-20121018
Component: ~dhcpconf(obsolete) Version:
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: DHCP Feature Depending on Ticket:
Estimated Difficulty: 0 Add Hours to Ticket: 0
Total Hours: 0 Internal?: no

Description

Ticket #2232 covers the option definition for V4 options. This ticket extends that design to account for any extensions needed for V6 options.

Subtickets

Change History (9)

comment:1 Changed 7 years ago by marcin

  • Owner set to marcin
  • Status changed from new to accepted

comment:2 Changed 7 years ago by marcin

These comments refer to both #2232 and #2233.

The common outline design for DHCPv6 and DHCPv4 options definition had been created 9 months ago on BIND10 wiki: http://bind10.isc.org/wiki/DhcpOptionDefinition. This document has been now slightly extended. The following tasks are proposed to implement "Option Definition" for either DHCPv4 or DHCPv6:

  • Implement OptionXDefinition class
  • Extend option factory search mechanism to support searching for options using option code or option name. It is possible to use option code now but since option codes may overlap we need to add indexing using unique option name.
  • Create definitions of standard options - as a proof of concept that option definition through .spec file actually works, we may define their formats in the .spec file. If later decided, we may move their definition to the code. This task involves parsing the option definitions and creating the collection of all standard OptionXDefinition objects.
  • Implement OptionCollection? in the Subnet class. The OptionCollection? will hold the read-to-send options for each subnet. This task involves creating the parser that reads the option data from the .spec file and initializes the OptionCollection?.
  • Add support for custom namespaces and addition of options to those namespaces. Options that are added to custom namespaces can be encapsulated by other options. At this point we need to extend OptionXDefinition to parse the options added to custom namespace linked with it and create internal list of "supported" sub-options. Other classes may query OptionXDefinition object to check if particular option is encapsulated or not.

comment:3 Changed 7 years ago by marcin

  • Owner changed from marcin to UnAssigned
  • Status changed from accepted to reviewing

One task missing on the list above:

  • Create ScopeX classes. Elements of these types will carry scopes and vandor spaces defined in the configuration manager.

There are still a few outstanding questions. Typically:

  • Do we want user to override standard options or not,
  • How do we manage suboptions. Once scope is created we can aggregate suboptions with it. We can also point to this scope name in the option definition so as the list of sub-options can be extracted from the scope and included in the option. However I presume that there may be cases when we want to include options based on some condition. This is not yet resolved.

Please review the http://bind10.isc.org/wiki/DhcpOptionDefinition.

comment:4 Changed 7 years ago by stephen

  • Owner changed from UnAssigned to stephen

comment:5 follow-up: Changed 7 years ago by stephen

  • Owner changed from stephen to marcin

Reviewed version 15 of http://bind10.isc.org/wiki/DhcpOptionDefinition. I've made some small changes to correct typos etc. and saved version 16.

In the following review, text quoted comes from version 15 of the document:

Introduction

the program will create OptionXDefinition objects only for those standard options which are not already defined in user options space

Presumably this means that standard options will be defined in the source code?

a UserXOption object is created to represent it

Would not one of the existing OptionX objects be better?

Options Definition (outline design)]

Array indication - if this value is set to true than multiple occurrences of the record are allowed

Could this be a simple integer? 0 implies unlimited, positive is the number of occurrences expected, negative is any number up to the modulus of the given value.

Suboptions - holds the list of suboptions being encapsulated by this option. This list is obtained by querying the list of all options belonging to the custom defined space specified in the Configuration Manager.

This seems to belong in the vector of structures part of the definition. Perhaps if the data type in the option indicates "suboptions", another element in the structure should be a list of option definitions that describe them?

The name is qualified with the vendor name (if present). OptionXDefinition objects are held in one of two areas, one for system-wide options and the other for vendor options. Within the system-wide area, a map object allows the option to be located by name and another map by value.

Do you mean "another map by code"?

In the vendor options area, the names are unique as each option is qualified by a vendor name, hence a map can be used. To identify options by value, a multimap is needed as options from different vendors may have the same code.

So if the options have the same vendor (or enterprise) number and same code, how are they distinguished on an incoming message? Also, what about user-defined options?

When an option has been identified in a received packet, the option code and name is used to identify appropriate option factory function

AFAIK, the incoming message does not include the option name, only the code.

If the option format does not match any common format

Does this mean "if the type of the data in the option definition is 'record'"?

Access to the data is through another data structure in UserXOption

Are these different from the current OptionX objects?

Internally, parsed data is held as string for each data element.

I think a vector<uint8_t> would be more appropriate, as the data may be of arbitrary type.

If the server has to add user-defined options to its responses, it is assumed that elsewhere in the configuration will be the values of the parameters to be used.

Check with Tomek. I assume that if any options (system-defined or user-defined) are to be added to the response, their will either (a) be specified in the configuration file or (b) be generated by the server "on the fly". If the former, the values should have already been compared against the definitions and OptionX objects created holding the value.

comment:6 Changed 7 years ago by marcin

I updated the list of tasks with more comprehensive description and added some that had been omitted earlier. This may be useful to create tickets for the following sprints.

Note: I am going to respond to the review in the next turn.


Basic OptionDefinition? class implementation without suboptions
OptionDefinition? class represents the option definition for single option instance. In particular, it holds data type (or data types) conveyed by the particular option. The data type may be any of predefined option types, e.g. uint8, uint16 etc, or it can be record of multiple different data types. Setting option type to 'record' allows to specify data types carried by the record. It is also possible to provide array indicator which specifies that there are multiple 'single values' or multiple 'records' within the option. When OptionDefinition? instance is created it returns the most appropriate 'factory' function to create the option for the specified definition. The 'factory' function uses raw buffer as an input to create the instance ot the option.
The 'basic' implementation does not provide 'encapsulation' capabilities.

Custom Option implementation
If the specified user option definition does not match any standard 'factory' function the CustomOption? instance is returned. CustomOption? is derived from Option class and it provides generic approch to access option data fields - using array index, field name within the record etc.

Custom namespaces (including vendor spaces)
Custom namespaces play important role when it comes to specification of vendor options or options that encapsulate other options. In DHCPv4 the pool of available option codes is limited because option code value is uint8. For this reason option codes may be not unique and supplementary information is needed to identify the particular option - namespace. Since namespaces can group options it becomes conevnient to use namespace name in the OptionDefinition? to point out that the particular option encapsulates multiple other options (belonging to the namespace). We need a way to specify namespaces through the Configuration Manager. This task assumes creation of Namespace class that holds namespace attributes.

Namespace encapsulation by Option
This task involves creating a "link" between OptionDefinition? and available namespaces. In other words, we need to extend the OptionDefinition? implementation to store the namespace(s) the particular option belongs to.

Extensions to option lookup mechanism
We need a way to search for the option factory function, option definition and option value using not only option code but combination of option code and namespace.

Extend "Subnet" with OptionCollection? structure
Options may be configured with different values for different subnets. Tomek has already implemented the support for subnet configuration and created corresponding Subnet object. We need to extend the Subnet class with OptionCollection? structure that will store instances of options that have been configured. This task should be quick but we need to make sure that it is possible to search for the particular option within this data structure using either option code or namespace it belongs to.

Setting option definitions from Configuration Manager
We need to create/extend the .spec file that will hold the data structure to define the option definitions. Also, we need to extend the configuration parser to read the data and create instances of option definitions.

Setting option values from from Configuration Manager
We need to create/extend the .spec file to store option values in it. Also, we need to read option values from the configuration data base. Based on this, we need to create Option instances for each option for which data has been specified and put this in the OptionCollection? data structure (in Subnet object).

Setting Namespaces from the Configuration Manager.
We need to provide the way to create new namespace using Configuration Manager.

comment:7 in reply to: ↑ 5 Changed 7 years ago by marcin

  • Owner changed from marcin to stephen

Replying to stephen:

Reviewed version 15 of http://bind10.isc.org/wiki/DhcpOptionDefinition. I've made some small changes to correct typos etc. and saved version 16.

I created version 18 of this document. I introduced several changes to the text that should address most of the bullets from the review.


In the following review, text quoted comes from version 15 of the document:

Introduction

the program will create OptionXDefinition objects only for those standard options which are not already defined in user options space

Presumably this means that standard options will be defined in the source code?

Yes. Standard options will be defined in the source code.

a UserXOption object is created to represent it

Would not one of the existing OptionX objects be better?

I renamed UserXOption to CustomOption? because UserXOption suggests that it is reserved for user-defined options but user-defined options can be also represented by other classes, e.g. Option6AddrLst.

The CustomOption? will be derived from the Option class and will extend it with data structures suitable to hold "array or records" and similar. However Options of this type will be created only in case there is no better candidate for this. Such "better candidates" have accessors and mutators that access and modify particular data fields within the option and perform validation on input buffer.

Options Definition (outline design)]

Array indication - if this value is set to true than multiple occurrences of the record are allowed

Could this be a simple integer? 0 implies unlimited, positive is the number of occurrences expected, negative is any number up to the modulus of the given value.

I wouldn't complicate things that much. We already have the 'record' option type that allows to enumarate the exact data fields we want to see in the option. So, if I wanted to put the limitation on the number of fields (say 3) I would simply create the option definition with type set to 'record' and add 3 fields of certain type to it. Array is a kind of "open" option where I can add unlimited number of fields of the certain type (e.g. multiple IPV6 addresses). The implication here is that I can't add suboptions here because the definition has no way to determine where the suboptions start in the buffer.

Suboptions - holds the list of suboptions being encapsulated by this option. This list is obtained by querying the list of all options belonging to the custom defined space specified in the Configuration Manager.

This seems to belong in the vector of structures part of the definition. Perhaps if the data type in the option indicates "suboptions", another element in the structure should be a list of option definitions that describe them?

I resigned from "vector of structures" and replaced it with the vector of "data types". This is because the planned OptionDefinition? functionality will not operate on particular fields but it will rather try to match their types with the common patters and return factory functions. For this reason information like "field name" is not needed here.

AFAIK, sub-options may encapsulated by whole option and mixing option data fields with suboptions is not what we want to have. In other words, I don't want options like:

  • option_code
  • option_len
  • data_field_1
  • data_field_2
  • suboption_1
  • data_field_3
  • suboption_2

For this reason I didn't want to put this into the data structure that is simply aimed to keep the information which data fields are stored in this option and in which order. Suboptions are meant to be appended at the end of option.

The name is qualified with the vendor name (if present). OptionXDefinition objects are held in one of two areas, one for system-wide options and the other for vendor options. Within the system-wide area, a map object allows the option to be located by name and another map by value.

Do you mean "another map by code"?

Yes.

In the vendor options area, the names are unique as each option is qualified by a vendor name, hence a map can be used. To identify options by value, a multimap is needed as options from different vendors may have the same code.

So if the options have the same vendor (or enterprise) number and same code, how are they distinguished on an incoming message? Also, what about user-defined options?

When an option has been identified in a received packet, the option code and name is used to identify appropriate option factory function

AFAIK, the incoming message does not include the option name, only the code.

I added some more comprehensive description in the document about handling sub-options.

If the option format does not match any common format

Does this mean "if the type of the data in the option definition is 'record'"?

No. Records can be matched with the common option formats too. For example, I can define the record that comprises one element of "uint8" type. This is still a record but the option constructed from this definition will contain single field of uint8 type. I do have Option6Int class already so I can use it for this option.

By common format I rather understand the format that has a C++ class derived from Option class it fits. However I can also think of some present classes which may fit the layout of custom option but should not be used for user-defined options. For example: IA_NA comprises 4 fields of the type uint_32 and has the corresponding class Option6IA. I user defines the 'record' with 3 uint32_t types he should not get Option6IA just because it has the same data layout. In the code we will need to filter out such specialized classes and never return them for user-defined options.

Access to the data is through another data structure in UserXOption

Are these different from the current OptionX objects?

Yes, I am planning to derive another class so as we can access particular data fields in the unified way.

Internally, parsed data is held as string for each data element.

I think a vector<uint8_t> would be more appropriate, as the data may be of arbitrary type.

That's true. I changed this in the text.

If the server has to add user-defined options to its responses, it is assumed that elsewhere in the configuration will be the values of the parameters to be used.

Check with Tomek. I assume that if any options (system-defined or user-defined) are to be added to the response, their will either (a) be specified in the configuration file or (b) be generated by the server "on the fly". If the former, the values should have already been compared against the definitions and OptionX objects created holding the value.

Yes. Options can be configured "statically" from the configuration file or generate "on the fly". The latter case is tricky because if you override the format of the option which is generated "on the fly" you don't know if your data matches the format. It can be verified by checking the definition and it they don't match you don't know how to set the data for it. You can either:

  • force a user that this option must be statically configured
  • rely on some conditional expressions that we may or may not want to implement
  • prohibit overriding standard options that are prepared "on the fly"

comment:8 Changed 7 years ago by stephen

  • Owner changed from stephen to marcin

Reviewed version 18 of DhcpOptionDefinition

I made some minor edits - mainly adding an exclamation mark in front of camel-case words (such as OptionDefinition) to prevent them appearing as hyperlinks within the wiki. I also corrected some typos and grammar.

The changes are OK. I think this document has gone about as far as it can go for now, so this ticket (and the accompanying #2232) can be closed.

After the current development phase has finished, we should aim to revisit the documentation and update it to reflect what was finally implemented.

comment:9 Changed 7 years ago by marcin

  • Resolution set to fixed
  • Status changed from reviewing to closed
Note: See TracTickets for help on using tickets.