diff options
Diffstat (limited to 'docs/install.rst')
| -rw-r--r-- | docs/install.rst | 211 |
1 files changed, 179 insertions, 32 deletions
diff --git a/docs/install.rst b/docs/install.rst index ba311a41..14d36fd9 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -13,33 +13,55 @@ The recommended system requirements are 512 MiB RAM and 2 GiB storage. Getting the software --------------------- -Registered subscribers can download stable release (LTS) images. If you log into https://support.vyos.io/ as a registered subscriber, you will see the "Downloads" link there. +Registered subscribers +^^^^^^^^^^^^^^^^^^^^^^ + +A registered subscriber can log into https://support.vyos.io/ to have access to a variety of different downloads via the "Downloads" link. +These downloads include LTS releases and associated hot-fixes, 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 get the LTS release by building it from source. The instructions for building from source can be found at: -Non-subscribers can get the LTS release by building it from source. Just follow the instructions in https://github.com/vyos/vyos-build -Everyone can dowload VyOS rolling images from https://downloads.vyos.io/ +Rolling releases +^^^^^^^^^^^^^^^^ + +Non-subscribers and subscribers can download bleeding-edge VyOS rolling images from: + +https://downloads.vyos.io/ + +The following link will always fetch the most updated AMD64 image of the current branch: + +https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso Preparing software verification ------------------------------- -This subsection and the following one applies to dowloaded LTS images, for other cases please jump to :ref:`Install`. +This subsection and the following one applies to downloaded LTS images, for other cases 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. -LTS images are signed by VyOS lead package-maintainer private key. If you have our public key, you will be able to verify the authenticity of the package. +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. -First you need to install GPG or another OpenPGP implementation. -On most GNU+Linux distributions it is installed by default because package managers use it to verify package signatures. -On other systems you may need to find and install the package. +The offical VyOS public key can be retrieved in a number of ways. Skip to :ref:`gpg-verification` if the key is already present. -Then you need VyOS public key. If you already have it, you can jump to :ref:`gpg-verification`. If you don't have it yet, you can get it from a key server. +It can be retrieved directly from a key server: ``gpg --recv-keys FD220285A0FE6D7E`` -Or open your web browser, visit a key server and copy our public key from there: https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E +Or it can be accessed from a key server via a web browser: -Or from this block below. +https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E +Or from the following block: .. code-block:: sh @@ -98,13 +120,11 @@ Or from this block below. -----END PGP PUBLIC KEY BLOCK----- - -Then you can paste that text in a new file, and import the file into GPG: +The key is then pasted into a new text file and imported into GPG: ``gpg --import file_with_the_public_key`` - -You can now check your GPG software has our public key. +The import can be verified with: .. code-block:: sh @@ -121,11 +141,11 @@ You can now check your GPG software has our public key. GPG verification ---------------- -As you have our public key, you just need the signature of the software you want to verify. +With the public key imported, the signature for the desired image needs to be downloaded. -.. note:: **In order to get the signature, go to your web browser and append .asc to the URL of your dowloaded VyOS image**. You will download a small *.asc* file, that's the signature of your image. +.. 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. -So finally you can verify the authenticity of your image. +Finally, verify the authencity of the downloaded image: .. code-block:: sh @@ -142,8 +162,9 @@ Install ------- -The VyOS ISO is a Live CD and will boot to a functional VyOS image. To login -to the system, use the default username ``vyos`` with password ``vyos``. +The VyOS ISO is a Live CD and will boot to a functional VyOS image. + +To login to the system, use the default username ``vyos`` with password ``vyos``. .. code-block:: sh @@ -160,20 +181,15 @@ to the system, use the default username ``vyos`` with password ``vyos``. Unlike general purpose Linux distributions, VyOS uses "image installation" that mimics the user experience of traditional hardware routers and allows -you to keep multiple VyOS versions on the same machine and switch to a previous -version if something breaks after upgrade. Every version is contained in its -own squashfs image that is mounted in a union filesystem together with a -directory for mutable data (configs etc.). +keeping multiple VyOS versions installed simultaneously. This makes it possible to switch to a previous +version if something breaks after an upgrade. -.. note:: Older versions used to support non-image installation (`install system` command). - Support for this is removed from VyOS 1.2 (crux) and newer releases +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. - This installation method has been deprecated since the time image installation - was introduced (long before the fork), and does not provide any version - management capabilities. You **should not** use it for new installations - even if it's still available in new versions. You should not worry about - older systems installed that way though, they can be upgraded with ``add - system image``. +.. note:: Older versions used to support non-image installation (``install system`` command). + Support for this is removed from VyOS 1.2 (crux) and newer releases. Older releases can still be upgraded + via ``add system image <image_path>`` To install VyOS, run ``install image``. @@ -238,3 +254,134 @@ After the installation is complete, remove the Live CD and reboot the system: + +.. _PXE Install: + +PXE Install +----------- + +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** +* A **DHCP server** +* A **TFTP server** +* A **HTTP server** (this is optional but we will use it to speed up our intallation) +* The **VyOS ISO** image to be installed (Do not use images prior to 1.2.3) +* The **pxelinux.0** and **ldlinux.c32** `files from the Syslinux distribution <https://kernel.org/pub/linux/utils/boot/syslinux/>`_ + +Step 1: DHCP +^^^^^^^^^^^^ + +Configure a DHCP server so that it gives the client + + - An **IP address** + - The **TFTP server address** (DHCP option 66). Sometimes named *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:: sh + + 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 + } + } + } + [edit] + vyos@vyos# + + +.. _tftp-server: + +Step 2: TFTP +^^^^^^^^^^^^ + +Configure a TFTP server so that it serves the following: + + + The file **pxelinux.0** from the *Syslinux* distribution + + The file **ldlinux.c32** 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 <https://wiki.syslinux.org/wiki/index.php?title=Config>`_ shown below, which we named `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:: sh + + vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 + [edit] + vyos@vyos# + + +Example of the contents of the TFTP server: + +.. code-block:: sh + + 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 + [edit] + vyos@vyos# + [edit] + 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 + [edit] + vyos@vyos# + + +Example of simple (no menu) configuration file: + +.. code-block:: sh + + 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://192.168.1.2:8000/filesystem.squashfs + [edit] + vyos@vyos# + + + +Step 3: HTTP +^^^^^^^^^^^^ + + a) As you can read in the configuration file, we are sending *filesystem.squashfs* through HTTP. As that is a heavy file, we choose HTTP to speed up its transfer. **Run a web server** --you can use a simple one like `Python's SimpleHTTPServer <https://docs.python.org/2/library/simplehttpserver.html>`_-- **and start serving the filesystem.squashfs file**. The file can be found inside the *live* directory of the extracted contents of the ISO file. + + + b) Edit the configuration file at the :ref:`tftp-server` so that it shows the correct URL at *fetch=http://address_of_your_HTTP_server/filesystem.squashfs*. Then 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 server and HTTP server have the right permissions to be accessed from the booting clients. + + +Step 4: Boot the clients +^^^^^^^^^^^^^^^^^^^^^^^^ + +Turn on the 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 normal VyOS installation. |