vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity
vyos-documentation/docs/installation/install.rst

457 lines
19 KiB
ReStructuredText
Raw Blame History

.. _installation:
############
Installation
############
VyOS installation requires a downloaded VyOS .iso file. That file is
a live install image that lets you boot a live VyOS. From the live
system, you can proceed to a permanent installation on a hard drive or
any other type of storage.
.. table:: Comparison of VyOS image releases
+--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+
| Release Type | Description | Release Cycle | Intended Use | Access to Images | Access to Source |
+==============+===================================================+===================+=======================================+=======================+==================+
| **Nightly | Automatically built from the current branch. | Every night | Developing VyOS, testing new | Everyone | Everyone |
| (Current)** | Always up to date with cutting edge development | | features, experimenting. | | |
| | but guaranteed to contain bugs. | | | | |
+--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+
| **Stream** | VyOS Stream serves as a technology preview and | Every quarter | Non-critical production environments, | Everyone | Everyone |
| | a qulity gate for the upcoming LTS release. | | preparing for the LTS release. | | |
| | Allows everyone to try new features and check if | | | | |
| | they work well or need improvements. | | | | |
+--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+
| **Release | Rather stable. All development focuses on testing | Irregularly until | Labs, small offices and non-critical | Everyone | Everyone |
| Candidate** | and hunting down remaining bugs following the | EPA comes out | production systems backed by a | | |
| | feature freeze. | | high-availability setup. | | |
+--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+
| **Early | Highly stable with no known bugs. Needs to be | Irregularly until | Non-critical production environments, | Everyone | Everyone |
| Production | tested repeatedly under different conditions | LTS comes out | preparing for the LTS release. | | |
| Access** | before it can become the final release. | | | | |
+--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+
| **Long-Term | Guaranteed to be stable and carefully maintained | Every major | Large-scale enterprise networks, | Subscribers, | Subscribers, |
| Support** | for several years after the release. No features | version | internet service providers, | contributors, | contributors |
| | are introduced but security updates are released | | critical production environments | non-profits, | |
| | in a timely manner. | | that call for minimum downtime. | emergency services, | |
| | | | | academic institutions | |
+--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+
Hardware requirements
=====================
The minimum system requirements are 4 GB RAM and 10 GB 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 access a
variety of different downloads via the "Downloads" link. These downloads
include LTS (Long-Term Support), the associated hot-fix releases, early public
access releases, pre-built VM images, as well as device specific installation
ISOs. See this article_ for more information on downloads.
.. figure:: /_static/images/vyosnew-downloads.png
Building from source
--------------------
Subscribers can download the source code for the LTS release from the
"Downloads" link, while non-subscribers can access the source code for the
Rolling release. Instructions can be found in the :ref:`build` section of this
manual. VyOS source code repository is available 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`. We depend on your feedback
to improve VyOS!
The following link contains the list of the most recent VyOS builds for AMD64
systems from the current branch:
https://vyos.net/get/nightly-builds/
Download Verification
---------------------
LTS images are signed by the VyOS lead package-maintainer private key. With
the official public key, the authenticity of the package can be
verified. Minisign is used for verification.
.. _minisign-verification:
Minisign verification
^^^^^^^^^^^^^^^^^^^^^
Currently we are using Minisign for release signing which is a simple tool to
sign files and verify signatures.
In 2015, OpenBSD introduced signify. An alternative implementation of the same
protocol is minisign, which is also available for Windows and macOS, and in most
GNU/Linux distros it's in the repositories now. It is portable, lightweight, and
uses the highly secure Ed25519 public-key signature system.
:vytask:`T2108` switched the validation system to prefer minisign over GPG keys.
To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run:
.. code-block:: none
$ minisign -V -P RWSIhkR/dkM2DSaBRniv/bbbAf8hmDqdbOEmgXkf1RxRoxzodgKcDyGq -m vyos-1.5-rolling-202409250007-generic-amd64.iso vyos-1.5-rolling-202409250007-generic-amd64.iso.minisig
Signature and comment signature verified
Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso hashed
During an image upgrade VyOS performas the following command:
.. code-block:: none
$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig
Signature and comment signature verified
Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso
.. note:: Starting with 1.4.3, VyOS uses Minisign exclusively. This should not
be a problem for anyone because Minisign signature verification has already
been present in all releases for years. But if you see an unexpected verification
error, you can solve that by updating your system to 1.4.2 first.
Removed support for GnuPG signatures(:vytask:`T7301`).
.. _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 tested 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 everything 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.
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 VyOS installation!
This command will install VyOS to your permanent storage.
Would you like to continue? [y/N] y
What would you like to name this image? (Default: 2025.09.17-0018-rolling)
Please enter a password for the "vyos" user:
Please confirm password for the "vyos" user:
What console should be used by default? (K: KVM, S: Serial)? (Default: S)
Probing disks
1 disk(s) found
The following disks were found:
Drive: /dev/vda (10.0 GB)
Which one should be used for installation? (Default: /dev/vda)
Installation will delete all data on the drive. Continue? [y/N] y
Searching for data from previous installations
No previous installation found
Would you like to use all the free space on the drive? [Y/n] Y
Creating partition table...
The following config files are available for boot:
1: /opt/vyatta/etc/config/config.boot
2: /opt/vyatta/etc/config.boot.default
Which file would you like as boot config? (Default: 1)
Creating temporary directories
Mounting new partitions
Creating a configuration file
Copying system image files
Installing GRUB configuration files
Installing GRUB to the drive
Cleaning up
Unmounting target filesystems
Removing temporary files
The image installed successfully; please reboot now.
3. After the installation is completed, 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 that 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 {
option {
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
}
subnet-id 1
}
}
.. _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_.
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.
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.
.. stop_vyoslinter
.. _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
.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config
.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration
.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html
.. _article: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913
.. start_vyoslinter
Reference in New Issue View Git Blame Copy Permalink