1 .. _command-line-interface:
6 FRR features a flexible modal command line interface. Often when adding new
7 features or modifying existing code it is necessary to create or modify CLI
8 commands. FRR has a powerful internal CLI system that does most of the heavy
13 FRR's CLI is organized by modes. Each mode is associated with some set of
14 functionality, e.g. EVPN, or some underlying object such as an interface. Each
15 mode contains a set of commands that control the associated functionality or
16 object. Users move between the modes by entering a command, which is usually
17 different for each source and destination mode.
19 A summary of the modes is given in the following figure.
21 .. graphviz:: ../figures/nodes.dot
23 .. seealso:: :ref:`cli-data-structures`
27 FRR exhibits, for historical reasons, a peculiar behavior called 'walkup'.
28 Suppose a user is in ``OSPF_NODE``, which contains only OSPF-specific commands,
29 and enters the following command: ::
31 ip route 192.168.100.0/24 10.0.2.2
33 This command is not defined in ``OSPF_NODE``, so the matcher will fail to match
34 the command in that node. The matcher will then check "parent" nodes of
35 ``OSPF_NODE``. In this case the direct parent of ``OSPF_NODE`` is
36 ``CONFIG_NODE``, so the current node switches to ``CONFIG_NODE`` and the command
37 is tried in that node. Since static route commands are defined in
38 ``CONFIG_NODE`` the command succeeds. The procedure of attempting to execute
39 unmatched commands by sequentially "walking up" to parent nodes only happens in
40 children (direct and indirect) below ``CONFIG_NODE`` and stops at
43 Unfortunately, the internal representation of the various modes is not actually
44 a graph. Instead, there is an array. The parent-child relationships are not
45 explicitly defined in any datastructure but instead are hard-coded into the
46 specific commands that switch nodes. For walkup, there is a function that takes
47 a node and returns the parent of the node. This interface causes all manner of
48 insidious problems, even for experienced developers, and needs to be fixed at
49 some point in the future.
51 Deprecation of old style of commands
52 ------------------------------------
54 There are currently 2 styles of defining commands within a FRR source file.
55 ``DEFUN`` and ``DEFPY``. ``DEFPY`` should be used for all new commands that
56 a developer is writing. This is because it allows for much better handling
57 of command line arguments as well as ensuring that input is correct. ``DEFUN``
58 is listed here for historical reasons as well as for ensuring that existing
59 code can be understood by new developers.
63 All definitions for the CLI system are exposed in ``lib/command.h``. In this
64 header there are a set of macros used to define commands. These macros are
65 collectively referred to as "DEFUNs", because of their syntax:
71 "example command FOO...",
76 // ...command handler...
79 DEFUNs generally take four arguments which are expanded into the appropriate
80 constructs for hooking into the CLI. In order these are:
82 - **Function name** - the name of the handler function for the command
83 - **Command name** - the identifier of the ``struct cmd_element`` for the
84 command. By convention this should be the function name with ``_cmd``
86 - **Command definition** - an expression in FRR's CLI grammar that defines the
87 form of the command and its arguments, if any
88 - **Doc string** - a newline-delimited string that documents each element in
89 the command definition
91 In the above example, ``command_name`` is the function name,
92 ``command_name_cmd`` is the command name, ``"example..."`` is the definition and
93 the last argument is the doc string. The block following the macro is the body
94 of the handler function, details on which are presented later in this section.
96 In order to make the command show up to the user it must be installed into the
97 CLI graph. To do this, call:
99 ``install_element(NODE, &command_name_cmd);``
101 This will install the command into the specified CLI node. Usually these calls
102 are grouped together in a CLI initialization function for a set of commands, and
103 the DEFUNs themselves are grouped into the same source file to avoid cluttering
104 the codebase. The names of these files follow the form ``*_vty.[ch]`` by
105 convention. Please do not scatter individual CLI commands in the middle of
106 source files; instead expose the necessary functions in a header and place the
107 command definition in a ``*_vty.[ch]`` file.
111 Please see :ref:`cli-workflow` for requirements when creating CLI commands
112 (e.g., JSON structure and formatting).
116 FRR uses its own grammar for defining CLI commands. The grammar draws from
117 syntax commonly seen in \*nix manpages and should be fairly intuitive. The
118 parser is implemented in Bison and the lexer in Flex. These may be found in
119 ``lib/command_parse.y`` and ``lib/command_lex.l``, respectively.
121 **ProTip**: if you define a new command and find that the parser is
122 throwing syntax or other errors, the parser is the last place you want
123 to look. Bison is very stable and if it detects a syntax error, 99% of
124 the time it will be a syntax error in your definition.
126 The formal grammar in BNF is given below. This is the grammar implemented in the
127 Bison parser. At runtime, the Bison parser reads all of the CLI strings and
128 builds a combined directed graph that is used to match and interpret user input.
130 Human-friendly explanations of how to use this grammar are given a bit later in
131 this section alongside information on the :ref:`cli-data-structures` constructed
135 command: `cmd_token_seq`
136 : `cmd_token_seq` `placeholder_token` "..."
137 cmd_token_seq: *empty*
138 : `cmd_token_seq` `cmd_token`
139 cmd_token: `simple_token`
141 simple_token: `literal_token`
142 : `placeholder_token`
143 literal_token: WORD `varname_token`
144 varname_token: "$" WORD
145 placeholder_token: `placeholder_token_real` `varname_token`
146 placeholder_token_real: IPV4
155 selector: "<" `selector_seq_seq` ">" `varname_token`
156 : "{" `selector_seq_seq` "}" `varname_token`
157 : "[" `selector_seq_seq` "]" `varname_token`
158 : "![" `selector_seq_seq` "]" `varname_token`
159 selector_seq_seq: `selector_seq_seq` "|" `selector_token_seq`
160 : `selector_token_seq`
161 selector_token_seq: `selector_token_seq` `selector_token`
163 selector_token: `selector`
168 The various capitalized tokens in the BNF above are in fact themselves
169 placeholders, but not defined as such in the formal grammar; the grammar
170 provides the structure, and the tokens are actually more like a type system for
171 the strings you write in your CLI definitions. A CLI definition string is broken
172 apart and each piece is assigned a type by the lexer based on a set of regular
173 expressions. The parser uses the type information to verify the string and
174 determine the structure of the CLI graph; additional metadata (such as the raw
175 text of each token) is encoded into the graph as it is constructed by the
176 parser, but this is merely a dumb copy job.
178 Here is a brief summary of the various token types along with examples.
180 +-----------------+--------------------------+-------------------------------------------------------+
181 | Token type | Syntax | Description |
182 +=================+==========================+=======================================================+
183 | ``WORD`` | ``show ip bgp`` | Matches itself. In the example every token is a WORD. |
184 +-----------------+--------------------------+-------------------------------------------------------+
185 | ``IPV4`` | ``A.B.C.D`` | Matches an IPv4 address. |
186 +-----------------+--------------------------+-------------------------------------------------------+
187 | ``IPV6`` | ``X:X::X:X`` | Matches an IPv6 address. |
188 +-----------------+--------------------------+-------------------------------------------------------+
189 | ``IPV4_PREFIX`` | ``A.B.C.D/M`` | Matches an IPv4 prefix in CIDR notation. |
190 +-----------------+--------------------------+-------------------------------------------------------+
191 | ``IPV6_PREFIX`` | ``X:X::X:X/M`` | Matches an IPv6 prefix in CIDR notation. |
192 +-----------------+--------------------------+-------------------------------------------------------+
193 | ``MAC`` | ``X:X:X:X:X:X`` | Matches a 48-bit mac address. |
194 +-----------------+--------------------------+-------------------------------------------------------+
195 | ``MAC_PREFIX`` | ``X:X:X:X:X:X/M`` | Matches a 48-bit mac address with a mask. |
196 +-----------------+--------------------------+-------------------------------------------------------+
197 | ``VARIABLE`` | ``FOOBAR`` | Matches anything. |
198 +-----------------+--------------------------+-------------------------------------------------------+
199 | ``RANGE`` | ``(X-Y)`` | Matches numbers in the range X..Y inclusive. |
200 +-----------------+--------------------------+-------------------------------------------------------+
201 | ``ASNUM`` | ``<A.B|(1-4294967295)>`` | Matches an AS in plain or dot format. |
202 +-----------------+--------------------------+-------------------------------------------------------+
204 When presented with user input, the parser will search over all defined
205 commands in the current context to find a match. It is aware of the various
206 types of user input and has a ranking system to help disambiguate commands. For
207 instance, suppose the following commands are defined in the user's current
213 example command (22-49)
214 example command A.B.C.D/X
216 The following table demonstrates the matcher's choice for a selection of
219 +---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+
220 | Input | Matched command | Reason |
221 +=================================+===========================+==============================================================================================================+
222 | ``example command eLi7eH4xx0r`` | example command FOO | ``eLi7eH4xx0r`` is not an integer or IPv4 prefix, |
223 | | | but FOO is a variable and matches all input. |
224 +---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+
225 | ``example command 42`` | example command (22-49) | ``42`` is not an IPv4 prefix. It does match both |
226 | | | ``(22-49)`` and ``FOO``, but RANGE tokens are more specific and have a higher priority than VARIABLE tokens. |
227 +---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+
228 | ``example command 10.3.3.0/24`` | example command A.B.C.D/X | The user entered an IPv4 prefix, which is best matched by the last command. |
229 +---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+
233 There are also constructs which allow optional tokens, mutual exclusion,
234 one-or-more selection and repetition.
236 - ``<angle|brackets>`` -- Contain sequences of tokens separated by pipes and
237 provide mutual exclusion. User input matches at most one option.
238 - ``[square brackets]`` -- Contains sequences of tokens that can be omitted.
239 ``[<a|b>]`` can be shortened to ``[a|b]``.
240 - ``![exclamation square brackets]`` -- same as ``[square brackets]``, but
241 only allow skipping the contents if the command input starts with ``no``.
242 (For cases where the positive command needs a parameter, but the parameter
243 is optional for the negative case.)
244 - ``{curly|braces}`` -- similar to angle brackets, but instead of mutual
245 exclusion, curly braces indicate that one or more of the pipe-separated
246 sequences may be provided in any order.
247 - ``VARIADICS...`` -- Any token which accepts input (anything except WORD)
248 which occurs as the last token of a line may be followed by an ellipsis,
249 which indicates that input matching the token may be repeated an unlimited
251 - ``$name`` -- Specify a variable name for the preceding token. See
252 "Variable Names" below.
256 - Options are allowed at the beginning of the command. The developer is
257 entreated to use these extremely sparingly. They are most useful for
258 implementing the 'no' form of configuration commands. Please think carefully
259 before using them for anything else. There is usually a better solution, even
260 if it is just separating out the command definition into separate ones.
261 - The developer should judiciously apply separation of concerns when defining
262 commands. CLI definitions for two unrelated or vaguely related commands or
263 configuration items should be defined in separate commands. Clarity is
264 preferred over LOC (within reason).
265 - The maximum number of space-separated tokens that can be entered is
266 presently limited to 256. Please keep this limit in mind when
267 implementing new CLI.
271 The parser tries to fill the "varname" field on each token. This can happen
272 either manually or automatically. Manual specifications work by appending
273 ``$name`` after the input specifier:
277 foo bar$cmd WORD$name A.B.C.D$ip
279 Note that you can also assign variable names to fixed input tokens, this can be
280 useful if multiple commands share code. You can also use "$name" after a
281 multiple-choice option:
285 foo bar <A.B.C.D|X:X::X:X>$addr [optionA|optionB]$mode
287 The variable name is in this case assigned to the last token in each of the
290 Automatic assignment of variable names works by applying the following rules:
292 - manual names always have priority
293 - a ``[no]`` at the beginning receives ``no`` as varname on the ``no`` token
294 - ``VARIABLE`` tokens whose text is not ``WORD`` or ``NAME`` receive a cleaned
295 lowercase version of the token text as varname, e.g. ``ROUTE-MAP`` becomes
297 - other variable tokens (i.e. everything except "fixed") receive the text of
298 the preceding fixed token as varname, if one can be found. E.g.
299 ``ip route A.B.C.D/M INTERFACE`` assigns "route" to the ``A.B.C.D/M`` token.
301 These rules should make it possible to avoid manual varname assignment in 90% of
306 Each token in a command definition should be documented with a brief doc string
307 that informs a user of the meaning and/or purpose of the subsequent command
308 tree. These strings are provided as the last parameter to DEFUN macros,
309 concatenated together and separated by an escaped newline (``\n``). These are
310 best explained by example.
314 DEFUN (config_terminal,
316 "configure terminal",
317 "Configuration from vty interface\n"
318 "Configuration terminal\n")
320 The last parameter is split into two lines for readability. Two newline
321 delimited doc strings are present, one for each token in the command. The second
322 string documents the functionality of the ``terminal`` command in the
323 ``configure`` subtree.
325 Note that the first string, for ``configure`` does not contain documentation for
326 'terminal'. This is because the CLI is best envisioned as a tree, with tokens
327 defining branches. An imaginary ``start`` token is the root of every command in
328 a CLI node. Each subsequent written token descends into a subtree, so the
329 documentation for that token ideally summarizes all the functionality contained
332 A consequence of this structure is that the developer must be careful to use the
333 same doc strings when defining multiple commands that are part of the same tree.
334 Commands which share prefixes must share the same doc strings for those
335 prefixes. On startup the parser will generate warnings if it notices
336 inconsistent doc strings. Behavior is undefined; the same token may show up
337 twice in completions, with different doc strings, or it may show up once with a
338 random doc string. Parser warnings should be heeded and fixed to avoid confusing
341 The number of doc strings provided must be equal to the amount of tokens present
342 in the command definition, read left to right, ignoring any special constructs.
344 In the examples below, each arrowed token needs a doc string.
351 "command <foo|bar> [example]"
356 ``DEFPY(...)`` is an enhanced version of ``DEFUN()`` which is preprocessed by
357 :file:`python/clidef.py`. The python script parses the command definition
358 string, extracts variable names and types, and generates a C wrapper function
359 that parses the variables and passes them on. This means that in the CLI
360 function body, you will receive additional parameters with appropriate types.
362 This is best explained by an example. Invoking ``DEFPY`` like this:
366 DEFPY(func, func_cmd, "[no] foo bar A.B.C.D (0-99)$num", "...help...")
368 defines the handler function like this:
372 func(self, vty, argc, argv, /* standard CLI arguments */
373 const char *no, /* unparsed "no" */
374 struct in_addr bar, /* parsed IP address */
375 const char *bar_str, /* unparsed IP address */
376 long num, /* parsed num */
377 const char *num_str) /* unparsed num */
379 Note that as documented in the previous section, ``bar`` is automatically
380 applied as variable name for ``A.B.C.D``. The Python script then detects this as
381 an IP address argument and generates code to parse it into a ``struct in_addr``,
382 passing it in ``bar``. The raw value is passed in ``bar_str``. The range/number
383 argument works in the same way with the explicitly given variable name.
388 +----------------------------+--------------------------------+--------------------------+
389 | Token(s) | Type | Value if omitted by user |
390 +============================+================================+==========================+
391 | ``A.B.C.D`` | ``struct in_addr`` | ``0.0.0.0`` |
392 +----------------------------+--------------------------------+--------------------------+
393 | ``X:X::X:X`` | ``struct in6_addr`` | ``::`` |
394 +----------------------------+--------------------------------+--------------------------+
395 | ``A.B.C.D + X:X::X:X`` | ``const union sockunion *`` | ``NULL`` |
396 +----------------------------+--------------------------------+--------------------------+
397 | ``A.B.C.D/M`` | ``const struct prefix_ipv4 *`` | ``all-zeroes struct`` |
398 +----------------------------+--------------------------------+--------------------------+
399 | ``X:X::X:X/M`` | ``const struct prefix_ipv6 *`` | ``all-zeroes struct`` |
400 +----------------------------+--------------------------------+--------------------------+
401 | ``A.B.C.D/M + X:X::X:X/M`` | ``const struct prefix *`` | ``all-zeroes struct`` |
402 +----------------------------+--------------------------------+--------------------------+
403 | ``(0-9)`` | ``long`` | ``0`` |
404 +----------------------------+--------------------------------+--------------------------+
405 | ``VARIABLE`` | ``const char *`` | ``NULL`` |
406 +----------------------------+--------------------------------+--------------------------+
407 | ``word`` | ``const char *`` | ``NULL`` |
408 +----------------------------+--------------------------------+--------------------------+
409 | *all other* | ``const char *`` | ``NULL`` |
410 +----------------------------+--------------------------------+--------------------------+
412 Note the following details:
414 - Not all parameters are pointers, some are passed as values.
415 - When the type is not ``const char *``, there will be an extra ``_str``
416 argument with type ``const char *``.
417 - You can give a variable name not only to ``VARIABLE`` tokens but also to
418 ``word`` tokens (e.g. constant words). This is useful if some parts of a
419 command are optional. The type will be ``const char *``.
420 - ``[no]`` will be passed as ``const char *no``.
421 - Most pointers will be ``NULL`` when the argument is optional and the
422 user did not supply it. As noted in the table above, some prefix
423 struct type arguments are passed as pointers to all-zeroes structs,
424 not as ``NULL`` pointers.
425 - If a parameter is not a pointer, but is optional and the user didn't use it,
426 the default value will be passed. Check the ``_str`` argument if you need to
427 determine whether the parameter was omitted.
428 - If the definition contains multiple parameters with the same variable name,
429 they will be collapsed into a single function parameter. The python code will
430 detect if the types are compatible (i.e. IPv4 + IPv6 variants) and choose a
431 corresponding C type.
432 - The standard DEFUN parameters (``self, vty, argc, argv``) are still present
433 and can be used. A DEFUN can simply be **edited into a DEFPY without further
434 changes and it will still work**; this allows easy forward migration.
435 - A file may contain both ``DEFUN`` and ``DEFPY`` statements.
437 Getting a parameter dump
438 """"""""""""""""""""""""
439 The clidef.py script can be called to get a list of DEFUNs/DEFPYs with the
440 parameter name/type list:
444 lib/clippy python/clidef.py --all-defun --show lib/plist.c > /dev/null
446 The generated code is printed to stdout, the info dump to stderr. The
447 ``--all-defun`` argument will make it process DEFUN blocks as well as DEFPYs,
448 which is useful prior to converting some DEFUNs. **The dump does not list the
449 ``_str`` arguments** to keep the output shorter.
451 Note that the ``clidef.py`` script cannot be run with python directly, it needs
452 to be run with *clippy* since the latter makes the CLI parser available.
454 Include & Makefile requirements
455 """""""""""""""""""""""""""""""
456 A source file that uses DEFPY needs to include the ``*_clippy.c`` file **before
457 all DEFPY statements**:
464 #include "daemon/filename_clippy.c"
471 This dependency needs to be marked in ``Makefile.am`` or ``subdir.am``: (there
472 is no ordering requirement)
478 # if linked into a LTLIBRARY (.la/.so):
479 filename.lo: filename_clippy.c
481 # if linked into an executable or static library (.a):
482 filename.o: filename_clippy.c
486 The block that follows a CLI definition is executed when a user enters input
487 that matches the definition. Its function signature looks like this:
491 int (*func) (const struct cmd_element *, struct vty *, int, struct cmd_token *[]);
493 The first argument is the command definition struct. The last argument is an
494 ordered array of tokens that correspond to the path taken through the graph, and
495 the argument just prior to that is the length of the array.
497 The arrangement of the token array has changed from Quagga's CLI implementation.
498 In the old system, missing arguments were padded with ``NULL`` so that the same
499 parts of a command would show up at the same indices regardless of what was
500 entered. The new system does not perform such padding and therefore it is
501 generally *incorrect* to assume consistent indices in this array. As a simple
508 command [foo] <bar|baz>
538 .. _cli-data-structures:
542 On startup, the CLI parser sequentially parses each command string definition
543 and constructs a directed graph with each token forming a node. This graph is
544 the basis of the entire CLI system. It is used to match user input in order to
545 generate command completions and match commands to functions.
547 There is one graph per CLI node (not the same as a graph node in the CLI graph).
548 The CLI node struct keeps a reference to its graph (see :file:`lib/command.h`).
550 While most of the graph maintains the form of a tree, special constructs
551 outlined in the Rules section introduce some quirks. ``<>``, ``[]`` and ``{}``
552 form self-contained 'subgraphs'. Each subgraph is a tree except that all of the
553 'leaves' actually share a child node. This helps with minimizing graph size and
556 As a working example, here is the graph of the following command: ::
558 show [ip] bgp neighbors [<A.B.C.D|X:X::X:X|WORD>] [json]
560 .. figure:: ../figures/cligraph.png
563 Graph of example CLI command
566 ``FORK`` and ``JOIN`` nodes are plumbing nodes that don't correspond to user
567 input. They're necessary in order to deduplicate these constructs where
570 Options follow the same form, except that there is an edge from the ``FORK``
571 node to the ``JOIN`` node. Since all of the subgraphs in the example command are
572 optional, all of them have this edge.
574 Keywords follow the same form, except that there is an edge from ``JOIN`` to
575 ``FORK``. Because of this the CLI graph cannot be called acyclic. There is
576 special logic in the input matching code that keeps a stack of paths already
577 taken through the node in order to disallow following the same path more than
580 Variadics are a bit special; they have an edge back to themselves, which allows
581 repeating the same input indefinitely.
583 The leaves of the graph are nodes that have no out edges. These nodes are
584 special; their data section does not contain a token, as most nodes do, or
585 ``NULL``, as in ``FORK``/``JOIN`` nodes, but instead has a pointer to a
586 ``cmd_element``. All paths through the graph that terminate on a leaf are
587 guaranteed to be defined by that command. When a user enters a complete command,
588 the command matcher tokenizes the input and executes a DFS on the CLI graph. If
589 it is simultaneously able to exhaust all input (one input token per graph node),
590 and then find exactly one leaf connected to the last node it reaches, then the
591 input has matched the corresponding command and the command is executed. If it
592 finds more than one node, then the command is ambiguous (more on this in
593 deduplication). If it cannot exhaust all input, the command is unknown. If it
594 exhausts all input but does not find an edge node, the command is incomplete.
596 The parser uses an incremental strategy to build the CLI graph for a node. Each
597 command is parsed into its own graph, and then this graph is merged into the
598 overall graph. During this merge step, the parser makes a best-effort attempt to
599 remove duplicate nodes. If it finds a node in the overall graph that is equal to
600 a node in the corresponding position in the command graph, it will intelligently
601 merge the properties from the node in the command graph into the
602 already-existing node. Subgraphs are also checked for isomorphism and merged
603 where possible. The definition of whether two nodes are 'equal' is based on the
604 equality of some set of token properties; read the parser source for the most
605 up-to-date definition of equality.
607 When the parser is unable to deduplicate some complicated constructs, this can
608 result in two identical paths through separate parts of the graph. If this
609 occurs and the user enters input that matches these paths, they will receive an
610 'ambiguous command' error and will be unable to execute the command. Most of the
611 time the parser can detect and warn about duplicate commands, but it will not
612 always be able to do this. Hence care should be taken before defining a new
613 command to ensure it is not defined elsewhere.
620 /* Command token struct. */
623 enum cmd_token_type type; // token type
624 uint8_t attr; // token attributes
625 bool allowrepeat; // matcher can match token repetitively?
627 char *text; // token text
628 char *desc; // token description
629 long long min, max; // for ranges
630 char *arg; // user input that matches this token
631 char *varname; // variable name
634 This struct is used in the CLI graph to match input against. It is also used to
635 pass user input to command handler functions, as it is frequently useful for
636 handlers to have access to that information. When a command is matched, the
637 sequence of ``cmd_tokens`` that form the matching path are duplicated and placed
638 in order into ``*argv[]``. Before this happens the ``->arg`` field is set to
639 point at the snippet of user input that matched it.
641 For most nontrivial commands the handler function will need to determine which
642 of the possible matching inputs was entered. Previously this was done by looking
643 at the first few characters of input. This is now considered an anti-pattern and
644 should be avoided. Instead, the ``->type`` or ``->text`` fields for this logic.
645 The ``->type`` field can be used when the possible inputs differ in type. When
646 the possible types are the same, use the ``->text`` field. This field has the
647 full text of the corresponding token in the definition string and using it makes
648 for much more readable code. An example is helpful.
654 command <(1-10)|foo|BAR>
656 In this example, the user may enter any one of:
657 - an integer between 1 and 10
661 If the user enters "command f", then:
665 argv[1]->type == WORD_TKN
667 argv[1]->text == "foo"
669 Range tokens have some special treatment; a token with ``->type == RANGE_TKN``
670 will have the ``->min`` and ``->max`` fields set to the bounding values of the
682 /* Prompt character at vty interface. */
685 /* Is this node's configuration goes to vtysh ? */
688 /* Node's configuration write function */
689 int (*func)(struct vty *);
691 /* Node's command graph */
692 struct graph *cmdgraph;
694 /* Vector of this node's command list. */
697 /* Hashed index of command node list, for de-dupping primarily */
698 struct hash *cmd_hash;
701 This struct corresponds to a CLI mode. The last three fields are most relevant
705 This is a pointer to the command graph that was described in the first part
706 of this section. It is the datastructure used for matching user input to
710 This is a list of all the ``struct cmd_element`` defined in the mode.
713 This is a hash table of all the ``struct cmd_element`` defined in the mode.
714 When ``install_element`` is called, it checks that the element it is given is
715 not already present in the hash table as a safeguard against duplicate calls
716 resulting in a command being defined twice, which renders the command
719 All ``struct cmd_node`` are themselves held in a static vector defined in
720 :file:`lib/command.c` that defines the global CLI space.
722 Command Abbreviation & Matching Priority
723 ----------------------------------------
724 It is possible for users to elide parts of tokens when the CLI matcher does not
725 need them to make an unambiguous match. This is best explained by example.
738 c d c -> ambiguous command
739 c d co -> match "command dog cow"
742 The parser will look ahead and attempt to disambiguate the input based on tokens
743 later on in the input string.
750 show ipv6 bgp X:X::X:X
756 s i b 4.3.2.1 -> match "show ip bgp A.B.C.D"
757 s i b ::e0 -> match "show ipv6 bgp X:X::X:X"
759 Reading left to right, both of these commands would be ambiguous since 'i' does
760 not explicitly select either 'ip' or 'ipv6'. However, since the user later
761 provides a token that matches only one of the commands (an IPv4 or IPv6 address)
762 the parser is able to look ahead and select the appropriate command. This has
763 some implications for parsing the ``*argv[]`` that is passed to the command
766 Now consider a command definition such as:
772 'foo' only matches the string 'foo', but 'VAR' matches any input, including
773 'foo'. Who wins? In situations like this the matcher will always choose the
774 'better' match, so 'foo' will win.
788 ``ip`` partially matches ``ipv6`` but exactly matches ``ip``, so ``ip`` will
794 To add a new CLI node, you should:
796 - define a new numerical node constant
797 - define a node structure in the relevant daemon
798 - call ``install_node()`` in the relevant daemon
799 - define and install the new node in vtysh
800 - define corresponding node entry commands in daemon and vtysh
801 - add a new entry to the ``ctx_keywords`` dictionary in ``tools/frr-reload.py``
803 Defining the numerical node constant
804 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
805 Add your new node value to the enum before ``NODE_TYPE_MAX`` in
811 AUTH_NODE, // Authentication mode of vty interface.
812 VIEW_NODE, // View node. Default mode of vty interface.
815 NODE_TYPE_MAX, // maximum
818 Defining a node structure
819 ^^^^^^^^^^^^^^^^^^^^^^^^^
820 In your daemon-specific code where you define your new commands that
821 attach to the new node, add a node definition:
825 static struct cmd_node my_new_node = {
826 .name = "my new node name",
827 .node = MY_NEW_NODE, // enum node_type lib/command.h
828 .parent_node = CONFIG_NODE,
829 .prompt = "%s(my-new-node-prompt)# ",
830 .config_write = my_new_node_config_write,
833 You will need to define ``my_new_node_config_write(struct vty \*vty)``
834 (or omit this field if you have no relevant configuration to save).
836 Calling ``install_node()``
837 ^^^^^^^^^^^^^^^^^^^^^^^^^^
838 In the daemon's initialization function, before installing your new commands
839 with ``install_element()``, add a call ``install_node(&my_new_node)``.
841 Defining and installing the new node in vtysh
842 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
843 The build tools automatically collect command definitions for vtysh.
844 However, new nodes must be coded in vtysh specifically.
846 In ``vtysh/vtysh.c``, define a stripped-down node structure and
847 call ``install_node()``:
851 static struct cmd_node my_new_node = {
852 .name = "my new node name",
853 .node = MY_NEW_NODE, /* enum node_type lib/command.h */
854 .parent_node = CONFIG_NODE,
855 .prompt = "%s(my-new-node-prompt)# ",
858 void vtysh_init_vty(void)
861 install_node(&my_new_node)
865 Defining corresponding node entry commands in daemon and vtysh
866 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
867 The command that descends into the new node is typically programmed
868 with ``VTY_PUSH_CONTEXT`` or equivalent in the daemon's CLI handler function.
869 (If the CLI has been updated to use the new northbound architecture,
870 ``VTY_PUSH_XPATH`` is used instead.)
872 In vtysh, you must implement a corresponding node change so that vtysh
873 tracks the daemon's movement through the node tree.
875 Although the build tools typically scan daemon code for CLI definitions
876 to replicate their parsing in vtysh, the node-descent function in the
877 daemon must be blocked from this replication so that a hand-coded
878 skeleton can be written in ``vtysh.c``.
880 Accordingly, use one of the ``*_NOSH`` macros such as ``DEFUN_NOSH``,
881 ``DEFPY_NOSH``, or ``DEFUN_YANG_NOSH`` for the daemon's node-descent
882 CLI definition, and use ``DEFUNSH`` in ``vtysh.c`` for the vtysh equivalent.
884 .. seealso:: :ref:`vtysh-special-defuns`
892 DEFPY_NOSH(my_new_node,
899 VTY_PUSH_CONTEXT(MY_NEW_NODE, bar);
908 DEFPY_YANG_NOSH(my_new_node,
915 VTY_PUSH_XPATH(MY_NEW_NODE, xbar);
924 DEFUNSH(VTYSH_ZEBRA, my_new_node,
930 vty->node = MY_NEW_NODE;
934 install_element(CONFIG_NODE, &my_new_node_cmd);
937 Adding a new entry to the ``ctx_keywords`` dictionary
938 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
939 In file ``tools/frr-reload.py``, the ``ctx_keywords`` dictionary
940 describes the various node relationships.
941 Add a new node entry at the appropriate level in this dictionary.
943 .. code-block:: python
957 Inspection & Debugging
958 ----------------------
962 It is sometimes useful to check all the possible combinations of input that
963 would match an arbitrary definition string. There is a tool in
964 :file:`tools/permutations` that reads CLI definition strings on ``stdin`` and
965 prints out all matching input permutations. It also dumps a text representation
966 of the graph, which is more useful for debugging than anything else. It looks
969 .. code-block:: shell
971 $ ./permutations "show [ip] bgp [<view|vrf> WORD]"
973 show ip bgp view WORD
980 This functionality is also built into VTY/VTYSH; :clicmd:`list permutations`
981 will list all possible matching input permutations in the current CLI node.
985 When in the Telnet or VTYSH console, :clicmd:`show cli graph` will dump the
986 entire command space of the current mode in the DOT graph language. This can be
987 fed into one of the various GraphViz layout engines, such as ``dot``,
990 For example, to generate an image of the entire command space for the top-level
991 mode (``ENABLE_NODE``):
993 .. code-block:: shell
995 sudo vtysh -c 'show cli graph' | dot -Tjpg -Grankdir=LR > graph.jpg
997 To do the same for the BGP mode:
999 .. code-block:: shell
1001 sudo vtysh -c 'conf t' -c 'router bgp' -c 'show cli graph' | dot -Tjpg -Grankdir=LR > bgpgraph.jpg
1003 This information is very helpful when debugging command resolution, tracking
1004 down duplicate / ambiguous commands, and debugging patches to the CLI graph