NFD

# NDNLPv2

{{>toc}}

NDNLPv2 is a link protocol for [Named Data Networking](https://named-data.net/).

It provides the following features:

* fragmentation and reassembly: fragment a network layer packet to fit in link MTU

* failure detection: rapidly detect link failure and recovery

* reliability: reduce packet loss

* integrity: prevent packet injection

* forwarding instruction: NACK, nexthop choice, cache control, etc

* packet information: for management and monitoring

NDNLPv2 is designed to be a **unified protocol** that can be used on all kinds of links, including but not limited to: UNIX sockets, Ethernet unicast/multicast, UDP unicast/multicast, TCP connections, WebSockets, etc.

The NDNLPv2 protocol operates as a **link adaptation layer**; it is above link layer and below network layer. Please refrain from calling it "layer 2.5": there is no such notion in RFC protocols.

Different links may need different features, or different designs of a feature. NDNLPv2 ensures that **all features are optional** and can be turned on or off on a per-link basis. NDNLPv2 also allows different designs of a feature to be adopted per-link.

NDNLPv2 deprecates and replaces: [original NDNLP (aka NDNLPv1)](https://named-data.net/publications/techreports/trlinkprotocol/), [NDNLPv1 multicast extension](https://github.com/NDN-Routing/NDNFD/blob/master/docs/NDNLP.md), [NDNLPv1-TLV](https://redmine.named-data.net/projects/nfd/wiki/NDNLP-TLV/7), [NDNLP-BFD](https://redmine.named-data.net/attachments/download/231/NDNLP-BFDSummaryReport.pdf), [NFD LocalControlHeader](https://redmine.named-data.net/projects/nfd/wiki/LocalControlHeader/25).

## General NDNLPv2 Packet Format

NDNLPv2 packet adopts a Type-Length-Value (TLV) structure similar to [NDN Packet Format](https://docs.named-data.net/NDN-packet-spec/0.3/tlv.html).

    LpPacket = LP-PACKET-TYPE TLV-LENGTH

               *LpHeaderField

               [Fragment]

    LpHeaderField = Sequence

    Sequence = SEQUENCE-TYPE TLV-LENGTH 8OCTET

    Fragment = FRAGMENT-TYPE TLV-LENGTH 1*OCTET

Outermost packet transmitted on a NDNLPv2 link is **LpPacket**.

In addition, a host MUST also accept bare network packets (Interest and Data) on a NDNLPv2 link, which SHOULD be interpreted as an LpPacket with the bare network packet as its Fragment. However, such packets could be dropped later in processing if the link configured to require a certain NDNLPv2 feature but a field is missing.

**LpHeaderField** is a repeatable optional structure in LpHeader.

NDNLPv2 features MAY add new header fields by extending the definition of LpHeaderField.

Unless otherwise specified, the same field shall appear at most once.

Unless otherwise specified, fields MUST appear in the order of increasing TLV-TYPE codes.

If an incoming LpPacket contains an unknown LpHeaderField, the following rules apply:

1. if the unknown field is in the range `[800, 959]` and the two least significant bits are both zero, the receiver SHOULD ignore the field and continue processing the packet;

2. otherwise, the receiver MUST drop the packet, but SHOULD NOT consider the link has an error.

Note: if a field is recognized but the relevant feature is disabled, it's not considered "unknown".

**Sequence** contains a sequence number that is useful in multiple features.

This field is REQUIRED if any enabled feature is using sequence numbers, otherwise it's OPTIONAL.

Bit width of the sequence number is determined on a per-link basis, 8 octets are recommended for today's links.

A host MUST generate consecutive sequence numbers for outgoing packets on the same face.

**Fragment** contains a fragment of one or more network layer packets.

The fragmentation and reassembly feature defines how Fragment field is constructed and interpreted.

When fragmentation and reassembly feature is disabled, the Fragment field contains a whole network layer packet.

Fragment is OPTIONAL; an LpPacket without Fragment is an **IDLE packet**.

## Indexed Fragmentation

Indexed fragmentation provides fragmentation and reassembly feature on datagram links that do not guarantee in-order delivery.

This feature defines two header fields:

    LpHeaderField =/ FragIndex / FragCount

    FragIndex = FRAG-INDEX-TYPE TLV-LENGTH NonNegativeInteger

    FragCount = FRAG-COUNT-TYPE TLV-LENGTH NonNegativeInteger

The sender slices a network layer packet into one or more fragments.

The size of each fragment MUST be small enough so that the LpPacket carrying every fragment is below the link MTU.

It is RECOMMENDED that all except the last fragments have the same size.

**FragCount** field indicates the number of fragments belonging to the same network layer packet.

It MUST be the same in all fragments belonging to the same network layer packet.

**FragIndex** field indicates the zero-based index of the current packet.

It MUST be assigned consecutively for fragments belonging to the same network layer packet, starting from zero.

The feature is named "indexed fragmentation" because every fragment is given an index in this field.

**Sequence** field is REQUIRED when this feature is enabled.

Fragments belonging to the same network layer packet MUST be assigned consecutive sequence numbers, in the same order with FragIndex.

For example, a 5000-octet network layer packet may be sliced as illustrated:

    +-------------+-------------+    +-------------+-------------+

    | LpPacket    | Fragment    |    | LpPacket    | Fragment    |

    | seq=8801    |             |    | seq=8802    |             |

    | FragIndex=0 | [0:1400]    |    | FragIndex=1 | [1400:2800] |

    | FragCount=4 |             |    | FragCount=4 |             |

    +-------------+-------------+    +-------------+-------------+

    +-------------+-------------+    +-------------+-------------+

    | LpPacket    | Fragment    |    | LpPacket    | Fragment    |

    | seq=8803    |             |    | seq=8804    |             |

    | FragIndex=2 | [2800:4200] |    | FragIndex=3 | [4200:5000] |

    | FragCount=4 |             |    | FragCount=4 |             |

    +-------------+-------------+    +-------------+-------------+

The receiver stores fragments in a *PartialMessageStore* data structure, which is a collection of PartialMessages, indexed by MessageIdentifier=Sequence-FragIndex.

Since both Sequence and FragIndex are assigned consecutively, MessageIdentifier would be the sequence number of the first fragment of a network layer packet.

After collecting all fragments belonging to a network layer packet, the receiver stitches them together, and delivers the complete network layer packet to the upper layer.

The receiver SHOULD maintain a reassembly timer for each PartialMessage, which is reset each time a new fragment is received.

If this timer expires, the PartialMessage is dropped.

The default duration of this timer is 500ms.

If this feature is enabled but FragIndex is missing, it is assumed to be 0 (zero).

If this feature is enabled but FragCount is missing, it is assumed to be 1 (one).

If this feature is disabled but either header field is received, the packet MUST be dropped.

Unless otherwise specified, header fields from other features MUST appear only in the first fragment.

If a header field appears on a subsequent fragment, it MUST be ignored, unless otherwise specified.

## Network NACK

A network NACK is a forwarding instruction from upstream to downstream that indicates the upstream is unable to satisfy an Interest.

This feature defines a header field:

    LpHeaderField =/ Nack

    Nack = NACK-TYPE TLV-LENGTH [NackReason]

    NackReason = NACK-REASON-TYPE TLV-LENGTH NonNegativeInteger

**Nack** header field indicates an Interest is a NACK, and is not a normal Interest.

The receiver MUST NOT process the packet as an Interest.

**NackReason** element MAY be included to indicate why the NACK is transmitted.  

The following NackReason values are defined:

Code  | Reason       | Description

----- | ------------ | --------------------------------------------------------------

0     | None         | (reserved)

50    | Congestion   | there is a congestion in the link between upstream and downstream, or on the best-known path between upstream and content source

100   | Duplicate    | the upstream has detected a duplicate Nonce in the Interest sent by the downstream

150   | NoRoute      | the upstream has no path to reach a content source due to routing problem or link failure

A receiver MUST be prepared to process a NACK without a reason.  

If NackReason element contains an unrecognized reason, the receiver MUST treat this NACK as a NACK without reason, and MUST NOT drop the packet.

Example of NACK of an Interest for `/example` with NACK reason "Duplicate":

    +--------------------------+---------------+

    | LpPacket                 | Interest      |

    |                          | Name=/example |

    | +-Nack-----------------+ | Nonce=35      |

    | | NackReason=Duplicate | |               |

    | +----------------------+ |               |

    +--------------------------+---------------+

It's RECOMMENDED to enable this feature on every link.  

If this feature is disabled but Nack is received, the packet MUST be dropped.

Nack header field is permitted only on an LpPacket carrying an Interest.  

When Nack appears on an LpPacket carrying a network layer packet other than an Interest, the packet MUST be dropped.

## PIT Token

    LpHeaderField =/ PitToken

    PitToken = PIT-TOKEN-TYPE TLV-LENGTH 1*32OCTET

The **PitToken** field is similar to the "Interest digest" as described in #3333, but it is hop-by-hop and does not require universal agreement.

A downstream attaches one or more bytes as the TLV-VALUE of this field when transmitting an Interest. These bytes are opaque to the upstream.

When the upstream responds to this Interest with a Data or Nack packet, it SHALL attach a PitToken field with the same bytes.

The downstream MUST verify these bytes before assuming the Data/Nack matches the Interest.

## Consumer-Controlled Forwarding

Consumer-controlled forwarding allows a local consumer application to explicitly specify the nexthop face to forward an Interest.

This feature defines a header field:

    LpHeaderField =/ NextHopFaceId

    NextHopFaceId = NEXT-HOP-FACE-ID-TYPE TLV-LENGTH NonNegativeInteger

**NextHopFaceId** indicates the nexthop FaceId to which an Interest should be forwarded.

A local consumer application MAY add this field to an LpPacket carrying an Interest.

The local forwarder SHOULD follow this instruction and forward the Interest to the specified nexthop, after ContentStore lookup does not find a match.

This feature is designed to be used on local faces only.

It SHOULD NOT be enabled on non-local faces.

If this feature is enabled but NextHopFaceId refers to a non-existent face, the Interest SHOULD be processed as if there is no available route.

If this feature is disabled but NextHopFaceId is received, the packet SHOULD be dropped, or this field MUST be ignored.

NextHopFaceId header field is permitted only on an LpPacket carrying an Interest, from an application to the forwarder.

When NextHopFaceId appears on an LpPacket carrying a network layer packet other than an Interest, the packet MUST be dropped.

When NextHopFaceId appears on an LpPacket that has a Nack header field, the packet SHOULD be dropped.

When NextHopFaceId is received by an application from a forwarder, this field MUST be ignored.

## Incoming Face Indication

Incoming face indication feature allows the forwarder to inform local applications about the face on which a packet is received.

This feature defines a header field:

    LpHeaderField =/ IncomingFaceId

    IncomingFaceId = INCOMING-FACE-ID-TYPE TLV-LENGTH NonNegativeInteger

**IncomingFaceId** contains the FaceId from which the network layer packet is received.

When this feature is enabled, the forwarder SHOULD attach this field to every network layer packet going to a local application, and indicate the FaceId on which this network layer packet was received by the forwarder.

If a Data packet comes from the ContentStore, IncomingFaceId SHOULD contain a special FaceId that represents the ContentStore, rather than the FaceId on which this Data packet was originally received.

Even if this feature is enabled, the application MUST be prepared to receive a packet without an IncomingFaceId field.

This feature is designed to be used on local faces only.

It SHOULD NOT be enabled on non-local faces.

IncomingFaceId header field is permitted only on an LpPacket from the forwarder to an application.

When IncomingFaceId is received by the forwarder from an application, this field MUST be ignored.

## Local Cache Policy

Local cache policy feature allows a local producer application to instruct ContentStore on whether and how to cache a Data packet.

This feature defines a header field:

    LpHeaderField =/ CachePolicy

    CachePolicy = CACHE-POLICY-TYPE TLV-LENGTH CachePolicyType

    CachePolicyType = CACHE-POLICY-TYPE-TYPE TLV-LENGTH NonNegativeInteger

**CachePolicy** header field gives a suggestion to the ContentStore.

The ContentStore MAY follow this suggestion.

**CachePolicyType** element MUST be included to indicate the suggestion.

The following CachePolicyType values are defined:

Code | Policy  | Description

-----|---------|--------------------------------

0    | None    | (reserved)

1    | NoCache | ContentStore SHOULD NOT admit the Data packet

If CachePolicyType field contains an unknown policy code, the forwarder SHOULD drop the packet.

The design places the policy code in the CachePolicyType element nested under CachePolicy, instead of having the code appear directly in CachePolicy header field, because in the future other policies that require additional arguments can be defined, and those arguments can appear as elements after CachePolicyType.

Example for a Data packet with "NoCache" policy:

    +-----------------------------+---------------+

    | LpPacket                    | Data          |

    |                             | Name=/example |

    | +-CachePolicy-------------+ | Content=xxxx  |

    | | CachePolicyType=NoCache | | Signature=xx  |

    | +-------------------------+ |               |

    +-----------------------------+---------------+

This feature is designed to be used on local faces only.

It SHOULD NOT be enabled on non-local faces.

If this feature is disabled but CachePolicy is received, this field MUST be ignored.

CachePolicy header field is permitted only on an LpPacket carrying a Data packet, from an application to the forwarder.

When CachePolicy header field appears on an LpPacket carrying a network layer packet other than a Data packet, the packet MUST be dropped.

When CachePolicy is received by an application from a forwarder, this field MUST be ignored.

## Congestion Marking

A host can signal the current congestion state to other hosts using the **CongestionMark** field. A value of 0 indicates *no congestion*; a value greater than 0 indicates some level of congestion. The exact meaning of the bits in this field is left up to the congestion control strategy in use.

This features defines a header field:

    LpHeaderField =/ CongestionMark

    CongestionMark = CONGESTION-MARK-TYPE TLV-LENGTH NonNegativeInteger

## Link Layer Reliability

To provide increased reliability and indicate potential congestion on a unicast link, a sender can expect frames successfully received by another host to be acknowledged.

After sending a link-layer frame (potentially fragmented, as described above), a host will expect an **Ack** field to be received on a frame returned in the opposite direction. This field will contain the **TxSequence** of the acknowledged frame. TxSequence numbers are assigned sequentially on the link, and are independent of the sequence number of the stored fragment. If the host does not receive this acknowledgement within the RTO (determined using the formula described below) and the frame has not been retransmitted more than a pre-determined number of times (the maximum number of retransmissions), the frame will be retransmitted on the link with the same sequence number, but a new TxSequence. In addition, if a configurable number of Acks (three by default) for greater TxSequences are received by the sender of the frame, the frame will be considered lost and the previously discussed retransmission logic will be followed.

To facilitate the retransmission of frames, each frame will be cached on the sender until it is acknowledged, at which point it can be deleted from the cache. The sender also keeps track of which frames were fragmented from which network-layer packet (if fragmentation occurred) and which unacknowledged TxSequences reference which transmitted frame. If one fragment of a network-layer packet exceeds the maximum number of retransmissions, the RTO timers of all fragments in the packet will be cancelled, all fragments of the packet will be deleted from the frame cache, and the entire packet will be considered lost. The sender will keep track of which sequence numbers are associated with which network-layer packets.

The receiver will extract the TxSequence of every received frame and will insert these numbers into a queue of pending Acks destined for the sender. When a frame is being transmitted in the opposite direction, any excess space under the MTU will be filled with TxSequences removed from this queue. An idle Ack timer is used to handle links that have gone idle. If a packet with a TxSequence is received and the packet has not been started, or has expired, the timer is started with a period of 5ms (or another configurable non-zero time period). Upon expiration of the timer, all Acks in the queue will be sent in IDLE packets. The receiver will also track the fragment sequence numbers of received non-IDLE frames for 1x the estimated RTO at the time of receipt. If the fragment sequence number of a received packet matches a recently received fragment sequence number, the fragment contained within will be dropped, but its TxSequence will be acknowledged to the sender and any Acks contained within the frame will be processed.

The RTO is determined using the standard TCP formula: `RTO = SRTT + 4 * RTTVAR`. The round-trip time (RTT) of a packet is measured as the difference between the time the frame was transmitted and when an Ack was received for it. Frames that have been retransmitted are not taken into account by this formula.

Multiple Ack fields can be sent in one LpPacket. If an Ack is received for an unknown TxSequence, the Ack will be ignored.

    LpHeaderField =/ TxSequence / Ack

    TxSequence = TX-SEQUENCE-TYPE TLV-LENGTH 8OCTET

    Ack = ACK-TYPE TLV-LENGTH 8OCTET

The **Sequence** field is required on any non-IDLE frames transmitted on a link while reliability is enabled.

*Modified from "Hop-By-Hop Best Effort Link Layer Reliability in Named Data Networking" by S. Vusirikala, et al.*

## Self-Learning Forwarding Support

[NDN self-learning](https://named-data.net/publications/on_broadcast-based_self-learning_ndn/) is a forwarding protocol that can automatically discover contents and forwarding paths in local area networks. This feature adds two hop-by-hop headers to support this forwarding protocol.

    LpHeaderField =/ NonDiscovery / PrefixAnnouncement

    NonDiscovery = NON-DISCOVERY-TYPE

                   TLV-LENGTH ; == 0

    PrefixAnnouncement = PREFIX-ANNOUNCEMENT-TYPE TLV-LENGTH Data

Self-learning distinguishes an Interest as either "discovery" or "non-discovery". A node transmits a discovery Interest to explore new forwarding paths, or transmits a non-discovery Interest to exploit existing forwarding paths. The **NonDiscovery** field indicates an Interest is "non-discovery"; otherwise, an Interest without this field is "discovery".

This field can only appear on an Interest. If this field appears on a Data or a Nack, the LpPacket MUST be dropped. If the self-learning forwarding protocol support feature is disabled or the chosen forwarding strategy does not support self-learning, this field SHOULD be ignored.

When replying to a discovery Interest, the upstream node SHOULD transmit the Data with a **PrefixAnnouncementHeader** field. This field indicates what name prefix the producer is serving, and assists the downstream node in updating its FIB. A PrefixAnnouncement contains a single Data TLV element, and the Data format follows the [[PrefixAnnouncement]] Protocol.

This field can only appear on a Data. If this field appears on an Interest or a Nack, the LpPacket MUST be dropped. If the self-learning forwarding protocol support feature is disabled or the chosen forwarding strategy does not support self-learning, this field SHOULD be ignored.

## TLV-TYPE Number Assignments

Type                     | number (dec)     | number (hex)

-------------------------|------------------|------------------

Fragment                 | 80               | 0x50

Sequence                 | 81               | 0x51

FragIndex                | 82               | 0x52

FragCount                | 83               | 0x53

HopCount (ndnSIM)        | 84               | 0x54

GeoTag (ndnSIM)          | 85               | 0x55

PitToken                 | 98               | 0x62

LpPacket                 | 100              | 0x64

Nack                     | 800              | 0x0320

NackReason               | 801              | 0x0321

IncomingFaceId           | 812              | 0x032C

NextHopFaceId            | 816              | 0x0330

*Reserved, formerly IncomingFaceId*| 817    | 0x0331

CachePolicy              | 820              | 0x0334

CachePolicyType          | 821              | 0x0335

CongestionMark           | 832              | 0x0340

Ack                      | 836              | 0x0344

TxSequence               | 840              | 0x0348

NonDiscovery             | 844              | 0x034C

PrefixAnnouncement       | 848              | 0x0350

### Reserved Blocks

Two blocks of TLV-TYPEs have been reserved by link protocols:

* `[80, 100]`: 1-octet encoding

* `[800, 1000]`: 3-octet encoding

TLV-TYPE numbers for LpHeaderField SHOULD be assigned according to the following rules:

1. if the field can be safely ignored by a receiver that doesn't understand the field, pick an unused number in the range `[800, 959]` whose two least significant bits are `00`.

2. if the field would occur frequently, pick an unused number in the range `[81, 99]`.

3. otherwise, pick an unused number in the range `[800, 959]` whose two least significant bits are `01`.

Note: number assignment for a TLV-TYPE nested within a LpHeaderField is not restricted by the above rules.