NFD

# RIB Management

**RIB Management** is a module of [[Management|NFD Management protocol]].

It provides:

* commands to register and unregister routes

* a dataset of routes

RIB Management commands and datasets are published in namespace `ndn:/localhost/nfd/rib`.

RIB Management commands are also published in namespace `ndn:/localhop/nfd/rib`.

## Route

A **route** indicates that contents under a certain name prefix may be available via a certain nexthop.

A route contains:

* Name prefix

* nexthop FaceId

* origin

* cost

* route inheritance flags

### Route origin

**Origin** indicates who is announcing a route.

* **app**(=0): indicates a Route toward a local producer application

* **static**(=255): indicates a static route

* **nlsr**(=128): indicates a route installed by NLSR routing protocol

* **client**(=65): indicates a Route toward a client node attached to this router, installed via remote registration

* **autoreg**(=64): indicates a Route toward a client node attached to this router, registered automatically by this router

* **autoconf**(=66): indicates a Route toward a HUB from the laptop, registered automatically by the ndn-autoconf tool

### Route cost

**Cost** indicates the preference among multiple routes with same Name prefix.

The nexthop face on a route with lower cost is preferred.

Unlike IP routing, the nexthop face to use is decided by forwarding strategy.

Route cost is a suggestion to strategy; strategy MAY consider route cost when making forwarding decisions.

### Route inheritance

Each route can have two route inheritance flags:

* CHILD\_INHERIT: indicates that this route may be used even if a longer prefix is matched.

  This flag applies on a single route.

* CAPTURE: indicates that no shorter prefix can be used; overrides CHILD\_INHERIT.

  This flag applies on the prefix: if any route of a prefix has this flag, the prefix will have this flag.

Example:

Name prefix | nexthop FaceId | CHILD\_INHERIT | CAPTURE

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

/           | 1              | yes            | no

/           | 2              | no             | no

/A          | 3              | yes            | no

/A/B/C      | 4              | yes            | no

/D          | 5              | yes            | yes

/D          | 6              | yes            | no

* Interest /A/P can go to face 1 and 3.

    * It cannot go to face 2, because that route has CHILD\_INHERIT=no.

* Interest /A/B/C/Q can go to face 1, 3, and 4.

* Interest /D/R can go to face 5 and 6.

    * It cannot go to face 1, because one of the routes on /D sets CAPTURE=yes.

* Interest /S can go to face 1 and 2.

### Effective routing cost

The routing cost of a nexthop face for a Name prefix is the lowest cost among all Routes toward this nexthop face that can apply to this Name prefix.

Example:

Name prefix | nexthop FaceId | Origin | Cost | CHILD\_INHERIT | CAPTURE

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

/A          | 1              | static | 10   | no             | no

/A          | 1              | nlsr   | 20   | yes            | no

/A          | 2              | static | 30   | no             | no

/A/B        | 1              | static | 40   | yes            | no

/A/B        | 2              | static | 50   | yes            | no

/A/B/C      | 3              | static | 60   | yes            | no

/A/B/C/D    | 4              | static | 70   | yes            | yes

The corresponding FIB should be:

Name prefix | NextHop records

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

/A          | (face=1,cost=10) (face=2,cost=30)

/A/B        | (face=1,cost=20) (face=2,cost=50)

/A/B/C      | (face=1,cost=20) (face=2,cost=50) (face=3,cost=60)

/A/B/C/D    | (face=4,cost=70)

## Control Commands

[[ControlCommand]] **management-module**: `rib`

### Register a route

**command-verb**: `register`

This command adds a route to the RIB.  

This command can be accepted on `ndn:/localhop/nfd` management prefix, in addition to the default `ndn:/localhost/nfd` management prefix.

ControlParameters fields:

* Name (required)

* FaceId (optional)

* Origin (optional)

* Cost (optional)

* Flags (optional)

* ExpirationPeriod (optional)

FaceId is the FaceId returned in [[FaceMgmt|Face Management]].

If FaceId is omitted or is set to zero, it is implied as the requesting face (self registration).  

If face does not exist, the command fails with code 410.

Origin defaults to app(=0).

Cost defaults to zero.

Flags is an inclusive OR of route inheritance flags.

CHILD\_INHERIT=1, CAPTURE=2.

It defaults to CHILD\_INHERIT.

ExpirationPeriod gives the duration (in milliseconds) in which this route is effective.

After ExpirationPeriod has elapsed, or when the face fails, the route is removed.

ExpirationPeriod defaults to Infinity.

If a route of same Name, FaceId, and Origin exists, its Cost and Flags are updated, and its lifetime is extended to now + ExpirationPeriod.

If the command succeeds, \<body> in ControlResponse block contains updated ControlParameters:

* Name: Name prefix

* FaceId: nexthop FaceId (not zero)

* Route: route origin

* Cost: route cost

* Flags: inclusive OR of route inheritance flags

* ExpirationPeriod: remaining lifetime (in milliseconds), or omitted if it's Infinity

### Unregister a route

**command-verb**: `unregister`

This command removes a route from the RIB.  

This command can be accepted on `ndn:/localhop/nfd` management prefix, in addition to the default `ndn:/localhost/nfd` management prefix.

ControlParameters fields:

* Name (required)

* FaceId (optional)

* Origin (optional)

FaceId is the FaceId returned in [[FaceMgmt|Face Management]].

If FaceId is omitted or is set to zero, it is implied as the requesting face (self deregistration).

Origin defaults to app(=0).

Self deregistration is unnecessary if client is quitting. NFD automatically removes routes belonging to a failed face.

Client needs self deregistration when it stops serving a name prefix, but intends to continue execution.

If route does not exist, this command does nothing, but is still considered successful.

If the command succeeds, \<body> in ControlResponse block contains updated ControlParameters:

* Name: unchanged

* FaceId: nexthop FaceId (not zero)

* Origin: unchanged if request specifies; app(=0) if request omits

### Semantics of successful responses

Successful responses from these commands indicate that NFD RIB Management has received and authorized the command, and will perform the requested updates shortly.

RIB and FIB updates are asynchronous, and they are not necessarily completed when the response is sent.

## RIB Dataset

Routes are published as a [[StatusDataset|Status Dataset]] at `ndn:/localhost/nfd/rib/list`.

Multiple routes of same Name prefix are organized into a **RIB entry**.

Each RIB entry is represented by a **RibEntry** block:

    RibEntry := RIB-ENTRY-TYPE TLV-LENGTH

                  Name

                  Route+

    Route    := ROUTE-TYPE TLV-LENGTH

                  FaceId

                  Origin

                  Cost

                  Flags

                  ExpirationPeriod?

Flags is inclusive OR of route inheritance flags, encoded in the same way as `register` command.  

ExpirationPeriod is the remaining lifetime of a route, or omitted if it's Infinity.

## TLV-TYPE assignments

Type                                        | Assigned value    | Assigned value (hex)

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

RibEntry                                    | 128               | 0x80

Route                                       | 129               | 0x81