There basically are three components that form VyOS CLI (command line interface):
- completion rules
vbash is modified bash (Bourne shell). One of the most significant modifications is command completion from the first level (in usual bash completion works only when a command or it's part already typed).
Completion rules rely on bash programmable autocompletion mechanism. You can find the script at /etc/bash_completion.d/vyatta-cfg Configuration mode "show", "set" and other commands are defined there, as well as many other things.
The templates is what is actually used to add new commands. They are located at /opt/vyatta/share. There are two directories: vyatta-cfg/templates for configuration mode templates and vyatta-op/templates for operational mode templates.
Templates are text files that contain tags. Tags for operational and configuration mode templates are different.
The commands are represented by directories under templates/ containing node.def file. node.def is the template file. If command allows (or requires) subcommands (like "show interfaces ethernet"), those subcommands are in node.tag subdirectory. This is what actually is under vyatta-op/templates:
# ls -l /opt/vyatta/share/vyatta-op/templates/ total 4 drwxr-xr-x 1 root root 57 Aug 20 11:37 add drwxr-xr-x 1 root root 283 Aug 20 11:38 clear drwxr-xr-x 1 root root 31 Aug 20 11:37 configure drwxr-xr-x 1 root root 48 Aug 20 11:37 connect drwxr-xr-x 1 root root 117 Aug 20 11:38 debug drwxr-xr-x 1 root root 56 Aug 20 11:37 delete drwxr-xr-x 1 root root 48 Aug 20 11:37 disconnect drwxr-xr-x 1 root root 43 Aug 20 11:37 format drwxr-xr-x 1 root root 51 Aug 20 11:37 generate drwxr-xr-x 1 root root 31 Aug 20 11:37 init-floppy drwxr-xr-x 1 root root 31 Aug 20 11:37 install-image drwxr-xr-x 1 root root 31 Aug 20 11:37 install-system drwxr-xr-x 1 root root 44 Aug 20 11:38 no [SNIP]
Let's add a dummy feature to demonstrate how it works. We will add "show echo" command that just shows its own argument. All code in templates is written in bourne shell scripting language. First we create a directory for it:
$ sudo mkdir /opt/vyatta/share/vyatta-op/templates/show/echo
Then we create its template:
$ sudo touch /opt/vyatta/share/vyatta-op/templates/show/echo/node.def
And then we put the following into node.def (e.g. with "nano" editor which is included in VyOS):
help: Demonstration feature, just shows the argument run: echo "If you give me an argument, I will show it."
Now we can see our new command in completion help:
vyos@vyos:~$ show <TAB> Possible completions: arp Show Address Resolution Protocol (ARP) information bridge Show bridging information [SNIP] echo Demonstration feature, just shows the command argument
And execute our command:
vyos@vyos:~$ show echo
If you give me an argument, I will show it.
Now we can add the function to show the argument.
vyos@vyos:~$ sudo mkdir /opt/vyatta/share/vyatta-op/templates/show/echo/node.tag vyos@vyos:~$ sudo touch /opt/vyatta/share/vyatta-op/templates/show/echo/node.tag/node.def
Put the following into its node.def:
help: Show the argument allowed: echo Anything run: echo $3
And now see its completion and execute it:
vyos@vyos:~$ show echo <TAB> Anything vyos@vyos:~$ show echo something The argument was: something vyos@vyos:~$
So to add an operational command you need to create its backend and templates. Some commands are very simple (e.g. "show hardware pci" is just a wrapper for lspci), other may have complex backends (e.g. "show interfaces").
And the summary of tags allowed in operational mode templates:
- help: Contains completion help text
- allowed: Contains code that shows allowed arguments
- run: Contains code that is ran on command execution