Project

General

Profile

Actions
History

Management »

FaceMgmt » History » Revision 37

« Previous | Revision 37/118 (diff) | Next »
Junxiao Shi, 07/19/2014 08:32 PM

Face Management

Face Management is a module of NFD Management protocol.
It provides:

  • commands to create and destroy faces
  • commands to enable and disable LocalControlHeader features on a face
  • a dataset of description of all active faces and their counters
  • a dataset of description of all active channels
  • a notification stream for face creating and destroying events

Face Management commands, datasets, and notifications are published in namespace ndn:/localhost/nfd/faces.

FaceUri

A FaceUri represents the underlying protocol and address used by a Face.

Every Face has two FaceUris: one for local endpoint, and the other for remote endpoint.

UDP

udp[4|6]://<IP-or-host>[:<port>]

Examples:

  • udp4://192.0.2.1:6363 (canonical form)
  • udp6://[2001:db8::1]:6363 (canonical form)
  • udp://192.0.2.1 (remote-port defaults to 6363)
  • udp://example.net:6363
  • udp4://example.net:6363 (resolve hostname to IPv4 address only)
  • udp6://example.net:6363 (resolve hostname to IPv6 address only)
  • udp4://224.0.23.170:56363 (multicast, canonical form)

TCP

tcp[4|6]://<IP-or-host>[:<port>]

Examples:

  • tcp4://192.0.2.1:6363 (canonical form)
  • tcp6://[2001:db8::1]:6363 (canonical form)
  • tcp://192.0.2.1 (remote-port defaults to 6363)
  • tcp://example.net:6363
  • tcp4://example.net:6363 (resolve hostname to IPv4 address only)
  • tcp6://example.net:6363 (resolve hostname to IPv6 address only)

UNIX stream

unix://<path>

Examples:

  • unix:///var/run/nfd.sock (note there are three forward-slashes after 'unix')

File Descriptor

fd://<file-descriptor>

Examples:

  • fd://6

Ethernet

ether://<MAC>

Examples:

  • ether://08:00:27:01:01:01
  • ether://33:33:01:01:01:01 (multicast)

Network Device

dev://<ifname>

Examples:

  • dev://eth0

Underlying protocol and FaceUri scheme

Underlying protocol remote FaceUri scheme local FaceUri scheme
IPv4 UDP unicast udp4 udp4
IPv6 UDP unicast udp6 udp6
IPv4 UDP multicast udp4 (multicast IP) udp4 (local IP, same port)
IPv4 TCP tcp4 tcp4
IPv6 TCP tcp6 tcp6
UNIX stream fd (file descriptor on NFD side) unix (socket path)
Ethernet multicast ether dev

Control Commands

ControlCommand management-module: faces

Create a face

command-verb: create

ControlParameters fields:

  • Uri (required): a UDP unicast or TCP FaceUri

This command allows creation of UDP unicast and TCP faces only.

If another face with same underlying protocol and remote address exists, the command is considered successful, and FaceId of that face is returned.

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

  • FaceId
  • Uri: FaceUri in canonical form - hostname is substituted with IP address, scheme name indicates either IPv4 or IPv6

Destroy a face

command-verb: destroy

ControlParameters fields:

  • FaceId (required)

If the specified face does not exist, this command does nothing, but is still considered successful.

Enable a LocalControlHeader feature

command-verb: enable-local-control

ControlParameters fields:

  • LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId

This command can only operate on the requesting face.

Disable a LocalControlHeader feature

command-verb: disable-local-control

ControlParameters fields:

  • LocalControlFeature (required): 1=IncomingFaceId, 2=NextHopFaceId

This command can only operate on the requesting face.

Face Dataset

Description and counters of all active faces are published as a Status Dataset at ndn:/localhost/nfd/faces/list.

Each face is represented by a FaceStatus block:

FaceStatus    ::= FACE-STATUS-TYPE TLV-LENGTH
                    FaceId
                    Uri (remote FaceUri)
                    LocalUri
                    ExpirationPeriod?
                    FaceFlags
                    NInInterests
                    NInDatas
                    NOutInterests
                    NOutDatas
                    NInBytes
                    NOutBytes

LocalUri      ::= LOCAL-URI-TYPE TLV-LENGTH
                    RFC3986 URI in UTF-8 encoding

FaceFlags     ::= FACE-FLAGS-TYPE TLV-LENGTH
                    nonNegativeInteger

NInInterests  ::= N-IN-INTERESTS-TYPE TLV-LENGTH
                    nonNegativeInteger

NInDatas      ::= N-IN-DATAS-TYPE TLV-LENGTH
                    nonNegativeInteger

NOutInterests ::= N-OUT-INTERESTS-TYPE TLV-LENGTH
                    nonNegativeInteger

NOutDatas     ::= N-OUT-DATAS-TYPE TLV-LENGTH
                    nonNegativeInteger

NInBytes      ::= N-IN-BYTES-TYPE TLV-LENGTH
                    nonNegativeInteger

NOutBytes     ::= N-OUT-BYTES-TYPE TLV-LENGTH
                    nonNegativeInteger
  • Uri is a FaceUri representing remote endpoint.
  • LocalUri is a FaceUri representing local endpoint.
  • ExpirationPeriod is the remaining lifetime of this face. If this field is omitted, the face has infinite lifetime. Currently, this is applicable to on-demand datagram faces only.
  • FaceFlags is a bitset providing additional information about the face. The following bits are currently defined:
    • 1: face is local
    • 2: face is on demand - accepted incoming connection, instead of initiated outgoing connection
  • NInInterests is the total number of incoming Interests since the face is established.
  • NInDatas is the total number of incoming Datas since the face is established.
  • NOutInterests is the total number of outgoing Interests since the face is established.
  • NOutDatas is the total number of outgoing Datas since the face is established.
  • NInBytes counts the number of bytes of link layer packets received via this face. This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.
  • NOutBytes counts the number of bytes of link layer packets sent via this face. This counter is initialized to zero when the face is established, and can wrap around after overflowing unsigned 64-bit integer range.

Query Operation

The query operation allows one to retrieve a subset of face dataset that contains faces satisfying a filter.

To run a query, the consumer should express an Interest with Name: ndn:/localhost/nfd/faces/query/<filter>, where <filter> is a FaceQueryFilter block that specifies zero or more conditions.

FaceQueryFilter ::= FACE-QUERY-FILTER-TYPE TLV-LENGTH
                      FaceId?
                      UriScheme?
                      Uri?
                      LocalUri?
                      IsMultiAccess?

UriScheme       ::= URI-SCHEME-TYPE TLV-LENGTH
                      string in UTF-8

IsMultiAccess   ::= IS-MULTI-ACCESS-TYPE TLV-LENGTH
                      (0x00 | 0x01)
  • FaceId permits a face if its FaceId equals the value
  • UriScheme permits a face if the scheme part of its local FaceUri or remote FaceUri equals the value
  • Uri permits a face if its remote FaceUri equals the value
  • LocalUri permits a face if its local FaceUri equals the value
  • IsMultiAccess permits a face if its isMultiAccess attribute equals the value

A face must satisfy ALL conditions to satisfy the filter.
Faces that satisfy the filter are represents by FaceStatus blocks, and published as a StatusDataset under the Interest Name (a Data packet's Name would be ndn:/localhost/nfd/faces/query/<filter>/<version>/<segment>).

Examples of filters:

  • a specific face: FaceId=260
  • a specific TCP tunnel: Uri=tcp4://192.0.2.1:6363
    note: FaceUri must precisely match what would appear in face dataset: use either "tcp4" or "tcp6" instead of "tcp", use IP address instead of DNS name, include port number
  • all TCP tunnels: UriScheme=tcp
    note: "tcp" permits both "tcp4" and "tcp6", "udp" permits both "udp4" and "udp6"
  • all UDP multicast faces: UriScheme=udp & IsMultiAccess=1
  • all Ethernet faces: UriScheme=ether note: UriScheme matches on both local and remote FaceUri, "dev" also works
  • all faces: no condition
    note: this is equivalent to face dataset, and face dataset should be preferred for this purpose

Channel Dataset

Description of all active channels is published as a Status Dataset at ndn:/localhost/nfd/faces/channels.

Each channel is represented by a ChannelStatus block:

ChannelStatus    := CHANNEL-STATUS-TYPE TLV-LENGTH
                      LocalUri
  • LocalUri is a FaceUri representing local endpoint.

Face Status Change Notification

Face status change events are published as a Notification Stream at ndn:/localhost/nfd/faces/events.
Notifications of all faces are sent into the same notification stream.

The Content of each notification Data packet is a FaceEventNotification block:

FaceEventNotification ::= FACE-EVENT-NOTIFICATION-TYPE TLV-LENGTH
                            FaceEventKind
                            FaceId
                            Uri
                            LocalUri
                            FaceFlags

FaceEventKind         ::= FACE-EVENT-KIND-TYPE TLV-LENGTH
                            nonNegativeInteger

FaceEventKind indicates the kind of event. Its possible values are:

  • 1: face is created
  • 2: face is destroyed

TLV-TYPE assignments

Type Assigned value Assigned value (hex)
FaceStatus 128 0x80
LocalUri 129 0x81
ChannelStatus 130 0x82
FaceFlags 194 0xc2
NInInterests 144 0x90
NInDatas 145 0x91
NOutInterests 146 0x92
NOutDatas 147 0x93
NInBytes 148 0x94
NOutBytes 149 0x95
UriScheme 131 0x83
IsMultiAccess 132 0x84
FaceEventNotification 192 0xc0
FaceEventKind 193 0xc1

Updated by Junxiao Shi almost 10 years ago · 37 revisions