Mojatatu Networks

Suite 400, 303 Moodie Dr. Ottawa K2H 9R4 Ontario Canada hadi@mojatatu.com

Routing Internet Engineering Task Force ForCES Protocol Extension Experience in implementing and deploying the Forwarding and Control Element Separation (ForCES) architecture has demonstrated the need for a few small extensions both to ease programmability and to improve wire efficiency of some transactions. The ForCES protocol is extended with a table range operation and a new extension for error handling. This document updates the semantics in RFCs 5810 and 7121 to achieve that end goal.

Experience in implementing and deploying the ForCES architecture has demonstrated the need for a few small extensions both to ease programmability and to improve wire efficiency of some transactions. This document describes a few extensions to the semantics in the ForCES protocol specification to achieve that end goal. This document describes and justifies the need for two small extensions that are backward compatible. This document also clarifies details of how dumping of a large table residing on an FE (Forwarding Element) is achieved. To summarize: A table range operation to allow a controller or control application to request an arbitrary range of table rows is introduced. Additional error codes returned to the controller (or control application) by an FE are introduced. Additionally, a new extension to carry details on error codes is introduced. As a result, this document updates the definition of the FE Protocol Object (FEPO) Logical Functional Block (LFB) in . While already supported, an FE response to a GET request of a large table that does not fit in a single Protocol Layer (PL) message is not described in . This document clarifies the details.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

This document reiterates the terminology defined in several ForCES documents (, , , and ) for the sake of contextual clarity. Control Element (CE) Forwarding Element (FE) FE Model LFB (Logical Functional Block) Class (or type) LFB Instance LFB Model LFB Metadata ForCES Component LFB Component ForCES Protocol Layer (ForCES PL) ForCES Protocol Transport Mapping Layer (ForCES TML)

In this section, we present sample use cases to illustrate each challenge being addressed.

Consider, for the sake of illustration, an FE table with 1 million reasonably sized table rows that are sparsely populated. Assume, again for the sake of illustration, that there are 2000 table rows sparsely populated between the row indices 23-10023. Implementation experience has shown that existing approaches for retrieving or deleting a sizable number of table rows are both programmatically tedious and inefficient on utilization of both compute and wire resources. By definition, ForCES GET and DEL requests sent from a controller (or control application) are prepended with a path to a component and sent to the FE. In the case of indexed tables, the component path can point to either a table or a table row index. As an example, a control application attempting to retrieve the first 2000 table rows appearing between row indices 23 and 10023 can achieve its goal in one of the following ways: Dump the whole table and filter for the needed 2000 table rows. Send up to 10000 ForCES PL requests, incrementing the index by one each time, and stop when the needed 2000 entries are retrieved. If the application had knowledge of which table rows existed (not unreasonable given the controller is supposed to be aware of state within a Network Element (NE)), then the application could take advantage of ForCES batching to send fewer large messages (each with different path entries for a total of 2000). As argued, while the above options exist, all are tedious.

has defined a generic set of error codes that are to be returned to the CE from an FE. Deployment experience has shown that it would be useful to have more fine-grained error codes. As an example, the error code E_NOT_SUPPORTED could be mapped to many FE error source possibilities that need to then be interpreted by the caller based on some understanding of the nature of the sent request. This makes debugging more time consuming.

This section describes a normative update to the ForCES protocol to address the issues discussed in .

We define a new TLV, TABLERANGE-TLV (type ID 0x0117), that will be associated with the PATH-DATA-TLV in the same manner the KEYINFO-TLV is. shows how this new TLV is constructed.

illustrates a GET request for a range of rows 11 to 23 of a table with a component path of "1/6".

The path flag F_SELTABRANGE (0x2, i.e., bit 1, where bit 0 is F_SELKEY as defined in ) MUST be set to indicate the presence of the TABLERANGE-TLV. The path flag bit F_SELTABRANGE can only be used in a GET or DEL and is mutually exclusive with F_SELKEY. The FE MUST enforce the path flag constraints and ensure that the selected path belongs to a defined, indexed table component. Any violation of these constraints MUST be rejected with an error code of E_INVALID_TFLAGS with a description of what the problem is when using extended error reporting (refer to ). It should be noted that there are combinations of path selection mechanisms that should not appear together for the sake of simplicity of operations. These include TABLERANGE-TLV and KEYINFO-TLV as well as multiple nested TABLERANGE-TLVs. The TABLERANGE-TLV contents constitute: A 32-bit start index. An index of 0 implies the beginning of the table row. A 32-bit end index. A value of 0xFFFFFFFF implies the last entry. The response for a table range query will either be: The requested table data returned (when at least one referenced row is available); in such a case, a response with a path pointing to the table and whose data content contains the row(s) will be sent to the CE. The data content MUST be encapsulated in a SPARSEDATA-TLV. The SPARSEDATA-TLV content will have the "I" (in Index-Length-Value (ILV)) for each table row indicating the table indices. An EXTENDEDRESULT-TLV (refer to ) when: the response is to a range delete request. The result will either be: a success if any of the rows that were requested are deleted; or a proper error code if none of the rows that were requested can be deleted. data is absent and an error code of E_EMPTY with an optional content string describing the nature of the error is used (refer to ). both a path key and path table range were stated on the path flags of the original request. In such a case, an error code of E_INVALID_TFLAGS with an optional content string describing the nature of the error is used (refer to ). other standard ForCES errors (such as Access Control List (ACL) constraints trying to retrieve contents of an unreadable table, accessing unknown components, etc.) occur.

We define the following: A new set of error codes. Allocation of some reserved codes for private use. A new TLV, EXTENDEDRESULT-TLV (0x0118), that will carry a code (which will be a superset of what is currently specified in ) as well as an optional cause content. This is illustrated in .

The EXTENDEDRESULT-TLV Result Value is 32 bits and is a superset of the RESULT-TLV Result Value defined in . The new version code space is 32 bits as opposed to the code size of 8 bits in . The first 8-bit values (256 codes) are common to both code spaces. Code Mnemonic Details 0x18 E_TIMED_OUTA timeout occurred while processing the message 0x19 E_INVALID_TFLAGSInvalid table flags 0x1A E_INVALID_OPRequested operation is invalid 0x1B E_CONGEST_NTNode congestion notification 0x1C E_COMPONENT_NOT_A_TABLEComponent not a table 0x1D E_PERMOperation not permitted 0x1E E_BUSYSystem is busy 0x1F E_EMPTYTable is empty 0x20 E_UNKNOWNA generic catch-all error code. Carries a string to further extrapolate what the error implies.

Codes 0x100-0x200 are reserved for use as private codes. Since these are freely available, it is expected that the FE and CE side implementations will both understand/interpret the semantics of any used codes and avoid any conflicts.

Like all other ForCES TLVs, the EXTENDEDRESULT-TLV is expected to be 32-bit aligned. The EXTENDEDRESULT-TLV Result Value derives and extends from the same current namespace that is used by the RESULT-TLV Result Value as specified in Section 7.1.7 of . The main difference is that there is now a 32-bit Result Value (as opposed to the old 8-bit). The Optional Cause Content is defined to further disambiguate the Result Value. It is expected that UTF-8 string values will be used. The content Result Value is intended to be consumed by the (human) operator, and implementations may choose to specify different content for the same error code. Additionally, future codes may specify cause content to be of types other than string. It is recommended that the maximum size of the cause string should not exceed 32 bytes. The cause string is not standardized by this document.

To support backward compatibility, we update the FEPO LFB (in ) to version 1.2. We also add a new component ID 16 (named EResultAdmin), and a capability component ID 32 (named EResultCapab). An FE will advertise its capability to support extended TLVs via the EResultCapab table. When an FE is capable of responding with both extended results and older result TLVs, it will have two table rows, one for each supported value. By default, an FE capable of supporting both modes will assume the lowest common denominator (i.e., EResultAdmin will be EResultNotSupported) and will issue responses using RESULT-TLVs. It should be noted that an FE advertising FEPO version 1.2 MUST support EXTENDEDRESULT-TLVs at minimum. On an FE that supports both RESULT-TLVs and EXTENDEDRESULT-TLVs, a master CE can turn on support for extended results by setting the EResultAdmin value to 2, in which case the FE MUST switch over to sending only EXTENDEDRESULT-TLVs. Likewise, a master CE can turn off extended result responses by writing a 1 to the EResultAdmin. An FE that does not support one mode or the other MUST reject setting EResultAdmin to a value it does not support by responding with an error code of E_NOT_SUPPORTED. It is expected that all CEs participating in a high availability (HA) mode be capable of supporting FEPO version 1.2 whenever EResultAdmin is set to strict support of EXTENDEDRESULT-TLVs. The consensus between CEs in an HA set up to set strict support of EXTENDEDRESULT-TLVs is out of scope for this document.

Imagine a GET request to a path that is a table, i.e., a table dump. Such a request is sent to the FE with a specific correlator, say X. Imagine this table to have a large number of entries at the FE. For the sake of illustration, let's say millions of rows. This requires that the FE delivers the response over multiple messages, all using the same correlator X. The ForCES protocol document does not adequately describe how a large multi-part GET response message is delivered; the text in this section clarifies. We limit the discussion to a table object only. Implementation experience of dumping large tables shows that we can use transaction flags to indicate that a GET response is the beginning, middle, or end of a multi-part message. In other words, we mirror the effect of an atomic transaction sent by a CE to an FE.

| | correlator = X | | | | (1) Query-Response, SOT,AT, OP=GET-RESPONSE, DATA | |<-----------------------------------------------------| | correlator = X | | DATA TLV (SPARSE/FULL) | | | | (2) Query-Response, MOT,AT, OP=GET-RESPONSE, DATA | |<-----------------------------------------------------| | correlator = X | | DATA TLV (SPARSE/FULL) | | | | (3) Query-Response, MOT,AT, OP=GET-RESPONSE, DATA | |<-----------------------------------------------------| | correlator = X | | DATA TLV (SPARSE/FULL) | . . . . . . . . | | | (N) Query-Response, MOT,AT, OP=GET-RESPONSE, DATA | |<-----------------------------------------------------| | correlator = X | | DATA TLV (SPARSE/FULL) | | | | (N) Query-Response, EOT,AT, OP=GET-RESPONSE | |<-----------------------------------------------------| | correlator = X | | RESULT-TLV (SUCCESS) | | | ]]>

The last message to go to the CE, which carries the End Of Transaction (EOT) flag, MUST NOT carry any data. This allows us to mirror ForCES two-phase commit (2PC) messaging where the last message is an empty commit message. A GET response will carry a RESULT-TLV in such a case.

This document updates <https://www.iana.org/assignments/forces> as follows: This document registers two new top-level TLVs and two new path flags; it also updates an IANA-registered FE Protocol Object Logical Functional Block (LFB). defines an update to the FE Protocol Object LFB to version 1.2. An entry for FE Protocol Object LFB version 1.2 has been added to the "Logical Functional Block (LFB) Class Names and Class Identifiers" sub-registry. The following new TLVs have been defined and added to the "TLV Types" sub-registry: TABLERANGE-TLV (type ID 0x0117) EXTENDEDRESULT-TLV (type ID 0x0118) The "RESULT-TLV Result Values" sub-registry has been updated as follows: Codes 0x21-0xFE are marked as Unassigned. Codes 0x18-0x20 are defined by this document in . Codes 0x100-0x200 are reserved for private use. A new "EXTENDEDRESULT-TLV Result Values" sub-registry has been created. The codes 0x00-0xFF are mirrored from the "RESULT-TLV Result Values" sub-registry. Any future allocations of this code range (in the range 0x21-0xFE) must be made only in the new "EXTENDEDRESULT-TLV Result Values" sub-registry and not in the "RESULT-TLV Result Values" sub-registry. The codes 0x100-0x200 are reserved for private use as described earlier, and the code ranges 0x21-0xFE and 0x201-0xFFFFFFFF are marked as Unassigned with the IANA allocation policy of Specification Required . The Designated Expert (DE) needs to ensure that existing deployments are not broken by any specified request. The DE should post a given code request to the ForCES WG mailing list (or a successor designated by the Area Director) for comment and review. The DE should then either approve or deny the registration request, publish a notice of the decision to the ForCES WG mailing list or its successor, and inform IANA of his/her decision. A denial notice must be justified by an explanation and, in the cases where it is possible, concrete suggestions on how the request can be modified so as to become acceptable.

The security considerations described in the ForCES protocol apply to this document as well.

Harvard University

1350 Mass. Ave. Cambridge MA 02138 - +1 617 495 3864 sob@harvard.edu

This version of FEPO updates the earlier one given in . The XML has been validated against the schema defined in .

CEHBPolicyValues The possible values of CE heartbeat policy uchar CEHBPolicy0 The CE will send heartbeats to the FE every CEHDI timeout if no other messages have been sent since. CEHBPolicy1 The CE will not send heartbeats to the FE. FEHBPolicyValues The possible values of FE heartbeat policy uchar FEHBPolicy0 The FE will not generate any heartbeats to the CE. FEHBPolicy1 The FE generates heartbeats to the CE every FEHI if no other messages have been sent to the CE. FERestartPolicyValues The possible values of FE restart policy uchar FERestartPolicy0 The FE restarts its state from scratch. HAModeValues The possible values of HA modes uchar NoHA The FE is not running in HA mode. ColdStandby The FE is running in HA mode cold standby. HotStandby The FE is running in HA mode hot standby. CEFailoverPolicyValues The possible values of CE failover policy uchar CEFailoverPolicy0 The FE should stop functioning immediately and transition to FE OperDisable state. CEFailoverPolicy1 The FE should continue forwarding even without an associated CE for CEFTI. The FE goes to FE OperDisable when the CEFTI expires and there is no association. Requires graceful restart support. FEHACapab The supported HA features uchar GracefullRestart The FE supports graceful restart. HA The FE supports HA. CEStatusType Status values. Status for each CE uchar Disconnected No connection attempt with the CE yet Connected The FE connection with the CE at the TML has been completed. Associated The FE has associated with the CE. IsMaster The CE is the master (and associated). LostConnection The FE was associated with the CE but lost the connection. Unreachable The CE is deemed as unreachable by the FE. StatisticsType Statistics Definition RecvPackets Packets received uint64 RecvErrPackets Packets received from CE with errors uint64 RecvBytes Bytes received from CE uint64 RecvErrBytes Bytes received from CE in error uint64 TxmitPackets Packets transmitted to CE uint64 TxmitErrPackets Packets transmitted to CE that incurred errors uint64 TxmitBytes Bytes transmitted to CE uint64 TxmitErrBytes Bytes transmitted to CE incurring errors uint64 AllCEType Table Type for AllCE component CEID ID of the CE uint32 Statistics Statistics per CE StatisticsType CEStatus Status of the CE CEStatusType ExtendedResultType Possible extended result support uchar EResultNotSupported Extended results are not supported. EResultSupported Extended results are supported. FEPO The FE Protocol Object, with extended result control 1.2 CurrentRunningVersion Currently running ForCES version uchar FEID Unicast FEID uint32 MulticastFEIDs The table of all multicast IDs uint32 CEHBPolicy The CE Heartbeat Policy CEHBPolicyValues CEHDI The CE Heartbeat Dead Interval in milliseconds uint32 FEHBPolicy The FE Heartbeat Policy FEHBPolicyValues FEHI The FE Heartbeat Interval in milliseconds uint32 CEID The Primary CE this FE is associated with uint32 BackupCEs The table of all backup CEs other than the primary uint32 CEFailoverPolicy The CE Failover Policy CEFailoverPolicyValues CEFTI The CE Failover Timeout Interval in milliseconds uint32 FERestartPolicy The FE Restart Policy FERestartPolicyValues LastCEID The Primary CE this FE was last associated with uint32 HAMode The HA mode used HAModeValues AllCEs The table of all CEs AllCEType EResultAdmin Turn extended results off or on, but default to off. ExtendedResultType 1 SupportableVersions The table of ForCES versions that FE supports uchar HACapabilities The table of HA capabilities the FE supports FEHACapab EResultCapab The table of supported result capabilities ExtendedResultType PrimaryCEDown The primary CE has changed. LastCEID LastCEID PrimaryCEChanged A new primary CE has been selected. CEID CEID ]]>

The author would like to thank Evangelos Haleplidis and Joel Halpern for discussions that made this document better. Adrian Farrel did an excellent AD review of the document, which improved the quality of this document. Tobias Gondrom did the Security Directorate review. Brian Carpenter did the Gen-ART review. Nevil Brownlee performed the Operations Directorate review. S. Moonesamy (SM) worked hard to review our publication process. Pearl Liang caught issues in the IANA text. The author would like to thank the following IESG members who reviewed and improved this document: Alia Atlas, Barry Leiba, Brian Haberman, Kathleen Moriarty, Richard Barnes, and Spencer Dawkins.