Gitiles
Code Review Sign In
gerrit.named-data.net / NFD / 15b5505e01488e75b5b85dfc866e494a2d6d3417 / . / docs / manpages / nfdc-face.rst
blob: 6fd87795c9c00e554a6733ce81adacf7dcc60109 [file] [log] [blame]
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]1nfdc-face
2=========
3
4SYNOPSIS
5--------
Junxiao Shi0d976922017-04-01 14:35:21 +0000[diff] [blame]6| nfdc face [list [[remote] <FACEURI>] [local <FACEURI>] [scheme <SCHEME>]]
Junxiao Shid6958012017-02-20 03:34:48 +0000[diff] [blame]7| nfdc face show [id] <FACEID>
Eric Newberry84d3adc2017-08-09 23:31:40 -0400[diff] [blame]8| nfdc face create [remote] <FACEURI> [[persistency] <PERSISTENCY>] [local <FACEURI>] [reliability on|off]
Junxiao Shid6958012017-02-20 03:34:48 +0000[diff] [blame]9| nfdc face destroy [face] <FACEID|FACEURI>
Junxiao Shi1d7fef52017-02-02 05:33:14 +0000[diff] [blame]10| nfdc channel [list]
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]11
12DESCRIPTION
13-----------
14In NFD, a face is the generalization of network interface.
15It could be a physical network interface to communicate on a physical link,
16an overlay communication channel between NFD and a remote node,
17or an inter-process communication channel between NFD and a local application.
18
Junxiao Shi0d976922017-04-01 14:35:21 +0000[diff] [blame]19The **nfdc face list** command shows a list of faces, their properties, and statistics,
20optionally filtered by remote endpoint, local endpoint, and FaceUri scheme.
21When multiple filters are specified, returned faces must satisfy all filters.
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]22
Junxiao Shi1f481fa2017-01-26 15:14:43 +0000[diff] [blame]23The **nfdc face show** command shows properties and statistics of one specific face.
24
Junxiao Shi0d976922017-04-01 14:35:21 +0000[diff] [blame]25The **nfdc face create** command creates a UDP unicast, TCP, or Ethernet unicast face.
26Local FaceUri is required for creating Ethernet unicast faces; otherwise it must be omitted.
Eric Newberry84d3adc2017-08-09 23:31:40 -0400[diff] [blame]27The NDNLPv2 unicast reliability feature may be explicitly enabled by specifying **reliability on**
28or explicitly disabled by specifying **reliability off**.
29If enabled, this feature must also be enabled on the other endpoint to function properly.
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]30
Junxiao Shi05dd4442017-02-06 22:50:07 +0000[diff] [blame]31The **nfdc face destroy** command destroys an existing face.
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]32
Junxiao Shi1d7fef52017-02-02 05:33:14 +0000[diff] [blame]33The **nfdc channel list** command shows a list of channels.
34Channels are listening sockets that can accept incoming connections and create new faces.
35
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]36OPTIONS
37-------
Junxiao Shif0dfb332017-02-02 05:32:25 +0000[diff] [blame]38<FACEID>
Junxiao Shi1f481fa2017-01-26 15:14:43 +0000[diff] [blame]39 Numerical identifier of the face.
Junxiao Shi1d7fef52017-02-02 05:33:14 +0000[diff] [blame]40 It is displayed in the output of **nfdc face list** and **nfdc face create** commands.
Junxiao Shi1f481fa2017-01-26 15:14:43 +0000[diff] [blame]41
Junxiao Shif0dfb332017-02-02 05:32:25 +0000[diff] [blame]42<FACEURI>
Junxiao Shi0d976922017-04-01 14:35:21 +0000[diff] [blame]43 A URI representing the remote or local endpoint of a face.
44 Examples:
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]45
Junxiao Shi0d976922017-04-01 14:35:21 +0000[diff] [blame]46 - udp4://192.0.2.1:6363
47 - udp6://[2001:db8::1]:6363
48 - udp://example.net
49 - tcp4://192.0.2.1:6363
50 - tcp6://[2001:db8::1]:6363
51 - tcp://example.net
52 - unix:///var/run/nfd.sock
53 - fd://6
54 - ether://[08:00:27:01:01:01]
55 - dev://eth0
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]56
57 When a hostname is specified, a DNS query is used to obtain the IP address.
58
Junxiao Shi0d976922017-04-01 14:35:21 +0000[diff] [blame]59<SCHEME>
60 The scheme portion of either remote or local endpoint.
61 Examples:
62
63 - udp4
64 - unix
65 - dev
66
Junxiao Shi1d7fef52017-02-02 05:33:14 +0000[diff] [blame]67<PERSISTENCY>
68 Either "persistent" or "permanent".
69 A "persistent" face (the default) is closed when a socket error occurs.
70 A "permanent" face survives socket errors, and is closed only with a **nfdc destroy** command.
71
Junxiao Shi1f481fa2017-01-26 15:14:43 +0000[diff] [blame]72EXIT CODES
73----------
Junxiao Shi1f481fa2017-01-26 15:14:43 +0000[diff] [blame]740: Success
75
761: An unspecified error occurred
77
782: Malformed command line
79
Junxiao Shi05dd4442017-02-06 22:50:07 +0000[diff] [blame]803: Face not found (**nfdc face show** and **nfdc face destroy** only)
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]81
Junxiao Shi05dd4442017-02-06 22:50:07 +0000[diff] [blame]824: FaceUri canonization failed (**nfdc face create** and **nfdc face destroy** only)
83
845: Ambiguous: multiple matching faces are found (**nfdc face destroy** only)
Junxiao Shi1d7fef52017-02-02 05:33:14 +0000[diff] [blame]85
Junxiao Shi0e13e1e2018-01-22 08:29:12 +0000[diff] [blame]86EXAMPLES
87--------
88nfdc face list
89 List all faces.
90
91nfdc face list scheme udp4
92 List all UDP-over-IPv4 faces.
93
94nfdc face show id 300
95 Show information about the face whose FaceId is 300.
96
97nfdc face create remote udp://router.example.net
98 Create a face with the specified remote FaceUri, keeping all other settings at their defaults.
99
100nfdc face create remote ether://[08:00:27:01:01:01] local dev://eth2 persistency permanent
101 Create a face with the specified remote FaceUri, local FaceUri, and persistency.
102
103nfdc face create remote udp://router.example.net reliability on
104 Create a face with the specified remote FaceUri and enable NDNLP reliability.
105
106nfdc face destroy 300
107 Destroy the face whose FaceId is 300.
108
109nfdc face destroy udp4://192.0.2.1:6363
110 Destroy the face whose remote FaceUri is "udp4://192.0.2.1:6363".
111
Junxiao Shi6c135622016-11-21 14:30:33 +0000[diff] [blame]112SEE ALSO
113--------
114nfd(1), nfdc(1)