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

1 files changed, 514 insertions, 0 deletions

diff --git a/docs/installation/install.rst b/docs/installation/install.rst
new file mode 100644
index 00000000..11d0fc88
--- /dev/null
+++ b/docs/installation/install.rst
@@ -0,0 +1,514 @@
+.. _installation:
+
+############
+Installation
+############
+
+VyOS installation requires to download a VyOS .iso file. That file is
+a live install image that lets you boot a live VyOS. From that live
+system you can proceed to the permanent installation on a hard drive or
+any other type of storage.
+
+
+Hardware requirements
+=====================
+
+The minimum 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.
+
+Download
+========
+
+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
+include LTS (Long-Term-Support) and associated hot-fix releases, early public
+access releases, pre-built VM images, as well as device specific installation
+ISOs.
+
+.. figure:: /_static/images/vyos-downloads.png
+
+Building from source
+----------------------
+
+Non-subscribers can always get the LTS release by building it from source.
+Instruction can be found in the :ref:`build` section of this manual. VyOS
+source code repository is available for everyone at
+https://github.com/vyos/vyos-build.
+
+Rolling Release
+---------------
+
+Everyone can download bleeding-edge VyOS rolling images from:
+https://downloads.vyos.io/
+
+.. note:: Rolling releases contain all the latest enhancements and fixes. This
+   means that there will be new bugs of course. If you think you hit a bug
+   please follow the guide at :ref:`bug_report`. To improve VyOS we depend on
+   your feedback!
+
+The following link will always fetch the most recent VyOS build for AMD64
+systems from the current branch:
+https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso
+
+
+Download Verification
+---------------------
+
+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.
+
+.. note:: This subsection only applies e applies to LTS images, for
+   Rolling images please jump to :ref:`live_installation`.
+
+Preparing for the 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 package signatures. If not pre-installed, it will need to be
+downloaded and installed.
+
+The official VyOS public key can be retrieved in a number of ways. Skip
+to :ref:`gpg-verification` if the key is already present.
+
+It can be retrieved directly from a key server:
+
+``gpg --recv-keys FD220285A0FE6D7E``
+
+Or it can be accessed via a web browser:
+
+https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E
+
+Or from the following block:
+
+.. code-block:: none
+
+  -----BEGIN PGP PUBLIC KEY BLOCK-----
+  Version: GnuPG v1.4.12 (GNU/Linux)
+
+  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
+  8vzPzaWHhkOkU8/J/Ci7+vNtUOZb
+  =Ld8S
+  -----END PGP PUBLIC KEY BLOCK-----
+
+Store the key in a new text file and import it into GPG via: ``gpg --import
+file_with_the_public_key``
+
+The import can be verified with:
+
+.. code-block:: none
+
+  $ gpg --list-keys
+  ...
+  pub   rsa4096 2015-08-12 [SC]
+      0694A9230F5139BF834BA458FD220285A0FE6D7E
+  uid           [ unknown] VyOS Maintainers (VyOS Release) <maintainers@vyos.net>
+  sub   rsa4096 2015-08-12 [E]
+
+.. _gpg-verification:
+
+GPG verification
+^^^^^^^^^^^^^^^^
+
+With the public key imported, the signature for the desired image needs
+to be downloaded.
+
+.. note:: The signature can be downloaded by appending `.asc` to the URL of the
+   downloaded VyOS image. That small *.asc* file is the signature for the
+   associated image.
+
+Finally, verify the authenticity of the downloaded image:
+
+.. code-block:: none
+
+  $ gpg2 --verify vyos-1.2.1-amd64.iso.asc  vyos-1.2.1-amd64.iso
+  gpg: Signature made So 14 Apr 12:58:07 2019 CEST
+  gpg:                using RSA key FD220285A0FE6D7E
+  gpg: Good signature from "VyOS Maintainers (VyOS Release) <maintainers@vyos.net>" [unknown]
+  Primary key fingerprint: 0694 A923 0F51 39BF 834B  A458 FD22 0285 A0FE 6D7E
+
+.. _live_installation:
+
+Live installation
+=================
+
+.. note:: A permanent VyOS installation always requires to go first
+   through a live installation.
+
+VyOS, as other GNU+Linux distributions, can be tasted without installing
+it in your hard drive. **With your downloaded VyOS .iso file you can
+create a bootable USB drive that will let you boot into a fully
+functional VyOS system**. Once you have tested it, you can either decide
+to begin a :ref:`permanent_installation` in your hard drive or power
+your system off, remove the USB drive, and leave everythng as it was.
+
+
+If you have a GNU+Linux system, you can create your VyOS bootable USB
+stick with with the ``dd`` command:
+
+ 1. Open your terminal emulator.
+
+ 2. Find out the device name of your USB drive (you can use the ``lsblk``
+    command)
+
+ 3. Unmount the USB drive. Replace X in the example below with the
+    letter of your device and keep the asterisk (wildcard) to unmount
+    all partitions.
+
+ .. code-block:: none
+
+  $ umount /dev/sdX*
+
+ 4. Write the image (your VyOS .iso file) to the USB drive.
+    Note that here you want to use the device name (e.g. /dev/sdb), not
+    the partition name (e.g. /dev/sdb1).
+
+  **Warning**: This will destroy all data on the USB drive!
+
+ .. code-block:: none
+
+   # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync
+
+ 5. Wait until you get the outcome (bytes copied). Be patient, in some
+    computers it might take more than one minute.
+
+ 6. Once ``dd`` has finished, pull the USB drive out and plug it into
+    the powered-off computer where you want to install (or test) VyOS.
+
+ 7. Power the computer on, making sure it boots from the USB drive (you
+    might need to select booting device or change booting settings).
+
+ 8. Once VyOS is completely loaded, enter the default credentials
+    (login: vyos, password: vyos).
+
+
+If you find difficulties with this method, prefer to use a GUI program,
+or have a different operating system, there are other programs you can
+use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux,
+macOS and Windows), Rufus_ (for Windows) and `many others`_. You can
+follow their instructions to create a bootable USB drive from an .iso
+file.
+
+.. hint:: The default username and password for the live system is *vyos*.
+
+
+.. _permanent_installation:
+
+Permanent installation
+======================
+
+.. note:: Before a permanent installation, VyOS requires a :ref:`live_installation`.
+
+Unlike general purpose Linux distributions, VyOS uses "image installation" that
+mimics the user experience of traditional hardware routers and allows keeping
+multiple VyOS versions installed simultaneously. This makes it possible to
+switch to a previous version if something breaks or miss-behaves after an image
+upgrade.
+
+Every version is contained in its own squashfs image that is mounted in a union
+filesystem together with a directory for mutable data such as configurations,
+keys, or custom scripts.
+
+.. note:: Older versions (prior to VyOS 1.1) used to support non-image
+   installation (``install system`` command). Support for this has been removed
+   from VyOS 1.2 and newer releases. Older releases can still be upgraded via
+   the general ``add system image <image_path>`` upgrade command (consult
+   :ref:`image-mgmt` for further information).
+
+
+In order to proceed with a permanent installation:
+
+ 1. Log into the VyOS live system (use the default credentials: vyos,
+    vyos)
+
+ 2. Run the ``install image`` command and follow the wizard:
+
+ .. code-block:: none
+
+   vyos@vyos:~$ install image
+   Welcome to the VyOS install program.  This script
+   will walk you through the process of installing the
+   VyOS image to a local hard drive.
+   Would you like to continue? (Yes/No) [Yes]: Yes
+   Probing drives: OK
+   Looking for pre-existing RAID groups...none found.
+   The VyOS image will require a minimum 2000MB root.
+   Would you like me to try to partition a drive automatically
+   or would you rather partition it manually with parted?  If
+   you have already setup your partitions, you may skip this step
+
+   Partition (Auto/Parted/Skip) [Auto]:
+
+   I found the following drives on your system:
+    sda    4294MB
+
+   Install the image on? [sda]:
+
+   This will destroy all data on /dev/sda.
+   Continue? (Yes/No) [No]: Yes
+
+   How big of a root partition should I create? (2000MB - 4294MB) [4294]MB:
+
+   Creating filesystem on /dev/sda1: OK
+   Done!
+   Mounting /dev/sda1...
+   What would you like to name this image? [1.2.0-rolling+201809210337]:
+   OK.  This image will be named: 1.2.0-rolling+201809210337
+   Copying squashfs image...
+   Copying kernel and initrd images...
+   Done!
+   I found the following configuration files:
+       /opt/vyatta/etc/config.boot.default
+   Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]:
+
+   Copying /opt/vyatta/etc/config.boot.default to sda.
+   Enter password for administrator account
+   Enter password for user 'vyos':
+   Retype password for user 'vyos':
+   I need to install the GRUB boot loader.
+   I found the following drives on your system:
+    sda    4294MB
+
+   Which drive should GRUB modify the boot partition on? [sda]:
+
+   Setting up grub: OK
+   Done!
+
+
+ 3. After the installation is complete, remove the live USB stick or
+    CD.
+
+ 4. Reboot the system.
+
+ .. code-block:: none
+
+  vyos@vyos:~$ reboot
+  Proceed with reboot? (Yes/No) [No] Yes
+
+ You will boot now into a permanent VyOS system.
+
+
+PXE Boot
+========
+
+VyOS can also be installed through PXE. This is a more complex
+installation method which allows deploying VyOS through the network.
+
+**Requirements**
+
+* Clients (where VyOS is to be installed) with a PXE-enabled NIC
+* :ref:`dhcp-server`
+* :ref:`tftp-server`
+* Webserver (HTTP) - optional, but we will use it to speed up installation
+* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3)
+* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution <https://kernel.org/pub/linux/utils/boot/syslinux/>`_
+
+Configuration
+-------------
+
+Step 1: DHCP
+^^^^^^^^^^^^
+
+Configure a DHCP server to provide the client with:
+
+* An IP address
+* The TFTP server address (DHCP option 66). Sometimes referred as *boot server*
+* The *bootfile name* (DHCP option 67), which is *pxelinux.0*
+
+In this example we configured an existent VyOS as the DHCP server:
+
+.. code-block:: none
+
+  vyos@vyos# show service dhcp-server
+   shared-network-name mydhcp {
+       subnet 192.168.1.0/24 {
+           bootfile-name pxelinux.0
+           bootfile-server 192.168.1.50
+           default-router 192.168.1.50
+           range 0 {
+               start 192.168.1.70
+               stop 192.168.1.100
+           }
+       }
+   }
+
+.. _install_from_tftp:
+
+Step 2: TFTP
+^^^^^^^^^^^^
+
+Configure a TFTP server so that it serves the following:
+
+* The *pxelinux.0* file from the Syslinux distribution
+* The *ldlinux.c32* file from the Syslinux distribution
+* The kernel of the VyOS software you want to deploy. That is the
+  *vmlinuz* file inside the */live* directory of the extracted
+  contents from the ISO file.
+* 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.
+* A directory named pxelinux.cfg which must contain the configuration
+  file. We will use the configuration_ file shown below, which we named
+  default_.
+
+.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config
+.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration
+
+In the example we configured our existent VyOS as the TFTP server too:
+
+.. code-block:: none
+
+  vyos@vyos# show service tftp-server
+   directory /config/tftpboot
+   listen-address 192.168.1.50
+
+Example of the contents of the TFTP server:
+
+.. code-block:: none
+
+  vyos@vyos# ls -hal /config/tftpboot/
+  total 29M
+  drwxr-sr-x 3 tftp tftp      4.0K Oct 14 00:23 .
+  drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 ..
+  -r--r--r-- 1 root vyattacfg  25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos
+  -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32
+  -rw-r--r-- 1 root vyattacfg  46K Oct 13 23:24 pxelinux.0
+  drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg
+  -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz
+
+  vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg
+  total 12K
+  drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 .
+  drwxr-sr-x 3 tftp tftp      4.0K Oct 14 00:23 ..
+  -rw-r--r-- 1 root root       191 Oct 14 01:10 default
+
+Example of simple (no menu) configuration file:
+
+.. code-block:: none
+
+  vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default
+  DEFAULT VyOS123
+
+  LABEL VyOS123
+   KERNEL vmlinuz
+   APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs
+
+Step 3: HTTP
+^^^^^^^^^^^^
+
+We also need to provide the *filesystem.squashfs* file. That is a heavy
+file and TFTP is slow, so you could send it through HTTP to speed up the
+transfer. That is how it is done in our example, you can find that in
+the configuration file above.
+
+**First** run a web server - you can use a simple one like
+`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs`
+file. The file can be found inside the `/live` directory of the
+extracted contents of the ISO file.
+
+**Second**, edit the configuration file of the :ref:`install_from_tftp`
+so that it shows the correct URL at
+``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``.
+
+.. note:: Do not change the name of the *filesystem.squashfs* file. If 
+   you are working with different versions, you can create different
+   directories instead.
+
+And **third**, restart the TFTP service. If you are using VyOS as your
+TFTP Server, you can restart the service with
+``sudo service tftpd-hpa restart``.
+
+.. note::  Make sure the available directories and files in both TFTP
+   and HTTP server have the right permissions to be accessed from the
+   booting clients.
+
+.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html
+
+Client Boot
+-----------
+
+Finally, turn on your PXE-enabled client or clients. They will
+automatically get an IP address from the DHCP server and start booting
+into VyOS live from the files automatically taken from the TFTP and HTTP
+servers.
+
+Once finished you will be able to proceed with the ``install image``
+command as in a regular VyOS installation.
+
+
+
+Known Issues
+============
+
+This is a list of known issues that can arise during installation.
+
+Black screen on install
+-----------------------
+
+GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts.
+This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a
+black screen after selecting the `Live system` option from the installation image.
+
+The workaround is to type `e` when the boot menu appears and edit the GRUB boot options.  Specifically, remove the:
+
+`console=ttyS0,115200`
+
+option, and type CTRL-X to boot.
+
+Installation can then continue as outlined above.
+
+.. _SYSLINUX: http://www.syslinux.org/
+.. _balenaEtcher: https://www.balena.io/etcher/
+.. _Rufus: https://rufus.ie/
+.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems