docs/manpages/nfdc-face.rst

nfdc-face
=========

Synopsis
--------

| **nfdc face** [**list** [[**remote**] *FACEURI*] [**local** *FACEURI*] [**scheme** *SCHEME*]]
| **nfdc face** **show** [**id**] *FACEID*
| **nfdc face** **create** [**remote**] *FACEURI* [[**persistency**] *PERSISTENCY*] [**local** *FACEURI*]
|               [**mtu** *MTU*] [**reliability** **on**\|\ **off**] [**congestion-marking** **on**\|\ **off**]
|               [**congestion-marking-interval** *MARKING-INTERVAL*]
|               [**default-congestion-threshold** *CONGESTION-THRESHOLD*]
| **nfdc face** **destroy** [**face**] *FACEID*\|\ *FACEURI*
| **nfdc channel** [**list**]

Description
-----------

In NFD, a face is the generalization of network interface.
It could be a physical network interface to communicate on a physical link,
an overlay communication channel between NFD and a remote node,
or an inter-process communication channel between NFD and a local application.

The **nfdc face list** command shows a list of faces, their properties, and statistics,
optionally filtered by remote endpoint, local endpoint, and FaceUri scheme.
When multiple filters are specified, returned faces must satisfy all filters.

The **nfdc face show** command shows properties and statistics of one specific face.

The **nfdc face create** command creates a UDP unicast, TCP, or Ethernet unicast face.
If the face already exists, the specified arguments will be used to update its properties, if
possible.
Local FaceUri is required for creating Ethernet unicast faces; otherwise it must be omitted.
The NDNLPv2 unicast reliability feature may be explicitly enabled by specifying **reliability on**
or explicitly disabled by specifying **reliability off**.
If enabled, this feature must also be enabled on the other endpoint to function properly.
Reliability is disabled by default.
The send queue congestion detection and signaling feature may be explicitly enabled by specifying
**congestion-marking on** or explicitly disabled by specifying **congestion-marking off**.
Congestion marking is enabled by default on TCP, UDP, and Unix stream faces and is disabled by
default on all other face types.
Parameters for this feature can set with the **congestion-marking-interval** option (specified in
milliseconds) and the **default-congestion-threshold** option (specified in bytes).
The effective MTUs of unicast Ethernet and UDP faces may be overridden using the **mtu** parameter
(specified in bytes).
The forwarder may limit the range of this override MTU and will use the minimum of it and the MTU
of the underlying Ethernet or UDP transport.

The **nfdc face destroy** command destroys an existing face.

The **nfdc channel list** command shows a list of channels.
Channels are listening sockets that can accept incoming connections and create new faces.

Options
-------

.. option:: <FACEID>

    Numerical identifier of the face.
    It is displayed in the output of **nfdc face list** and **nfdc face create** commands.

.. option:: <FACEURI>

    A URI representing the remote or local endpoint of a face.
    Examples:

    - udp4://192.0.2.1:6363
    - udp6://[2001:db8::1]:6363
    - udp://example.net
    - tcp4://192.0.2.1:6363
    - tcp6://[2001:db8::1]:6363
    - tcp://example.net
    - unix:///run/nfd/nfd.sock
    - fd://6
    - ether://[08:00:27:01:01:01]
    - dev://eth0

    See the `FaceUri section <https://redmine.named-data.net/projects/nfd/wiki/FaceMgmt#FaceUri>`__
    of the NFD Face Management protocol for more details on the syntax.
    If a hostname is specified, :program:`nfdc` will perform a DNS resolution to obtain the
    corresponding IP address.

.. option:: <SCHEME>

    The scheme portion of either remote or local endpoint.
    Examples:

    - udp4
    - unix
    - dev

.. option:: <PERSISTENCY>

    Either "persistent" or "permanent".
    A "persistent" face (the default) is closed when a socket error occurs.
    A "permanent" face survives socket errors, and is closed only with a **nfdc destroy** command.

.. option:: <MTU>

    The MTU used to override the MTU of the underlying transport on Ethernet and UDP faces.
    This MTU serves as an upper bound for the MTU provided by the transport.
    The range of acceptable values may be limited by the forwarder.
    To unset this override, specify the MTU as "auto".

.. option:: <MARKING-INTERVAL>

    The initial marking interval (in milliseconds) during an incident of congestion.

.. option:: <CONGESTION-THRESHOLD>

    This value serves two purposes:
    It is the maximum bound of the congestion threshold for the face, as well as the default
    threshold used if the face does not support retrieving the capacity of the send queue.

Exit Status
-----------

0
    Success.

1
    An unspecified error occurred.

2
    Malformed command line.

3
    Face not found (**nfdc face show** and **nfdc face destroy** only).

4
    FaceUri canonization failed (**nfdc face create** and **nfdc face destroy** only).

5
    Ambiguous: multiple matching faces are found (**nfdc face destroy** only).

Examples
--------

``nfdc face list``
    List all faces.

``nfdc face list scheme udp4``
    List all UDP-over-IPv4 faces.

``nfdc face show id 300``
    Show information about the face whose FaceId is 300.

``nfdc face create remote udp://router.example.net``
    Create a face with the specified remote FaceUri, keeping all other settings at their defaults.

``nfdc face create remote ether://[08:00:27:01:01:01] local dev://eth2 persistency permanent``
    Create a face with the specified remote FaceUri, local FaceUri, and persistency.

``nfdc face create remote udp://router.example.net reliability on``
    Create a face with the specified remote FaceUri and enable NDNLP reliability.

``nfdc face create remote udp://router.example.net congestion-marking-interval 100 default-congestion-threshold 65536``
    Create a face with the specified remote FaceUri. Set the base congestion marking interval to
    100 ms and the default congestion threshold to 65536 bytes.

``nfdc face create remote udp://router.example.net congestion-marking off``
    Create a face with the specified remote FaceUri and explicitly disable congestion marking.

``nfdc face create remote udp://router.example.net mtu 4000``
    Create a face with the specified remote FaceUri and set the override MTU to 4000 bytes.

``nfdc face destroy 300``
    Destroy the face whose FaceId is 300.

``nfdc face destroy udp4://192.0.2.1:6363``
    Destroy the face whose remote FaceUri is "udp4://192.0.2.1:6363".

See Also
--------

:manpage:`nfdc(1)`