vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-12-17 19:12:41 +01:00
Code Issues Packages Projects Releases Wiki Activity

toc: build proper doc in html and pdf

Browse Source
This commit is contained in:
Christian Poessinger 2019-11-23 18:32:28 +01:00
parent 79f15b05c2
commit 2e2e9b887a
6 changed files with 97 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/about.rst Normal file
View File

@ -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.

45
docs/cli.rst
View File

@ -1,27 +1,29 @@
.. _cli: .. _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 Operational mode allows for commands to perform operational system tasks and
view system and service status, while configuration mode allows for the 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 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 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. 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`. For example typing ``sh`` followed by the ``TAB`` key will complete to
Pressing **[tab]** a second time will display the possible sub-commands of the ``show``. Pressing ``TAB`` a second time will display the possible
`show` command. sub-commands of the ``show`` command.
.. code-block:: sh .. code-block:: sh
vyos@vyos:~$ s[tab] vyos@vyos:~$ s[tab]
set show set show
vyos@vyos:~$
Example showing possible show commands: Example showing possible show commands:
@ -50,24 +52,24 @@ Example showing possible show commands:
host Show host information host Show host information
incoming Show ethernet input-policy information incoming Show ethernet input-policy information
: q : 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 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: When viewing in page mode the following commands are available:
* **[q]** key can be used to cancel output * ``q`` key can be used to cancel output
* **[space]** will scroll down one page * ``space`` will scroll down one page
* **[b]** will scroll back one page * ``b`` will scroll back one page
* **[return]** will scroll down one line * ``return`` will scroll down one line
* **[up-arrow]** and **[down-arrow]** will scroll up or down one line at a * ``up-arrow`` and ``down-arrow`` will scroll up or down one line at a
time respectively 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. 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 .. code-block:: sh
@ -75,7 +77,8 @@ To enter configuration mode use the `configure` command:
[edit] [edit]
vyos@vyos:~# 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 .. code-block:: sh

8
docs/history.rst
View File

@ -1,7 +1,8 @@
.. _history: .. _history:
#######
History History
======= #######
VyOS is a Linux-based network operating system that provides software-based VyOS is a Linux-based network operating system that provides software-based
network routing, firewall, and VPN functionality. 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 `XORP project <http://www.xorp.org/>`_, which was the original routing engine
for Vyatta. for Vyatta.
In the 4.0 release of Vyatta, the routing engine was changed to Quagga. 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
As of version 1.2, VyOS now uses `FRRouting <https://frrouting.org/>`_ as the
routing engine. routing engine.
How is VyOS different from any other router distributions and platform? How is VyOS different from any other router distributions and platform?

49
docs/index.rst
View File

@ -3,41 +3,28 @@
VyOS User Guide VyOS User Guide
=============== ===============
VyOS is an open source network operating system based on Debian GNU/Linux. ############
Introduction
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:: .. toctree::
:caption: Introduction
:maxdepth: 2 :maxdepth: 2
about
history history
install install
cli cli
quick-start quick-start
######
Basics
######
.. _introduction:
.. toctree::
:maxdepth: 2
configuration-overview configuration-overview
interfaces/index interfaces/index
routing/index routing/index
@ -52,12 +39,13 @@ you.
load-balancing load-balancing
image-mgmt image-mgmt
commandscripting commandscripting
.. modules
########
Appendix
########
.. _appendix: .. _appendix:
.. toctree:: .. toctree::
:caption: Appendix
:maxdepth: 2 :maxdepth: 2
appendix/releasenotes appendix/releasenotes
@ -68,10 +56,12 @@ you.
appendix/vyos-on-baremetal appendix/vyos-on-baremetal
appendix/migrate-from-vyatta appendix/migrate-from-vyatta
############
Contributing
############
.. _contributing: .. _contributing:
.. toctree:: .. toctree::
:caption: Contributing
:maxdepth: 2 :maxdepth: 2
contributing/build-vyos contributing/build-vyos
@ -79,6 +69,7 @@ you.
contributing/development contributing/development
contributing/documentation contributing/documentation
################ ################
Copyright Notice Copyright Notice
################ ################

31
docs/install.rst
View File

@ -1,20 +1,21 @@
.. _installation: .. _installation:
############
Installation Installation
============ ############
Requirements Requirements
------------ ============
The recommended system requirements are 512 MiB RAM and 2 GiB storage. Depending 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 on your use you might need additional RAM and CPU resources e.g. when having
multiple BGP full tables in your system. multiple BGP full tables in your system.
Getting the software Getting the software
--------------------- ====================
Registered subscribers Registered subscribers
^^^^^^^^^^^^^^^^^^^^^^ ----------------------
Registered subscribers can log into https://support.vyos.io/ to have access to Registered subscribers can log into https://support.vyos.io/ to have access to
a variety of different downloads via the "Downloads" link. These downloads a variety of different downloads via the "Downloads" link. These downloads
@ -25,15 +26,14 @@ ISOs.
.. figure:: /_static/images/vyos-downloads.png .. figure:: /_static/images/vyos-downloads.png
Building from source Building from source
^^^^^^^^^^^^^^^^^^^^ ----------------------
Non-subscribers can get the LTS release by building it from source. Instruction Non-subscribers can get the LTS release by building it from source. Instruction
can be found here: :ref:`build` can be found here: :ref:`build` and the source repository is available
for everyone at https://github.com/vyos/vyos-build.
https://github.com/vyos/vyos-build Rolling Release
---------------
Rolling releases
^^^^^^^^^^^^^^^^
Non-subscribers and subscribers can download bleeding-edge VyOS rolling images Non-subscribers and subscribers can download bleeding-edge VyOS rolling images
from: https://downloads.vyos.io/ from: https://downloads.vyos.io/
@ -43,14 +43,15 @@ current branch:
https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso 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 This subsection and the following one applies to downloaded LTS images, for
other versions please jump to :ref:`Install`. other versions please jump to :ref:`Install`.
LTS images are signed by VyOS lead package-maintainer private key. With the LTS images are signed by VyOS lead package-maintainer private key. With the
official public key, the authenticity of the package can be verified. 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 First, install GPG or another OpenPGP implementation. On most GNU+Linux
distributions it is installed by default as package managers use it to verify 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 verification GPG
---------------- ---
With the public key imported, the signature for the desired image needs to be With the public key imported, the signature for the desired image needs to be
downloaded. downloaded.
@ -164,7 +165,7 @@ Finally, verify the authencity of the downloaded image:
.. _Install: .. _Install:
Install Install
------- =======
VyOS ISO is a Live CD and will boot to a functional VyOS image. VyOS ISO is a Live CD and will boot to a functional VyOS image.

5
docs/quick-start.rst
View File

@ -1,7 +1,8 @@
.. _quick-start: .. _quick-start:
Quick Start Guide ###########
================= Quick Start
###########
Below is a very basic configuration example that will provide a NAT gateway Below is a very basic configuration example that will provide a NAT gateway
for a device with two interfaces. for a device with two interfaces.