vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

config-overview: show-config-private and restructure seeing & navigating

Browse Source 
Add command to show config without private data, restructure seeing
& navigating, and fine tune other small details.
This commit is contained in:
currite 2020-03-18 01:01:35 +01:00
parent d61018109b
commit 063c7a88eb
1 changed files with 170 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

315
docs/configuration-overview.rst
View File

@ -4,38 +4,41 @@
Configuration Overview Configuration Overview
###################### ######################
VyOS makes use of a unified configuration file for the entire systems VyOS makes use of a unified configuration file for the entire system's
configuration: ``/config/config.boot``. This allows easy template creation, configuration: ``/config/config.boot``. This allows easy template
backup, and replication of system configuration. A system can thus also be creation, backup, and replication of system configuration. A system can
easily cloned by simply copying the required configuration files. thus also be easily cloned by simply copying the required configuration
files.
Terminology Terminology
=========== ===========
A VyOS system has three major types of configurations: A VyOS system has three major types of configurations:
* **Active/Running** configuration is the system configuration that is loaded * **Active** or **Running** configuration is the system configuration
and currently active (used by VyOS). Any change in the configuration will that is loaded and currently active (used by VyOS). Any change in
have to be committed to belong to the active/running configuration. the configuration will have to be committed to belong to the
active/running configuration.
* **Working** - is the configuration which is currently being modified in * **Working** - is the configuration which is currently being modified
configuration mode. Changes made to the working configuration do not go into in configuration mode. Changes made to the working configuration do
effect until the changes are committed with the :cfgcmd:`commit` command. At not go into effect until the changes are committed with the
which time the working configuration will become the active or running :cfgcmd:`commit` command. At which time the working configuration will
configuration. become the active or running configuration.
* **Saved** - is a configuration saved to a file using the :cfgcmd:`save` * **Saved** - is a configuration saved to a file using the
command. It allows you to keep safe a configuration for future uses. There :cfgcmd:`save` command. It allows you to keep safe a configuration for
can be multiple configuration files. The default or "boot" configuration is future uses. There can be multiple configuration files. The default or
saved and loaded from the file ``/config/config.boot``. "boot" configuration is saved and loaded from the file
``/config/config.boot``.
Seeing the configuration Seeing and navigating the configuration
======================== =======================================
.. opcmd:: show configuration .. opcmd:: show configuration
View the current active configuration, also known as the running View the current active configuration, also known as the running
configuration. configuration, from the operational mode.
.. code-block:: none .. code-block:: none
@ -91,13 +94,14 @@ Seeing the configuration
} }
By default, the configuration is displayed in a hierarchy like the above 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. example, this is only one of the possible ways to display the
When the configuration is generated and the device is configured, changes are configuration. When the configuration is generated and the device is
added through a collection of :cfgcmd:`set` and :cfgcmd:`delete` commands. configured, changes are added through a collection of :cfgcmd:`set` and
:cfgcmd:`delete` commands.
.. opcmd:: show configuration commands .. opcmd:: show configuration commands
Get a collection of all the set commands required which led to this Get a collection of all the set commands required which led to the
running configuration. running configuration.
.. code-block:: none .. code-block:: none
@ -117,52 +121,23 @@ added through a collection of :cfgcmd:`set` and :cfgcmd:`delete` commands.
set system syslog global facility all level 'notice' set system syslog global facility all level 'notice'
set system syslog global facility protocols level 'debug' set system syslog global facility protocols level 'debug'
Both these commands should be executed when in operational mode, they do not Both these ``show`` commands should be executed when in operational
work directly in configuration mode. The is a special way on how to mode, they do not work directly in configuration mode. There is a
:ref:`run_opmode_from_config_mode`. special way on how to :ref:`run_opmode_from_config_mode`.
Comment .. 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`_.
.. cfgcmd:: comment <config node> "comment text" .. _`forum`: https://forum.vyos.io
Add comment as an annotation to a configuration node.
The ``comment` command allows you to insert a comment above the ``<config
node>`` configuration section. Comments are enclosed with ``/*`` and ``*/``
as open/close delimiters. A ``comment`` cannot be used at the top of the
configuration hierarchy, only on subsections. 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.
Navigating the configuration The config mode
============================ ---------------
When entering the configuration mode you are navigating inside the tree When entering the configuration mode you are navigating inside a tree
structure exported in the overview above, to enter configuration mode enter structure, to enter configuration mode enter the command
the command :opcmd:`configure` when in operational mode. :opcmd:`configure` when in operational mode.
.. code-block:: none .. code-block:: none
@ -170,11 +145,17 @@ the command :opcmd:`configure` when in operational mode.
[edit] [edit]
vyos@vyos# vyos@vyos#
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. .. 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 .. code-block:: none
@ -185,17 +166,16 @@ The current hierarchy level can be changed by the :cfgcmd:`edit` command.
vyos@vyos# vyos@vyos#
You are now in a sublevel relative to ``interfaces ethernet eth0``, all 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 commands executed from this point on are relative to this sublevel. Use
the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top of the eithe the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top
hierarchy. You can also use the :cfgcmd:`up` command to move only one level up of the hierarchy. You can also use the :cfgcmd:`up` command to move only
at a time. one level up at a time.
The :cfgcmd:`show` command within configuration mode will show the working .. cfgcmd:: show
configuration indicating line changes with ``+`` for additions, ``>`` for
replacements and ``-`` for deletions.
.. note:: When going into configuration mode, prompt changes from The :cfgcmd:`show` command within configuration mode will show the
``$`` to ``#``. working configuration indicating line changes with ``+`` for additions,
``>`` for replacements and ``-`` for deletions.
**Example:** **Example:**
@ -228,8 +208,8 @@ replacements and ``-`` for deletions.
loopback lo { loopback lo {
} }
It is also possible to display all `set` commands within configuration mode It is also possible to display all `set` commands within configuration
using :cfgcmd:`show | commands` mode using :cfgcmd:`show | commands`
.. code-block:: none .. code-block:: none
@ -237,8 +217,9 @@ using :cfgcmd:`show | commands`
set address dhcp set address dhcp
set hw-id 00:53:ad:44:3b:03 set hw-id 00:53:ad:44:3b:03
These commands are also relative to the level you are inside and only relevant These commands are also relative to the level you are inside and only
configuration blocks will be displayed when entering a sub-level. relevant configuration blocks will be displayed when entering a
sub-level.
.. code-block:: none .. code-block:: none
@ -247,9 +228,9 @@ configuration blocks will be displayed when entering a sub-level.
address dhcp address dhcp
hw-id 00:53:ad:44:3b:03 hw-id 00:53:ad:44:3b:03
Exiting from the configuration mode is done via the :cfgcmd:`exit` command from Exiting from the configuration mode is done via the :cfgcmd:`exit`
the top level, executing :cfgcmd:`exit` from within a sub-level takes you back command from the top level, executing :cfgcmd:`exit` from within a
to the top level. sub-level takes you back to the top level.
.. code-block:: none .. code-block:: none
@ -259,16 +240,56 @@ to the top level.
vyos@vyos# exit vyos@vyos# exit
Warning: configuration changes have not been saved. Warning: configuration changes have not been saved.
Comment
-------
.. 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. Comments are enclosed with
``/*`` and ``*/`` as open/close delimiters. A ``comment`` cannot be
used at the top of the configuration hierarchy, only on subsections.
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.
Editing the configuration Editing the configuration
========================= =========================
The configuration can be edited by the use of :cfgcmd:`set` and :cfgcmd:`delete` The configuration can be edited by the use of :cfgcmd:`set` and
commands from within configuration mode. Configuration commands are flattened :cfgcmd:`delete` commands from within configuration mode. Configuration
from the tree into 'one-liner' commands shown in :opcmd:`show configuration commands are flattened from the tree into 'one-liner' commands shown in
commands` from operation mode. :opcmd:`show configuration commands` from operation mode.
Commands are relative to the level where they are executed and all redundant Commands are relative to the level where they are executed and all
information from the current level is removed from the command entered. redundant information from the current level is removed from the command
entered.
.. code-block:: none .. code-block:: none
@ -278,15 +299,16 @@ information from the current level is removed from the command entered.
[edit interfaces ethernet eth0] [edit interfaces ethernet eth0]
vyos@vyos# set address 203.0.113.6/24 vyos@vyos# set address 203.0.113.6/24
These two commands above are essentially the same, just executed from different These two commands above are essentially the same, just executed from
levels in the hierarchy. different levels in the hierarchy.
.. cfgcmd:: delete .. cfgcmd:: delete
To delete a configuration entry use the :cfgcmd:`delete` command, this also To delete a configuration entry use the :cfgcmd:`delete` command,
deletes all sub-levels under the current level you've specified in the this also deletes all sub-levels under the current level you've
:cfgcmd:`delete` command. Deleting an entry will also result in the element specified in the :cfgcmd:`delete` command. Deleting an entry will
reverting back to its default value if one exists. also result in the element reverting back to its default value if one
exists.
.. code-block:: none .. code-block:: none
@ -295,8 +317,8 @@ levels in the hierarchy.
.. cfgcmd:: commit .. cfgcmd:: commit
Any change you do on the configuration, will not take effect until committed Any change you do on the configuration, will not take effect until
using the :cfgcmd:`commit` command in configuration mode. committed using the :cfgcmd:`commit` command in configuration mode.
.. code-block:: none .. code-block:: none
@ -308,9 +330,9 @@ levels in the hierarchy.
.. cfgcmd:: save .. cfgcmd:: save
In order to preserve configuration changes upon reboot, the configuration In order to preserve configuration changes upon reboot, the
must also be saved once applied. This is done using the :cfgcmd:`save` configuration must also be saved once applied. This is done using the
command in configuration mode. :cfgcmd:`save` command in configuration mode.
.. code-block:: none .. code-block:: none
@ -334,9 +356,9 @@ levels in the hierarchy.
.. cfgcmd:: exit [discard] .. cfgcmd:: exit [discard]
Configuration mode can not be exited while uncommitted changes exist. To Configuration mode can not be exited while uncommitted changes exist.
exit configuration mode without applying changes, the :cfgcmd:`exit discard` To exit configuration mode without applying changes, the
command must be used. :cfgcmd:`exit discard` command must be used.
All changes in the working config will thus be lost. All changes in the working config will thus be lost.
@ -353,16 +375,17 @@ levels in the hierarchy.
Access opmode from config mode Access opmode from config mode
============================== ==============================
When inside configuration mode you are not directly able to execute operational When inside configuration mode you are not directly able to execute
commands. operational commands.
.. cfgcmd:: run .. cfgcmd:: run
Access to these commands are possible through the use of the ``run [command]`` Access to these commands are possible through the use of the
command. From this command you will have access to everything accessible from ``run [command]`` command. From this command you will have access to
operational mode. everything accessible from operational mode.
Command completion and syntax help with ``?`` and ``[tab]`` will also work. Command completion and syntax help with ``?`` and ``[tab]`` will also
work.
.. code-block:: none .. code-block:: none
@ -376,17 +399,17 @@ commands.
Managing configurations Managing configurations
======================= =======================
VyOS comes with an integrated versioning system for the system configuration. VyOS comes with an integrated versioning system for the system
It automatically maintains a backup of every previous configuration configuration. It automatically maintains a backup of every previous
which has been committed to the system. configuration which has been committed to the system. The configurations
The configurations are versioned locally for rollback are versioned locally for rollback but they can also be stored on a
but they can also be stored on a remote host for archiving/backup reasons. remote host for archiving/backup reasons.
Local Archive Local Archive
------------- -------------
Revisions are stored on disk. You can view, compare and rollback them to any Revisions are stored on disk. You can view, compare and rollback them to
previous revisions if something goes wrong. any previous revisions if something goes wrong.
.. opcmd:: show system commit .. opcmd:: show system commit
@ -429,11 +452,12 @@ previous revisions if something goes wrong.
9 2013-12-12 15:42:07 root by boot-config-loader 9 2013-12-12 15:42:07 root by boot-config-loader
10 2013-12-12 15:42:06 root by init 10 2013-12-12 15:42:06 root by init
Revisions can be compared with :cfgcmd:`compare N M` command, where N and M Revisions can be compared with :cfgcmd:`compare N M` command, where N
are revision numbers. The output will describe how the configuration N is and M are revision numbers. The output will describe how the
when compared to YM indicating with a plus sign (``+``) the additional parts configuration N is when compared to YM indicating with a plus sign
N has when compared to M, and indicating with a minus sign (``-``) the (``+``) the additional parts N has when compared to M, and indicating
lacking parts N misses when compared to Y. with a minus sign (``-``) the lacking parts N misses when compared to
Y.
.. code-block:: none .. code-block:: none
@ -452,16 +476,16 @@ previous revisions if something goes wrong.
.. cfgcmd:: set system config-management commit-revisions <N> .. cfgcmd:: set system config-management commit-revisions <N>
You can specify the number of revisions stored on disk. N can be in the You can specify the number of revisions stored on disk. N can be in
range of 0 - 65535. When the number of revisions exceeds the configured the range of 0 - 65535. When the number of revisions exceeds the
value, the oldest revision is removed. configured value, the oldest revision is removed. The default setting
The default setting for this value is to store 20 revisions locally. for this value is to store 20 revisions locally.
Rollback Changes Rollback Changes
---------------- ----------------
You can rollback configuration changes using the rollback command. This will You can rollback configuration changes using the rollback command. This
apply the selected revision and trigger a system reboot. willn apply the selected revision and trigger a system reboot.
.. cfgcmd:: rollback <N> .. cfgcmd:: rollback <N>
@ -482,17 +506,17 @@ apply the selected revision and trigger a system reboot.
Remote Archive Remote Archive
-------------- --------------
VyOS can upload the configuration to a remote location after each call to VyOS can upload the configuration to a remote location after each call
:cfgcmd:`commit`. You will have to set the commit-archive location. to :cfgcmd:`commit`. You will have to set the commit-archive location.
TFTP, FTP, and SFTP servers are supported. TFTP, FTP, and SFTP servers are supported. Every time a :cfgcmd:`commit`
Every time a :cfgcmd:`commit` is successfull is successfull the ``config.boot`` file will be copied to the defined
the ``config.boot`` file will be copied to the defined destination(s). destination(s). The filename used on the remote host will be
The filename used on the remote host will be ``config.boot-hostname.YYYYMMDD_HHMMSS`` ``config.boot-hostname.YYYYMMDD_HHMMSS``
.. cfgcmd:: set system config-management commit-archive location <URI> .. cfgcmd:: set system config-management commit-archive location <URI>
Specify remote location of commit archive as any of the below :abbr:`URI (Uniform Specify remote location of commit archive as any of the below
Resource Identifier)` :abbr:`URI (Uniform Resource Identifier)`
* ``scp://<user>:<passwd>@<host>/<dir>`` * ``scp://<user>:<passwd>@<host>/<dir>``
* ``sftp://<user>:<passwd>@<host>/<dir>`` * ``sftp://<user>:<passwd>@<host>/<dir>``
@ -504,19 +528,20 @@ The filename used on the remote host will be ``config.boot-hostname.YYYYMMDD_HHM
Restore Default Restore Default
--------------- ---------------
In the case you want to completely delete your configuration and restore the In the case you want to completely delete your configuration and restore
default one, you can enter the following command in configuration mode: the default one, you can enter the following command in configuration
mode:
.. code-block:: none .. code-block:: none
load /opt/vyatta/etc/config.boot.default load /opt/vyatta/etc/config.boot.default
You will be asked if you want to continue. If you accept, you will have to use You will be asked if you want to continue. If you accept, you will have
:cfgcmd:`commit` if you want to make the changes active. 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 Then you may want to :cfgcmd:`save` in order to delete the saved
too. configuration too.
.. note:: If you are remotely connected, you will lose your connection. You may .. note:: If you are remotely connected, you will lose your connection.
want to copy first the config, edit it to ensure connectivity, and load the You may want to copy first the config, edit it to ensure
edited config. connectivity, and load the edited config.