]>
Commit | Line | Data |
---|---|---|
281ba953 QY |
1 | .. _command-line-interface: |
2 | ||
a42f7818 QY |
3 | Command Line Interface |
4 | ====================== | |
d1890d04 | 5 | |
a42f7818 QY |
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 | |
9 | lifting for you. | |
d1890d04 | 10 | |
cb3d8153 QY |
11 | Modes |
12 | ----- | |
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. | |
18 | ||
19 | A summary of the modes is given in the following figure. | |
20 | ||
21 | .. graphviz:: ../figures/nodes.dot | |
22 | ||
23 | .. seealso:: :ref:`cli-data-structures` | |
24 | ||
25 | Walkup | |
26 | ^^^^^^ | |
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: :: | |
30 | ||
31 | ip route 192.168.100.0/24 10.0.2.2 | |
32 | ||
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 | |
41 | ``CONFIG_NODE``. | |
42 | ||
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. | |
50 | ||
51 | Defining Commands | |
52 | ----------------- | |
a42f7818 QY |
53 | All definitions for the CLI system are exposed in ``lib/command.h``. In this |
54 | header there are a set of macros used to define commands. These macros are | |
55 | collectively referred to as "DEFUNs", because of their syntax: | |
d1890d04 QY |
56 | |
57 | :: | |
58 | ||
a42f7818 QY |
59 | DEFUN(command_name, |
60 | command_name_cmd, | |
61 | "example command FOO...", | |
62 | "Examples\n" | |
63 | "CLI command\n" | |
64 | "Argument\n") | |
65 | { | |
66 | // ...command handler... | |
67 | } | |
68 | ||
69 | DEFUNs generally take four arguments which are expanded into the appropriate | |
70 | constructs for hooking into the CLI. In order these are: | |
71 | ||
72 | - **Function name** - the name of the handler function for the command | |
73 | - **Command name** - the identifier of the ``struct cmd_element`` for the | |
74 | command. By convention this should be the function name with ``_cmd`` | |
75 | appended. | |
76 | - **Command definition** - an expression in FRR's CLI grammar that defines the | |
77 | form of the command and its arguments, if any | |
78 | - **Doc string** - a newline-delimited string that documents each element in | |
79 | the command definition | |
80 | ||
81 | In the above example, ``command_name`` is the function name, | |
cb3d8153 QY |
82 | ``command_name_cmd`` is the command name, ``"example..."`` is the definition and |
83 | the last argument is the doc string. The block following the macro is the body | |
84 | of the handler function, details on which are presented later in this section. | |
a42f7818 QY |
85 | |
86 | In order to make the command show up to the user it must be installed into the | |
87 | CLI graph. To do this, call: | |
88 | ||
89 | ``install_element(NODE, &command_name_cmd);`` | |
90 | ||
91 | This will install the command into the specified CLI node. Usually these calls | |
cb3d8153 QY |
92 | are grouped together in a CLI initialization function for a set of commands, and |
93 | the DEFUNs themselves are grouped into the same source file to avoid cluttering | |
94 | the codebase. The names of these files follow the form ``*_vty.[ch]`` by | |
95 | convention. Please do not scatter individual CLI commands in the middle of | |
96 | source files; instead expose the necessary functions in a header and place the | |
97 | command definition in a ``*_vty.[ch]`` file. | |
d1890d04 | 98 | |
a42f7818 | 99 | Definition Grammar |
cb3d8153 | 100 | ^^^^^^^^^^^^^^^^^^ |
a42f7818 QY |
101 | FRR uses its own grammar for defining CLI commands. The grammar draws from |
102 | syntax commonly seen in \*nix manpages and should be fairly intuitive. The | |
103 | parser is implemented in Bison and the lexer in Flex. These may be found in | |
104 | ``lib/command_lex.l`` and ``lib/command_parse.y``, respectively. | |
d1890d04 | 105 | |
a42f7818 QY |
106 | **ProTip**: if you define a new command and find that the parser is |
107 | throwing syntax or other errors, the parser is the last place you want | |
108 | to look. Bison is very stable and if it detects a syntax error, 99% of | |
109 | the time it will be a syntax error in your definition. | |
d1890d04 | 110 | |
cb3d8153 QY |
111 | The formal grammar in BNF is given below. This is the grammar implemented in the |
112 | Bison parser. At runtime, the Bison parser reads all of the CLI strings and | |
113 | builds a combined directed graph that is used to match and interpret user input. | |
e53d5853 QY |
114 | |
115 | Human-friendly explanations of how to use this grammar are given a bit later in | |
116 | this section alongside information on the :ref:`cli-data-structures` constructed | |
117 | by the parser. | |
118 | ||
119 | .. productionlist:: | |
120 | command: `cmd_token_seq` | |
121 | : `cmd_token_seq` `placeholder_token` "..." | |
122 | cmd_token_seq: *empty* | |
123 | : `cmd_token_seq` `cmd_token` | |
124 | cmd_token: `simple_token` | |
125 | : `selector` | |
126 | simple_token: `literal_token` | |
127 | : `placeholder_token` | |
128 | literal_token: WORD `varname_token` | |
129 | varname_token: "$" WORD | |
130 | placeholder_token: `placeholder_token_real` `varname_token` | |
131 | placeholder_token_real: IPV4 | |
132 | : IPV4_PREFIX | |
133 | : IPV6 | |
134 | : IPV6_PREFIX | |
135 | : VARIABLE | |
136 | : RANGE | |
137 | : MAC | |
138 | : MAC_PREFIX | |
139 | selector: "<" `selector_seq_seq` ">" `varname_token` | |
140 | : "{" `selector_seq_seq` "}" `varname_token` | |
141 | : "[" `selector_seq_seq` "]" `varname_token` | |
142 | selector_seq_seq: `selector_seq_seq` "|" `selector_token_seq` | |
143 | : `selector_token_seq` | |
144 | selector_token_seq: `selector_token_seq` `selector_token` | |
145 | : `selector_token` | |
146 | selector_token: `selector` | |
147 | : `simple_token` | |
148 | ||
d1890d04 | 149 | Tokens |
cb3d8153 | 150 | ^^^^^^ |
e53d5853 QY |
151 | The various capitalized tokens in the BNF above are in fact themselves |
152 | placeholders, but not defined as such in the formal grammar; the grammar | |
153 | provides the structure, and the tokens are actually more like a type system for | |
cb3d8153 QY |
154 | the strings you write in your CLI definitions. A CLI definition string is broken |
155 | apart and each piece is assigned a type by the lexer based on a set of regular | |
156 | expressions. The parser uses the type information to verify the string and | |
157 | determine the structure of the CLI graph; additional metadata (such as the raw | |
158 | text of each token) is encoded into the graph as it is constructed by the | |
e53d5853 QY |
159 | parser, but this is merely a dumb copy job. |
160 | ||
161 | Here is a brief summary of the various token types along with examples. | |
a42f7818 QY |
162 | |
163 | +-----------------+-----------------+-------------------------------------------------------------+ | |
164 | | Token type | Syntax | Description | | |
165 | +=================+=================+=============================================================+ | |
166 | | ``WORD`` | ``show ip bgp`` | Matches itself. In the given example every token is a WORD. | | |
167 | +-----------------+-----------------+-------------------------------------------------------------+ | |
168 | | ``IPV4`` | ``A.B.C.D`` | Matches an IPv4 address. | | |
169 | +-----------------+-----------------+-------------------------------------------------------------+ | |
170 | | ``IPV6`` | ``X:X::X:X`` | Matches an IPv6 address. | | |
171 | +-----------------+-----------------+-------------------------------------------------------------+ | |
172 | | ``IPV4_PREFIX`` | ``A.B.C.D/M`` | Matches an IPv4 prefix in CIDR notation. | | |
173 | +-----------------+-----------------+-------------------------------------------------------------+ | |
174 | | ``IPV6_PREFIX`` | ``X:X::X:X/M`` | Matches an IPv6 prefix in CIDR notation. | | |
175 | +-----------------+-----------------+-------------------------------------------------------------+ | |
176 | | ``MAC`` | ``M:A:C`` | Matches a 48-bit mac address. | | |
177 | +-----------------+-----------------+-------------------------------------------------------------+ | |
178 | | ``MAC_PREFIX`` | ``M:A:C/M`` | Matches a 48-bit mac address with a mask. | | |
179 | +-----------------+-----------------+-------------------------------------------------------------+ | |
180 | | ``VARIABLE`` | ``FOOBAR`` | Matches anything. | | |
181 | +-----------------+-----------------+-------------------------------------------------------------+ | |
182 | | ``RANGE`` | ``(X-Y)`` | Matches numbers in the range X..Y inclusive. | | |
183 | +-----------------+-----------------+-------------------------------------------------------------+ | |
184 | ||
185 | When presented with user input, the parser will search over all defined | |
186 | commands in the current context to find a match. It is aware of the various | |
187 | types of user input and has a ranking system to help disambiguate commands. For | |
188 | instance, suppose the following commands are defined in the user's current | |
189 | context: | |
d1890d04 | 190 | |
a42f7818 | 191 | :: |
d1890d04 | 192 | |
cb3d8153 QY |
193 | example command FOO |
194 | example command (22-49) | |
195 | example command A.B.C.D/X | |
a42f7818 QY |
196 | |
197 | The following table demonstrates the matcher's choice for a selection of | |
198 | possible user input. | |
199 | ||
cb3d8153 QY |
200 | +---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+ |
201 | | Input | Matched command | Reason | | |
202 | +=================================+===========================+==============================================================================================================+ | |
203 | | ``example command eLi7eH4xx0r`` | example command FOO | ``eLi7eH4xx0r`` is not an integer or IPv4 prefix, | | |
204 | | | | but FOO is a variable and matches all input. | | |
205 | +---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+ | |
206 | | ``example command 42`` | example command (22-49) | ``42`` is not an IPv4 prefix. It does match both | | |
207 | | | | ``(22-49)`` and ``FOO``, but RANGE tokens are more specific and have a higher priority than VARIABLE tokens. | | |
208 | +---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+ | |
209 | | ``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. | | |
210 | +---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+ | |
a42f7818 QY |
211 | |
212 | Rules | |
cb3d8153 QY |
213 | ^^^^^ |
214 | There are also constructs which allow optional tokens, mutual exclusion, | |
215 | one-or-more selection and repetition. | |
a42f7818 QY |
216 | |
217 | - ``<angle|brackets>`` -- Contain sequences of tokens separated by pipes and | |
218 | provide mutual exclusion. User input matches at most one option. | |
219 | - ``[square brackets]`` -- Contains sequences of tokens that can be omitted. | |
220 | ``[<a|b>]`` can be shortened to ``[a|b]``. | |
221 | - ``{curly|braces}`` -- similar to angle brackets, but instead of mutual | |
222 | exclusion, curly braces indicate that one or more of the pipe-separated | |
223 | sequences may be provided in any order. | |
224 | - ``VARIADICS...`` -- Any token which accepts input (anything except WORD) | |
225 | which occurs as the last token of a line may be followed by an ellipsis, | |
226 | which indicates that input matching the token may be repeated an unlimited | |
227 | number of times. | |
d1890d04 QY |
228 | - ``$name`` -- Specify a variable name for the preceding token. See |
229 | "Variable Names" below. | |
230 | ||
231 | Some general notes: | |
232 | ||
233 | - Options are allowed at the beginning of the command. The developer is | |
234 | entreated to use these extremely sparingly. They are most useful for | |
a42f7818 QY |
235 | implementing the 'no' form of configuration commands. Please think carefully |
236 | before using them for anything else. There is usually a better solution, even | |
237 | if it is just separating out the command definition into separate ones. | |
238 | - The developer should judiciously apply separation of concerns when defining | |
239 | commands. CLI definitions for two unrelated or vaguely related commands or | |
240 | configuration items should be defined in separate commands. Clarity is | |
241 | preferred over LOC (within reason). | |
d1890d04 QY |
242 | - The maximum number of space-separated tokens that can be entered is |
243 | presently limited to 256. Please keep this limit in mind when | |
244 | implementing new CLI. | |
245 | ||
246 | Variable Names | |
cb3d8153 QY |
247 | ^^^^^^^^^^^^^^ |
248 | The parser tries to fill the "varname" field on each token. This can happen | |
249 | either manually or automatically. Manual specifications work by appending | |
250 | ``$name`` after the input specifier: | |
d1890d04 QY |
251 | |
252 | :: | |
253 | ||
cb3d8153 | 254 | foo bar$cmd WORD$name A.B.C.D$ip |
d1890d04 | 255 | |
cb3d8153 QY |
256 | Note that you can also assign variable names to fixed input tokens, this can be |
257 | useful if multiple commands share code. You can also use "$name" after a | |
258 | multiple-choice option: | |
d1890d04 QY |
259 | |
260 | :: | |
261 | ||
cb3d8153 | 262 | foo bar <A.B.C.D|X:X::X:X>$addr [optionA|optionB]$mode |
d1890d04 | 263 | |
cb3d8153 QY |
264 | The variable name is in this case assigned to the last token in each of the |
265 | branches. | |
d1890d04 | 266 | |
cb3d8153 | 267 | Automatic assignment of variable names works by applying the following rules: |
d1890d04 QY |
268 | |
269 | - manual names always have priority | |
cb3d8153 QY |
270 | - a ``[no]`` at the beginning receives ``no`` as varname on the ``no`` token |
271 | - ``VARIABLE`` tokens whose text is not ``WORD`` or ``NAME`` receive a cleaned | |
272 | lowercase version of the token text as varname, e.g. ``ROUTE-MAP`` becomes | |
273 | ``route_map``. | |
274 | - other variable tokens (i.e. everything except "fixed") receive the text of | |
275 | the preceding fixed token as varname, if one can be found. E.g. | |
276 | ``ip route A.B.C.D/M INTERFACE`` assigns "route" to the ``A.B.C.D/M`` token. | |
d1890d04 | 277 | |
cb3d8153 QY |
278 | These rules should make it possible to avoid manual varname assignment in 90% of |
279 | the cases. | |
d1890d04 | 280 | |
cb3d8153 QY |
281 | Doc Strings |
282 | ^^^^^^^^^^^ | |
283 | Each token in a command definition should be documented with a brief doc string | |
284 | that informs a user of the meaning and/or purpose of the subsequent command | |
285 | tree. These strings are provided as the last parameter to DEFUN macros, | |
286 | concatenated together and separated by an escaped newline (``\n``). These are | |
287 | best explained by example. | |
d1890d04 | 288 | |
cb3d8153 QY |
289 | :: |
290 | ||
291 | DEFUN (config_terminal, | |
292 | config_terminal_cmd, | |
293 | "configure terminal", | |
294 | "Configuration from vty interface\n" | |
295 | "Configuration terminal\n") | |
296 | ||
297 | The last parameter is split into two lines for readability. Two newline | |
298 | delimited doc strings are present, one for each token in the command. The second | |
299 | string documents the functionality of the ``terminal`` command in the | |
300 | ``configure`` subtree. | |
301 | ||
302 | Note that the first string, for ``configure`` does not contain documentation for | |
303 | 'terminal'. This is because the CLI is best envisioned as a tree, with tokens | |
304 | defining branches. An imaginary ``start`` token is the root of every command in | |
305 | a CLI node. Each subsequent written token descends into a subtree, so the | |
306 | documentation for that token ideally summarizes all the functionality contained | |
307 | in the subtree. | |
308 | ||
309 | A consequence of this structure is that the developer must be careful to use the | |
310 | same doc strings when defining multiple commands that are part of the same tree. | |
311 | Commands which share prefixes must share the same doc strings for those | |
312 | prefixes. On startup the parser will generate warnings if it notices | |
313 | inconsistent doc strings. Behavior is undefined; the same token may show up | |
314 | twice in completions, with different doc strings, or it may show up once with a | |
315 | random doc string. Parser warnings should be heeded and fixed to avoid confusing | |
316 | users. | |
317 | ||
318 | The number of doc strings provided must be equal to the amount of tokens present | |
319 | in the command definition, read left to right, ignoring any special constructs. | |
320 | ||
321 | In the examples below, each arrowed token needs a doc string. | |
d1890d04 QY |
322 | |
323 | :: | |
324 | ||
cb3d8153 QY |
325 | "show ip bgp" |
326 | ^ ^ ^ | |
327 | ||
328 | "command <foo|bar> [example]" | |
329 | ^ ^ ^ ^ | |
330 | ||
331 | DEFPY | |
332 | ^^^^^ | |
333 | ``DEFPY(...)`` is an enhanced version of ``DEFUN()`` which is preprocessed by | |
334 | :file:`python/clidef.py`. The python script parses the command definition | |
335 | string, extracts variable names and types, and generates a C wrapper function | |
336 | that parses the variables and passes them on. This means that in the CLI | |
337 | function body, you will receive additional parameters with appropriate types. | |
338 | ||
339 | This is best explained by an example. Invoking ``DEFPY`` like this: | |
340 | ||
341 | .. code-block:: c | |
342 | ||
343 | DEFPY(func, func_cmd, "[no] foo bar A.B.C.D (0-99)$num", "...help...") | |
d1890d04 | 344 | |
cb3d8153 | 345 | defines the handler function like this: |
d1890d04 | 346 | |
cb3d8153 | 347 | .. code-block:: c |
d1890d04 | 348 | |
cb3d8153 QY |
349 | func(self, vty, argc, argv, /* standard CLI arguments */ |
350 | const char *no, /* unparsed "no" */ | |
351 | struct in_addr bar, /* parsed IP address */ | |
352 | const char *bar_str, /* unparsed IP address */ | |
353 | long num, /* parsed num */ | |
354 | const char *num_str) /* unparsed num */ | |
d1890d04 | 355 | |
cb3d8153 QY |
356 | Note that as documented in the previous section, ``bar`` is automatically |
357 | applied as variable name for ``A.B.C.D``. The Python script then detects this as | |
358 | an IP address argument and generates code to parse it into a ``struct in_addr``, | |
359 | passing it in ``bar``. The raw value is passed in ``bar_str``. The range/number | |
360 | argument works in the same way with the explicitly given variable name. | |
d1890d04 QY |
361 | |
362 | Type rules | |
cb3d8153 QY |
363 | """""""""" |
364 | ||
365 | +----------------------------+--------------------------------+--------------------------+ | |
366 | | Token(s) | Type | Value if omitted by user | | |
367 | +============================+================================+==========================+ | |
368 | | ``A.B.C.D`` | ``struct in_addr`` | ``0.0.0.0`` | | |
369 | +----------------------------+--------------------------------+--------------------------+ | |
370 | | ``X:X::X:X`` | ``struct in6_addr`` | ``::`` | | |
371 | +----------------------------+--------------------------------+--------------------------+ | |
372 | | ``A.B.C.D + X:X::X:X`` | ``const union sockunion *`` | ``NULL`` | | |
373 | +----------------------------+--------------------------------+--------------------------+ | |
374 | | ``A.B.C.D/M`` | ``const struct prefix_ipv4 *`` | ``NULL`` | | |
375 | +----------------------------+--------------------------------+--------------------------+ | |
376 | | ``X:X::X:X/M`` | ``const struct prefix_ipv6 *`` | ``NULL`` | | |
377 | +----------------------------+--------------------------------+--------------------------+ | |
378 | | ``A.B.C.D/M + X:X::X:X/M`` | ``const struct prefix *`` | ``NULL`` | | |
379 | +----------------------------+--------------------------------+--------------------------+ | |
380 | | ``(0-9)`` | ``long`` | ``0`` | | |
381 | +----------------------------+--------------------------------+--------------------------+ | |
382 | | ``VARIABLE`` | ``const char *`` | ``NULL`` | | |
383 | +----------------------------+--------------------------------+--------------------------+ | |
384 | | ``word`` | ``const char *`` | ``NULL`` | | |
385 | +----------------------------+--------------------------------+--------------------------+ | |
386 | | *all other* | ``const char *`` | ``NULL`` | | |
387 | +----------------------------+--------------------------------+--------------------------+ | |
d1890d04 QY |
388 | |
389 | Note the following details: | |
390 | ||
a42f7818 | 391 | - Not all parameters are pointers, some are passed as values. |
cb3d8153 QY |
392 | - When the type is not ``const char *``, there will be an extra ``_str`` |
393 | argument with type ``const char *``. | |
394 | - You can give a variable name not only to ``VARIABLE`` tokens but also to | |
395 | ``word`` tokens (e.g. constant words). This is useful if some parts of a | |
396 | command are optional. The type will be ``const char *``. | |
d1890d04 | 397 | - ``[no]`` will be passed as ``const char *no``. |
cb3d8153 QY |
398 | - Pointers will be ``NULL`` when the argument is optional and the user did not |
399 | use it. | |
400 | - If a parameter is not a pointer, but is optional and the user didn't use it, | |
401 | the default value will be passed. Check the ``_str`` argument if you need to | |
402 | determine whether the parameter was omitted. | |
403 | - If the definition contains multiple parameters with the same variable name, | |
404 | they will be collapsed into a single function parameter. The python code will | |
405 | detect if the types are compatible (i.e. IPv4 + IPv6 variants) and choose a | |
406 | corresponding C type. | |
407 | - The standard DEFUN parameters (``self, vty, argc, argv``) are still present | |
408 | and can be used. A DEFUN can simply be **edited into a DEFPY without further | |
409 | changes and it will still work**; this allows easy forward migration. | |
410 | - A file may contain both ``DEFUN`` and ``DEFPY`` statements. | |
d1890d04 QY |
411 | |
412 | Getting a parameter dump | |
cb3d8153 QY |
413 | """""""""""""""""""""""" |
414 | The clidef.py script can be called to get a list of DEFUNs/DEFPYs with the | |
415 | parameter name/type list: | |
d1890d04 QY |
416 | |
417 | :: | |
418 | ||
cb3d8153 | 419 | lib/clippy python/clidef.py --all-defun --show lib/plist.c > /dev/null |
d1890d04 QY |
420 | |
421 | The generated code is printed to stdout, the info dump to stderr. The | |
cb3d8153 QY |
422 | ``--all-defun`` argument will make it process DEFUN blocks as well as DEFPYs, |
423 | which is useful prior to converting some DEFUNs. **The dump does not list the | |
424 | ``_str`` arguments** to keep the output shorter. | |
d1890d04 | 425 | |
cb3d8153 QY |
426 | Note that the ``clidef.py`` script cannot be run with python directly, it needs |
427 | to be run with *clippy* since the latter makes the CLI parser available. | |
d1890d04 QY |
428 | |
429 | Include & Makefile requirements | |
cb3d8153 QY |
430 | """"""""""""""""""""""""""""""" |
431 | A source file that uses DEFPY needs to include the ``*_clippy.c`` file **before | |
432 | all DEFPY statements**: | |
d1890d04 | 433 | |
cb3d8153 | 434 | .. code-block:: c |
d1890d04 | 435 | |
cb3d8153 QY |
436 | /* GPL header */ |
437 | #include ... | |
438 | ... | |
439 | #ifndef VTYSH_EXTRACT_PL | |
440 | #include "daemon/filename_clippy.c" | |
441 | #endif | |
d1890d04 | 442 | |
cb3d8153 QY |
443 | DEFPY(...) |
444 | DEFPY(...) | |
d1890d04 | 445 | |
cb3d8153 | 446 | install_element(...) |
d1890d04 | 447 | |
cb3d8153 QY |
448 | This dependency needs to be marked in ``Makefile.am`` or ``subdir.am``: (there |
449 | is no ordering requirement) | |
d1890d04 | 450 | |
cb3d8153 | 451 | .. code-block:: make |
d1890d04 | 452 | |
cb3d8153 | 453 | # ... |
d1890d04 | 454 | |
cb3d8153 QY |
455 | # if linked into a LTLIBRARY (.la/.so): |
456 | filename.lo: filename_clippy.c | |
d1890d04 | 457 | |
cb3d8153 QY |
458 | # if linked into an executable or static library (.a): |
459 | filename.o: filename_clippy.c | |
d1890d04 | 460 | |
cb3d8153 QY |
461 | Handlers |
462 | ^^^^^^^^ | |
463 | The block that follows a CLI definition is executed when a user enters input | |
464 | that matches the definition. Its function signature looks like this: | |
d1890d04 | 465 | |
cb3d8153 | 466 | .. code-block:: c |
d1890d04 | 467 | |
cb3d8153 | 468 | int (*func) (const struct cmd_element *, struct vty *, int, struct cmd_token *[]); |
d1890d04 | 469 | |
cb3d8153 QY |
470 | The first argument is the command definition struct. The last argument is an |
471 | ordered array of tokens that correspond to the path taken through the graph, and | |
472 | the argument just prior to that is the length of the array. | |
d1890d04 | 473 | |
cb3d8153 QY |
474 | The arrangement of the token array has changed from Quagga's CLI implementation. |
475 | In the old system, missing arguments were padded with ``NULL`` so that the same | |
476 | parts of a command would show up at the same indices regardless of what was | |
477 | entered. The new system does not perform such padding and therefore it is | |
478 | generally *incorrect* to assume consistent indices in this array. As a simple | |
479 | example: | |
480 | ||
481 | Command definition: | |
d1890d04 QY |
482 | |
483 | :: | |
484 | ||
cb3d8153 | 485 | command [foo] <bar|baz> |
d1890d04 | 486 | |
cb3d8153 | 487 | User enters: |
d1890d04 | 488 | |
cb3d8153 QY |
489 | :: |
490 | ||
491 | command foo bar | |
492 | ||
493 | Array: | |
494 | ||
495 | :: | |
496 | ||
497 | [0] -> command | |
498 | [1] -> foo | |
499 | [2] -> bar | |
500 | ||
501 | User enters: | |
d1890d04 QY |
502 | |
503 | :: | |
504 | ||
cb3d8153 QY |
505 | command baz |
506 | ||
507 | Array: | |
508 | ||
509 | :: | |
510 | ||
511 | [0] -> command | |
512 | [1] -> baz | |
d1890d04 | 513 | |
d1890d04 | 514 | |
e53d5853 QY |
515 | .. _cli-data-structures: |
516 | ||
d1890d04 QY |
517 | Data Structures |
518 | --------------- | |
cb3d8153 QY |
519 | On startup, the CLI parser sequentially parses each command string definition |
520 | and constructs a directed graph with each token forming a node. This graph is | |
521 | the basis of the entire CLI system. It is used to match user input in order to | |
522 | generate command completions and match commands to functions. | |
d1890d04 | 523 | |
cb3d8153 QY |
524 | There is one graph per CLI node (not the same as a graph node in the CLI graph). |
525 | The CLI node struct keeps a reference to its graph (see :file:`lib/command.h`). | |
d1890d04 QY |
526 | |
527 | While most of the graph maintains the form of a tree, special constructs | |
cb3d8153 QY |
528 | outlined in the Rules section introduce some quirks. ``<>``, ``[]`` and ``{}`` |
529 | form self-contained 'subgraphs'. Each subgraph is a tree except that all of the | |
530 | 'leaves' actually share a child node. This helps with minimizing graph size and | |
531 | debugging. | |
d1890d04 | 532 | |
e53d5853 QY |
533 | As a working example, here is the graph of the following command: :: |
534 | ||
535 | show [ip] bgp neighbors [<A.B.C.D|X:X::X:X|WORD>] [json] | |
536 | ||
88ba7d9e | 537 | .. figure:: ../figures/cligraph.png |
e53d5853 QY |
538 | :align: center |
539 | ||
540 | Graph of example CLI command | |
d1890d04 | 541 | |
d1890d04 | 542 | |
e53d5853 | 543 | ``FORK`` and ``JOIN`` nodes are plumbing nodes that don't correspond to user |
d1890d04 QY |
544 | input. They're necessary in order to deduplicate these constructs where |
545 | applicable. | |
546 | ||
e53d5853 | 547 | Options follow the same form, except that there is an edge from the ``FORK`` |
cb3d8153 QY |
548 | node to the ``JOIN`` node. Since all of the subgraphs in the example command are |
549 | optional, all of them have this edge. | |
d1890d04 | 550 | |
e53d5853 QY |
551 | Keywords follow the same form, except that there is an edge from ``JOIN`` to |
552 | ``FORK``. Because of this the CLI graph cannot be called acyclic. There is | |
553 | special logic in the input matching code that keeps a stack of paths already | |
554 | taken through the node in order to disallow following the same path more than | |
555 | once. | |
d1890d04 | 556 | |
e53d5853 QY |
557 | Variadics are a bit special; they have an edge back to themselves, which allows |
558 | repeating the same input indefinitely. | |
d1890d04 | 559 | |
e53d5853 QY |
560 | The leaves of the graph are nodes that have no out edges. These nodes are |
561 | special; their data section does not contain a token, as most nodes do, or | |
cb3d8153 QY |
562 | ``NULL``, as in ``FORK``/``JOIN`` nodes, but instead has a pointer to a |
563 | ``cmd_element``. All paths through the graph that terminate on a leaf are | |
564 | guaranteed to be defined by that command. When a user enters a complete command, | |
565 | the command matcher tokenizes the input and executes a DFS on the CLI graph. If | |
566 | it is simultaneously able to exhaust all input (one input token per graph node), | |
567 | and then find exactly one leaf connected to the last node it reaches, then the | |
568 | input has matched the corresponding command and the command is executed. If it | |
569 | finds more than one node, then the command is ambiguous (more on this in | |
570 | deduplication). If it cannot exhaust all input, the command is unknown. If it | |
571 | exhausts all input but does not find an edge node, the command is incomplete. | |
e53d5853 QY |
572 | |
573 | The parser uses an incremental strategy to build the CLI graph for a node. Each | |
574 | command is parsed into its own graph, and then this graph is merged into the | |
cb3d8153 QY |
575 | overall graph. During this merge step, the parser makes a best-effort attempt to |
576 | remove duplicate nodes. If it finds a node in the overall graph that is equal to | |
577 | a node in the corresponding position in the command graph, it will intelligently | |
578 | merge the properties from the node in the command graph into the | |
e53d5853 QY |
579 | already-existing node. Subgraphs are also checked for isomorphism and merged |
580 | where possible. The definition of whether two nodes are 'equal' is based on the | |
581 | equality of some set of token properties; read the parser source for the most | |
d1890d04 QY |
582 | up-to-date definition of equality. |
583 | ||
e53d5853 QY |
584 | When the parser is unable to deduplicate some complicated constructs, this can |
585 | result in two identical paths through separate parts of the graph. If this | |
586 | occurs and the user enters input that matches these paths, they will receive an | |
cb3d8153 QY |
587 | 'ambiguous command' error and will be unable to execute the command. Most of the |
588 | time the parser can detect and warn about duplicate commands, but it will not | |
589 | always be able to do this. Hence care should be taken before defining a new | |
590 | command to ensure it is not defined elsewhere. | |
d1890d04 | 591 | |
cb3d8153 QY |
592 | struct cmd\_token |
593 | ^^^^^^^^^^^^^^^^^ | |
594 | ||
595 | .. code-block:: c | |
596 | ||
597 | /* Command token struct. */ | |
598 | struct cmd_token | |
599 | { | |
600 | enum cmd_token_type type; // token type | |
601 | uint8_t attr; // token attributes | |
602 | bool allowrepeat; // matcher can match token repetitively? | |
603 | ||
604 | char *text; // token text | |
605 | char *desc; // token description | |
606 | long long min, max; // for ranges | |
607 | char *arg; // user input that matches this token | |
608 | char *varname; // variable name | |
609 | }; | |
610 | ||
611 | This struct is used in the CLI graph to match input against. It is also used to | |
612 | pass user input to command handler functions, as it is frequently useful for | |
613 | handlers to have access to that information. When a command is matched, the | |
614 | sequence of ``cmd_tokens`` that form the matching path are duplicated and placed | |
615 | in order into ``*argv[]``. Before this happens the ``->arg`` field is set to | |
616 | point at the snippet of user input that matched it. | |
617 | ||
618 | For most nontrivial commands the handler function will need to determine which | |
619 | of the possible matching inputs was entered. Previously this was done by looking | |
620 | at the first few characters of input. This is now considered an anti-pattern and | |
621 | should be avoided. Instead, the ``->type`` or ``->text`` fields for this logic. | |
622 | The ``->type`` field can be used when the possible inputs differ in type. When | |
623 | the possible types are the same, use the ``->text`` field. This field has the | |
624 | full text of the corresponding token in the definition string and using it makes | |
625 | for much more readable code. An example is helpful. | |
d1890d04 | 626 | |
cb3d8153 | 627 | Command definition: |
d1890d04 | 628 | |
a42f7818 QY |
629 | :: |
630 | ||
cb3d8153 | 631 | command <(1-10)|foo|BAR> |
d1890d04 | 632 | |
cb3d8153 QY |
633 | In this example, the user may enter any one of: |
634 | - an integer between 1 and 10 | |
635 | - "foo" | |
636 | - anything at all | |
d1890d04 | 637 | |
cb3d8153 | 638 | If the user enters "command f", then: |
d1890d04 QY |
639 | |
640 | :: | |
641 | ||
cb3d8153 QY |
642 | argv[1]->type == WORD_TKN |
643 | argv[1]->arg == "f" | |
644 | argv[1]->text == "foo" | |
d1890d04 | 645 | |
cb3d8153 QY |
646 | Range tokens have some special treatment; a token with ``->type == RANGE_TKN`` |
647 | will have the ``->min`` and ``->max`` fields set to the bounding values of the | |
648 | range. | |
d1890d04 | 649 | |
cb3d8153 QY |
650 | struct cmd\_element |
651 | ^^^^^^^^^^^^^^^^^^^ | |
d1890d04 | 652 | |
cb3d8153 | 653 | .. code-block:: c |
d1890d04 | 654 | |
cb3d8153 QY |
655 | struct cmd_node { |
656 | /* Node index. */ | |
657 | enum node_type node; | |
d1890d04 | 658 | |
cb3d8153 QY |
659 | /* Prompt character at vty interface. */ |
660 | const char *prompt; | |
d1890d04 | 661 | |
cb3d8153 QY |
662 | /* Is this node's configuration goes to vtysh ? */ |
663 | int vtysh; | |
d1890d04 | 664 | |
cb3d8153 QY |
665 | /* Node's configuration write function */ |
666 | int (*func)(struct vty *); | |
d1890d04 | 667 | |
cb3d8153 QY |
668 | /* Node's command graph */ |
669 | struct graph *cmdgraph; | |
d1890d04 | 670 | |
cb3d8153 QY |
671 | /* Vector of this node's command list. */ |
672 | vector cmd_vector; | |
d1890d04 | 673 | |
cb3d8153 QY |
674 | /* Hashed index of command node list, for de-dupping primarily */ |
675 | struct hash *cmd_hash; | |
676 | }; | |
d1890d04 | 677 | |
cb3d8153 QY |
678 | This struct corresponds to a CLI mode. The last three fields are most relevant |
679 | here. | |
d1890d04 | 680 | |
cb3d8153 QY |
681 | cmdgraph |
682 | This is a pointer to the command graph that was described in the first part | |
683 | of this section. It is the datastructure used for matching user input to | |
684 | commands. | |
d1890d04 | 685 | |
cb3d8153 QY |
686 | cmd_vector |
687 | This is a list of all the ``struct cmd_element`` defined in the mode. | |
d1890d04 | 688 | |
cb3d8153 QY |
689 | cmd_hash |
690 | This is a hash table of all the ``struct cmd_element`` defined in the mode. | |
691 | When ``install_element`` is called, it checks that the element it is given is | |
692 | not already present in the hash table as a safeguard against duplicate calls | |
693 | resulting in a command being defined twice, which renders the command | |
694 | ambiguous. | |
695 | ||
696 | All ``struct cmd_node`` are themselves held in a static vector defined in | |
697 | :file:`lib/command.c` that defines the global CLI space. | |
698 | ||
699 | Command Abbreviation & Matching Priority | |
700 | ---------------------------------------- | |
701 | It is possible for users to elide parts of tokens when the CLI matcher does not | |
702 | need them to make an unambiguous match. This is best explained by example. | |
d1890d04 QY |
703 | |
704 | Command definitions: | |
705 | ||
706 | :: | |
707 | ||
cb3d8153 QY |
708 | command dog cow |
709 | command dog crow | |
d1890d04 QY |
710 | |
711 | User input: | |
712 | ||
713 | :: | |
714 | ||
cb3d8153 QY |
715 | c d c -> ambiguous command |
716 | c d co -> match "command dog cow" | |
717 | ||
d1890d04 | 718 | |
cb3d8153 QY |
719 | The parser will look ahead and attempt to disambiguate the input based on tokens |
720 | later on in the input string. | |
d1890d04 QY |
721 | |
722 | Command definitions: | |
723 | ||
724 | :: | |
725 | ||
cb3d8153 QY |
726 | show ip bgp A.B.C.D |
727 | show ipv6 bgp X:X::X:X | |
d1890d04 QY |
728 | |
729 | User enters: | |
730 | ||
731 | :: | |
732 | ||
cb3d8153 QY |
733 | s i b 4.3.2.1 -> match "show ip bgp A.B.C.D" |
734 | s i b ::e0 -> match "show ipv6 bgp X:X::X:X" | |
d1890d04 | 735 | |
cb3d8153 QY |
736 | Reading left to right, both of these commands would be ambiguous since 'i' does |
737 | not explicitly select either 'ip' or 'ipv6'. However, since the user later | |
738 | provides a token that matches only one of the commands (an IPv4 or IPv6 address) | |
739 | the parser is able to look ahead and select the appropriate command. This has | |
740 | some implications for parsing the ``*argv[]`` that is passed to the command | |
741 | handler. | |
d1890d04 QY |
742 | |
743 | Now consider a command definition such as: | |
744 | ||
745 | :: | |
746 | ||
cb3d8153 | 747 | command <foo|VAR> |
d1890d04 | 748 | |
cb3d8153 QY |
749 | 'foo' only matches the string 'foo', but 'VAR' matches any input, including |
750 | 'foo'. Who wins? In situations like this the matcher will always choose the | |
751 | 'better' match, so 'foo' will win. | |
d1890d04 QY |
752 | |
753 | Consider also: | |
754 | ||
755 | :: | |
756 | ||
8957c78a | 757 | show <ip|ipv6> foo |
d1890d04 QY |
758 | |
759 | User input: | |
760 | ||
761 | :: | |
762 | ||
8957c78a | 763 | show ip foo |
d1890d04 | 764 | |
cb3d8153 | 765 | ``ip`` partially matches ``ipv6`` but exactly matches ``ip``, so ``ip`` will |
d1890d04 QY |
766 | win. |
767 | ||
8957c78a QY |
768 | Inspection & Debugging |
769 | ---------------------- | |
770 | ||
d1890d04 | 771 | Permutations |
8957c78a QY |
772 | ^^^^^^^^^^^^ |
773 | It is sometimes useful to check all the possible combinations of input that | |
774 | would match an arbitrary definition string. There is a tool in | |
cb3d8153 QY |
775 | :file:`tools/permutations` that reads CLI definition strings on ``stdin`` and |
776 | prints out all matching input permutations. It also dumps a text representation | |
777 | of the graph, which is more useful for debugging than anything else. It looks | |
778 | like this: | |
d1890d04 | 779 | |
8957c78a | 780 | .. code-block:: shell |
d1890d04 | 781 | |
cb3d8153 | 782 | $ ./permutations "show [ip] bgp [<view|vrf> WORD]" |
d1890d04 | 783 | |
cb3d8153 QY |
784 | show ip bgp view WORD |
785 | show ip bgp vrf WORD | |
786 | show ip bgp | |
787 | show bgp view WORD | |
788 | show bgp vrf WORD | |
789 | show bgp | |
d1890d04 | 790 | |
8957c78a QY |
791 | This functionality is also built into VTY/VTYSH; :clicmd:`list permutations` |
792 | will list all possible matching input permutations in the current CLI node. | |
793 | ||
794 | Graph Inspection | |
795 | ^^^^^^^^^^^^^^^^ | |
796 | When in the Telnet or VTYSH console, :clicmd:`show cli graph` will dump the | |
797 | entire command space of the current mode in the DOT graph language. This can be | |
798 | fed into one of the various GraphViz layout engines, such as ``dot``, | |
799 | ``neato``, etc. | |
800 | ||
801 | For example, to generate an image of the entire command space for the top-level | |
802 | mode (``ENABLE_NODE``): | |
803 | ||
804 | .. code-block:: shell | |
805 | ||
806 | sudo vtysh -c 'show cli graph' | dot -Tjpg -Grankdir=LR > graph.jpg | |
807 | ||
808 | To do the same for the BGP mode: | |
809 | ||
810 | .. code-block:: shell | |
811 | ||
812 | sudo vtysh -c 'conf t' -c 'router bgp' -c 'show cli graph' | dot -Tjpg -Grankdir=LR > bgpgraph.jpg | |
813 | ||
814 | This information is very helpful when debugging command resolution, tracking | |
815 | down duplicate / ambiguous commands, and debugging patches to the CLI graph | |
816 | builder. |