CLI

From VyOS Wiki
(Redirected from Command line interface)
Jump to: navigation, search

VyOS provides a unified command line interface to all its features.

The CLI is modal

There are two modes: operational mode and configuration mode. They are often referred to as op mode and conf mode for brevity.

In operational mode you can view system information such as routing tables, firewall rule counters and so on. You can also initiate system reload, shutdown, or upgrade from this mode. You cannot change the system configuration from op mode.

In configuration mode you can change the system configuration. You can switch to this mode with configure command and leave with exit.

You can tell which mode you are in by command line prompt. In op mode it ends with "$", while in conf mode it ends with "#".

You can execute op mode commands from conf mode with "run" prefix, as in "run show ip route". VyOS people sometimes use "run" in conversations to emphasize that they are talking about op mode commands, since in some cases there are op mode and conf mode commands with the same name but different purpose, e.g. "show interfaces" in op mode that shows network interface information and "show interfaces" in conf mode that shows configuration of all network interfaces.

The CLI is stateful

Unlike e.g. Cisco IOS, VyOS doesn't apply changes immediately when you issue a command.

When VyOS boots, it loads the system configuration from /config/config.boot file. It is loaded into running config.

When you enter configuration mode, a config session is created and you get your own copy of the running config, we call it proposed config. This is what you edit with set/delete command.

You can view your changes and discard them with discard command or commit with commit. If your proposed configuraton contains errors (e.g. you are trying to use two mutually exclusive options at the same time), commit fails and the running config remains unchanged.

Example

Here's an example session:

Connecting to the router:

[admin@workstation ~]$ ssh vyos@router.example.com
Welcome to VyOS
vyos@router.example.com's password: 
Linux vyos 3.13.11-1-amd64-vyos #1 SMP Mon Feb 9 18:34:28 UTC 2015 x86_64
Welcome to VyOS.
This system is open-source software. The exact distribution terms for 
each module comprising the full system are described in the individual 
files in /usr/share/doc/*/copyright.
Last login: Tue Feb 17 08:43:14 2015 from 203.0.113.1
vyos@router:~$

Now we are in op mode. Let's execute a command:

vyos@router:~$ show system uptime 
 12:12:11 up 14 days,  2:45,  1 user,  load average: 0.02, 0.02, 0.05

Now let's switch to conf mode:

vyos@router:~$ configure 
[edit]
vyos@router# 

As we can see from the "#" prompt, we are in conf mode now. Now we can view the whole configuration with "show", or specific subtree with "show <path>".

vyos@vyos-test-2# show system name-server 
 name-server 192.0.2.10

Let's add another name server:

vyos@router# set system name-server 192.0.2.20 
[edit]
vyos@router# show system name-server 
 name-server 192.0.2.10
+name-server 192.0.2.20

The "+" sign in front of a config option means that we have added it. Maybe delete the old name server?

vyos@router# show system name-server 
-name-server 192.0.2.10
+name-server 192.0.2.20

The "-" sign tells us that we deleted that option.

Now when we have uncommited changes, we can't exit the conf mode without commiting or discarding them.

vyos@router# exit
Cannot exit: configuration modified.
Use 'exit discard' to discard the changes and exit.

Let's commit the changes with "commit" command.

vyos@router# commit
[edit]
vyos@router# show system name-server 
 name-server 192.0.2.20

Commit changes the running config, but not the saved config! To make the changes persistent, we need to save them.

vyos@router# save
Saving configuration to '/config/config.boot'...
Done

Now we try running an op mode command from conf mode:

vyos@router# run show system memory 
Total: 496
Free:  389
Used:  107

Noticed the "[edit]"? In fact it's the config level and you can change it. Support we want the old name server back. Now we do to the "system" level.

vyos@router# edit system 
[edit system]
vyos@router# set name-server 192.0.2.10
[edit system]

Now we can go back to the top level with "top" command.

vyos@router# top
[edit]

If you are deep in the config tree, you can also use the "up" command to go one level up instead of going to the top.

vyos@router# edit firewall name Foo
[edit firewall name Foo]
vyos@router# up
[edit firewall]
vyos@router# up
[edit]

Let's see what a failed commit looks like:

vyos@router# set interfaces ethernet eth0 dhcpv6-options temporary 
[edit]
vyos@router# set interfaces ethernet eth0 dhcpv6-options parameters-only 
[edit]
vyos@router# commit
[ interfaces ethernet eth0 dhcpv6-options ]
dhcpv6-options: ifname is eth0
Re-starting DHCPv6 client on eth0...
Stopping daemon...
Deleting related files...
Stopping old daemon...
Error: temporary and parameters-only options are mutually exclusive!

[[interfaces ethernet eth0 dhcpv6-options]] failed
Commit failed

By default all commits are recorded and previus revisions of the config are stored. You can view who made commits:

vyos@router# run show system commit 
0   2015-02-24 13:00:14 by vyos via cli
1   2015-02-24 13:00:08 by vyos via cli
2   2015-02-24 12:20:32 by vyos via cli
3   2015-02-24 12:19:41 by vyos via cli
...

You can also view the difference between two commits (by default difference with the running config is shown): This means four commits ago we did "set system ipv6 disable-forwarding".

vyos@router# run show system commit diff 4
[edit system]
+ipv6 {
+    disable-forwarding
+}

What if you are doing something dangerous? Suppose you want to setup a firewall, and you are not sure there are no mistakes that will lock you out of your system. You can use confirmed commit. If you issue "commit-confirm" command, your changes will be commited, and if you don't issue "confirm" command in 10 minutes, your system will reboot into previous config revision (note: not the saved config, but to the point before the unfortunate commit).

vyos@router# set interfaces ethernet eth0 firewall local name FromWorld
vyos@router# commit-confirm 
commit confirm will be automatically reboot in 10 minutes unless confirmed
Proceed? [confirm]y
[edit]
vyos@router# confirm 
[edit]

You can copy and remove configuration subtrees. Suppose you set up a firewall ruleset "FromWorld" with one rule that allows traffic from specific subnet. Now you want to setup a similar rule, but for different subnet. Change your edit level to "firewall name FromWorld" and use "copy rule 10 to rule 20", then modify rule 20.

vyos@router# show firewall name FromWorld 
 default-action drop
 rule 10 {
     action accept
     source {
         address 203.0.113.0/24
     }
 }
[edit]
vyos@router# edit firewall name FromWorld 
[edit firewall name FromWorld]
vyos@router# copy rule 10 to rule 20
[edit firewall name FromWorld]
vyos@router# set rule 20 source address 198.51.100.0/24
[edit firewall name FromWorld]
vyos@router# commit
[edit firewall name FromWorld]

You can also rename config subtrees:

vyos@router# rename rule 10 to rule 5
[edit firewall name FromWorld]
vyos@router# commit
[edit firewall name FromWorld]

Note that "show" command respects your edit level and from this level you can view the modified firewall ruleset with just "show" with no parameters.

vyos@router# show 
 default-action drop
 rule 5 {
     action accept
     source {
         address 203.0.113.0/24
     }
 }
 rule 20 {
     action accept
     source {
         address 198.51.100.0/24
     }
 }