diff options
Diffstat (limited to 'docs/cli.md')
| -rw-r--r-- | docs/cli.md | 203 |
1 files changed, 145 insertions, 58 deletions
diff --git a/docs/cli.md b/docs/cli.md index e961c790..0931c9d6 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -2,15 +2,22 @@ # Command Line Interface -The VyOS {abbr}`CLI (Command-Line Interface)` comprises an operational and a configuration mode. +The VyOS {abbr}`CLI (Command-Line Interface)` comprises an operational and a +configuration mode. ## Operational Mode -Operational mode allows for commands to perform operational system tasks and view system and service status, while configuration mode allows for the modification of system configuration. +Operational mode allows for commands to perform operational system tasks and +view system and service status, while configuration mode allows for the +modification of system configuration. -The CLI provides a built-in help system. In the CLI the `?` key may be used to display available commands. The `TAB` key can be used to auto-complete commands and will present the help system upon a conflict or unknown value. +The CLI provides a built-in help system. In the CLI the `?` key may be used to +display available commands. The `TAB` key can be used to auto-complete commands +and will present the help system upon a conflict or unknown value. -For example typing `sh` followed by the `TAB` key will complete to `show`. Pressing `TAB` a second time will display the possible sub-commands of the `show` command. +For example typing `sh` followed by the `TAB` key will complete to `show`. +Pressing `TAB` a second time will display the possible sub-commands of the +`show` command. ``` none vyos@vyos:~$ s[tab] @@ -45,9 +52,11 @@ Possible completions: : q ``` -You can scroll up with the keys `[Shift]+[PageUp]` and scroll down with `[Shift]+[PageDown]`. +You can scroll up with the keys `[Shift]+[PageUp]` and scroll down with +`[Shift]+[PageDown]`. -When the output of a command results in more lines than can be displayed on the terminal screen the output is paginated as indicated by a `:` prompt. +When the output of a command results in more lines than can be displayed on the +terminal screen the output is paginated as indicated by a `:` prompt. When viewing in page mode the following commands are available: : - `q` key can be used to cancel output @@ -61,57 +70,82 @@ When viewing in page mode the following commands are available: ### Operational mode command families -Many operational mode commands in VyOS are placed in families such as `show`, `clear`, or `reset`. Every such family has a specific meaning to allow the user to guess how the command is going to behave --- in particular, whether it will be disruptive to the system or not. +Many operational mode commands in VyOS are placed in families such as `show`, +`clear`, or `reset`. Every such family has a specific meaning to allow the user +to guess how the command is going to behave --- in particular, whether it will +be disruptive to the system or not. -Note that this convention was not always followed with perfect consistency and some commands may still be in wrong families, so you should always check the command help and documentation if you are not sure what exactly it does. +Note that this convention was not always followed with perfect consistency and +some commands may still be in wrong families, so you should always check the +command help and documentation if you are not sure what exactly it does. #### clear -\"Clear\" commands are completely non-disruptive to any system operations. Generally, they can be used freely without hesitation. +\"Clear\" commands are completely non-disruptive to any system operations. +Generally, they can be used freely without hesitation. -Most often their purpose is to remove or reset various debug and diagnostic information such as system logs and packet counters. +Most often their purpose is to remove or reset various debug and diagnostic +information such as system logs and packet counters. Examples: - `clear console` --- clears the screen. -- `clear interfaces ethernet eth0 counters` --- zeroes packet counters on `eth0`. +- `clear interfaces ethernet eth0 counters` --- zeroes packet counters on + `eth0`. - `clear log` --- deletes all system log entries. #### reset -\"Reset\" commands can be locally-disruptive. They may, for example, terminate a single user session or a session with a dynamic routing protocol peer. - -They should be used with caution since they may have a significant impact on a particular users in the network. -- `reset pppoe-server username jsmith` --- terminate all PPPoE sessions from user `jsmith`. -- `reset bgp 192.0.2.54` --- terminates the BGP session with neighbor 192.0.2.54. -- `reset vpn ipsec site-to-site peer vpn.example.com` --- terminates IPsec tunnels to `vpn.example.com`. +\"Reset\" commands can be locally-disruptive. They may, for example, terminate a +single user session or a session with a dynamic routing protocol peer. + +They should be used with caution since they may have a significant impact on a +particular users in the network. +- `reset pppoe-server username jsmith` --- terminate all PPPoE sessions from + user `jsmith`. +- `reset bgp 192.0.2.54` --- terminates the BGP session with neighbor + 192.0.2.54. +- `reset vpn ipsec site-to-site peer vpn.example.com` --- terminates IPsec + tunnels to `vpn.example.com`. - `reset session tty1` --- terminates the TTY user session `tty1` #### restart -\"Restart\" operations may disrupt an entire subsystem. Most often they initiate a restart of a server process, which causes it to be unavailable for a brief period and resets all the process state. +\"Restart\" operations may disrupt an entire subsystem. Most often they initiate +a restart of a server process, which causes it to be unavailable for a brief +period and resets all the process state. They should be used with extreme caution. -- `restart dhcp server` --- restarts the IPv4 DHCP server process (DHCP requests are not served while it is restarting). -- `restart ipsec` --- restarts the IPsec process (which forces all sessions and all IPsec process state to reset). +- `restart dhcp server` --- restarts the IPv4 DHCP server process (DHCP requests + are not served while it is restarting). +- `restart ipsec` --- restarts the IPsec process (which forces all sessions and + all IPsec process state to reset). #### force -\"Force\" commands force the system to perform an action that it might perform by itself at a later point. +\"Force\" commands force the system to perform an action that it might perform +by itself at a later point. Examples: -- `force arp request interface eth1 address 10.3.0.2` --- send a gratuitous ARP request. -- `force root-partition-auto-resize` --- grow the root filesystem to the size of the system partition (this is also done on startup, but this command can do it without a reboot). +- `force arp request interface eth1 address 10.3.0.2` --- send a gratuitous ARP + request. +- `force root-partition-auto-resize` --- grow the root filesystem to the size of + the system partition (this is also done on startup, but this command can do it + without a reboot). #### execute -\"Execute\" commands are for executing various diagnostic and auxiliary actions that the system would never perform by itself. +\"Execute\" commands are for executing various diagnostic and auxiliary actions +that the system would never perform by itself. Examples: -- `execute wake-on-lan interface <intf> host <MAC>` --- send a Wake-On-LAN packet to a host. +- `execute wake-on-lan interface <intf> host <MAC>` --- send a Wake-On-LAN + packet to a host. #### show -\"Show\" commands display various system information. They may occasionally use a pager for long outputs, that you can quit by pressing the Q button. Their output is always finite, however. +\"Show\" commands display various system information. They may occasionally use +a pager for long outputs, that you can quit by pressing the Q button. Their +output is always finite, however. Examples: - `show system login` --- displays current system users. @@ -119,7 +153,8 @@ Examples: #### monitor -\"Monitor\" commands initiate various monitoring operations that may output information continuously, until terminated with `Ctrl-C` or disabled. +\"Monitor\" commands initiate various monitoring operations that may output +information continuously, until terminated with `Ctrl-C` or disabled. Examples: - `monitor log` --- continuously outputs latest system logs. @@ -144,20 +179,33 @@ exit vyos@vyos:~$ ``` -See the configuration section of this document for more information on configuration mode. +See the configuration section of this document for more information on +configuration mode. (configuration-overview)= # Configuration Overview -VyOS makes use of a unified configuration file for the entire system\'s configuration: `/config/config.boot`. This allows easy template creation, backup, and replication of system configuration. A system can thus also be easily cloned by simply copying the required configuration files. +VyOS makes use of a unified configuration file for the entire system\'s +configuration: `/config/config.boot`. This allows easy template creation, +backup, and replication of system configuration. A system can thus also be +easily cloned by simply copying the required configuration files. ## Terminology A VyOS system has three major types of configurations: -- **Active** or **running configuration** is the system configuration that is loaded and currently active (used by VyOS). Any change in the configuration will have to be committed to belong to the active/running configuration. -- **Working configuration** is the one that is currently being modified in configuration mode. Changes made to the working configuration do not go into effect until the changes are committed with the {cfgcmd}`commit` command. At which time the working configuration will become the active or running configuration. -- **Saved configuration** is the one saved to a file using the {cfgcmd}`save` command. It allows you to keep safe a configuration for future uses. There can be multiple configuration files. The default or \"boot\" configuration is saved and loaded from the file `/config/config.boot`. +- **Active** or **running configuration** is the system configuration that is + loaded and currently active (used by VyOS). Any change in the configuration + will have to be committed to belong to the active/running configuration. +- **Working configuration** is the one that is currently being modified in + configuration mode. Changes made to the working configuration do not go into + effect until the changes are committed with the {cfgcmd}`commit` command. At + which time the working configuration will become the active or running + configuration. +- **Saved configuration** is the one saved to a file using the {cfgcmd}`save` + command. It allows you to keep safe a configuration for future uses. There can + be multiple configuration files. The default or \"boot\" configuration is + saved and loaded from the file `/config/config.boot`. ## Seeing and navigating the configuration @@ -219,7 +267,10 @@ system { ::: ``` -By default, the configuration is displayed in a hierarchy like the above example, this is only one of the possible ways to display the configuration. When the configuration is generated and the device is configured, changes are added through a collection of {cfgcmd}`set` and {cfgcmd}`delete` commands. +By default, the configuration is displayed in a hierarchy like the above +example, this is only one of the possible ways to display the configuration. +When the configuration is generated and the device is configured, changes are +added through a collection of {cfgcmd}`set` and {cfgcmd}`delete` commands. ```{opcmd} show configuration commands @@ -243,7 +294,9 @@ set system syslog global facility protocols level 'debug' ::: ``` -Both these `show` commands should be executed when in operational mode, they do not work directly in configuration mode. There is a special way on how to {ref}`run_opmode_from_config_mode`. +Both these `show` commands should be executed when in operational mode, they do +not work directly in configuration mode. There is a special way on how to +{ref}`run_opmode_from_config_mode`. ::::{hint} @@ -360,7 +413,9 @@ View the current active configuration in readable JSON format. ### The config mode -When entering the configuration mode you are navigating inside a tree structure, to enter configuration mode enter the command {opcmd}`configure` when in operational mode. +When entering the configuration mode you are navigating inside a tree structure, +to enter configuration mode enter the command {opcmd}`configure` when in +operational mode. ``` none vyos@vyos$ configure @@ -372,7 +427,9 @@ vyos@vyos# When going into configuration mode, prompt changes from `$` to `#`. :::: -All commands executed here are relative to the configuration level you have entered. You can do everything from the top level, but commands will be quite lengthy when manually typing them. +All commands executed here are relative to the configuration level you have +entered. You can do everything from the top level, but commands will be quite +lengthy when manually typing them. The current hierarchy level can be changed by the {cfgcmd}`edit` command. @@ -384,12 +441,17 @@ vyos@vyos# edit interfaces ethernet eth0 vyos@vyos# ``` -You are now in a sublevel relative to `interfaces ethernet eth0`, all commands executed from this point on are relative to this sublevel. Use either the {cfgcmd}`top` or {cfgcmd}`exit` command to go back to the top of the hierarchy. You can also use the {cfgcmd}`up` command to move only one level up at a time. +You are now in a sublevel relative to `interfaces ethernet eth0`, all commands +executed from this point on are relative to this sublevel. Use either the +{cfgcmd}`top` or {cfgcmd}`exit` command to go back to the top of the hierarchy. +You can also use the {cfgcmd}`up` command to move only one level up at a time. ```{cfgcmd} show ``` -The {cfgcmd}`show` command within configuration mode will show the working configuration indicating line changes with `+` for additions, `>` for replacements and `-` for deletions. +The {cfgcmd}`show` command within configuration mode will show the working +configuration indicating line changes with `+` for additions, `>` for +replacements and `-` for deletions. **Example:** ``` none @@ -421,7 +483,8 @@ vyos@vyos# show interfaces } ``` -It is also possible to display all {cfgcmd}`set` commands within configuration mode using {cfgcmd}`show | commands` +It is also possible to display all {cfgcmd}`set` commands within configuration +mode using {cfgcmd}`show | commands` ``` none vyos@vyos# show interfaces ethernet eth0 | commands @@ -429,7 +492,8 @@ set address dhcp set hw-id 00:53:ad:44:3b:03 ``` -These commands are also relative to the level you are inside and only relevant configuration blocks will be displayed when entering a sub-level. +These commands are also relative to the level you are inside and only relevant +configuration blocks will be displayed when entering a sub-level. ``` none [edit interfaces ethernet eth0] @@ -438,7 +502,9 @@ vyos@vyos# show hw-id 00:53:ad:44:3b:03 ``` -Exiting from the configuration mode is done via the {cfgcmd}`exit` command from the top level, executing {cfgcmd}`exit` from within a sub-level takes you back to the top level. +Exiting from the configuration mode is done via the {cfgcmd}`exit` command from +the top level, executing {cfgcmd}`exit` from within a sub-level takes you back +to the top level. ``` none [edit interfaces ethernet eth0] @@ -450,18 +516,22 @@ Warning: configuration changes have not been saved. ## Editing the configuration -The configuration can be edited by the use of {cfgcmd}`set` and {cfgcmd}`delete` commands from within configuration mode. +The configuration can be edited by the use of {cfgcmd}`set` and {cfgcmd}`delete` +commands from within configuration mode. ```{cfgcmd} set Use this command to set the value of a parameter or to create a new element. ``` -Configuration commands are flattened from the tree into \'one-liner\' commands shown in {opcmd}`show configuration commands` from operation mode. Commands are relative to the level where they are executed and all redundant information from the current level is removed from the command entered. +Configuration commands are flattened from the tree into \'one-liner\' commands +shown in {opcmd}`show configuration commands` from operation mode. Commands are +relative to the level where they are executed and all redundant information from +the current level is removed from the command entered. ``` none [edit] -vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 +vyos@vyos# set interfaces ethernet eth0 address 192.0.2.100/24 ``` ``` none @@ -469,7 +539,8 @@ vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 vyos@vyos# set address 203.0.113.6/24 ``` -These two commands above are essentially the same, just executed from different levels in the hierarchy. +These two commands above are essentially the same, just executed from different +levels in the hierarchy. ```{cfgcmd} delete @@ -524,8 +595,7 @@ Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... Done ``` -::: -:::: + ```{cfgcmd} exit \[discard\] Configuration mode can not be exited while uncommitted changes exist. To exit configuration mode without applying changes, the {cfgcmd}`exit discard` command must be used. @@ -659,7 +729,8 @@ An important thing to note is that since the comment is added on top of the sect ## Access opmode from config mode -When inside configuration mode you are not directly able to execute operational commands. +When inside configuration mode you are not directly able to execute operational +commands. ```{cfgcmd} run @@ -679,11 +750,15 @@ eth0 0.0.0.0/0 u/u ## Managing configurations -VyOS comes with an integrated versioning system for the system configuration. It automatically maintains a backup of every previous configuration which has been committed to the system. The configurations are versioned locally for rollback but they can also be stored on a remote host for archiving/backup reasons. +VyOS comes with an integrated versioning system for the system configuration. It +automatically maintains a backup of every previous configuration which has been +committed to the system. The configurations are versioned locally for rollback +but they can also be stored on a remote host for archiving/backup reasons. ### Local Archive -Revisions are stored on disk. You can view, compare and rollback them to any previous revisions if something goes wrong. +Revisions are stored on disk. You can view, compare and rollback them to any +previous revisions if something goes wrong. ```{opcmd} show system commit @@ -758,7 +833,8 @@ vyos@vyos# compare 0 6 Show commit revision difference. ``` -The command above also lets you see the difference between two commits. By default the difference with the running config is shown. +The command above also lets you see the difference between two commits. By +default the difference with the running config is shown. ``` none vyos@router# run show system commit diff 4 @@ -772,7 +848,8 @@ This means four commits ago we did `set system ipv6 disable-forwarding`. ### Rollback Changes -You can rollback configuration changes using the rollback command. This will apply the selected revision and trigger a system reboot. +You can rollback configuration changes using the rollback command. This will +apply the selected revision and trigger a system reboot. ```{cfgcmd} rollback \<N\> @@ -793,7 +870,11 @@ The system is going down for reboot NOW! ### Remote Archive -VyOS can upload the configuration to a remote location after each call to {cfgcmd}`commit`. You will have to set the commit-archive location. TFTP, FTP, SCP and SFTP servers are supported. Every time a {cfgcmd}`commit` is successful the `config.boot` file will be copied to the defined destination(s). The filename used on the remote host will be `config.boot-hostname.YYYYMMDD_HHMMSS`. +VyOS can upload the configuration to a remote location after each call to +{cfgcmd}`commit`. You will have to set the commit-archive location. TFTP, FTP, +SCP and SFTP servers are supported. Every time a {cfgcmd}`commit` is successful +the `config.boot` file will be copied to the defined destination(s). The +filename used on the remote host will be `config.boot-hostname.YYYYMMDD_HHMMSS`. ```{cfgcmd} set system config-management commit-archive location \<URI\> @@ -827,9 +908,12 @@ Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance used t ### Saving and loading manually -You can use the `save` and `load` commands if you want to manually manage specific configuration files. +You can use the `save` and `load` commands if you want to manually manage +specific configuration files. -When using the [save](#save) command, you can add a specific location where to store your configuration file. And, when needed it, you will be able to load it with the `load` command: +When using the [save](#save) command, you can add a specific location where to +store your configuration file. And, when needed it, you will be able to load it +with the `load` command: ```{cfgcmd} load \<URI\> @@ -853,15 +937,18 @@ If you are remotely connected, you will lose your connection. You may want to co ### Restore Default -In the case you want to completely delete your configuration and restore the default one, you can enter the following command in configuration mode: +In the case you want to completely delete your configuration and restore the +default one, you can enter the following command in configuration mode: ``` none load /opt/vyatta/etc/config.boot.default ``` -You will be asked if you want to continue. If you accept, you will have to use {cfgcmd}`commit` if you want to make the changes active. +You will be asked if you want to continue. If you accept, you will have to use +{cfgcmd}`commit` if you want to make the changes active. -Then you may want to {cfgcmd}`save` in order to delete the saved configuration too. +Then you may want to {cfgcmd}`save` in order to delete the saved configuration +too. ::::{note} Prompt changes from `$` to `#`. To exit configuration mode, type `exit`. |