This document proposes a new design for nfdc command which combines existing nfdc and nfd-status commands, as a unified command for monitoring and controlling NFD.
nfdc has three operation modes.
one-shot mode executes a single command. An example interaction looks like:
$ nfdc face
id=288 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.8:6363 persistent in=500i,400d,20n,60000B out=450i,300d,100n,50000B
id=289 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.9:6363 persistent in=502i,402d,22n,60002B out=452i,302d,102n,50002B
$ nfdc face create udp4://router.example.com
face-created id=300 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.2:6363 persistent
batch mode executes multiple commands. nfdc -f <filename> executes a batch file. An example interaction looks like:
$ cat commands.txt
face create udp4://router.example.com permanent
route add / udp4://router.example.com cost 10
route add /corp udp4://router.example.org
$ nfdc -f command.txt
face-created id=300 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.2:6363 permanent
route-added prefix=/ nexthop=300 cost=10 origin=255
face-created id=301 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.3:6363 persistent
route-added prefix=/corp nexthop=301 cost=0 origin=255
$ echo $?
0
interactive mode displays a command prompt and allows the operator to type in commands. nfdc -i enters the interactive mode. An example interaction looks like:
$ nfdc -i
nfdc> face
nfdc face> list
id=288 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.8:6363 persistent in=500i,400d,20n,60000B out=450i,300d,100n,50000B
id=289 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.9:6363 persistent in=502i,402d,22n,60002B out=452i,302d,102n,50002B
nfdc face> create udp4://router.example.com permanent
face-created id=300 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.2:6363 permanent
nfdc face> exit
nfdc> route add / udp4://router.example.com cost 10
route-added prefix=/ nexthop=300 cost=10 origin=255
nfdc> quit
nfdc accepts inputs in the form of command line. In one-shot mode, each invocation accepts a command line; in batch mode, each line in the batch file is a command line.
A command line starts with a noun and a verb, followed by zero or more arguments.
The noun denotes an item that can be operated on. It should be written in singular form. Examples are: status, face, strategy, route.
The verb denotes an action to be carried on the item. It should be written in present tense. Examples are: list, show, create, destroy, add, remove, set, unset, load, unload, reset.
A combination of module and verb defines a command.
All arguments are named. Each named argument should be specified as the name followed by the value; the value can have zero or more tokens.
In addition, each command may accept zero or more commonly used arguments as positional arguments; in other words, the argument name can be omitted if they are specified in the defined order. For an argument to be accepted as a positional argument, its value must be distinguishable from possible argument names. Positional arguments must be specified before any named arguments.
face create command accepts remote and persistency as two positional arguments, so the following command lines are equivalent:
face create udp4://router.example.com persistent
face create udp4://router.example.com persistency persistent
face create remote udp4://router.example.com persistency persistent
face create persistency persistent remote udp4://router.example.com
In one-shot and batch modes, if a command line has only the module, verb list is implied.
The following command lines are equivalent in one-shot and batch modes:
face
face list
A command line, except those requesting information, yields one or more command results.
A positive result indicates a successful command execution.
It starts with an action summary which contains the noun, a hyphen, and the verb as past particle. Examples are: face-created, strategy-set, route-added. The action summary is written as one token for easier script consumption; it's also human readable.
After the action summary, attributes of the item is printed as key-value pairs separated by spaces; each key-value pair is represented as key=value. If the key corresponds to a command argument, it should use the same word as the argument name.
A negative result indicates a failed command execution.
It starts with a failure summary which is similar to the action summary but with the word "not" injected in between. Examples are: face-not-created, strategy-not-set, route-not-added.
Then it's a reason summary which indicates the failure reason. Examples are: timeout, not-authorized, bad-response, response-validation-error. The reason summary is written as one token for easier script consumption; it's also human readable.
After the failure summary and reason summary, key-value pairs about the failure can be printed in the same format as a positive result.
A command line requesting information, typically with list or show verb, yields a status report.
A status report of one item (typically from show verb) should print one attribute per line.
A status report of multiple items (typically from list verb) should print one item per line, and use tab-separated or key=value format on each line.
This section gives a brief list of all commands and their arguments.
status show # general status
status list # alias of "status show"
status report [[format] text] # full status report in text
status report [format] xml # full status report in text
face list [[remote] <uri>] [local <uri>] [scheme <scheme>]
face show [id] <id>
face create [remote] <uri> [[persistency] <persistent|permanent>]
face destroy [id] <id>
face destroy [remote] <uri>
channel list
strategy list
strategy show [prefix] <prefix>
strategy set [prefix] <prefix> [strategy] <strategy-name>
strategy unset [prefix] <prefix>
fib-entry list
route list [[nexthop] <id|uri>] [origin <origin>]
route show [prefix] <prefix>
route add [prefix] <prefix> [nexthop] <id|uri> [cost <cost>] [origin <origin>] [no-inherit] [capture] [expires <millis>]
route remove [prefix] <prefix> [nexthop] <id|uri> [origin <origin>]
In one-shot and interactive modes, a help command is provided. This command has a special syntax that it does not have a noun before help verb, and its arguments are positional only.
help [<noun> [<verb>]]
In one-shot mode:
helpprints a list of commands each with a brief single-line description.help <noun>prints a list of verbs under the noun each with a brief description, which may contain commonly used arguments.help <noun> <verb>prints detailed help.
In interactive mode when the current noun is empty:
helpprints a list of nouns each with a brief single-line description, plushelp,exit, andquit.help <noun>andhelp <noun> <verb>behave same as in one-shot mode.
In interactive mode when the current noun is not empty:
helpprints a list of verbs under the current noun, and a list of nouns, each with a brief single-line description, plushelp,exit, andquit.help <noun>andhelp <noun> <verb>behave same as in one-shot mode.help <verb>where the verb is valid under the current noun behaves same ashelp <current-noun> <verb>.
help command is not supported in batch mode.
nfdc -h or nfdc (without arguments) prints an introduction on the three operating modes, and an invitation on getting more help with nfdc help.
Under interactive mode, the program remembers a current noun; initially, the current noun is empty.
The prompt should start with nfdc, followed by the current noun if not empty, and then a > symbol.
Each typed line can be one of:
- A noun. This changes the current noun to this noun.
- A complete command line starting with noun and verb. This executes the command without considering or changing the current noun.
- A command line without the noun, when the current noun is not empty. This executes the command as if the current noun is specified on the command line.
quit. This stops the program.exit. If the current noun is empty, this is equivalent toquit; otherwise, this clears the current noun to empty.
In interactive mode, pressing TAB or ? key shows possible completions of the current token, or possible next tokens if the current token is complete.
Old nfdc and nfd-status commands are mapped into new commands as:
nfdc register => route add
nfdc unregister => route remove
nfdc create => face create
nfdc destroy => face destroy
nfdc set-strategy => strategy set
nfdc unset-strategy => strategy unset
nfdc add-nexthop => (not supported)
nfdc remove-nexthop => (not supported)
nfd-status => status report text
nfd-status -x => status report xml
nfd-status --general => status show
nfd-status --channels => channel list
nfd-status --faces => face list
nfd-status --fib => fib-entry list
nfd-status --rib => route list
nfd-status --sc => strategy list