mirror of
https://github.com/vyos/vyos-documentation.git
synced 2025-10-26 08:41:46 +01:00
overview: rewrite with new cfgcmd/opcmd syntax
This commit is contained in:
Christian Poessinger
parent
b61205ca9d
commit
21aec14168
@ -4,12 +4,38 @@
|
||||
Configuration Overview
|
||||
######################
|
||||
|
||||
VyOS makes use of a unified configuration file for all system configuration:
|
||||
`config.boot`. This allows for easy template creation, backup, and replication
|
||||
of system configuration.
|
||||
VyOS makes use of a unified configuration file for the entire systems
|
||||
configuration: ``/config/config.boot``. This allows easy template creation,
|
||||
backup, and replication of system configuration. A sytem can thus also be
|
||||
easily cloned by simply copying the required configuration files.
|
||||
|
||||
The current active configuration -aka running configuration- can be viewed
|
||||
using the show configuration command.
|
||||
Terminology
|
||||
===========
|
||||
|
||||
A VyOS system has three major types of configurations:
|
||||
|
||||
* **Active/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** - is the configuration which 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** - is a configuration 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``.
|
||||
|
||||
Work the Config
|
||||
===============
|
||||
|
||||
.. opcmd:: show configuration
|
||||
|
||||
View the current active configuration, also known as the running
|
||||
configuration.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -17,7 +43,7 @@ using the show configuration command.
|
||||
interfaces {
|
||||
ethernet eth0 {
|
||||
address dhcp
|
||||
hw-id 00:53:dd:44:3b:0f
|
||||
hw-id 00:53:00:00:aa:01
|
||||
}
|
||||
loopback lo {
|
||||
}
|
||||
@ -64,10 +90,10 @@ using the show configuration command.
|
||||
}
|
||||
}
|
||||
|
||||
By default the configuration is displayed in a hierarchy like the example above,
|
||||
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 ``set`` and ``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
|
||||
|
||||
@ -92,43 +118,15 @@ running configuration.
|
||||
set system syslog global facility protocols level 'debug'
|
||||
|
||||
Both these commands should be executed when in operational mode, they do not
|
||||
work in configuration mode.
|
||||
|
||||
Terminology
|
||||
===========
|
||||
|
||||
A VyOS system has three major types of configurations:
|
||||
|
||||
Active/Running
|
||||
--------------
|
||||
|
||||
The active or running configuration is the system configuration that is loaded
|
||||
and currently being used by VyOS. Any change in the configuration will have to
|
||||
be committed to belong to the active/running configuration.
|
||||
|
||||
Working
|
||||
-------
|
||||
|
||||
The working configuration is the configuration which 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 `commit` command.
|
||||
At which time the working configuration will become the active or running
|
||||
configuration.
|
||||
|
||||
Saved
|
||||
-----
|
||||
|
||||
A saved configuration is a configuration saved to a file using the ``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.boot.
|
||||
work directly in configuration mode. The is a special way on how to
|
||||
:ref:`run_opmode_from_config_mode`.
|
||||
|
||||
Navigating
|
||||
==========
|
||||
|
||||
When entering the configuration mode you are navigating inside the tree
|
||||
structure exported in the overview above, to enter configuration mode enter
|
||||
the command ``configure`` when in operational mode.
|
||||
the command :opcmd:`configure` when in operational mode.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -136,14 +134,11 @@ the command ``configure`` when in operational mode.
|
||||
[edit]
|
||||
vyos@vyos#
|
||||
|
||||
.. note:: When going into configuration mode, prompt changes from *$* to *#*.
|
||||
To exit configuration mode, type `exit`.
|
||||
|
||||
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.
|
||||
|
||||
To change the current hierarchy level use the command: ``edit``
|
||||
The current hierarchy level can be changed by the :cfgcmd:`edit` command.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -155,13 +150,19 @@ To change the current hierarchy level use the command: ``edit``
|
||||
|
||||
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 ``top`` or ``exit`` command to go back to the top of the hierarchy. You can
|
||||
also use the ``up`` command to move only one level up at a time.
|
||||
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.
|
||||
|
||||
The ``show`` command within configuration mode will show the working
|
||||
The :cfgcmd:`show` command within configuration mode will show the working
|
||||
configuration indicating line changes with ``+`` for additions, ``>`` for
|
||||
replacements and ``-`` for deletions.
|
||||
|
||||
.. note:: When going into configuration mode, prompt changes from
|
||||
``$`` to ``#``.
|
||||
|
||||
**Example:**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
vyos@vyos:~$ configure
|
||||
@ -192,7 +193,7 @@ replacements and ``-`` for deletions.
|
||||
}
|
||||
|
||||
It is also possible to display all `set` commands within configuration mode
|
||||
using ``show | commands``
|
||||
using :cfgcmd:`show | commands`
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -210,9 +211,9 @@ configuration blocks will be displayed when entering a sub-level.
|
||||
address dhcp
|
||||
hw-id 00:53:ad:44:3b:03
|
||||
|
||||
Exiting from the configuration mode is done via the ``exit`` command from the
|
||||
top level, executing `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.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -225,14 +226,13 @@ level.
|
||||
Managing
|
||||
========
|
||||
|
||||
The configuration is managed by the use of ``set`` and ``delete`` commands from
|
||||
within configuration mode. Configuration commands are flattened from the tree
|
||||
into 'one-liner' commands shown in ``show configuration commands`` from
|
||||
operation mode.
|
||||
The configuration is managed by the use of :cfgcmd:`set` and :cfgcmd:`delete`
|
||||
commands from within configuration mode. Configuration commands are flattened
|
||||
from the tree into 'one-liner' commands shown in :opcmd:`show configuration
|
||||
commands` from operation mode.
|
||||
|
||||
These commands are also relative to the level where they are executed and all
|
||||
redundant information from the current level is removed from the command
|
||||
entered.
|
||||
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
|
||||
|
||||
@ -245,18 +245,22 @@ entered.
|
||||
These two commands above are essentially the same, just executed from different
|
||||
levels in the hierarchy.
|
||||
|
||||
To delete a configuration entry use the ``delete`` command, this also deletes
|
||||
all sub-levels under the current level you've specified in the ``delete``
|
||||
command. Deleting an entry will also result in the element reverting back to
|
||||
its default value if one exists.
|
||||
.. 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 ``commit`` command in configuration mode.
|
||||
using the :cfgcmd:`commit` command in configuration mode.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -266,9 +270,11 @@ using the ``commit`` command in configuration mode.
|
||||
Warning: configuration changes have not been saved.
|
||||
vyos@vyos:~$
|
||||
|
||||
In order to preserve configuration changes upon reboot, the configuration must
|
||||
also be saved once applied. This is done using the ``save`` command in
|
||||
configuration mode.
|
||||
.. cfgcmd:: save
|
||||
|
||||
In order to preserve configuration changes upon reboot, the configuration
|
||||
must also be saved once applied. This is done using the :cfgcmd:`save`
|
||||
command in configuration mode.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -276,18 +282,6 @@ configuration mode.
|
||||
Saving configuration to '/config/config.boot'...
|
||||
Done
|
||||
|
||||
Configuration mode can not be exited while uncommitted changes exist. To exit
|
||||
configuration mode without applying changes, the exit discard command can be
|
||||
used.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
vyos@vyos# exit
|
||||
Cannot exit: configuration modified.
|
||||
Use 'exit discard' to discard the changes and exit.
|
||||
[edit]
|
||||
vyos@vyos# exit discard
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
vyos@vyos# save [tab]
|
||||
@ -302,12 +296,32 @@ used.
|
||||
######################################################################## 100.0%
|
||||
Done
|
||||
|
||||
Access from config mode
|
||||
=======================
|
||||
.. 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
|
||||
|
||||
.. _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.
|
||||
@ -323,22 +337,25 @@ Command completion and syntax help with ``?`` and ``[tab]`` will also work.
|
||||
--------- ---------- --- -----------
|
||||
eth0 0.0.0.0/0 u/u
|
||||
|
||||
Archive
|
||||
=======
|
||||
Config Archive
|
||||
==============
|
||||
|
||||
VyOS automatically maintains backups of previous configurations.
|
||||
VyOS automatically maintains backups of every previous configurations which
|
||||
has been comitted to the system.
|
||||
|
||||
Local archive and revisions
|
||||
---------------------------
|
||||
Local Archive
|
||||
-------------
|
||||
|
||||
Revisions are stored on disk. You can view them, compare them, and rollback to
|
||||
previous revisions if anything goes wrong.
|
||||
Revisions are stored on disk. You can view, compare and rollback them to any
|
||||
previous revisions if something goes wrong.
|
||||
|
||||
To view existing revisions, use ``show system commit`` operational mode command.
|
||||
.. opcmd:: show system commit
|
||||
|
||||
View all existing revisions on the local system.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
vyos@vyos-test-2# run show system commit
|
||||
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
|
||||
@ -348,8 +365,9 @@ To view existing revisions, use ``show system commit`` operational mode command.
|
||||
6 2015-03-25 00:16:47 by vyos via cli
|
||||
7 2015-03-24 23:43:45 by root via boot-config-loader
|
||||
|
||||
To compare configuration revisions in configuration mode, use the compare
|
||||
command:
|
||||
.. cfgcmd:: compare <saved | N> <M>
|
||||
|
||||
Compare difference in configuration revisions.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -372,18 +390,15 @@ command:
|
||||
9 2013-12-12 15:42:07 root by boot-config-loader
|
||||
10 2013-12-12 15:42:06 root by init
|
||||
|
||||
Comparing Revisions
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can compare revisions with ``compare X Y`` command, where X and Y are
|
||||
revision numbers. The output will describe how the configuration X is when
|
||||
compared to Y, indicating with a plus sign (``+``) the additional parts X has
|
||||
when compared to y, and indicating with a minus sign (``-``) the lacking parts
|
||||
x misses when compared to y.
|
||||
Revisions can be compared with :cfgcmd:`compare N M` command, where N and M
|
||||
are revision numbers. The output will describe how the configuration N is
|
||||
when compared to YM 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 Y.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
vyos@vyos-test-2# compare 0 6
|
||||
vyos@vyos# compare 0 6
|
||||
[edit interfaces]
|
||||
+dummy dum1 {
|
||||
+ address 10.189.0.1/31
|
||||
@ -396,46 +411,48 @@ x misses when compared to y.
|
||||
- address 192.0.2.4/24
|
||||
-}
|
||||
|
||||
Rolling Back Changes
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
.. cfgcmd:: set system config-management commit-revisions <N>
|
||||
|
||||
You can rollback configuration using the rollback command. This command will
|
||||
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.
|
||||
|
||||
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!
|
||||
|
||||
Configuring the archive size
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Remote Archive
|
||||
--------------
|
||||
|
||||
You can specify the number of revisions stored on disk with ``set system
|
||||
config-management commit-revisions X``, where X is a number between 0 and 65535.
|
||||
When the number of revisions exceeds that number, the oldest revision is
|
||||
removed.
|
||||
VyOS can upload the configuration to a remote location after each call to
|
||||
:cfgcmd:`commit`. TFTP, FTP, and SFTP servers are supported.
|
||||
|
||||
Remote archive
|
||||
^^^^^^^^^^^^^^
|
||||
.. cfgcmd set system config-management commit-archive location <URI>
|
||||
|
||||
VyOS can copy the config to a remote location after each commit. TFTP, FTP,
|
||||
and SFTP servers are supported.
|
||||
Specify remote location of commit archive.
|
||||
|
||||
You can specify the location with:
|
||||
|
||||
* ``set system config-management commit-archive location URL``
|
||||
|
||||
For example, ``set system config-management commit-archive location tftp://10.0.0.1/vyos``.
|
||||
|
||||
You can specify the location with ``set system config-management commit-archive
|
||||
location URL`` command, e.g. ``set system config-management commit-archive
|
||||
location tftp://10.0.0.1/vyos``.
|
||||
* scp://<user>:<passwd>@<host>/<dir>
|
||||
* sftp://<user>:<passwd>@<host>/<dir>
|
||||
* ftp://<user>:<passwd>@<host>/<dir>
|
||||
* tftp://<host>/<dir>
|
||||
|
||||
Restore Default
|
||||
===============
|
||||
@ -447,10 +464,11 @@ default one, you can enter the following command in configuration mode:
|
||||
|
||||
load /opt/vyatta/etc/config.boot.default
|
||||
|
||||
You will be asked if you want to continue. If you accept,
|
||||
you will have to use `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 ``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:: 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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user