troubleshooting: adjust to new chapter style

1 files changed, 152 insertions, 146 deletions

diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
index 17d1ebb3..45934925 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -1,98 +1,169 @@
 .. _troubleshooting:
 
+###############
 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
--------------------------------
+******************
+Connectivity Tests
+******************
+
+Basic Connectivity Tests
+========================
 
 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 :ref:`cli`
 section and are omitted from the output here):
 
-.. code-block:: none
+.. opcmd:: ping <destination>
 
-  vyos@vyos:~$ ping
-  Possible completions:
-    <hostname>    Send Internet Control Message Protocol (ICMP) echo request
-    <x.x.x.x>
-    <h:h:h:h:h:h:h:h>
+   Send ICMP echo requests to destination host. There are multiple options to
+   ping, inkl. VRF support.
 
-Several options are available when more extensive troubleshooting is needed:
-
-.. code-block:: none
-
-  vyos@vyos:~$ ping 10.1.1.1
-  Possible completions:
-    <Enter>       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:: none
 
-.. code-block:: none
+     vyos@vyos:~$ ping 10.1.1.1
+     Possible completions:
+       <Enter>       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
+       vrf
+
+
+.. opcmd:: traceroute <destination>
+
+   Trace path to target.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ traceroute
+     Possible completions:
+       <hostname>    Track network path to specified node
+       <x.x.x.x>
+       <h:h:h:h:h:h:h:h>
+       ipv4          Track network path to <hostname|IPv4 address>
+       ipv6          Track network path to <hostname|IPv6 address>
+
+
+Advanced Connectivity Tests
+===========================
+
+.. opcmd:: monitor traceroute <destination>
+
+   However, another helper is available which combines ping and traceroute
+   into a single tool. An example of its output is shown:
+
+   .. code-block:: none
+
+     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 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.
+
+IPv6 Topology Discovery
+=======================
+
+IPv6 uses different techniques to discover its Neighbors/topology.
+
+Router Discovery
+----------------
+
+.. opcmd:: force ipv6-rd interface <interface> [address <ipv6-address>]
+
+   Discover routers via eth0.
+
+   Example:
+
+   .. code-block:: none
+
+     vyos@vyos:~$ force ipv6-rd interface eth0
+     Soliciting ff02::2 (ff02::2) on eth0...
+
+     Hop limit                 :           60 (      0x3c)
+     Stateful address conf.    :           No
+     Stateful other conf.      :           No
+     Mobile home agent         :           No
+     Router preference         :         high
+     Neighbor discovery proxy  :           No
+     Router lifetime           :         1800 (0x00000708) seconds
+     Reachable time            :  unspecified (0x00000000)
+     Retransmit time           :  unspecified (0x00000000)
+      Prefix                   : 240e:fe:8ca7:ea01::/64
+       On-link                 :          Yes
+       Autonomous address conf.:          Yes
+       Valid time              :      2592000 (0x00278d00) seconds
+       Pref. time              :        14400 (0x00003840) seconds
+      Prefix                   : fc00:470:f1cd:101::/64
+       On-link                 :          Yes
+       Autonomous address conf.:          Yes
+       Valid time              :      2592000 (0x00278d00) seconds
+       Pref. time              :        14400 (0x00003840) seconds
+      Recursive DNS server     : fc00:470:f1cd::ff00
+       DNS server lifetime     :          600 (0x00000258) seconds
+      Source link-layer address: 00:98:2B:F8:3F:11
+      from fe80::298:2bff:fef8:3f11
 
-  vyos@vyos:~$ traceroute
-  Possible completions:
-    <hostname>    Track network path to specified node
-    <x.x.x.x>
-    <h:h:h:h:h:h:h:h>
-    ipv4          Track network path to <hostname|IPv4 address>
-    ipv6          Track network path to <hostname|IPv6 address>
+Neighbor Discovery
+------------------
 
-However, another tool, mtr_, is available which combines ping and traceroute
-into a single tool. An example of its output is shown:
+.. opcmd:: force ipv6-nd interface <interface> address <ipv6-address>
 
-.. code-block:: none
 
-  vyos@vyos:~$ mtr 10.62.212.12
+   Example:
 
-                             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
+   .. code-block:: none
 
-.. note:: The output of ``mtr`` consumes the screen and will replace your
-   command prompt.
+     vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1
 
-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.
+     Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0...
+     Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1
 
+**********
 Monitoring
-----------
+**********
 
 VyOS features several monitoring tools.
 
 .. code-block:: none
 
-  vyos@vyos:~$ monitor 
+  vyos@vyos:~$ monitor
   Possible completions:
     bandwidth     Monitor interface bandwidth in real time
     bandwidth-test
@@ -120,17 +191,17 @@ VyOS features several monitoring tools.
     vpn           Monitor VPN
     vrrp          Monitor Virtual Router Redundancy Protocol (VRRP)
     webproxy      Monitor Webproxy service
-  
+
 
 Traffic Dumps
-^^^^^^^^^^^^^
+=============
 
 To monitor interface traffic, issue the :code:`monitor traffic interface <name>`
 command, replacing `<name>` with your chosen interface.
 
 .. code-block:: none
 
-  vyos@vyos:~$ monitor traffic interface eth0 
+  vyos@vyos:~$ monitor traffic interface eth0
   tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
   listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
   15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64
@@ -150,15 +221,15 @@ Traffic can be filtered and saved.
 
 .. code-block:: none
 
-  vyos@vyos:~$ monitor traffic interface eth0 
+  vyos@vyos:~$ monitor traffic interface eth0
   Possible completions:
     <Enter>       Execute the current command
     filter        Monitor traffic matching filter conditions
     save          Save traffic dump from an interface to a file
 
 
-Interface Bandwidth
-^^^^^^^^^^^^^^^^^^^
+Interface Bandwidth Usage
+=========================
 
 to take a quick view on the used bandwidth of an interface use the ``monitor
 bandwidth`` command
@@ -189,8 +260,8 @@ show the following:
       0.61 :::::||.....................................................
            1   5   10   15   20   25   30   35   40   45   50   55   60
 
-Interface performance
-^^^^^^^^^^^^^^^^^^^^^
+Interface Performance
+=====================
 
 To take a look on the network bandwidth between two nodes, the ``monitor
 bandwidth-test`` command is used to run iperf.
@@ -215,7 +286,7 @@ bandwidth-test`` command is used to run iperf.
 
 
 Monitor command
-^^^^^^^^^^^^^^^
+===============
 
 The ``monitor command`` command allows you to repeatedly run a command to view
 a continuously refreshed output. The command is run and output every 2 seconds,
@@ -243,8 +314,9 @@ Will clear the screen and show you the output of ``show interfaces`` every
   vti0             172.25.254.2/30                   u/u
   vti1             172.25.254.9/30                   u/u
 
-Clear Command
--------------
+****************
+Terminal/Console
+****************
 
 Sometimes you need to clear counters or statistics to troubleshoot better.
 
@@ -286,77 +358,12 @@ to clear counters on firewall rulesets or single rules
   vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters
 
 
+******************
+System Information
+******************
 
-IPv6 topology discovery
------------------------
-
-Topology discovery tool supporting IPv6 in vyos1.3
-
-Router discovery
-^^^^^^^^^^^^^^^^
-
-Vyos 1.3 supports the following commands to complete IPv6 Router Discovery:
-
-.. code-block:: none
-
-  vyos@vyos:~$ force ipv6-rd  interface <interface> [address <ip>]
-
-Example:
-
-.. code-block:: none
-
-  vyos@vyos:~$ force ipv6-rd  interface eth0
-  Soliciting ff02::2 (ff02::2) on eth0...
-
-  Hop limit                 :           60 (      0x3c)
-  Stateful address conf.    :           No
-  Stateful other conf.      :           No
-  Mobile home agent         :           No
-  Router preference         :         high
-  Neighbor discovery proxy  :           No
-  Router lifetime           :         1800 (0x00000708) seconds
-  Reachable time            :  unspecified (0x00000000)
-  Retransmit time           :  unspecified (0x00000000)
-   Prefix                   : 240e:fe:8ca7:ea01::/64
-    On-link                 :          Yes
-    Autonomous address conf.:          Yes
-    Valid time              :      2592000 (0x00278d00) seconds
-    Pref. time              :        14400 (0x00003840) seconds
-   Prefix                   : fc00:470:f1cd:101::/64
-    On-link                 :          Yes
-    Autonomous address conf.:          Yes
-    Valid time              :      2592000 (0x00278d00) seconds
-    Pref. time              :        14400 (0x00003840) seconds
-   Recursive DNS server     : fc00:470:f1cd::ff00
-    DNS server lifetime     :          600 (0x00000258) seconds
-   Source link-layer address: 00:98:2B:F8:3F:11
-   from fe80::298:2bff:fef8:3f11
-
-Neighbor Discovery
-^^^^^^^^^^^^^^^^^^
-
-Vyos1.3 supports IPv6 host topology detection. The following commands can be used to detect the occupation of IPv6 address:
-
-.. code-block:: none
-
-  vyos@vyos:~$ force ipv6-nd interface <interface> address <ip>
-
-Example:
-
-.. code-block:: none
-
-  vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1
-  Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0...
-  Target link-layer address: 00:98:2B:F8:3F:11
-   from fc00:470:f1cd:101::1
-
-
-
-Basic System Information
-------------------------
-
-Boot steps
-^^^^^^^^^^
+Boot Steps
+==========
 
 VyOS 1.2 uses `Debian Jessie`_ as the base Linux operating system. Jessie was
 the first version of Debian that uses systemd_ as the default init system.
@@ -400,6 +407,5 @@ These are the boot steps for VyOS 1.2
 .. _vyatta-cfg: https://github.com/vyos/vyatta-cfg
 .. _systemd: https://freedesktop.org/wiki/Software/systemd/
 .. _`Debian Jessie`: https://www.debian.org/releases/jessie/
-.. _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