From 2d5ece952b5971fc653f2855376b525b92f9a13b Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Fri, 5 Oct 2018 16:10:41 +0200 Subject: Remove IPv6 chapter IPv6 specific stuff is handeled direclty in the chapters like Network Interface addresses or BGP. --- docs/ch13-clustering.rst | 28 ++++++++ docs/ch13-ipv6.rst | 4 -- docs/ch14-clustering.rst | 28 -------- docs/ch14-image-mgmt.rst | 104 +++++++++++++++++++++++++++ docs/ch15-image-mgmt.rst | 104 --------------------------- docs/ch15-troubleshooting.rst | 164 ++++++++++++++++++++++++++++++++++++++++++ docs/ch16-troubleshooting.rst | 164 ------------------------------------------ docs/index.rst | 8 +-- 8 files changed, 299 insertions(+), 305 deletions(-) create mode 100644 docs/ch13-clustering.rst delete mode 100644 docs/ch13-ipv6.rst delete mode 100644 docs/ch14-clustering.rst create mode 100644 docs/ch14-image-mgmt.rst delete mode 100644 docs/ch15-image-mgmt.rst create mode 100644 docs/ch15-troubleshooting.rst delete mode 100644 docs/ch16-troubleshooting.rst (limited to 'docs') diff --git a/docs/ch13-clustering.rst b/docs/ch13-clustering.rst new file mode 100644 index 00000000..9f14c6ae --- /dev/null +++ b/docs/ch13-clustering.rst @@ -0,0 +1,28 @@ +Clustering +========== + +VyOS supports multicast and unicast clustering. Multicast is default and to +use the unicast method you can add the peer directive to the interface with +the ip of the other cluster member. + +In the example below SSH is clustered between two nodes with the unicast +method. + +.. code-block:: sh + + cluster { + dead-interval 20000 + group cluster { + auto-failback false + primary vyos + secondary vyos2 + service ssh + service 192.168.0.123/24/eth0 + } + interface eth0 { + peer 192.168.0.121 + } + keepalive-interval 5000 + monitor-dead-interval 20000 + pre-shared-secret S3cr#t + } diff --git a/docs/ch13-ipv6.rst b/docs/ch13-ipv6.rst deleted file mode 100644 index 7d5ce6a2..00000000 --- a/docs/ch13-ipv6.rst +++ /dev/null @@ -1,4 +0,0 @@ -IPv6 -==== - -Need to import content from https://wiki.vyos.net/wiki/IPv6 diff --git a/docs/ch14-clustering.rst b/docs/ch14-clustering.rst deleted file mode 100644 index 9f14c6ae..00000000 --- a/docs/ch14-clustering.rst +++ /dev/null @@ -1,28 +0,0 @@ -Clustering -========== - -VyOS supports multicast and unicast clustering. Multicast is default and to -use the unicast method you can add the peer directive to the interface with -the ip of the other cluster member. - -In the example below SSH is clustered between two nodes with the unicast -method. - -.. code-block:: sh - - cluster { - dead-interval 20000 - group cluster { - auto-failback false - primary vyos - secondary vyos2 - service ssh - service 192.168.0.123/24/eth0 - } - interface eth0 { - peer 192.168.0.121 - } - keepalive-interval 5000 - monitor-dead-interval 20000 - pre-shared-secret S3cr#t - } diff --git a/docs/ch14-image-mgmt.rst b/docs/ch14-image-mgmt.rst new file mode 100644 index 00000000..05370d8c --- /dev/null +++ b/docs/ch14-image-mgmt.rst @@ -0,0 +1,104 @@ +System Image Management +======================= + +The VyOS image-based installation is implemented by creating a directory for +each image on the storage device selected during the install process. + +The directory structure of the boot device: + +.. code-block:: sh + + / + /boot + /boot/grub + /boot/1.2.0-rolling+201810021347 + +The image directory contains the system kernel, a compressed image of the root +filesystem for the OS, and a directory for persistent storage, such as +configuration. + +On boot, the system will extract the OS image into memory and mount the +appropriate live-rw sub-directories to provide persistent storage system +configuration. + +This process allows for a system to always boot to a known working state, as +the OS image is fixed and non-persistent. It also allows for multiple releases +of VyOS to be installed on the same storage device. + +The image can be selected manually at boot if needed, but the system will +otherwise boot the image configured to be the default. + +The default boot image can be set using the :code:`set system image +default-boot` command in operational mode. + +A list of available images can be shown using the :code:`show system image` +command in operational mode. + +.. code-block:: sh + + vyos@vyos:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809280337 + 4: 1.2.0-rolling+201809252218 + 5: 1.2.0-rolling+201809192034 + 6: 1.2.0-rolling+201809191744 + 7: 1.2.0-rolling+201809150337 + 8: 1.2.0-rolling+201809141130 + 9: 1.2.0-rolling+201809140949 + 10: 1.2.0-rolling+201809131722 + + vyos@vyos:~$ + +Images no longer needed can be removed using the :code:`delete system image` +command. + + +Update VyOS Installation +------------------------ + +Finally, new system images can be added using the `add system image` command. +The add image command will extract the image from the release ISO (either on +the local filesystem or remotely if a URL is provided). The image install +process will prompt you to use the current system configuration and SSH +security keys, allowing for the new image to boot using the current +configuration. + +.. code-block:: sh + + vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso + Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 + curl: (22) The requested URL returned error: 404 Not Found + + Unable to fetch digital signature file. + Do you want to continue without signature check? (yes/no) [yes] + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [1.2.0-rolling+201810030440]: + + OK. This image will be named: 1.2.0-rolling+201810030440 + We do not have enough disk space to install this image! + We need 344880 KB, but we only have 17480 KB. + Exiting... + +**NOTE #1:** Rolling releases are not GPG signed, only the real release build +will have a proper GPG signature. + +**NOTE #2:** VyOS configuration is associated to each image, and each image has +a unique copy of its configuration. This is different than a traditional +network router where the configuration is shared across all images. + +If you need some files from a previous images - take a look inside a +:code:`/live` directory. + diff --git a/docs/ch15-image-mgmt.rst b/docs/ch15-image-mgmt.rst deleted file mode 100644 index 05370d8c..00000000 --- a/docs/ch15-image-mgmt.rst +++ /dev/null @@ -1,104 +0,0 @@ -System Image Management -======================= - -The VyOS image-based installation is implemented by creating a directory for -each image on the storage device selected during the install process. - -The directory structure of the boot device: - -.. code-block:: sh - - / - /boot - /boot/grub - /boot/1.2.0-rolling+201810021347 - -The image directory contains the system kernel, a compressed image of the root -filesystem for the OS, and a directory for persistent storage, such as -configuration. - -On boot, the system will extract the OS image into memory and mount the -appropriate live-rw sub-directories to provide persistent storage system -configuration. - -This process allows for a system to always boot to a known working state, as -the OS image is fixed and non-persistent. It also allows for multiple releases -of VyOS to be installed on the same storage device. - -The image can be selected manually at boot if needed, but the system will -otherwise boot the image configured to be the default. - -The default boot image can be set using the :code:`set system image -default-boot` command in operational mode. - -A list of available images can be shown using the :code:`show system image` -command in operational mode. - -.. code-block:: sh - - vyos@vyos:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.2.0-rolling+201810021347 (default boot) - 2: 1.2.0-rolling+201810021217 - 3: 1.2.0-rolling+201809280337 - 4: 1.2.0-rolling+201809252218 - 5: 1.2.0-rolling+201809192034 - 6: 1.2.0-rolling+201809191744 - 7: 1.2.0-rolling+201809150337 - 8: 1.2.0-rolling+201809141130 - 9: 1.2.0-rolling+201809140949 - 10: 1.2.0-rolling+201809131722 - - vyos@vyos:~$ - -Images no longer needed can be removed using the :code:`delete system image` -command. - - -Update VyOS Installation ------------------------- - -Finally, new system images can be added using the `add system image` command. -The add image command will extract the image from the release ISO (either on -the local filesystem or remotely if a URL is provided). The image install -process will prompt you to use the current system configuration and SSH -security keys, allowing for the new image to boot using the current -configuration. - -.. code-block:: sh - - vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso - Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 - curl: (22) The requested URL returned error: 404 Not Found - - Unable to fetch digital signature file. - Do you want to continue without signature check? (yes/no) [yes] - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [1.2.0-rolling+201810030440]: - - OK. This image will be named: 1.2.0-rolling+201810030440 - We do not have enough disk space to install this image! - We need 344880 KB, but we only have 17480 KB. - Exiting... - -**NOTE #1:** Rolling releases are not GPG signed, only the real release build -will have a proper GPG signature. - -**NOTE #2:** VyOS configuration is associated to each image, and each image has -a unique copy of its configuration. This is different than a traditional -network router where the configuration is shared across all images. - -If you need some files from a previous images - take a look inside a -:code:`/live` directory. - diff --git a/docs/ch15-troubleshooting.rst b/docs/ch15-troubleshooting.rst new file mode 100644 index 00000000..47abab04 --- /dev/null +++ b/docs/ch15-troubleshooting.rst @@ -0,0 +1,164 @@ +Troubleshooting +=============== + +Sometimes things break or don't work as expected. This section describes +several troubleshooting tools provided by VyOS that can help when something +goes wrong. + +Basic Connectivity Verification +------------------------------- + +Verifying connectivity can be done with the familiar `ping` and `traceroute` +commands. The options for each are shown (the options for each command were +displayed using the built-in help as described in the `Command-Line Interface`_ +section and are omitted from the output here): + +.. code-block:: sh + + vyos@vyos:~$ ping + Possible completions: + Send Internet Control Message Protocol (ICMP) echo request + + + +Several options are available when more extensive troubleshooting is needed: + +.. code-block:: sh + + vyos@vyos:~$ ping 8.8.8.8 + Possible completions: + Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + +.. code-block:: sh + + vyos@vyos:~$ traceroute + Possible completions: + Track network path to specified node + + + ipv4 Track network path to + ipv6 Track network path to + +However, another tool, mtr_, is available which combines ping and traceroute +into a single tool. An example of its output is shown: + +.. code-block:: sh + + vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] + vyos (0.0.0.0) + Keys: Help Display mode Restart statistics Order of fields quit + Packets Pings + Host Loss% Snt Last Avg Best Wrst StDev + 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 + 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 + 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 + 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 + +**NOTE:** The output of '''mtr''' consumes the screen and will replace your +command prompt. + +Several options are available for changing the display output. Press `h` to +invoke the built in help system. To quit, just press `q` and you'll be returned +to the VyOS command prompt. + +Monitoring Network Interfaces +----------------------------- + +It's possible to monitor network traffic, either at the flow level or protocol +level. This can be useful when troubleshooting a variety of protocols and +configurations. The following interface types can be monitored: + +.. code-block:: sh + + vyos@vyos:~$ monitor interfaces + Possible completions: + Execute the current command + bonding Monitor a bonding interface + bridge Monitor a bridge interface + ethernet Monitor a ethernet interface + loopback Monitor a loopback interface + openvpn Monitor an openvpn interface + pppoe Monitor pppoe interface + pseudo-ethernet + Monitor a pseudo-ethernet interface + tunnel Monitor a tunnel interface + vrrp Monitor a vrrp interface + vti Monitor a vti interface + wireless Monitor wireless interface + +To monitor traffic flows, issue the :code:`monitor interfaces flow` +command, replacing `` and `` with your desired interface type and +name, respectively. Output looks like the following: + +.. code-block:: sh + + 12.5Kb 25.0Kb 37.5Kb 50.0Kb 62.5Kb + ???????????????????????????????????????????????????????????????????????????????????????????????????? + 10.11.111.255 => 10.11.110.37 0b 0b 0b + <= 624b 749b 749b + 10.11.110.29 => 10.62.200.11 0b 198b 198b + <= 0b 356b 356b + 255.255.255.255 => 10.11.110.47 0b 0b 0b + <= 724b 145b 145b + 10.11.111.255 => 10.11.110.47 0b 0b 0b + <= 724b 145b 145b + 10.11.111.255 => 10.11.110.255 0b 0b 0b + <= 680b 136b 136b + ???????????????????????????????????????????????????????????????????????????????????????????????????? + TX: cumm: 26.7KB peak: 40.6Kb rates: 23.2Kb 21.4Kb 21.4Kb + RX: 67.5KB 63.6Kb 54.6Kb 54.0Kb 54.0Kb + TOTAL: 94.2KB 104Kb 77.8Kb 75.4Kb 75.4Kb + +Several options are available for changing the display output. Press `h` to +invoke the built in help system. To quit, just press `q` and you'll be returned +to the VyOS command prompt. + +To monitor interface traffic, issue the :code:`monitor interfaces +traffic` command, replacing `` and `` with your desired interface +type and name, respectively. This command invokes the familiar tshark_ utility +and the following options are available: + +.. code-block:: sh + + vyos@vyos:~$ monitor interfaces ethernet eth0 traffic + Possible completions: + Execute the current command + detail Monitor detailed traffic for the specified ethernet interface + filter Monitor filtered traffic for the specified ethernet interface + save Save monitored traffic to a file + unlimited Monitor traffic for the specified ethernet interface + +To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command +prompt. The `detail` keyword provides verbose output of the traffic seen on +the monitored interface. The `filter` keyword accepts valid `PCAP filter +expressions`_, enclosed in single or double quotes (e.g. "port 25" or "port 161 +and udp"). The `save` keyword allows you to save the traffic dump to a file. +The `unlimited` keyword is used to specify that an unlimited number of packets +can be captured (by default, 1,000 packets are captured and you're returned to +the VyOS command prompt). + +.. _mtr: http://www.bitwizard.nl/mtr/ +.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html +.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html diff --git a/docs/ch16-troubleshooting.rst b/docs/ch16-troubleshooting.rst deleted file mode 100644 index 47abab04..00000000 --- a/docs/ch16-troubleshooting.rst +++ /dev/null @@ -1,164 +0,0 @@ -Troubleshooting -=============== - -Sometimes things break or don't work as expected. This section describes -several troubleshooting tools provided by VyOS that can help when something -goes wrong. - -Basic Connectivity Verification -------------------------------- - -Verifying connectivity can be done with the familiar `ping` and `traceroute` -commands. The options for each are shown (the options for each command were -displayed using the built-in help as described in the `Command-Line Interface`_ -section and are omitted from the output here): - -.. code-block:: sh - - vyos@vyos:~$ ping - Possible completions: - Send Internet Control Message Protocol (ICMP) echo request - - - -Several options are available when more extensive troubleshooting is needed: - -.. code-block:: sh - - vyos@vyos:~$ ping 8.8.8.8 - Possible completions: - Execute the current command - adaptive Ping options - allow-broadcast - audible - bypass-route - count - deadline - flood - interface - interval - mark - no-loopback - numeric - pattern - quiet - record-route - size - timestamp - tos - ttl - verbose - -.. code-block:: sh - - vyos@vyos:~$ traceroute - Possible completions: - Track network path to specified node - - - ipv4 Track network path to - ipv6 Track network path to - -However, another tool, mtr_, is available which combines ping and traceroute -into a single tool. An example of its output is shown: - -.. code-block:: sh - - vyos@vyos:~$ mtr 10.62.212.12 - - My traceroute [v0.85] - vyos (0.0.0.0) - Keys: Help Display mode Restart statistics Order of fields quit - Packets Pings - Host Loss% Snt Last Avg Best Wrst StDev - 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 - 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 - 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 - 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 - -**NOTE:** The output of '''mtr''' consumes the screen and will replace your -command prompt. - -Several options are available for changing the display output. Press `h` to -invoke the built in help system. To quit, just press `q` and you'll be returned -to the VyOS command prompt. - -Monitoring Network Interfaces ------------------------------ - -It's possible to monitor network traffic, either at the flow level or protocol -level. This can be useful when troubleshooting a variety of protocols and -configurations. The following interface types can be monitored: - -.. code-block:: sh - - vyos@vyos:~$ monitor interfaces - Possible completions: - Execute the current command - bonding Monitor a bonding interface - bridge Monitor a bridge interface - ethernet Monitor a ethernet interface - loopback Monitor a loopback interface - openvpn Monitor an openvpn interface - pppoe Monitor pppoe interface - pseudo-ethernet - Monitor a pseudo-ethernet interface - tunnel Monitor a tunnel interface - vrrp Monitor a vrrp interface - vti Monitor a vti interface - wireless Monitor wireless interface - -To monitor traffic flows, issue the :code:`monitor interfaces flow` -command, replacing `` and `` with your desired interface type and -name, respectively. Output looks like the following: - -.. code-block:: sh - - 12.5Kb 25.0Kb 37.5Kb 50.0Kb 62.5Kb - ???????????????????????????????????????????????????????????????????????????????????????????????????? - 10.11.111.255 => 10.11.110.37 0b 0b 0b - <= 624b 749b 749b - 10.11.110.29 => 10.62.200.11 0b 198b 198b - <= 0b 356b 356b - 255.255.255.255 => 10.11.110.47 0b 0b 0b - <= 724b 145b 145b - 10.11.111.255 => 10.11.110.47 0b 0b 0b - <= 724b 145b 145b - 10.11.111.255 => 10.11.110.255 0b 0b 0b - <= 680b 136b 136b - ???????????????????????????????????????????????????????????????????????????????????????????????????? - TX: cumm: 26.7KB peak: 40.6Kb rates: 23.2Kb 21.4Kb 21.4Kb - RX: 67.5KB 63.6Kb 54.6Kb 54.0Kb 54.0Kb - TOTAL: 94.2KB 104Kb 77.8Kb 75.4Kb 75.4Kb - -Several options are available for changing the display output. Press `h` to -invoke the built in help system. To quit, just press `q` and you'll be returned -to the VyOS command prompt. - -To monitor interface traffic, issue the :code:`monitor interfaces -traffic` command, replacing `` and `` with your desired interface -type and name, respectively. This command invokes the familiar tshark_ utility -and the following options are available: - -.. code-block:: sh - - vyos@vyos:~$ monitor interfaces ethernet eth0 traffic - Possible completions: - Execute the current command - detail Monitor detailed traffic for the specified ethernet interface - filter Monitor filtered traffic for the specified ethernet interface - save Save monitored traffic to a file - unlimited Monitor traffic for the specified ethernet interface - -To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command -prompt. The `detail` keyword provides verbose output of the traffic seen on -the monitored interface. The `filter` keyword accepts valid `PCAP filter -expressions`_, enclosed in single or double quotes (e.g. "port 25" or "port 161 -and udp"). The `save` keyword allows you to save the traffic dump to a file. -The `unlimited` keyword is used to specify that an unlimited number of packets -can be captured (by default, 1,000 packets are captured and you're returned to -the VyOS command prompt). - -.. _mtr: http://www.bitwizard.nl/mtr/ -.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html -.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html diff --git a/docs/index.rst b/docs/index.rst index 8fd6d15d..79c71c6f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,13 +43,11 @@ as a router and firewall platform for cloud deployments. .. include:: ch12-system.rst -.. include:: ch13-ipv6.rst +.. include:: ch13-clustering.rst -.. include:: ch14-clustering.rst +.. include:: ch14-image-mgmt.rst -.. include:: ch15-image-mgmt.rst - -.. include:: ch16-troubleshooting.rst +.. include:: ch15-troubleshooting.rst Indices and tables ================== -- cgit v1.2.3