diff options
| -rw-r--r-- | docs/about.rst | 29 | ||||
| -rw-r--r-- | docs/cli.rst | 45 | ||||
| -rw-r--r-- | docs/history.rst | 8 | ||||
| -rw-r--r-- | docs/index.rst | 49 | ||||
| -rw-r--r-- | docs/install.rst | 33 | ||||
| -rw-r--r-- | docs/quick-start.rst | 5 |
6 files changed, 97 insertions, 72 deletions
diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 00000000..4af91890 --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,29 @@ +.. _about: + +##### +About +##### + +VyOS is an open source network operating system based on Debian GNU/Linux. + +VyOS provides a free routing platform that competes directly with other +commercially available solutions from well known network providers. Because +VyOS is run on standard amd64, i586 and ARM systems, it is able to be used +as a router and firewall platform for cloud deployments. + +We use multiple live versions of our manual hosted thankfully by +https://readthedocs.org. We will provide one version of the manual for every +VyOS major version starting with VyOS 1.2 which will receive Long-term support +(LTS). + +The manual version is selected/specified by it's Git branch name. You can +switch between versions of the documentation by selecting the appropriate +branch on the bottom left corner. + +VyOS CLI syntax may change between major (and sometimes minor) versions. Please +always refer to the documentation matching your current, running installation. +If a change in the CLI is required, VyOS will ship a so called migration script +which will take care of adjusting the synatax. No action needs to be taken by +you. + + diff --git a/docs/cli.rst b/docs/cli.rst index c1306c82..10d8c1ec 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,27 +1,29 @@ .. _cli: -Command-Line Interface -====================== +### +CLI +### -The VyOS CLI comprises an :ref:`commandtree_operationmode` and a :ref:`commandtree_configmode`. +The VyOS :abbr:`CLI (Command-Line Interface)` comprises an +:ref:`commandtree_operationmode` and a :ref:`commandtree_configmode`. Operational mode allows for commands to perform operational system tasks and view system and service status, while configuration mode allows for the -modification of system configuration. The :ref:`command tree page<commandtree>` lists available commands and their functions. +modification of system configuration. The :ref:`command tree page<commandtree>` +lists available commands and their functions. -The CLI provides a built-in help system. In the CLI the **[?]** key may be used -to display available commands. The **[tab]** key can be used to auto-complete +The CLI provides a built-in help system. In the CLI the ``?`` key may be used +to display available commands. The ``TAB`` key can be used to auto-complete commands and will present the help system upon a conflict or unknown value. -For example typing `sh` followed by the **[tab]** key will complete to `show`. -Pressing **[tab]** a second time will display the possible sub-commands of the -`show` command. +For example typing ``sh`` followed by the ``TAB`` key will complete to +``show``. Pressing ``TAB`` a second time will display the possible +sub-commands of the ``show`` command. .. code-block:: sh vyos@vyos:~$ s[tab] set show - vyos@vyos:~$ Example showing possible show commands: @@ -50,24 +52,24 @@ Example showing possible show commands: host Show host information incoming Show ethernet input-policy information : q - vyos@vyos:~$ -You can scroll up with the keys [Shift]+[PageUp] and sroll down with [Shift]+[PageDown]. +You can scroll up with the keys ``[Shift]+[PageUp]`` and scroll down with +``[Shift]+[PageDown]``. When the output of a command results in more lines than can be displayed on the -terminal screen the output is paginated as indicated by a : prompt. +terminal screen the output is paginated as indicated by a ``:`` prompt. When viewing in page mode the following commands are available: - * **[q]** key can be used to cancel output - * **[space]** will scroll down one page - * **[b]** will scroll back one page - * **[return]** will scroll down one line - * **[up-arrow]** and **[down-arrow]** will scroll up or down one line at a + * ``q`` key can be used to cancel output + * ``space`` will scroll down one page + * ``b`` will scroll back one page + * ``return`` will scroll down one line + * ``up-arrow`` and ``down-arrow`` will scroll up or down one line at a time respectively - * **[left-arrow]** and **[right-arrow]** can be used to scroll left or right + * ``left-arrow`` and ``right-arrow`` can be used to scroll left or right in the event that the output has lines which exceed the terminal size. -To enter configuration mode use the `configure` command: +To enter configuration mode use the ``configure`` command: .. code-block:: sh @@ -75,7 +77,8 @@ To enter configuration mode use the `configure` command: [edit] vyos@vyos:~# -.. note:: Prompt changes from `$` to `#`. To exit configuration mode, type `exit`. +.. note:: Prompt changes from ``$`` to ``#``. To exit configuration mode, + type ``exit``. .. code-block:: sh diff --git a/docs/history.rst b/docs/history.rst index a596cc79..b1393520 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -1,7 +1,8 @@ .. _history: +####### History -======= +####### VyOS is a Linux-based network operating system that provides software-based network routing, firewall, and VPN functionality. @@ -18,9 +19,8 @@ syntax and :ref:`cli` are loosely derived from Juniper JUNOS as modelled by the `XORP project <http://www.xorp.org/>`_, which was the original routing engine for Vyatta. -In the 4.0 release of Vyatta, the routing engine was changed to Quagga. - -As of version 1.2, VyOS now uses `FRRouting <https://frrouting.org/>`_ as the +In the 4.0 release of Vyatta, the routing engine was changed to Quagga. As of +VyOS version 1.2, VyOS now uses `FRRouting <https://frrouting.org/>`_ as the routing engine. How is VyOS different from any other router distributions and platform? diff --git a/docs/index.rst b/docs/index.rst index 5f18c011..742b8eec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,41 +3,28 @@ VyOS User Guide =============== -VyOS is an open source network operating system based on Debian GNU/Linux. - -VyOS provides a free routing platform that competes directly with other -commercially available solutions from well known network providers. Because -VyOS is run on standard amd64, i586 and ARM systems, it is able to be used -as a router and firewall platform for cloud deployments. - -##### -About -##### - -We use multiple live versions of our manual hosted thankfully by -https://readthedocs.org. We will provide one version of the manual for every -VyOS major version starting with VyOS 1.2 which will receive Long-term support -(LTS). - -The manual version is selected/specified by it's Git branch name. You can -switch between versions of the documentation by selecting the appropriate -branch on the bottom left corner. - -VyOS CLI syntax may change between major (and sometimes minor) versions. Please -always refer to the documentation matching your current, running installation. -If a change in the CLI is required, VyOS will ship a so called migration script -which will take care of adjusting the synatax. No action needs to be taken by -you. +############ +Introduction +############ .. _introduction: .. toctree:: - :caption: Introduction :maxdepth: 2 + about history install cli quick-start + +###### +Basics +###### + +.. _introduction: +.. toctree:: + :maxdepth: 2 + configuration-overview interfaces/index routing/index @@ -52,12 +39,13 @@ you. load-balancing image-mgmt commandscripting -.. modules +######## +Appendix +######## .. _appendix: .. toctree:: - :caption: Appendix :maxdepth: 2 appendix/releasenotes @@ -68,10 +56,12 @@ you. appendix/vyos-on-baremetal appendix/migrate-from-vyatta +############ +Contributing +############ .. _contributing: .. toctree:: - :caption: Contributing :maxdepth: 2 contributing/build-vyos @@ -79,6 +69,7 @@ you. contributing/development contributing/documentation + ################ Copyright Notice ################ diff --git a/docs/install.rst b/docs/install.rst index 8a7b60be..92b13c64 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,20 +1,21 @@ .. _installation: +############ Installation -============ +############ Requirements ------------- +============ The recommended system requirements are 512 MiB RAM and 2 GiB storage. Depending on your use you might need additional RAM and CPU resources e.g. when having multiple BGP full tables in your system. Getting the software ---------------------- +==================== Registered subscribers -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- Registered subscribers can log into https://support.vyos.io/ to have access to a variety of different downloads via the "Downloads" link. These downloads @@ -25,15 +26,14 @@ ISOs. .. figure:: /_static/images/vyos-downloads.png Building from source -^^^^^^^^^^^^^^^^^^^^ +---------------------- Non-subscribers can get the LTS release by building it from source. Instruction -can be found here: :ref:`build` - -https://github.com/vyos/vyos-build +can be found here: :ref:`build` and the source repository is available +for everyone at https://github.com/vyos/vyos-build. -Rolling releases -^^^^^^^^^^^^^^^^ +Rolling Release +--------------- Non-subscribers and subscribers can download bleeding-edge VyOS rolling images from: https://downloads.vyos.io/ @@ -43,14 +43,15 @@ current branch: https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso -Preparing software verification -------------------------------- +Software verification +===================== This subsection and the following one applies to downloaded LTS images, for other versions please jump to :ref:`Install`. LTS images are signed by VyOS lead package-maintainer private key. With the official public key, the authenticity of the package can be verified. +:abbr:`GPG (GNU Privacy Guard)` is used for verification. First, install GPG or another OpenPGP implementation. On most GNU+Linux distributions it is installed by default as package managers use it to verify @@ -141,8 +142,8 @@ The import can be verified with: .. _gpg-verification: -GPG verification ----------------- +GPG +--- With the public key imported, the signature for the desired image needs to be downloaded. @@ -164,7 +165,7 @@ Finally, verify the authencity of the downloaded image: .. _Install: Install -------- +======= VyOS ISO is a Live CD and will boot to a functional VyOS image. @@ -324,7 +325,7 @@ Configure a TFTP server so that it serves the following: * The initial ramdisk of the VyOS ISO you want to deploy. That is the ``initrd.img`` file inside the ``/live`` directory of the extracted contents from the ISO file. Do not use an empty (0 bytes) initrd.img file you might - find, the correct file may have a longer name. + find, the correct file may have a longer name. * A directory named pxelinux.cfg which must contain the configuration file: We will use the configuration_ file shown below, which we named default_ diff --git a/docs/quick-start.rst b/docs/quick-start.rst index 2aa3cbbb..9021dea9 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -1,7 +1,8 @@ .. _quick-start: -Quick Start Guide -================= +########### +Quick Start +########### Below is a very basic configuration example that will provide a NAT gateway for a device with two interfaces. |