From 543b1524ec0de506fc94b145de19b3dcdd0d950a Mon Sep 17 00:00:00 2001 From: Davide Pesavento Date: Tue, 25 Jun 2024 17:00:32 -0400 Subject: [PATCH] docs: reformat man pages to improve consistency and readability Change-Id: I4f9afbc73c365dfa31eb6cd1e4a48368b6a9064f --- docs/conf.py | 20 ++-- docs/manpages.rst | 2 +- docs/manpages/ndn-autoconfig-server.rst | 18 ++-- docs/manpages/ndn-autoconfig.rst | 19 ++-- docs/manpages/nfd-asf-strategy.rst | 20 ++-- docs/manpages/nfd-autoreg.rst | 78 ++++++++------- docs/manpages/nfd-status-http-server.rst | 50 ++++++---- docs/manpages/nfd-status.rst | 16 ++-- docs/manpages/nfd.rst | 50 ++++++---- docs/manpages/nfdc-cs.rst | 35 ++++--- docs/manpages/nfdc-face.rst | 115 ++++++++++++++--------- docs/manpages/nfdc-route.rst | 110 +++++++++++++--------- docs/manpages/nfdc-status.rst | 25 +++-- docs/manpages/nfdc-strategy.rst | 75 +++++++++------ docs/manpages/nfdc.rst | 84 ++++++++++------- docs/releases.rst | 4 +- 16 files changed, 433 insertions(+), 288 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 83b4c5275..d1dd21149 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,22 +75,24 @@ def addExtensionIfExists(extension: str): # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('manpages/nfd', 'nfd', 'the Named Data Networking Forwarding Daemon', [], 1), - ('manpages/nfdc', 'nfdc', 'interact with NFD management from the command line', [], 1), - ('manpages/nfdc-status', 'nfdc-status', 'show NFD status', [], 1), + ('manpages/nfd', 'nfd', 'Named Data Networking Forwarding Daemon', [], 1), + ('manpages/nfdc', 'nfdc', 'manage a running NFD from the command line', [], 1), + ('manpages/nfdc-status', 'nfdc-status', 'show NFD\'s status', [], 1), ('manpages/nfdc-face', 'nfdc-face', 'show and manipulate NFD\'s faces', [], 1), ('manpages/nfdc-route', 'nfdc-route', 'show and manipulate NFD\'s routes', [], 1), ('manpages/nfdc-cs', 'nfdc-cs', 'show and manipulate NFD\'s Content Store', [], 1), ('manpages/nfdc-strategy', 'nfdc-strategy', 'show and manipulate NFD\'s strategy choices', [], 1), ('manpages/nfd-status', 'nfd-status', 'show a comprehensive report of NFD\'s status', [], 1), - ('manpages/nfd-status-http-server', 'nfd-status-http-server', 'NFD status HTTP server', [], 1), - ('manpages/ndn-autoconfig-server', 'ndn-autoconfig-server', 'auto-configuration server for NDN', [], 1), - ('manpages/ndn-autoconfig', 'ndn-autoconfig', 'auto-configuration client for NDN', [], 1), - ('manpages/ndn-autoconfig.conf', 'ndn-autoconfig.conf', 'configuration file for ndn-autoconfig', [], 5), - ('manpages/nfd-autoreg', 'nfd-autoreg', 'NFD automatic prefix registration daemon', [], 1), - ('manpages/nfd-asf-strategy', 'nfd-asf-strategy', 'NFD ASF strategy', [], 7), + ('manpages/nfd-status-http-server', 'nfd-status-http-server', 'NFD status HTTP server', [], 1), + ('manpages/nfd-autoreg', 'nfd-autoreg', 'NFD automatic prefix registration daemon', [], 1), + ('manpages/ndn-autoconfig', 'ndn-autoconfig', 'auto-configuration client for NDN', [], 1), + ('manpages/ndn-autoconfig-server', 'ndn-autoconfig-server', 'auto-configuration server for NDN', [], 1), + ('manpages/ndn-autoconfig.conf', 'ndn-autoconfig.conf', 'configuration file for ndn-autoconfig', [], 5), + ('manpages/nfd-asf-strategy', 'nfd-asf-strategy', 'NFD ASF strategy', [], 7), ] +man_show_urls = True + # -- Misc options ------------------------------------------------------------ diff --git a/docs/manpages.rst b/docs/manpages.rst index 3804626ae..d09732378 100644 --- a/docs/manpages.rst +++ b/docs/manpages.rst @@ -15,8 +15,8 @@ Man pages manpages/nfd-status manpages/nfd-status-http-server schema + manpages/nfd-autoreg manpages/ndn-autoconfig manpages/ndn-autoconfig.conf manpages/ndn-autoconfig-server local-prefix-discovery - manpages/nfd-autoreg diff --git a/docs/manpages/ndn-autoconfig-server.rst b/docs/manpages/ndn-autoconfig-server.rst index 369252e50..a5b6bff7a 100644 --- a/docs/manpages/ndn-autoconfig-server.rst +++ b/docs/manpages/ndn-autoconfig-server.rst @@ -34,16 +34,20 @@ this block is the ``Uri`` for the HUB, preferably a UDP tunnel. ``-V`` Print version number and exit. -Exit status +Exit Status ----------- -0: No error. +0 + No error. -1: An unspecified error occurred. +1 + An unspecified error occurred. -2: Malformed command line, e.g., invalid, missing, or unknown argument. +2 + Malformed command line, e.g., invalid, missing, or unknown argument. -4: Insufficient privileges. +4 + Insufficient privileges. Examples -------- @@ -54,7 +58,7 @@ Examples ndn-autoconfig-server -p /ndn/edu/ucla tcp://spurs.cs.ucla.edu -See also +See Also -------- -:ref:`ndn-autoconfig` +:manpage:`ndn-autoconfig(1)` diff --git a/docs/manpages/ndn-autoconfig.rst b/docs/manpages/ndn-autoconfig.rst index c455bb996..c1294b6db 100644 --- a/docs/manpages/ndn-autoconfig.rst +++ b/docs/manpages/ndn-autoconfig.rst @@ -172,18 +172,23 @@ Send a DNS query to find home hub. If this query is answered, connect to the home hub and terminate auto-discovery. Otherwise, the auto-discovery fails. -Exit status +Exit Status ----------- -0: No error. +0 + No error. -1: An unspecified error occurred. +1 + An unspecified error occurred. -2: Malformed command line, e.g., invalid, missing, or unknown argument. +2 + Malformed command line, e.g., invalid, missing, or unknown argument. -4: Insufficient privileges. +4 + Insufficient privileges. -See also +See Also -------- -:ref:`ndn-autoconfig-server`, :doc:`ndn-autoconfig.conf` +:manpage:`ndn-autoconfig-server(1)`, +:doc:`ndn-autoconfig.conf` diff --git a/docs/manpages/nfd-asf-strategy.rst b/docs/manpages/nfd-asf-strategy.rst index 08471440a..45339b85c 100644 --- a/docs/manpages/nfd-asf-strategy.rst +++ b/docs/manpages/nfd-asf-strategy.rst @@ -5,7 +5,7 @@ Synopsis -------- **nfdc strategy set** **prefix** *NAME* **strategy** -/localhost/nfd/strategy/asf[/v=4][/**probing-interval**\ ~\ *INTERVAL*][/**max-timeouts**\ ~\ *TIMEOUTS*] +/localhost/nfd/strategy/asf[/v=5][/**probing-interval**\ ~\ *INTERVAL*][/**max-timeouts**\ ~\ *TIMEOUTS*] Description ----------- @@ -17,14 +17,14 @@ next hops to learn their RTTs. Options ------- -.. option:: probing-interval +.. option:: probing-interval This optional parameter tells ASF how often to send a probe to determine alternative paths. The value is specified in milliseconds (non-negative integer). Smaller values will result in higher overhead but faster reaction. The default value is 1 minute and the minimum value is 1 second. -.. option:: max-timeouts +.. option:: max-timeouts This optional parameter makes ASF switch to another appropriate face (if available) after it has encountered the specified number of timeouts. The value is a positive @@ -36,24 +36,24 @@ Options Examples -------- -nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf +``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf`` Use the default values for all parameters. -nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=4/probing-interval~30000 +``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=5/probing-interval~30000`` Set the probing interval to 30 seconds. -nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=4/max-timeouts~5 +``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=5/max-timeouts~5`` Set the maximum number of timeouts to 5. -nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=4/probing-interval~30000/max-timeouts~2 +``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=5/probing-interval~30000/max-timeouts~2`` Set the probing interval to 30 seconds and the maximum number of timeouts to 2. -nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=4/retx-suppression-multiplier~2.5/probing-interval~45000 +``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=5/retx-suppression-multiplier~2.5/probing-interval~45000`` Set the retransmission suppression multiplier to 2.5 and the probing interval to 45 seconds. See :manpage:`nfdc-strategy(1)` for more information on the retransmission suppression parameters. -See also +See Also -------- -nfdc(1), nfdc-strategy(1) +:manpage:`nfdc-strategy(1)` diff --git a/docs/manpages/nfd-autoreg.rst b/docs/manpages/nfd-autoreg.rst index 3ce898aa5..58390d678 100644 --- a/docs/manpages/nfd-autoreg.rst +++ b/docs/manpages/nfd-autoreg.rst @@ -4,12 +4,16 @@ nfd-autoreg Synopsis -------- -**nfd-autoreg** --prefix= [--prefix=]... +| **nfd-autoreg** [**-i**\|\ **\--prefix** *prefix*]... [**-a**\|\ **\--all-faces-prefix** *prefix*]... +| [**-b**\|\ **\--blacklist** *network*]... [**-w**\|\ **\--whitelist** *network*]... \ + [**-c**\|\ **\--cost** *cost*] +| **nfd-autoreg** **-h**\|\ **\--help** +| **nfd-autoreg** **-V**\|\ **\--version** Description ----------- -``nfd-autoreg`` is a daemon application that automatically registers the specified +:program:`nfd-autoreg` is a daemon application that automatically registers the specified prefix(es) when new on-demand faces are created (i.e., when a new UDP face is created as the result of an incoming packet or when a new TCP face is created as the result of an incoming connection). @@ -17,53 +21,61 @@ incoming connection). Options ------- -``-i`` or ``--prefix`` - Prefix that should be automatically registered when a new remote face is created. - Can be repeated multiple times to specify additional prefixes. +.. option:: -i , --prefix -``-c`` or ``--cost`` - RIB cost to be assigned to auto-registered prefixes. If not specified, default cost - is set to 255. + Prefix that should be automatically registered when a new remote face is created. + Can be repeated multiple times to specify additional prefixes. -``-w`` or ``--whitelist`` - Whitelisted network, e.g., 192.168.2.0/24 or ::1/128. Can be repeated multiple times - to specify multiple whitelisted networks. +.. option:: -b , --blacklist - Prefix(es) will be auto-registered only when remote IP address is within the specified - range(s), except blacklist ranges. + Blacklisted network, e.g., 192.168.2.32/30 or ::1/128. Can be repeated multiple times + to specify multiple blacklisted networks. - Default: 0.0.0.0/0 and ::/0 + The prefixes will be auto-registered only when the remote IP address is NOT inside the + specified range(s), but is inside the range defined by the whitelist(s), if any. -``-b`` or ``--blacklist`` - Blacklisted network, e.g., 192.168.2.32/30 or ::1/128. Can be repeated multiple times - to specify multiple blacklisted networks. + Default: none. - Prefix(es) will be auto-registered only when remote IP address in **NOT** within the - specified range(s), but is within the range define by the whitelist(s). +.. option:: -w , --whitelist - Default: none + Whitelisted network, e.g., 192.168.2.0/24 or ::1/128. Can be repeated multiple times + to specify multiple whitelisted networks. -``-h`` or ``--help`` - Print help message and exit. + The prefixes will be auto-registered only when the remote IP address is inside the + specified range(s), excluding any blacklisted range(s). -``-V`` or ``--version`` - Show version information and exit. + Default: 0.0.0.0/0 and ::/0. -Exit status +.. option:: -c , --cost + + RIB cost to assign to auto-registered prefixes. If not specified, the cost is set to 255. + +.. option:: -h, --help + + Print help message and exit. + +.. option:: -V, --version + + Show version information and exit. + +Exit Status ----------- -0: No error. +0 + No error. -1: An unspecified error occurred. +1 + An unspecified error occurred. -2: Malformed command line, e.g., invalid, missing, or unknown argument. +2 + Malformed command line, e.g., invalid, missing, or unknown argument. -4: Insufficient privileges. +4 + Insufficient privileges. Examples -------- -Auto-register two prefixes for any newly created on-demand face, except those that has -source IP address in ``10.0.0.0/8`` network:: - - nfd-autoreg --prefix=/app1/video --prefix=/app2/pictures -b 10.0.0.0/8 +``nfd-autoreg -i /app1/video -i /app2/pictures -b 10.0.0.0/8`` + Auto-register two prefixes for any newly created on-demand faces, except those that + have their remote IP address in the 10.0.0.0/8 network. diff --git a/docs/manpages/nfd-status-http-server.rst b/docs/manpages/nfd-status-http-server.rst index 5dc4b0c95..c7ee6f6ec 100644 --- a/docs/manpages/nfd-status-http-server.rst +++ b/docs/manpages/nfd-status-http-server.rst @@ -4,38 +4,52 @@ nfd-status-http-server Synopsis -------- -**nfd-status-http-server** [**-h**] [**-a** *IPADDR*] [**-p** *PORT*] [**-r**] [**-v**] +| **nfd-status-http-server** [**-a**\|\ **\--address** *address*] [**-p**\|\ **\--port** *port*] \ + [**-f**\|\ **\--workdir** *dir*] [**-r**\|\ **\--robots**] [**-v**\|\ **\--verbose**] +| **nfd-status-http-server** **-h**\|\ **\--help** +| **nfd-status-http-server** **-V**\|\ **\--version** Description ----------- -``nfd-status-http-server`` is a daemon that enables the retrieval of NFD's status over HTTP. +:program:`nfd-status-http-server` is a daemon that enables the retrieval of NFD's status over HTTP. Options ------- -``-h`` - Show help message and exit. +.. option:: -a
, --address
-``-a `` - HTTP server IP address (default is 127.0.0.1). + HTTP server IP address (default is 127.0.0.1). -``-p `` - HTTP server port number (default is 6380). +.. option:: -p , --port -``-r`` - Enable HTTP robots to crawl (disabled by default). + HTTP server port number (default is 6380). -``-v`` - Verbose mode. +.. option:: -f , --workdir -Examples --------- + Set the server's working directory. + +.. option:: -r, --robots + + Enable HTTP robots to crawl (disabled by default). + +.. option:: -v, --verbose + + Enable verbose mode. -Start NFD's HTTP status server on all IPv4 interfaces, port 80 (requires root):: +.. option:: -h, --help - nfd-status-http-server -a 0.0.0.0 -p 80 + Print help message and exit. + +.. option:: -V, --version + + Show version information and exit. + +Examples +-------- -Start NFD's HTTP status server on all IPv6 interfaces, port 8000:: +``nfd-status-http-server -a 0.0.0.0 -p 80`` + Start NFD's HTTP status server on all IPv4 interfaces, port 80 (requires privileges). - nfd-status-http-server -a :: -p 8000 +``nfd-status-http-server -a :: -p 8000`` + Start NFD's HTTP status server on all IPv6 interfaces, port 8000. diff --git a/docs/manpages/nfd-status.rst b/docs/manpages/nfd-status.rst index f140483c1..b056465a5 100644 --- a/docs/manpages/nfd-status.rst +++ b/docs/manpages/nfd-status.rst @@ -1,14 +1,18 @@ nfd-status ========== -SYNOPSIS +Synopsis -------- -| nfd-status -DESCRIPTION +**nfd-status** + +Description ----------- -**nfd-status** is an alias of **nfdc status report**, which prints a comprehensive report of NFD status. -SEE ALSO +:program:`nfd-status` is an alias of **nfdc status report**, +which prints a comprehensive report of NFD status. + +See Also -------- -nfdc-status(1) + +:manpage:`nfdc-status(1)` diff --git a/docs/manpages/nfd.rst b/docs/manpages/nfd.rst index a3ed42bf1..57db00ce9 100644 --- a/docs/manpages/nfd.rst +++ b/docs/manpages/nfd.rst @@ -4,45 +4,57 @@ nfd Synopsis -------- -**nfd** [**-h**] [**-V**] [**-c** *file*] [**-m**] +| **nfd** [**-c**\|\ **\--config** *file*] +| **nfd** **-h**\|\ **\--help** +| **nfd** **-m**\|\ **\--modules** +| **nfd** **-V**\|\ **\--version** Description ----------- -NFD forwarding daemon. +NFD is a network forwarder that implements the Named Data Networking (NDN) protocol. Options ------- -``-c `` or ``--config `` - Specify the path to nfd configuration file (default: ``${SYSCONFDIR}/ndn/nfd.conf``). +.. option:: -c , --config -``-m`` or ``--modules`` - List available logging modules. + Specify the path to NFD's configuration file. -``-h`` or ``--help`` - Print help message and exit. +.. option:: -h, --help -``-V`` or ``--version`` - Show version information and exit. + Print help message and exit. -Exit status +.. option:: -m, --modules + + List available logging modules. + +.. option:: -V, --version + + Show version information and exit. + +Exit Status ----------- -0: No error. +0 + No error. -1: An unspecified error occurred. +1 + An unspecified error occurred. -2: Malformed command line, e.g., invalid, missing, or unknown argument. +2 + Malformed command line, e.g., invalid, missing, or unknown argument. -4: Insufficient privileges. +4 + Insufficient privileges. Examples -------- -Start NFD forwarding daemon as super user and use a configuration file from the current -working directory. +``sudo nfd --config nfd.conf`` + Start NFD as super user with a configuration file from the current directory. -:: +See Also +-------- - sudo nfd --config nfd.conf +:manpage:`nfdc(1)` diff --git a/docs/manpages/nfdc-cs.rst b/docs/manpages/nfdc-cs.rst index 831dd7d88..c231a7c76 100644 --- a/docs/manpages/nfdc-cs.rst +++ b/docs/manpages/nfdc-cs.rst @@ -1,40 +1,49 @@ nfdc-cs ======= -SYNOPSIS +Synopsis -------- -| nfdc cs [info] -| nfdc cs config [capacity ] [admit on|off] [serve on|off] -| nfdc cs erase [count ] -DESCRIPTION +| **nfdc cs** [**info**] +| **nfdc cs** **config** [**capacity** *CAPACITY*] [**admit** **on**\|\ **off**] [**serve** **on**\|\ **off**] +| **nfdc cs** **erase** *PREFIX* [**count** *COUNT*] + +Description ----------- + The **nfdc cs info** command shows CS statistics information. The **nfdc cs config** command updates CS configuration. The **nfdc cs erase** command erases cached Data under a name prefix. -OPTIONS +Options ------- - + +.. option:: + Maximum number of Data packets the CS can store. Lowering the capacity causes the CS to evict excess Data packets. -admit on|off +.. option:: admit on|off + Whether the CS can admit new Data. -serve on|off +.. option:: serve on|off + Whether the CS can satisfy incoming Interests using cached Data. Turning this off causes all CS lookups to miss. - +.. option:: + Name prefix of cached Data packets. - +.. option:: + Maximum number of cached Data packets to erase. The default is "no limit". -SEE ALSO +See Also -------- -nfd(1), nfdc(1) + +:manpage:`nfdc(1)` diff --git a/docs/manpages/nfdc-face.rst b/docs/manpages/nfdc-face.rst index 410b814ce..d9022afad 100644 --- a/docs/manpages/nfdc-face.rst +++ b/docs/manpages/nfdc-face.rst @@ -1,20 +1,21 @@ nfdc-face ========= -SYNOPSIS +Synopsis -------- -| nfdc face [list [[remote] ] [local ] [scheme ]] -| nfdc face show [id] -| nfdc face create [remote] [[persistency] ] [local ] -| [reliability on|off] [congestion-marking on|off] -| [congestion-marking-interval ] -| [default-congestion-threshold ] -| [mtu ] -| nfdc face destroy [face] -| nfdc channel [list] - -DESCRIPTION + +| **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, @@ -50,13 +51,16 @@ 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 +Options ------- - + +.. option:: + Numerical identifier of the face. It is displayed in the output of **nfdc face list** and **nfdc face create** commands. - +.. option:: + A URI representing the remote or local endpoint of a face. Examples: @@ -71,9 +75,13 @@ OPTIONS - ether://[08:00:27:01:01:01] - dev://eth0 - When a hostname is specified, a DNS query is used to obtain the IP address. + See the `FaceUri section `__ + 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:: - The scheme portion of either remote or local endpoint. Examples: @@ -81,75 +89,88 @@ OPTIONS - unix - dev - +.. option:: + 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:: + + 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:: + The initial marking interval (in milliseconds) during an incident of congestion. - +.. option:: + 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. - - 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". +Exit Status +----------- -EXIT CODES ----------- -0: Success +0 + Success. -1: An unspecified error occurred +1 + An unspecified error occurred. -2: Malformed command line +2 + Malformed command line. -3: Face not found (**nfdc face show** and **nfdc face destroy** only) +3 + Face not found (**nfdc face show** and **nfdc face destroy** only). -4: FaceUri canonization failed (**nfdc face create** 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) +5 + Ambiguous: multiple matching faces are found (**nfdc face destroy** only). -EXAMPLES +Examples -------- -nfdc face list + +``nfdc face list`` List all faces. -nfdc face list scheme udp4 +``nfdc face list scheme udp4`` List all UDP-over-IPv4 faces. -nfdc face show id 300 +``nfdc face show id 300`` Show information about the face whose FaceId is 300. -nfdc face create remote udp://router.example.net +``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 +``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 +``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 +``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 +``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 +``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 +``nfdc face destroy 300`` Destroy the face whose FaceId is 300. -nfdc face destroy udp4://192.0.2.1:6363 +``nfdc face destroy udp4://192.0.2.1:6363`` Destroy the face whose remote FaceUri is "udp4://192.0.2.1:6363". -SEE ALSO +See Also -------- -nfd(1), nfdc(1) + +:manpage:`nfdc(1)` diff --git a/docs/manpages/nfdc-route.rst b/docs/manpages/nfdc-route.rst index 8c7cffa1c..5a4982daf 100644 --- a/docs/manpages/nfdc-route.rst +++ b/docs/manpages/nfdc-route.rst @@ -1,20 +1,22 @@ nfdc-route ========== -SYNOPSIS +Synopsis -------- -| nfdc route [list [[nexthop] ] [origin ]] -| nfdc route show [prefix] -| nfdc route add [prefix] [nexthop] [origin ] -| [cost ] [no-inherit] [capture] [expires ] -| nfdc route remove [prefix] [nexthop] [origin ] -| nfdc fib [list] - -DESCRIPTION + +| **nfdc route** [**list** [[**nexthop**] *FACEID*\|\ *FACEURI*] [**origin** *ORIGIN*]] +| **nfdc route** **show** [**prefix**] *PREFIX* +| **nfdc route** **add** [**prefix**] *PREFIX* [**nexthop**] *FACEID*\|\ *FACEURI* [**origin** *ORIGIN*] \ + [**cost** *COST*] [**no-inherit**] [**capture**] [**expires** *EXPIRATION*] +| **nfdc route** **remove** [**prefix**] *PREFIX* [**nexthop**] *FACEID*\|\ *FACEURI* [**origin** *ORIGIN*] +| **nfdc fib** [**list**] + +Description ----------- + In NFD, the routing information base (RIB) stores static or dynamic routing information registered by applications, operators, and NFD itself. -Each *route* in the RIB indicates that contents under a name prefix may be available via a nexthop. +Each route in the RIB indicates that contents under a name prefix may be available via a nexthop. A route contains a name prefix, a nexthop face, the origin, a cost, and a set of route inheritance flags; refer to NFD Management protocol for more information. @@ -26,86 +28,108 @@ The **nfdc route add** command requests to add a route. If a route with the same prefix, nexthop, and origin already exists, it is updated with the specified cost, route inheritance flags, and expiration period. This command returns when the request has been accepted, but does not wait for RIB update completion. -If no face matching the specified URI is found, nfdc will attempt to implicitly create a face with -this URI before adding the route. +If no face matching the specified URI is found, :program:`nfdc` will attempt to implicitly create a face +with this URI before adding the route. The **nfdc route remove** command removes a route with matching prefix, nexthop, and origin. The **nfdc fib list** command shows the forwarding information base (FIB), which is calculated from RIB routes and used directly by NFD forwarding. -OPTIONS +Options ------- - + +.. option:: + Name prefix of the route. - +.. option:: + Numerical identifier of the face. It is displayed in the output of **nfdc face list** and **nfdc face create** commands. - +.. option:: + An URI representing the remote endpoint of a face. In **nfdc route add** command, it must uniquely match an existing face. In **nfdc route remove** command, it must match one or more existing faces. - - Origin of the route, i.e. who is announcing the route. + See the `FaceUri section `__ + of the NFD Face Management protocol for more details on the syntax. + +.. option:: + + Origin of the route, i.e., who is announcing the route. The default is 255, indicating a static route. - +.. option:: + The administrative cost of the route. The default is 0. -no-inherit - Unset CHILD_INHERIT flag in the route. +.. option:: no-inherit + + Unset ``CHILD_INHERIT`` flag in the route. + +.. option:: capture + + Set ``CAPTURE`` flag in the route. -capture - Set CAPTURE flag in the route. +.. option:: - Expiration time of the route, in milliseconds. When the route expires, NFD removes it from the RIB. The default is infinite, which keeps the route active until the nexthop face is destroyed. -EXIT CODES ----------- -0: Success +Exit Status +----------- + +0 + Success. -1: An unspecified error occurred +1 + An unspecified error occurred. -2: Malformed command line +2 + Malformed command line. -3: Face not found +3 + Face not found. -4: FaceUri canonization failed +4 + FaceUri canonization failed. -5: Ambiguous: multiple matching faces are found (**nfdc route add** only) +5 + Ambiguous: multiple matching faces are found (**nfdc route add** only). -6: Route not found (**nfdc route list** and **nfdc route show** only) +6 + Route not found (**nfdc route list** and **nfdc route show** only). -EXAMPLES +Examples -------- -nfdc route list + +``nfdc route list`` List all routes. -nfdc route list nexthop 300 +``nfdc route list nexthop 300`` List routes whose nexthop is face 300. -nfdc route list origin static +``nfdc route list origin static`` List static routes. -nfdc route show prefix /localhost/nfd +``nfdc route show prefix /localhost/nfd`` List routes with name prefix "/localhost/nfd". -nfdc route add prefix /ndn nexthop 300 cost 100 +``nfdc route add prefix /ndn nexthop 300 cost 100`` Add a route with prefix "/ndn" toward face 300, with administrative cost 100. -nfdc route add prefix / nexthop udp://router.example.net +``nfdc route add prefix / nexthop udp://router.example.net`` Add a route with prefix "/" toward a face with the specified remote FaceUri. -nfdc route remove prefix /ndn nexthop 300 origin static +``nfdc route remove prefix /ndn nexthop 300 origin static`` Remove the route whose prefix is "/ndn", nexthop is face 300, and origin is "static". -SEE ALSO +See Also -------- -nfd(1), nfdc(1) + +:manpage:`nfdc(1)` diff --git a/docs/manpages/nfdc-status.rst b/docs/manpages/nfdc-status.rst index 3a1959b84..5b26ce335 100644 --- a/docs/manpages/nfdc-status.rst +++ b/docs/manpages/nfdc-status.rst @@ -1,13 +1,15 @@ nfdc-status =========== -SYNOPSIS +Synopsis -------- -| nfdc status [show] -| nfdc status report [] -DESCRIPTION +| **nfdc status** [**show**] +| **nfdc status** **report** [*FORMAT*] + +Description ----------- + The **nfdc status show** command shows general status of NFD, including its version, uptime, data structure counters, and global packet counters. @@ -21,12 +23,19 @@ The **nfdc status report** command prints a comprehensive report of NFD status, - CS statistics information (individually available from **nfdc cs info**) - list of strategy choices (individually available from **nfdc strategy list**) -OPTIONS +Options ------- - + +.. option:: + The format of NFD status report, either ``text`` or ``xml``. The default is ``text``. -SEE ALSO +See Also -------- -nfdc(1), nfdc-channel(1), nfdc-face(1), nfdc-fib(1), nfdc-route(1), nfdc-strategy(1) + +:manpage:`nfdc(1)`, +:manpage:`nfdc-cs(1)`, +:manpage:`nfdc-face(1)`, +:manpage:`nfdc-route(1)`, +:manpage:`nfdc-strategy(1)` diff --git a/docs/manpages/nfdc-strategy.rst b/docs/manpages/nfdc-strategy.rst index 93b0d4509..e028df535 100644 --- a/docs/manpages/nfdc-strategy.rst +++ b/docs/manpages/nfdc-strategy.rst @@ -1,15 +1,17 @@ nfdc-strategy ============= -SYNOPSIS +Synopsis -------- -| nfdc strategy [list] -| nfdc strategy show [prefix] -| nfdc strategy set [prefix] [strategy] -| nfdc strategy unset [prefix] -DESCRIPTION +| **nfdc strategy** [**list**] +| **nfdc strategy** **show** [**prefix**] *PREFIX* +| **nfdc strategy** **set** [**prefix**] *PREFIX* [**strategy**] *STRATEGY* +| **nfdc strategy** **unset** [**prefix**] *PREFIX* + +Description ----------- + In NFD, packet forwarding behavior is determined by forwarding pipelines and forwarding strategies. The forwarding pipelines define general steps of packet processing. Forwarding strategies provide the intelligence to make decision on whether, when, and where @@ -23,79 +25,90 @@ The **nfdc strategy list** command shows a list of strategy choices. The **nfdc strategy show** command shows the effective strategy choice for a specific name. The **nfdc strategy set** command sets the strategy for a name prefix. -The strategy for ``"/"`` prefix is the default strategy. +The strategy for the ``"/"`` prefix is the default strategy. The **nfdc strategy unset** command clears the strategy choice at a name prefix, so that a strategy choice at a shorter prefix or the default strategy will be used. It undoes a prior **nfdc strategy set** command on the same name prefix. -It is prohibited to unset the strategy choice for ``"/"`` prefix because there must always be a -default strategy. +It is prohibited to unset the strategy choice for the ``"/"`` prefix because there must always be +a default strategy. -OPTIONS +Options ------- - + +.. option:: + The name prefix of a strategy choice. The strategy choice is effective for all Interests under the name prefix, unless overridden by another strategy choice at a longer prefix. - +.. option:: + A name that identifies the forwarding strategy. - Consult NFD Developer's Guide for a complete list of all implemented strategies. + Consult the NFD Developer's Guide for a complete list of all implemented strategies. For the ASF, BestRoute, and Multicast strategies, the following options may be supplied to configure exponential retransmission suppression by appending them after the strategy name and version number. - **retx-suppression-initial** + retx-suppression-initial Starting duration of the suppression interval within which any retransmitted Interests are considered for suppression. The default value is 10 ms. Format: ``retx-suppression-initial~`` - **retx-suppression-max** + retx-suppression-max Maximum duration of the suppression interval. Must not be smaller than **retx-suppression-initial**. The default value is 250 ms. Format: ``retx-suppression-max~`` - **retx-suppression-multiplier** + retx-suppression-multiplier The suppression interval is increased by this multiplier. The default value is 2. Format: ``retx-suppression-multiplier~`` See :manpage:`nfd-asf-strategy(7)` for details on additional parameters for ASF strategy. -EXIT CODES ----------- -0: Success +Exit Status +----------- + +0 + Success. -1: An unspecified error occurred +1 + An unspecified error occurred. -2: Malformed command line +2 + Malformed command line. -7: Strategy not found (**nfdc strategy set** only) +7 + Strategy not found (**nfdc strategy set** only). -EXAMPLES +Examples -------- -nfdc strategy list + +``nfdc strategy list`` List all configured strategy choices. -nfdc strategy show prefix /localhost/ping/1 +``nfdc strategy show prefix /localhost/ping/1`` Identify which strategy will handle Interests named "/localhost/ping/1". -nfdc strategy set prefix / strategy /localhost/nfd/strategy/best-route +``nfdc strategy set prefix / strategy /localhost/nfd/strategy/best-route`` Set the default strategy to best-route, latest version. -nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/multicast/v=4 +``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/multicast/v=4`` Set the strategy for the "/ndn" prefix to multicast, version 4. -nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/multicast/v=4/retx-suppression-initial~20/retx-suppression-max~500 +``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/multicast/v=4/retx-suppression-initial~20/retx-suppression-max~500`` Set the strategy for the "/ndn" prefix to multicast, version 4, with retransmission suppression initial interval set to 20 ms and maximum interval set to 500 ms. -nfdc strategy unset prefix /ndn +``nfdc strategy unset prefix /ndn`` Clear the strategy choice for the "/ndn" prefix. -SEE ALSO +See Also -------- -nfd(1), nfdc(1), nfd-asf-strategy(7) + +:manpage:`nfdc(1)`, +:manpage:`nfd-asf-strategy(7)` diff --git a/docs/manpages/nfdc.rst b/docs/manpages/nfdc.rst index 1e77830fe..2e5d089e4 100644 --- a/docs/manpages/nfdc.rst +++ b/docs/manpages/nfdc.rst @@ -1,58 +1,74 @@ nfdc ==== -SYNOPSIS +Synopsis -------- -| nfdc COMMAND [ARGUMENTS] ... -| nfdc help [COMMAND] -| nfdc [-h|--help] -| nfdc -V|--version -| nfdc -f|--batch BATCH-FILE -DESCRIPTION +| **nfdc** *COMMAND* [*ARGUMENTS*]... +| **nfdc** **help** [*COMMAND*] +| **nfdc** [**-h**\|\ **\--help**] +| **nfdc** **-V**\|\ **\--version** +| **nfdc** **-f**\|\ **\--batch** *file* + +Description ----------- -**nfdc** is a tool to manage a running instance of NFD. -Features of nfdc are organized into subcommands. -To print a list of all subcommands, run **nfdc** without arguments. -To show how to use a subcommand, run **nfdc help** followed by the subcommand name. +:program:`nfdc` is a command-line tool to manage a running instance of NFD. + +All features of :program:`nfdc` are organized into subcommands. +To print a list of all subcommands, run ``nfdc`` without arguments. +To show how to use a subcommand, run ``nfdc help`` followed by the subcommand name. -OPTIONS +Options ------- - - A subcommand name. - It usually contains a noun and a verb. - +.. option:: + + A subcommand name. It usually contains a noun and a verb. + +.. option:: + Arguments to the subcommand. -``-h`` or ``--help`` +.. option:: -h, --help + Print a list of available subcommands and exit. -``-V`` or ``--version`` +.. option:: -V, --version + Show version information and exit. -``-f BATCH-FILE`` or ``--batch BATCH-FILE`` - Process arguments specified in the ``BATCH-FILE`` as if they would have appeared - in the command line (but without ``nfdc``). When necessary, arguments should be - escaped using backslash ``\``, single ``'``, or double quotes ``"``. If any of - the command fails, the processing will be stopped at that command with error - code 2. Empty lines and lines that start with ``#`` character will be ignored. - Note that the batch file does not support empty string arguments - (``""`` or ``''``), even if they are supported by the regular command line ``nfdc``. +.. option:: -f , --batch + + Process the list of arguments specified in *file* as if they would have appeared on + the command line. + When running a sequence of commands in rapid succession from a script, this option + ensures that the commands are properly timestamped and can therefore be accepted + by NFD. - When running a sequence of commands in rapid succession from a script, this - option ensures that the commands are properly timestamped and can therefore - be accepted by NFD. + When necessary, arguments should be escaped using a backslash (``\``), single quotes + (``'``), or double quotes (``"``). + If any of the commands fail, processing will stop at that command and :program:`nfdc` + will exit with error code 2. + Empty lines and lines that start with the ``#`` character are ignored. + Note that the batch file does not support empty string arguments (``""`` or ``''``), + even if they would normally be supported on the regular command line of :program:`nfdc`. -EXAMPLES +Examples -------- -nfdc + +``nfdc`` List all subcommands. -nfdc help face create +``nfdc help face create`` Show how to use the ``nfdc face create`` subcommand. -SEE ALSO +See Also -------- -nfdc-status(1), nfdc-face(1), nfdc-route(1), nfdc-cs(1), nfdc-strategy(1) + +:manpage:`nfd(1)`, +:manpage:`nfdc-cs(1)`, +:manpage:`nfdc-face(1)`, +:manpage:`nfdc-route(1)`, +:manpage:`nfdc-status(1)`, +:manpage:`nfdc-strategy(1)` diff --git a/docs/releases.rst b/docs/releases.rst index 541760e11..8afd0e1f6 100644 --- a/docs/releases.rst +++ b/docs/releases.rst @@ -1,5 +1,5 @@ -All NFD Releases -================ +Release History +=============== .. toctree:: :glob: