CLI internals

From VyOS Wiki
Jump to: navigation, search

There basically are three components that form VyOS CLI (command line interface):

  • vbash
  • completion rules
  • templates

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

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
  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>
vyos@vyos:~$ show echo something
The argument was: something

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