summaryrefslogtreecommitdiff
path: root/docs/cli.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/cli.rst')
-rw-r--r--docs/cli.rst750
1 files changed, 740 insertions, 10 deletions
diff --git a/docs/cli.rst b/docs/cli.rst
index 4694cc5d..7964c490 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -1,19 +1,18 @@
.. _cli:
-###
-CLI
-###
+#####################
+Comand Line Interface
+#####################
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. The list of all operational level commands
-is available at :ref:`operational_level_commands`.
+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
@@ -73,10 +72,7 @@ When viewing in page mode the following commands are available:
in the event that the output has lines which exceed the terminal size.
Configuration Mode
-==================
-
-The list of all operational level commands is available at
-:ref:`configuration_level_commands`.
+##################
To enter configuration mode use the ``configure`` command:
@@ -97,3 +93,737 @@ To enter configuration mode use the ``configure`` command:
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.
+
+Terminology
+###########
+
+live
+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``.
+
+Seeing and navigating the configuration
+=======================================
+
+.. opcmd:: show configuration
+
+ View the current active configuration, also known as the running
+ configuration, from the operational mode.
+
+ .. code-block:: none
+
+ vyos@vyos:~$ show configuration
+ interfaces {
+ ethernet eth0 {
+ address dhcp
+ hw-id 00:53:00:00:aa:01
+ }
+ loopback lo {
+ }
+ }
+ service {
+ ssh {
+ port 22
+ }
+ }
+ system {
+ config-management {
+ commit-revisions 20
+ }
+ console {
+ device ttyS0 {
+ speed 9600
+ }
+ }
+ login {
+ user vyos {
+ authentication {
+ encrypted-password ****************
+ }
+ level admin
+ }
+ }
+ ntp {
+ server 0.pool.ntp.org {
+ }
+ server 1.pool.ntp.org {
+ }
+ server 2.pool.ntp.org {
+ }
+ }
+ syslog {
+ global {
+ facility all {
+ level notice
+ }
+ facility protocols {
+ level debug
+ }
+ }
+ }
+ }
+
+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
+
+ Get a collection of all the set commands required which led to the
+ running configuration.
+
+ .. code-block:: none
+
+ vyos@vyos:~$ show configuration commands
+ set interfaces ethernet eth0 address 'dhcp'
+ set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f'
+ set interfaces loopback 'lo'
+ set service ssh port '22'
+ set system config-management commit-revisions '20'
+ set system console device ttyS0 speed '9600'
+ set system login user vyos authentication encrypted-password '$6$Vt68...QzF0'
+ set system login user vyos level 'admin'
+ set system ntp server '0.pool.ntp.org'
+ set system ntp server '1.pool.ntp.org'
+ set system ntp server '2.pool.ntp.org'
+ set system syslog global facility all level 'notice'
+ 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`.
+
+.. hint:: Use the ``show configuration commands | strip-private``
+ command when you want to hide private data. You may want to do so if
+ you want to share your configuration on the `forum`_.
+
+.. _`forum`: https://forum.vyos.io
+
+
+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.
+
+.. code-block:: none
+
+ vyos@vyos$ configure
+ [edit]
+ vyos@vyos#
+
+
+.. note:: 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.
+
+The current hierarchy level can be changed by the :cfgcmd:`edit`
+command.
+
+.. code-block:: none
+
+ [edit]
+ vyos@vyos# edit interfaces ethernet eth0
+
+ [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
+eithe 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.
+
+**Example:**
+
+.. code-block:: none
+
+ vyos@vyos:~$ configure
+ [edit]
+ vyos@vyos# show interfaces
+ ethernet eth0 {
+ description MY_OLD_DESCRIPTION
+ disable
+ hw-id 00:53:dd:44:3b:03
+ }
+ loopback lo {
+ }
+ [edit]
+ vyos@vyos# set interfaces ethernet eth0 address dhcp
+ [edit]
+ vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION
+ [edit]
+ vyos@vyos# delete interfaces ethernet eth0 disable
+ [edit]
+ vyos@vyos# show interfaces
+ ethernet eth0 {
+ + address dhcp
+ > description MY_NEW_DESCRIPTION
+ - disable
+ hw-id 00:53:dd:44:3b:03
+ }
+ loopback lo {
+ }
+
+It is also possible to display all `set` commands within configuration
+mode using :cfgcmd:`show | commands`
+
+.. code-block:: none
+
+ vyos@vyos# show interfaces ethernet eth0 | commands
+ 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.
+
+.. code-block:: none
+
+ [edit interfaces ethernet eth0]
+ vyos@vyos# show
+ address dhcp
+ 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.
+
+.. code-block:: none
+
+ [edit interfaces ethernet eth0]
+ vyos@vyos# exit
+ [edit]
+ vyos@vyos# exit
+ 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.
+
+.. 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.
+
+.. code-block:: none
+
+ [edit]
+ vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24
+
+
+.. code-block:: none
+
+ [edit interfaces ethernet eth0]
+ 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.
+
+.. cfgcmd:: delete
+
+ To delete a configuration entry use the :cfgcmd:`delete` command,
+ this also deletes all sub-levels under the current level you've
+ specified in the :cfgcmd:`delete` command. Deleting an entry will
+ also result in the element reverting back to its default value if one
+ exists.
+
+ .. code-block:: none
+
+ [edit interfaces ethernet eth0]
+ vyos@vyos# delete address 192.0.2.100/24
+
+.. cfgcmd:: commit
+
+ Any change you do on the configuration, will not take effect until
+ committed using the :cfgcmd:`commit` command in configuration mode.
+
+ .. code-block:: none
+
+ vyos@vyos# commit
+ [edit]
+ vyos@vyos# exit
+ Warning: configuration changes have not been saved.
+ vyos@vyos:~$
+
+.. _save:
+
+.. cfgcmd:: save
+
+ Use this command to preserve configuration changes upon reboot. By
+ default it is stored at */config/config.boot*. In the case you want
+ to store the configuration file somewhere else, you can add a local
+ path, an SCP address, an FTP address or a TFTP address.
+
+ .. code-block:: none
+
+ vyos@vyos# save
+ Saving configuration to '/config/config.boot'...
+ Done
+
+ .. code-block:: none
+
+ vyos@vyos# save [tab]
+ Possible completions:
+ <Enter> Save to system config file
+ <file> Save to file on local machine
+ scp://<user>:<passwd>@<host>:/<file> Save to file on remote machine
+ ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine
+ tftp://<host>/<file> Save to file on remote machine
+ vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot
+ Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'...
+ ######################################################################## 100.0%
+ 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.
+
+ All changes in the working config will thus be lost.
+
+ .. code-block:: none
+
+ vyos@vyos# exit
+ Cannot exit: configuration modified.
+ Use 'exit discard' to discard the changes and exit.
+ [edit]
+ vyos@vyos# exit discard
+
+
+.. cfgcmd:: commit-confirm <minutes>
+
+ Use this command to temporarily commit your changes and set the
+ number of minutes available for validation. ``confirm`` must
+ be entered within those minutes, otherwise the system will reboot
+ into the previous configuration. The default value is 10 minutes.
+
+
+ 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
+ the ``commit-confirm`` command, your changes will be commited, and if
+ you don't issue issue the ``confirm`` command in 10 minutes, your
+ system will reboot into previous config revision.
+
+ .. code-block:: none
+
+ 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]
+
+
+ .. note:: A reboot because you did not enter ``confirm`` will not
+ take you necessarily to the *saved configuration*, but to the
+ point before the unfortunate commit.
+
+
+.. cfgcmd:: copy
+
+ Copy a configuration element.
+
+ 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.
+
+
+ .. code-block:: none
+
+ 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]
+
+
+.. cfgcmd:: rename
+
+ Rename a configuration element.
+
+ You can also rename config subtrees:
+
+ .. code-block:: none
+
+ 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.
+
+ .. code-block:: none
+
+ 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
+ }
+ }
+
+
+.. cfgcmd:: comment <config node> "comment text"
+
+ Add comment as an annotation to a configuration node.
+
+ The ``comment`` command allows you to insert a comment above the
+ ``<config node>`` configuration section. When shown, comments are
+ enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments
+ need to be commited, just like other config changes.
+
+ To remove an existing comment from your current configuration,
+ specify an empty string enclosed in double quote marks (``""``) as
+ the comment text.
+
+ Example:
+
+ .. code-block:: none
+
+ vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool"
+ vyos@vyos# commit
+ vyos@vyos# show
+ firewall {
+ /* Yes I know this VyOS is cool */
+ all-ping enable
+ broadcast-ping disable
+ ...
+ }
+
+ .. note:: An important thing to note is that since the comment is
+ added on top of the section, it will not appear if the ``show
+ <section>`` command is used. With the above example, the `show
+ firewall` command would return starting after the ``firewall
+ {`` line, hiding the comment.
+
+
+
+
+
+
+.. _run_opmode_from_config_mode:
+
+Access opmode from config mode
+==============================
+
+When inside configuration mode you are not directly able to execute
+operational commands.
+
+.. cfgcmd:: run
+
+ Access to these commands are possible through the use of the
+ ``run [command]`` command. From this command you will have access to
+ everything accessible from operational mode.
+
+ Command completion and syntax help with ``?`` and ``[tab]`` will also
+ work.
+
+ .. code-block:: none
+
+ [edit]
+ vyos@vyos# run show interfaces
+ Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+ Interface IP Address S/L Description
+ --------- ---------- --- -----------
+ 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.
+
+Local Archive
+-------------
+
+Revisions are stored on disk. You can view, compare and rollback them to
+any previous revisions if something goes wrong.
+
+.. opcmd:: show system commit
+
+ View all existing revisions on the local system.
+
+ .. code-block:: none
+
+ vyos@vyos:~$ show system commit
+ 0 2015-03-30 08:53:03 by vyos via cli
+ 1 2015-03-30 08:52:20 by vyos via cli
+ 2 2015-03-26 21:26:01 by root via boot-config-loader
+ 3 2015-03-26 20:43:18 by root via boot-config-loader
+ 4 2015-03-25 11:06:14 by root via boot-config-loader
+ 5 2015-03-25 01:04:28 by root via boot-config-loader
+ 6 2015-03-25 00:16:47 by vyos via cli
+ 7 2015-03-24 23:43:45 by root via boot-config-loader
+
+
+.. cfgcmd:: set system config-management commit-revisions <N>
+
+ You can specify the number of revisions stored on disk. N can be in
+ the range of 0 - 65535. When the number of revisions exceeds the
+ configured value, the oldest revision is removed. The default setting
+ for this value is to store 100 revisions locally.
+
+
+Compare configurations
+----------------------
+
+VyOS lets you compare different configurations.
+
+.. cfgcmd:: compare <saved | N> <M>
+
+ Use this command to spot what the differences are between different
+ configurations.
+
+ .. code-block:: none
+
+ vyos@vyos# compare [tab]
+ Possible completions:
+ <Enter> Compare working & active configurations
+ saved Compare working & saved configurations
+ <N> Compare working with revision N
+ <N> <M> Compare revision N with M
+ Revisions:
+ 0 2013-12-17 20:01:37 root by boot-config-loader
+ 1 2013-12-13 15:59:31 root by boot-config-loader
+ 2 2013-12-12 21:56:22 vyos by cli
+ 3 2013-12-12 21:55:11 vyos by cli
+ 4 2013-12-12 21:27:54 vyos by cli
+ 5 2013-12-12 21:23:29 vyos by cli
+ 6 2013-12-12 21:13:59 root by boot-config-loader
+ 7 2013-12-12 16:25:19 vyos by cli
+ 8 2013-12-12 15:44:36 vyos by cli
+ 9 2013-12-12 15:42:07 root by boot-config-loader
+ 10 2013-12-12 15:42:06 root by init
+
+ The command :cfgcmd:`compare` allows you to compare different type of
+ configurations. It also lets you compare different revisions through
+ the :cfgcmd:`compare N M` command, where N and M are revision
+ numbers. The output will describe how the configuration N is when
+ compared to M indicating with a plus sign (``+``) the additional
+ parts N has when compared to M, and indicating with a minus sign
+ (``-``) the lacking parts N misses when compared to M.
+
+ .. code-block:: none
+
+ vyos@vyos# compare 0 6
+ [edit interfaces]
+ +dummy dum1 {
+ + address 10.189.0.1/31
+ +}
+ [edit interfaces ethernet eth0]
+ +vif 99 {
+ + address 10.199.0.1/31
+ +}
+ -vif 900 {
+ - address 192.0.2.4/24
+ -}
+
+
+.. opcmd:: show system commit diff <number>
+
+ 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.
+
+.. code-block:: none
+
+ vyos@router# run show system commit diff 4
+ [edit system]
+ +ipv6 {
+ + disable-forwarding
+ +}
+
+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.
+
+.. cfgcmd:: rollback <N>
+
+ Rollback to revision N (currently requires reboot)
+
+ .. code-block:: none
+
+ vyos@vyos# compare 1
+ [edit system]
+ >host-name vyos-1
+ [edit]
+
+ vyos@vyos# rollback 1
+ Proceed with reboot? [confirm][y]
+ Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013):
+ 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 successfull 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>
+
+ Specify remote location of commit archive as any of the below
+ :abbr:`URI (Uniform Resource Identifier)`
+
+ * ``scp://<user>:<passwd>@<host>:/<dir>``
+ * ``sftp://<user>:<passwd>@<host>/<dir>``
+ * ``ftp://<user>:<passwd>@<host>/<dir>``
+ * ``tftp://<host>/<dir>``
+
+.. note:: The number of revisions don't affect the commit-archive.
+
+.. note:: You may find VyOS not allowing the secure connection because
+ it cannot verify the legitimacy of the remote server. You can use
+ the workaround below to quickly add the remote host's SSH
+ fingerprint to your ``~/.ssh/known_hosts`` file:
+
+ .. code-block:: none
+
+ vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts
+
+Saving and loading manually
+---------------------------
+
+You can use the ``save`` and ``load`` commands if you want to manually
+manage specific configuration files.
+
+When using the 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>
+
+ Use this command to load a configuration which will replace the
+ running configuration. Define the location of the configuration file
+ to be loaded. You can use a path to a local file, an SCP address, an
+ SFTP address, an FTP address, an HTTP address, an HTTPS address or a
+ TFTP address.
+
+ .. code-block:: none
+
+ vyos@vyos# load
+ Possible completions:
+ <Enter> Load from system config file
+ <file> Load from file on local machine
+ scp://<user>:<passwd>@<host>:/<file> Load from file on remote machine
+ sftp://<user>:<passwd>@<host>/<file> Load from file on remote machine
+ ftp://<user>:<passwd>@<host>/<file> Load from file on remote machine
+ http://<host>/<file> Load from file on remote machine
+ https://<host>/<file> Load from file on remote machine
+ tftp://<host>/<file> Load from file on remote machine
+
+
+
+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:
+
+.. code-block:: 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.
+
+Then you may want to :cfgcmd:`save` in order to delete the saved
+configuration too.
+
+.. note:: If you are remotely connected, you will lose your connection.
+ You may want to copy first the config, edit it to ensure
+ connectivity, and load the edited config.
+
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-03 05:48:29 +0000