diff options
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | docs/commandtree/configmode.rst | 500 | ||||
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | docs/system/eventhandler.rst | 48 | ||||
| -rw-r--r-- | docs/system/flowaccounting.rst | 26 | ||||
| -rw-r--r-- | docs/system/index.rst | 4 |
6 files changed, 578 insertions, 4 deletions
@@ -38,4 +38,4 @@ Windows PowerShell docker run -v "$($pwd.path):/vyos" -w "/vyos/docs" -i -t --rm vyos-docu bash ``` -Inside the container you can the build the documentation as stated above +Inside the container you can then build the documentation as stated above. diff --git a/docs/commandtree/configmode.rst b/docs/commandtree/configmode.rst index ca8df284..abb20f98 100644 --- a/docs/commandtree/configmode.rst +++ b/docs/commandtree/configmode.rst @@ -23,4 +23,502 @@ Configuration mode run Run an operational-mode command save Save configuration to a file set Set the value of a parameter or create a new element - show Show the configuration (default values may be suppressed)
\ No newline at end of file + show Show the configuration (default values may be suppressed) + + +Confirm +^^^^^^^ + +The ``confirm`` command confirms the prior ``commit-confirm``. + +Comment +^^^^^^^ + +The ``comment`` commands allow you to insert a comment above the current configuration section. +The command cannot be used at the top of the configuration hierarchy, only on subsections. Comments needs to be commited, just like other config changes. + +To add a comment to a section, while being already at the proper section level: + +.. code-block:: sh + + [edit <section>] + vyos@vyos# comment "Type Comment Here" + +To add a comment directly to a section, from the top or a higher section: + +.. code-block:: sh + + [edit] + vyos@vyos# comment <section> "Type Comment Here" + +To remove a comment, add a blank comment to overwrite: + +.. code-block:: sh + + [edit <section>] + vyos@vyos# comment "" + +Examples +******** + +To add a comment to the "interfaces" section: + +.. code-block:: sh + + [edit] + vyos@vyos# edit interfaces + [edit interfaces] + vyos@vyos# comment "Here is a comment" + [edit interfaces] + vyos@vyos# commit + +The comment would then appear like this: + +.. code-block:: sh + + [edit] + vyos@vyos# show + /* Here is a comment */ + interfaces { + ethernet eth0 { + [...] + + +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 interfaces`` command would return starting after the "interfaces {" line, hiding the comment: + +.. code-block:: sh + + [edit] + vyos@vyos# show interfaces + ethernet eth0 { + [...] + + +To add a comment to the interfaces section from the top: + +.. code-block:: sh + + [edit] + vyos@vyos# comment interfaces "test" + + +The comment can be added to any node that already exists, even if it's multiple levels lower: + +.. code-block:: sh + + [edit] + vyos@vyos# comment interfaces ethernet eth0 vif 222 address "Far down comment" + + +Commit +^^^^^^ + +The ``commit`` command commits the proposed changes to the configuration file. +Every changes done in the configuration session is only applied when the configuration is committed. To view the changes that will be applied, use the show command. +To discard the changes without committing, use the ``discard`` command. The ``commit`` command doesn't save the configuration, you need to manually use the ``save`` command. + +The confirm keyword can be added, see ``commit-confirm``. A comment can be entered, it will appear in the commit log. + +.. code-block:: sh + + [edit] + vyos@vyos# commit + Possible completions: + <Enter> Commit working configuration + comment Comment for commit log + +Commit-confirm +^^^^^^^^^^^^^^ + +The ``commit-confirm`` command commits the proposed changes to the configuration file and starts a timer. +If the ``confirm`` command is not entered before the timer expiration, the configuration will be rolled back and VyOS will reboot. +The default timer value is 10 minutes, but a custom value can be entered. + +.. code-block:: sh + + [edit] + vyos@vyos# commit-confirm + Possible completions: + <Enter> Commit, rollback/reboot in 10 minutes if no confirm + <N> Commit, rollback/reboot in N minutes if no confirm + comment Comment for commit log + + +Compare +^^^^^^^ + +VyOS maintains backups of previous configurations. To compare configuration revisions in configuration mode, use the compare command: + +.. code-block:: sh + + [edit] + vyos@vyos# compare + 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 2019-03-20 20:57:22 root by boot-config-loader + 1 2019-03-15 20:00:04 root by boot-config-loader + 2 2019-03-05 01:58:39 vyos by cli + 3 2019-03-05 01:54:59 vyos by cli + 4 2019-03-05 01:53:08 vyos by cli + 5 2019-03-05 01:52:21 vyos by cli + 6 2019-02-24 21:01:24 root by boot-config-loader + 7 2019-02-21 22:00:12 vyos by cli + 8 2019-02-21 21:56:49 vyos by cli + + +Copy +^^^^ + +The ``copy`` command allows you to copy a configuration object. + +Copy the configuration entrys from a firewall name WAN rule 1 to rule 2. + +.. code-block:: sh + + [edit firewall name WAN] + vyos@vyos# show + rule 1 { + action accept + source { + address 10.1.0.0/24 + } + } + [edit firewall name WAN] + vyos@vyos# copy rule 1 to rule 2 + [edit firewall name WAN] + vyos@vyos# show + rule 1 { + action accept + source { + address 10.1.0.0/24 + } + } + +rule 2 { + + action accept + + source { + + address 10.1.0.0/24 + + } + +} + +Delete +^^^^^^ + +The ``delte`` command is to delete a configuration entry. + +This Example delete the hole ``service tftp-server`` section. + +.. code-block:: sh + + delete service tftp-server + +Discard +^^^^^^^ + +The ``discard`` command removes all pending configuration changes. + +.. code-block:: sh + + [edit] + vyos@vyos# discard + + Changes have been discarded + +Edit +^^^^ + +The ``edit`` command allows you to navigate down into the configuration tree. +To get back to an upper level, use the ``up`` command or use the ``top`` command to get back to the upper most level. +The ``[edit]`` text displays where the user is located in the configuration tree. + +.. code-block:: sh + + [edit] + vyos@vyos# edit interfaces + [edit interfaces] + vyos@vyos# edit ethernet eth0 + [edit interfaces ethernet eth0] + +Exit +^^^^ + +The ``exit`` command exits the current configuration mode. If the current configuration level isn't the top-most, then the configuration level is put back to the top-most level. +If the configuration level is at the top-most level, then it exits the configuration mode and returns to operational mode. +The ``exit`` command cannot be used if uncommitted changes exists in the configuration file. To exit with uncommitted changes, you either need to use the ``exit discard`` command or you need to commit the changes before exiting. +The ``exit`` command doesn't save the configuration, only the ``save`` command does. A warning will be given when exiting with unsaved changes. Using the ``exit`` command in operational mode will logout the session. + + +Exiting from a configuration level: + + +.. code-block:: sh + + [edit interfaces ethernet eth0] + vyos@vyos# exit + [edit] + vyos@vyos# + +Exiting from configuration mode: + +.. code-block:: sh + + [edit] + vyos@vyos# exit + exit + vyos@vyos:~$ + +Exiting from operational mode: + +.. code-block:: sh + + vyos@vyos:~$ exit + logout + +Error message when trying to exit with uncommitted changes: + +.. code-block:: sh + + vyos@vyos# exit + Cannot exit: configuration modified. + Use 'exit discard' to discard the changes and exit. + [edit] + vyos@vyos# + + +Warning message when exiting with unsaved changes: + +.. code-block:: sh + + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + exit + vyos@vyos:~$ + +Load +^^^^ + +The ``load`` command load a configuration from a local or remote file. You have to be use ``commit`` to make the change active + +.. code-block:: sh + + <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 + + +.. code-block:: sh + + [edit] + vyos@vyos# load + Loading configuration from '/config/config.boot'... + + Load complete. Use 'commit' to make changes active. + + +Loadkey +^^^^^^^^ + +Copies the content of a public key to the ~/.ssh/authorized_keys file. + +.. code-block:: sh + + loadkey <username> [tab] + + <file> Load from file on local machine + scp://<user>@<host>/<file> Load from file on remote machine + sftp://<user>@<host>/<file> Load from file on remote machine + ftp://<user>@<host>/<file> Load from file on remote machine + http://<host>/<file> Load from file on remote machine + tftp://<host>/<file> Load from file on remote machine + +Merge +^^^^^ + +The ``merge`` command merge the config from a local or remote file with the running config. + +In the example below exist a ``default-firewall.config`` file with some common firewall rules you saved earlier. + +.. code-block:: sh + + [edit] + vyos@vyos# show firewall + Configuration under specified path is empty + [edit] + vyos@vyos# merge default-firewall.config + Loading configuration from '/config/default-firewall.config'... + + Merge complete. Use 'commit' to make changes active. + [edit] + vyos@vyos# + + vyos@vyos# show firewall + +all-ping enable + +broadcast-ping disable + +config-trap disable + +ipv6-receive-redirects disable + +ipv6-src-route disable + +ip-src-route disable + +log-martians enable + +name WAN { + + default-action drop + + rule 1 { + + action accept + + source { + + address 10.1.0.0/24 + + } + + } + + rule 2 { + + action accept + + source { + + address 10.1.0.0/24 + + } + ...... + + +Rename +^^^^^^ + +The ``rename`` command allows you to rename or move a configuration object. + +See here how to move the configuration entrys from vlanid 3 to 2 + +.. code-block:: sh + + [edit interfaces ethernet eth1] + vyos@vyos# show + duplex auto + hw-id 08:00:27:81:c6:59 + smp-affinity auto + speed auto + vif 3 { + address 10.4.4.4/32 + } + [edit interfaces ethernet eth1] + vyos@vyos# rename vif 3 to vif 2 + [edit interfaces ethernet eth1] + vyos@vyos# show + duplex auto + hw-id 08:00:27:81:c6:59 + smp-affinity auto + speed auto + +vif 2 { + + address 10.4.4.4/32 + +} + -vif 3 { + - address 10.4.4.4/32 + -} + [edit interfaces ethernet eth1] + vyos@vyos# + + +Rollback +^^^^^^^^ + +You can ``rollback`` configuration using the rollback command, however this command will currently trigger a system reboot. +Use the compare command to verify the configuration you want to rollback to. + +.. code-block:: sh + + 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 2018): + + The system is going down for reboot NOW! + [edit] + vyos@vyos# + +Run +^^^ + +The ``run`` command allows you to execute any operational mode commands without exiting the configuration session. + +.. code-block:: sh + + [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 10.1.1.1/24 u/u + + +Save +^^^^ + +The ``save`` command saves the current configuration to non-volatile storage. VyOS also supports saving and loading configuration remotely using SCP, FTP, or TFTP. + +.. code-block:: sh + + <Enter> Save to system config file + <file> Save to file on local machine + scp://<user>:<passwd>@<host>/<file> Save to file on remote machine + sftp://<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 + +Set +^^^ + +The ``set`` command create all configuration entrys + +.. code-block:: sh + + [edit] + vyos@vyos# set protocols static route 0.0.0.0/0 next-hop 192.168.1.1 + +Show +^^^^ + +The ``show`` command in the configuration mode displays the configuration and show uncommitted changes. + +Show the hole config, the address and description of eth1 is moving to vlan 2 if you commit the changes. + +.. code-block:: sh + + [edit] + vyos@vyos# show + interfaces { + dummy dum0 { + address 10.3.3.3/24 + } + ethernet eth0 { + address dhcp + duplex auto + hw-id 08:00:27:2b:c0:0b + smp-affinity auto + speed auto + } + ethernet eth1 { + - address 10.1.1.1/32 + - description "MGMT Interface" + duplex auto + hw-id 08:00:27:81:c6:59 + smp-affinity auto + speed auto + + vif 2 { + + address 10.1.1.1/32 + + description "MGMT Interface" + + } + } + loopback lo { + } + } + service { + ssh { + port 22 + ......
\ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index e193541f..344cd761 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,7 +28,7 @@ as a router and firewall platform for cloud deployments. services/index.rst system/index.rst clustering.rst - image-mgmt.rst + image-mgmt.rst troubleshooting.rst examples.rst commandtree/index.rst diff --git a/docs/system/eventhandler.rst b/docs/system/eventhandler.rst new file mode 100644 index 00000000..6204abcc --- /dev/null +++ b/docs/system/eventhandler.rst @@ -0,0 +1,48 @@ +.. _event-handler: + +Event Handler +------------- + +Event handler allows you to execute scripts when a string that matches a regex appears in a text stream (e.g. log file). + +It uses "feeds" (output of commands, or a named pipes) and "policies" that define what to execute if a regex is matched. + +.. code-block:: sh + + system + event-handler + feed <name> + description <feed description> + policy <policy name> + source + preset + syslog # Use the syslog logs for feed + custom + command <command to execute> # E.g. "tail -f /var/log/somelogfile" + named-pipe <path to a names pipe> + policy <policy name> + description <policy description> + event <event name> + description <event description> + pattern <regex> + run <command to run> + +In this small example a script runs every time a login failed and an interface goes down + +.. code-block:: sh + + vyos@vyos# show system event-handler + feed Syslog { + policy MyPolicy + source { + preset syslog + } + } + policy MyPolicy { + description "Test policy" + event BadThingsHappened { + pattern "authentication failure" + pattern "interface \.* index \d+ .* DOWN.*" + run /config/scripts/email-to-admin + } + }
\ No newline at end of file diff --git a/docs/system/flowaccounting.rst b/docs/system/flowaccounting.rst new file mode 100644 index 00000000..1231dcf3 --- /dev/null +++ b/docs/system/flowaccounting.rst @@ -0,0 +1,26 @@ +.. _flow-accounting: + + +Flow Accounting +--------------- + +VyOS supports flow accounting through NetFlow or sFlow. + +For both types you need to specify the interfaces for which the data will be collected: + +.. code-block:: sh + + set system flow-accounting interface eth0 + set system flow-accounting interface bond3 + + +NetFlow is a protocol originating from Cisco Systems. It works on level3. +VyOS supports version 1, 5 and 9 + +NetFlow v5 example: + +.. code-block:: sh + + set system flow-accounting netflow engine-id 100 + set system flow-accounting netflow version 5 + set system flow-accounting netflow server 192.168.2.10 port 2055
\ No newline at end of file diff --git a/docs/system/index.rst b/docs/system/index.rst index aa414a82..368b62ff 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -10,7 +10,9 @@ should be ready for further configuration which is described in this chapter. .. toctree:: :maxdepth: 2 :hidden: - + + eventhandler + flowaccounting host-information systemusers syslog |