wiki:DDNSDesignDocument

DDNS Design

  1. Introduction
  2. Place within the BIND 10 system
  3. Communication with the other modules
    1. Message queue
    2. Boss module
    3. ConfigManager?
    4. b10-auth
    5. Data sources
    6. b10-xfrout
    7. Other modules
  4. Handling of DDNS UPDATE messages
    1. Process zone section
    2. Checking ACLs
    3. Checking DDNS prerequisites
    4. Checking data consistency
    5. Incrementing SOA serial value
    6. Forming an IXFR-out friendly set of changes
    7. Applying the change
  5. Configuration

Introduction

This document describes the design we (plan to) use to implement server-side DDNS functionality.

Place within the BIND 10 system

DDNS will be running as a separate process module, called b10-ddns. It will not listen for DDNS packets itself, but it will receive them from another module. Initially this will be b10-auth, but in the future we may have some kind of receptionist model (possibly implemented in several potential modules, and even b10-auth itself again, but that is currently out of scope for this document).

For reading DNS zone data, and applying changes, it shall use the Data Source API, it will *not* directly write to any backend store. If the API requires additions, these shall be addressed during the development of the DDNS module.

b10-ddns will be written in Python. If any subset of its functionality needs drastic speed improvements, we can consider making C++ library calls for those, but initially it shall be pure python (using the existing BIND 10 libraries as available).

Specific additions to current frameworks and API's in the rest of the system that have been identified so far shall be pointed out together with their associated ticket number below.

Communication with the other modules

Message queue

b10-ddns shall connect to the message queue like any other component, i.e. by intializing a isc.cc.ModuleCCSession object. This should be implemented in #1451.

Boss module

Apart from getting started and stopped by the boss module, b10-ddns does not need any other communication with it. b10-ddns does not need a priviliged port to run on, and hence does not need to start communications with the Boss process itself.

ConfigManager?

b10-ddns shall receive its configuration through standard communication with the ConfigManager? module. This should be implemented by the ModuleCCSession, and apart from defining a config_handler and a command_handler, this does not require any other functionality in the b10-ddns module. Stubs for these should be implemented in #1451.

b10-auth

Since b10-ddns does not listen for DNS messages itself, it needs to be passed UPDATE messages. This should be done in the same wait it is done for b10-xfrout. Note that the exact framework for this is under discussion, but no matter what the framework should look like in the end, they should be similar for DDNS and other modules.

One feature in the passing of DNS packets from b10-auth to other modules that the current implementation does not have yet is UDP message passing. This will be addressed in #1452.

Once #1452 is finished, we can implement this in #1454.

Data sources

Not strictly a module, but checking prerequisites and consistency, and for applying updates to the data source backends should be done through the high-level data source API. This API should have the functionality needed for this. Known gaps at this points are to be implemented in #1483 and #1484.

b10-xfrout

When an update has sucessfully been applied, b10-xfrout must be informed that the zone has changed, and that it can send out NOTIFY packets to slave servers, if necessary.

The ticket to implement this is #1513

Other modules

There is no need for b10-ddns to contact any other modules. Other modules may send commands to b10-ddns, but apart from defining which commands there are, that is out of scope for b10-ddns itself.

One notable future feature here is the interaction between DHCP and DDNS; Automatically updating zone data as DHCP leases are handed out or canceled is a much-requested feature. Whether this will be done through the DDNS module or through some other construct is undecided at this point.

Handling of DDNS UPDATE messages

Note: This sections provides a few suggested method names, as well as arguments and return values. This design is currently based on these names, but during development we may find a slightly different approach is necessary or wanted. We should follow this document, but be reasonable when logic dictates a different approach should be taken. Naturally, this document should then be updated.

A specific DDNS update is handled by an instance of the DDNSSession class; this class is responsible for handling the update and respond to the client, as described in the next sections.

(note that in a future version we may not send responses from the module itself; it may be passed back to whatever part of the system gave the update packet to the module)

Process zone section

Once the DNS message has been passed to the b10-ddns module, it can perform some initial checks on it. These are defined in RFC 2136 section 3.1. This section also defines how to respond for error cases.

The DDNSSession class defines a method for this check called _parse_update_packet(), it will need the Message object to read the zone section. It will need to access the DataSource? API, to see whether the zone is known, and to find the correct data source. If the verification fails, an error should be logged, an error response should be sent back to the client, and the update should be aborted.

If the check succeeds the module should create a DataSourceUpdater? object in the session, ready to check prerequisites and apply updates in the steps described below.

This should be implemented in ticket #1512

Checking ACLs

According to RFC 2136 section 3.3, ACL (permission) checks should be performed after zone and prerequisite checks. This, however, may not be the best place to do it, and we might want to perform ACL checks earlier. There are actually two levels of ACL checks we can do;

  • Whether the sender may send UPDATE packets we should consider in the first place
  • Whether the sender may send UPDATE packets for the specific zone it it trying to update.

The first one could even be done before the packet is passed to b10-ddns in the first place. For the second, if the acl is broad, it might be useful to do it before checking prerequisites and it might fit naturally in the zone section processing. Whether we do it before, at, or after the zone section is processed, we should process ACL before checking prerequisites, even if this technically violates the RFC.

The response to ACL matching will be defined by the specific ACL check results, but if the ACL check does not succeed, the result should be logged, and the update processing should stop. If the ACL check succeeds, processing should continue with prerequisite checking.

This will be implemented in ticket #1458.

Checking DDNS prerequisites

RFC 2136 defines the various rules for prerequisite checking.

The main method to perform these checks is called _check_prerequisites(). It should have access to the update Message object, to read the prerequisites from (either through a member of the DDNSSession object or as an argument), and the Updater object as created by or after the method that checks the zone section. It is subdivided into several smaller methods, for the different types of checks.

RFC 2136 defines the response that should be sent when a check fails, and how to proceed; a message should be logged, and the update should be aborted.

This will be implemented in ticket #1455 or its followup tickets.

Checking data consistency

Before committing the update, we can perform a number of consistency checks, so that we do not end up with inconsistent zone data.

At this moment we don't have any specific consistency checks defined. Any that come up should be added in #1459, and this section should be updated.

Incrementing SOA serial value

If the update itself does not change the SOA resource record, its serial should be incremented. RFC 2136 defines a number of scenarios that can be chosen to decide when the serial should be incremented. b10-ddns increments it on each succesfull update.

So after all basic checks have been performed, and the DDNSSession class is ready to perform the update, it should first check whether the SOA record is in the changeset. If not, it should add the removal of the SOA RR, and the subsequent addition of the same SOA RR with an incremented serial number to the changeset.

This should be implemented in ticket #1514

Forming an IXFR-out friendly set of changes

In order to be able to support IXFR-out, the data source API requires changes to be specified in a specific format. Conversion from the original update section in the original message to the correct format will be implemented in ticket #1456.

Applying the change

Once all checks have passed, and the update is ready, it can be committed. This is done in task #1457. This also includes sending back a success response, and logging that the zone has been updated. Unless there is a separate ticket for this, it should also include notifying b10-xfrout or b10-zonemgr that the zone has changed.

Configuration

Since we do not (yet?) have zone-centric configuration, the proposal is to use zone-names as references for zones; currently the only defined element of each entry would be a list of ACLs.

Initially, the only entry in DDNS configuration will be DDNS/zones, which is a named_set, where the name equals the zone name, and whose entries are a map with one item 'update_acls', which is a list of ACL specifications.

Ticket #1451 adds the above configuration items to the ddns.spec file. If work on any ticket add configuration items, this section should be updated.

Last modified 6 years ago Last modified on Dec 18, 2011, 5:43:38 PM