Merge branch 'sagitta' of https://github.com/rebortg/vyos-documentation

4 files changed, 423 insertions, 0 deletions

diff --git a/docs/operation/boot-options.rst b/docs/operation/boot-options.rst
new file mode 100644
index 00000000..d054748f
--- /dev/null
+++ b/docs/operation/boot-options.rst
@@ -0,0 +1,57 @@
+.. _boot-options:
+
+
+############
+Boot Options
+############
+
+.. warning:: This function may be highly disruptive.
+   It may cause major service interruption, so make sure you really
+   need it and verify your input carefully.
+
+
+
+VyOS has several kernel command line options to modify the normal boot
+process. 
+To add an option, select the desired image in GRUB menu at load
+time, press **e**, edit the first line, and press **Ctrl-x** to boot when
+ready.
+
+.. image:: /_static/images/boot-options.png
+   :width: 80%
+   :align: center
+
+
+Specify custom config file
+==========================
+
+Tells the system to use specified file instead of ``/config/config.boot``.
+If specified file does not exist or is not readable, fall back to
+default config. No additional verification is performed, so make sure
+you specify a valid config file.
+
+.. code-block:: none
+
+   vyos-config=/path/to/file
+
+To load the *factory default* config, use:
+
+.. code-block:: none
+
+   vyos-config=/opt/vyatta/etc/config.boot.default
+
+
+Disable specific boot process steps
+===================================
+
+These options disable some boot steps. Make sure you understand the
+:ref:`boot process <boot-steps>` well before using them!
+
+.. glossary::
+
+    no-vyos-migrate
+      Do not perform config migration.
+
+    no-vyos-firewall
+      Do not initialize default firewall chains, renders any firewall configuration unusable.
+
diff --git a/docs/operation/index.rst b/docs/operation/index.rst
new file mode 100644
index 00000000..647b5b25
--- /dev/null
+++ b/docs/operation/index.rst
@@ -0,0 +1,11 @@
+##############
+Operation Mode
+##############
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   information
+   ip-commands
+   boot-options
\ No newline at end of file
diff --git a/docs/operation/information.rst b/docs/operation/information.rst
new file mode 100644
index 00000000..02d6f1ec
--- /dev/null
+++ b/docs/operation/information.rst
@@ -0,0 +1,97 @@
+.. _information:
+
+***********
+Information
+***********
+
+VyOS features a rich set of operational level commands to retrieve arbitrary
+information about your running system.
+
+########
+Hardware
+########
+
+.. _hardware_usb:
+
+USB
+===
+
+In the past serial interface have been defined as ttySx and ttyUSBx where x was
+an instance number of the serial interface. It was discovered that from system
+boot to system boot the mapping of USB based serial interfaces will differ,
+depending which driver was loaded first by the operating system. This will become
+rather painful if you not only have serial interfaces for a console server
+connected but in addition also a serial backed :ref:`wwan-interface`.
+
+To overcome this issue and the fact that in almost 50% of all cheap USB to serial
+converters there is no serial number programmed, the USB to serial interface is
+now directly identified by the USB root bridge and bus it connects to. This
+somehow mimics the new network interface definitions we see in recend Linux
+distributions.
+
+For additional details you can refer to https://phabricator.vyos.net/T2490.
+
+.. opcmd:: show hardware usb
+
+  Retrieve a tree like representation of all connected USB devices.
+
+  .. note:: If a device is unplugged and re-plugged it will receive a new
+    Port, Dev, If identification.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show hardware usb
+    /:  Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M
+        |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M
+            |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M
+            |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M
+            |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M
+            |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M
+    /:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M
+    /:  Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M
+        |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M
+        |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M
+            |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+            |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+            |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+            |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+            |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M
+                |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M
+                    |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                    |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                    |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                    |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+
+
+.. opcmd:: show hardware usb serial
+
+  Retrieve a list and description of all connected USB serial devices. The device name
+  displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing the serial console
+  as console-server device.
+
+  .. code-block:: none
+
+    vyos@vyos$ show hardware usb serial
+    Device           Model               Vendor
+    ------           ------              ------
+    usb0b1.3p1.0     MC7710              Sierra Wireless, Inc.
+    usb0b1.3p1.2     MC7710              Sierra Wireless, Inc.
+    usb0b1.3p1.3     MC7710              Sierra Wireless, Inc.
+    usb0b1p1.0       USB-Serial_Controller_D Prolific Technology, Inc.
+    usb0b2.3.3.4p1.0 Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.3.4p1.1 Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.3.4p1.2 Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.3.4p1.3 Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.4p1.0   Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.4p1.1   Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.4p1.2   Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.4p1.3   Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.4p1.0     Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.4p1.1     Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.4p1.2     Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.4p1.3     Quad_RS232-HS       Future Technology Devices International, Ltd
+
diff --git a/docs/operation/ip-commands.rst b/docs/operation/ip-commands.rst
new file mode 100644
index 00000000..eba4fd90
--- /dev/null
+++ b/docs/operation/ip-commands.rst
@@ -0,0 +1,258 @@
+.. _ip-commands:
+
+###########
+IP commands
+###########
+
+IPv4
+====
+
+System configuration commands
+-----------------------------
+
+.. cfgcmd:: set system ip disable-forwarding
+
+   Use this command to disable IPv4 forwarding on all interfaces.
+
+.. cfgcmd:: set system ip arp table-size <number>
+
+   Use this command to define the maximum number of entries to keep in
+   the ARP cache (1024, 2048, 4096, 8192, 16384, 32768).
+
+.. cfgcmd:: set system ip multipath layer4-hashing
+
+   Use this command to use Layer 4 information for IPv4 ECMP hashing.
+
+
+Operational commands
+--------------------
+
+show commands
+^^^^^^^^^^^^^
+
+See below the different parameters available for the IPv4 **show** command:
+
+.. code-block:: none
+
+   vyos@vyos:~$ show ip
+   Possible completions:
+     access-list   Show all IP access-lists
+     as-path-access-list
+                   Show all as-path-access-lists
+     bgp           Show Border Gateway Protocol (BGP) information
+     community-list
+                   Show IP community-lists
+     extcommunity-list
+                   Show extended IP community-lists
+     forwarding    Show IP forwarding status
+     groups        Show IP multicast group membership
+     igmp          Show IGMP (Internet Group Management Protocol) information
+     large-community-list
+                   Show IP large-community-lists
+     multicast     Show IP multicast
+     ospf          Show IPv4 Open Shortest Path First (OSPF) routing information
+     pim           Show PIM (Protocol Independent Multicast) information
+     ports         Show IP ports in use by various system services
+     prefix-list   Show all IP prefix-lists
+     protocol      Show IP route-maps per protocol
+     rip           Show Routing Information Protocol (RIP) information
+     route         Show IP routes
+
+
+reset commands
+^^^^^^^^^^^^^^
+
+And the different IPv4 **reset** commands available:
+
+.. code-block:: none
+
+   vyos@vyos:~$ reset ip
+   Possible completions:
+     arp           Reset Address Resolution Protocol (ARP) cache
+     bgp           Clear Border Gateway Protocol (BGP) statistics or status
+     igmp          IGMP clear commands
+     multicast     IP multicast routing table
+     route         Reset IP route
+
+IPv6
+====
+
+System configuration commands
+-----------------------------
+
+.. cfgcmd:: set system ipv6 disable
+
+   Use this command to disable assignment of IPv6 addresses on all
+   interfaces.
+
+.. cfgcmd:: set system ipv6 disable-forwarding
+
+   Use this command to disable IPv6 forwarding on all interfaces.
+
+.. cfgcmd:: set system ipv6 neighbor table-size <number>
+
+   Use this command to define the maximum number of entries to keep in
+   the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768).
+
+.. cfgcmd:: set system ipv6 strict-dad
+
+   Use this command to disable IPv6 operation on interface when
+   Duplicate Address Detection fails on Link-Local address.
+
+.. cfgcmd:: set system ipv6 multipath layer4-hashing
+
+   Use this command to user Layer 4 information for ECMP hashing.
+
+
+Operational commands
+--------------------
+
+Show commands
+^^^^^^^^^^^^^
+
+.. opcmd:: show ipv6 neighbors
+
+   Use this command to show IPv6 Neighbor Discovery Protocol information.
+
+.. opcmd:: show ipv6 groups
+
+   Use this command to show IPv6 multicast group membership.
+
+.. opcmd:: show ipv6 forwarding
+
+   Use this command to show IPv6 forwarding status.
+
+.. opcmd:: show ipv6 route
+
+   Use this command to show IPv6 routes.
+
+   Check the many parameters available for the `show ipv6 route` command:
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show ipv6 route
+      Possible completions:
+        <Enter>       Execute the current command
+        <X:X::X:X>    Show IPv6 routes of given address or prefix
+        <X:X::X:X/M>
+        bgp           Show IPv6 BGP routes
+        cache         Show kernel IPv6 route cache
+        connected     Show IPv6 connected routes
+        forward       Show kernel IPv6 route table
+        isis          Show IPv6 ISIS routes
+        kernel        Show IPv6 kernel routes
+        ospfv3        Show IPv6 OSPF6 routes
+        ripng         Show IPv6 RIPNG routes
+        static        Show IPv6 static routes
+        summary       Show IPv6 routes summary
+        table         Show IP routes in policy table
+        vrf           Show IPv6 routes in VRF
+
+
+.. opcmd:: show ipv6 prefix-list
+
+   Use this command to show all IPv6 prefix lists
+
+   There are different parameters for getting prefix-list information:
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show ipv6 prefix-list
+      Possible completions:
+        <Enter>       Execute the current command
+        <WORD>        Show specified IPv6 prefix-list
+        detail        Show detail of IPv6 prefix-lists
+        summary       Show summary of IPv6 prefix-lists
+
+.. opcmd:: show ipv6 access-list
+
+   Use this command to show all IPv6 access lists
+
+   You can also specify which IPv6 access-list should be shown:
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show ipv6 access-list
+      Possible completions:
+        <Enter>       Execute the current command
+        <text>        Show specified IPv6 access-list
+
+.. opcmd:: show ipv6 bgp
+
+   Use this command to show IPv6 Border Gateway Protocol information.
+
+
+   In addition, you can specify many other parameters to get BGP
+   information:
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show ipv6 bgp
+      Possible completions:
+        <Enter>       Execute the current command
+        <X:X::X:X>    Show BGP information for given address or prefix
+        <X:X::X:X/M>
+        community     Show routes matching the communities
+        community-list
+                      Show routes matching the community-list
+        filter-list   Show routes conforming to the filter-list
+        large-community
+                      Show routes matching the large-community-list
+        large-community-list
+        neighbors     Show detailed information on TCP and BGP neighbor connections
+        prefix-list   Show routes matching the prefix-list
+        regexp        Show routes matching the AS path regular expression
+        route-map     Show BGP routes matching the specified route map
+        summary       Show summary of BGP neighbor status
+
+
+.. opcmd:: show ipv6 ospfv3
+
+   Use this command to get information about OSPFv3.
+
+   You can get more specific OSPFv3 information by using the parameters
+   shown below:
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show ipv6 ospfv3
+      Possible completions:
+        <Enter>       Execute the current command
+        area          Show OSPFv3 spf-tree information
+        border-routers
+                      Show OSPFv3 border-router (ABR and ASBR) information
+        database      Show OSPFv3 Link state database information
+        interface     Show OSPFv3 interface information
+        linkstate     Show OSPFv3 linkstate routing information
+        neighbor      Show OSPFv3 neighbor information
+        redistribute  Show OSPFv3 redistribute External information
+        route         Show OSPFv3 routing table information
+
+.. opcmd:: show ipv6 ripng
+
+   Use this command to get information about the RIPNG protocol
+
+.. opcmd:: show ipv6 ripng status
+
+   Use this command to show the status of the RIPNG protocol
+
+
+Reset commands
+^^^^^^^^^^^^^^
+
+.. opcmd:: reset ipv6 bgp <address>
+
+   Use this command to clear Border Gateway Protocol statistics or
+   status.
+
+
+.. opcmd:: reset ipv6 neighbors <address | interface>
+
+   Use this command to reset IPv6 Neighbor Discovery Protocol cache for
+   an address or interface.
+
+.. opcmd:: reset ipv6 route cache
+
+   Use this command to flush the kernel IPv6 route cache.
+   An address can be added to flush it only for that route.
+