From a6c226d4b4e79c07121b0a609d2fb78cae70f3b0 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 19:24:16 +0100 Subject: arange installation and image management --- docs/appendix/migrate-from-vyatta.rst | 164 ------------ docs/appendix/virtual/index.rst | 12 - docs/appendix/virtual/libvirt.rst | 160 ------------ docs/appendix/virtual/vyos-on-gns3.rst | 176 ------------- docs/appendix/virtual/vyos-on-vmware.rst | 32 --- docs/appendix/vyos-on-baremetal.rst | 411 ------------------------------ docs/appendix/vyos-on-clouds.rst | 173 ------------- docs/image-mgmt.rst | 193 -------------- docs/installation/cloud/aws.rst | 54 ++++ docs/installation/cloud/azure.rst | 53 ++++ docs/installation/cloud/gcp.rst | 55 ++++ docs/installation/cloud/index.rst | 13 + docs/installation/cloud/oracel.rst | 8 + docs/installation/image.rst | 115 +++++++++ docs/installation/index.rst | 3 +- docs/installation/iso.rst | 2 + docs/installation/migrate-from-vyatta.rst | 164 ++++++++++++ docs/installation/upate.rst | 79 ++++++ docs/installation/virtual/eve-ng.rst | 8 + docs/installation/virtual/gns3.rst | 176 +++++++++++++ docs/installation/virtual/index.rst | 12 + docs/installation/virtual/libvirt.rst | 160 ++++++++++++ docs/installation/virtual/proxmox.rst | 8 + docs/installation/virtual/vmware.rst | 32 +++ docs/installation/vyos-on-baremetal.rst | 411 ++++++++++++++++++++++++++++++ 25 files changed, 1352 insertions(+), 1322 deletions(-) delete mode 100644 docs/appendix/migrate-from-vyatta.rst delete mode 100644 docs/appendix/virtual/index.rst delete mode 100644 docs/appendix/virtual/libvirt.rst delete mode 100644 docs/appendix/virtual/vyos-on-gns3.rst delete mode 100644 docs/appendix/virtual/vyos-on-vmware.rst delete mode 100644 docs/appendix/vyos-on-baremetal.rst delete mode 100644 docs/appendix/vyos-on-clouds.rst delete mode 100644 docs/image-mgmt.rst create mode 100644 docs/installation/cloud/aws.rst create mode 100644 docs/installation/cloud/azure.rst create mode 100644 docs/installation/cloud/gcp.rst create mode 100644 docs/installation/cloud/index.rst create mode 100644 docs/installation/cloud/oracel.rst create mode 100644 docs/installation/image.rst create mode 100644 docs/installation/iso.rst create mode 100644 docs/installation/migrate-from-vyatta.rst create mode 100644 docs/installation/upate.rst create mode 100644 docs/installation/virtual/eve-ng.rst create mode 100644 docs/installation/virtual/gns3.rst create mode 100644 docs/installation/virtual/index.rst create mode 100644 docs/installation/virtual/libvirt.rst create mode 100644 docs/installation/virtual/proxmox.rst create mode 100644 docs/installation/virtual/vmware.rst create mode 100644 docs/installation/vyos-on-baremetal.rst diff --git a/docs/appendix/migrate-from-vyatta.rst b/docs/appendix/migrate-from-vyatta.rst deleted file mode 100644 index f15c3d5a..00000000 --- a/docs/appendix/migrate-from-vyatta.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. _migrate_from_vyatta: - -Migrate from Vyatta Core -======================== - -VyOS 1.x line aims to preserve backward compatibility and provide a safe -upgrade path for existing Vyatta Core users. You may think of VyOS 1.0.0 as -VC7.0. - -Vyatta release compatibility ----------------------------- - -Vyatta Core releases from 6.5 to 6.6 should be 100% compatible. - -Vyatta Core 6.4 and earlier may have incompatibilities. In Vyatta 6.5 the -"modify" firewall was removed and replaced with the ``set policy route`` -command family, old configs can not be automatically converted. You will have -to adapt it to post-6.5 Vyatta syntax manually. - -.. note:: Also, in Vyatta Core 6.5 remote access VPN interfaces have been - renamed from ``pppX`` to ``l2tpX`` and ``pptpX``. If you are using - zone based firewalling in Vyatta Core pre-6.5 versions, make sure to change - interface names in rules for remote access VPN. - -Upgrade procedure ------------------ - -You just use ``add system image``, as if it was a new VC release (see -:ref:`update_vyos` for additional information). The only thing you want to do -is to verify the new images digital signature. You will have to add the public -key manually once as it is not shipped the first time. - -.. code-block:: none - - vyatta@vyatta:~$ wget http://wiki.vyos.net/so3group_maintainers.key - Connecting to vyos.net (x.x.x.x:80) - so3group_maintainers 100% |*************************| 3125 --:--:-- ETA - vyatta@vyatta:~$ sudo apt-key add so3group_maintainers.key - OK - vyatta@vyatta:~$ - -For completion the key below corresponds to the key listed in the URL above. - -.. code-block:: none - - -----BEGIN PGP PUBLIC KEY BLOCK----- - Version: GnuPG v1.4.12 (GNU/Linux) - - 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 - Pr6fWpIruuc7Gg9rUF0L - =VQTr - -----END PGP PUBLIC KEY BLOCK----- - -Next add the VyOS image. - -This example uses VyOS 1.0.0, however, it's better to install the latest -release. - -.. code-block:: none - - vyatta@vyatta:~$ show system image - The system currently has the following image(s) installed: - 1: VC6.6R1 (default boot) (running image) - - vyatta@vyatta:~$ add system image https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso - Trying to fetch ISO file from https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 223M 100 223M 0 0 960k 0 0:03:57 0:03:57 --:--:-- 657k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 836 100 836 0 0 4197 0 --:--:-- --:--:-- --:--:-- 4287 - Found it. Checking digital signature... - gpg: directory `/root/.gnupg' created - gpg: new configuration file `/root/.gnupg/gpg.conf' created - gpg: WARNING: options in `/root/.gnupg/gpg.conf' are not yet active during this run - gpg: keyring `/root/.gnupg/pubring.gpg' created - gpg: Signature made Sun Dec 22 16:51:42 2013 GMT using RSA key ID A442E6E9 - gpg: /root/.gnupg/trustdb.gpg: trustdb created - gpg: Good signature from "SO3 Group Maintainers " - gpg: WARNING: This key is not certified with a trusted signature! - gpg: There is no indication that the signature belongs to the owner. - Primary key fingerprint: DD5B B405 35E7 F6E3 4278 1ABF B744 E25A A442 E6E9 - Digital signature is valid. - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [1.0.0]: [return] - OK. This image will be named: 1.0.0 - Installing "1.0.0" image. - Copying new release files... - - Would you like to save the current configuration - directory and config file? (Yes/No) [Yes]: [return] - Copying current configuration... - - Would you like to save the SSH host keys from your - current configuration? (Yes/No) [Yes]: [return] - Copying SSH keys... - Setting up grub configuration... - Done. - - vyatta@vyatta:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.0.0 (default boot) - 2: VC6.6R1 (running image) - -Upon reboot, you should have a working installation of VyOS. - -You can go back to your Vyatta install using the ``set system image -default-boot`` command and selecting the your previous Vyatta Core image. - -.. note:: Future releases of VyOS will break the direct upgrade path from - Vyatta core. Please upgrade through an intermediate VyOS version e.g. VyOS - 1.2. After this you can continue upgrading to newer releases once you bootet - into VyOS 1.2 once. diff --git a/docs/appendix/virtual/index.rst b/docs/appendix/virtual/index.rst deleted file mode 100644 index 7ede37b5..00000000 --- a/docs/appendix/virtual/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _virtual: - -Running on Virtual Environments -=============================== - - -.. toctree:: - :maxdepth: 2 - - libvirt - vyos-on-vmware - vyos-on-gns3 diff --git a/docs/appendix/virtual/libvirt.rst b/docs/appendix/virtual/libvirt.rst deleted file mode 100644 index 0d624b94..00000000 --- a/docs/appendix/virtual/libvirt.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _libvirt: - -*************************** -Running on Libvirt Qemu/KVM -*************************** - -Libvirt is an open-source API, daemon and management tool for managing platform virtualization. -There are several ways to deploy VyOS on libvirt kvm. Use Virt-manager and native CLI. -In an example we will be use use 4 gigabytes of memory, 2 cores CPU and default network virbr0. - -CLI -=== - -Deploy from ISO ---------------- - -Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, the disk ``qcow2`` will be created automatically. -The ``default`` network is the virtual network (type Virtio) created by the hypervisor with NAT. - -.. code-block:: none - - $ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom /var/lib/libvirt/images/vyos.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r1`` - -.. code-block:: none - - $ virsh console vyos_r1 - - Connected to domain vyos_r1 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ install image - -After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. - -Deploy from qcow2 ------------------ -The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` images is that they don't need to be installed. -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - -Create VM with ``import`` qcow2 disk option. - -.. code-block:: none - - $ virt-install -n vyos_r2 \ - --ram 4096 \ - --vcpus 2 \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r2`` - -.. code-block:: none - - $ virsh console vyos_r2 - - Connected to domain vyos_r2 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ - -The system is fully operational. - -Virt-manager -============ -The virt-manager application is a desktop user interface for managing virtual machines through libvirt. -On the linux open :abbr:`VMM (Virtual Machine Manager)`. - -Deploy from ISO ---------------- - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` - -2. Choose ``Local install media`` (ISO) - -.. figure:: /_static/images/virt-libvirt-01.png - -3. Choose path to iso vyos.iso. Operating System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Disk size - -.. figure:: /_static/images/virt-libvirt-04.png - -6. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -7. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-06.png - -Deploy from qcow2 ------------------ - -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` - -2. Choose ``Import existing disk`` image - -.. figure:: /_static/images/virt-libvirt-qc-01.png - -3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously downloaded . Operation System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-qc-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -6. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-qc-03.png - - - diff --git a/docs/appendix/virtual/vyos-on-gns3.rst b/docs/appendix/virtual/vyos-on-gns3.rst deleted file mode 100644 index 93ea9ae2..00000000 --- a/docs/appendix/virtual/vyos-on-gns3.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. _vyos-on-gns3: - -############### -Running on GNS3 -############### - -Sometimes you may want to test VyOS in a lab environment. -`GNS3 `__ is a network emulation software you -might use for it. - -This guide will provide the necessary steps for installing -and setting up VyOS on GNS3. - -Requirements ------------- - -The following items are required: - -* A VyOS installation image (.iso file). - `Here `__ you - can find how to get it. - -* A working GNS3 installation. For further information see the - `GNS3 documentation `__. - -.. _vm_setup: - -VM setup --------- - -First, a virtual machine (VM) for the VyOS installation must be created -in GNS3. - -Go to the GNS3 **File** menu, click **New template** and choose select -**Manually create a new Template**. - -.. figure:: /_static/images/gns3-01.png - -Select **Quemu VMs** and then click on the ``New`` button. - -.. figure:: /_static/images/gns3-02.png - -Write a name for your VM, for instance "VyOS", and click ``Next``. - -.. figure:: /_static/images/gns3-03.png - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click ``Next``. - -.. figure:: /_static/images/gns3-04.png - -Select **telnet** as your console type and click ``Next``. - -.. figure:: /_static/images/gns3-05.png - -Select **New image** for the base disk image of your VM and click -``Create``. - -.. figure:: /_static/images/gns3-06.png - -Use the defaults in the **Binary and format** window and click -``Next``. - -.. figure:: /_static/images/gns3-07.png - -Use the defaults in the **Qcow2 options** window and click ``Next``. - -.. figure:: /_static/images/gns3-08.png - -Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu -image creator**. - -.. figure:: /_static/images/gns3-09.png - -Click ``Finish`` to end the **New QEMU VM template** wizard. - -.. figure:: /_static/images/gns3-10.png - -Now the VM settings have to be edited. - -Being again at the **Preferences** window, having **Qemu VMs** -selected and having our new VM selected, click the ``Edit`` button. - -.. figure:: /_static/images/gns3-11.png - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -* Click on the ``Browse...`` button to choose the **Symbol** you want to - have representing your VM. -* In **Category** select in which group you want to find your VM. -* Set the **Boot priority** to **CD/DVD-ROM**. - -.. figure:: /_static/images/gns3-12.png - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -.. figure:: /_static/images/gns3-13.png - -At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image -you want to install. - -.. figure:: /_static/images/gns3-14.png - -.. note:: You probably will want to accept to copy the .iso file to your - default image directory when you are asked. - -In the **Network** tab, set **0** as the number of adapters, set the -**Name format** to **eth{0}** and the **Type** to **Paravirtualized -Network I/O (virtio-net-pci)**. - -.. figure:: /_static/images/gns3-15.png - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click ``OK``, which will save and close the **QEMU VM template -configuration** window. - -.. figure:: /_static/images/gns3-16.png - -At the general **Preferences** window, click ``OK`` to save and close. - -.. figure:: /_static/images/gns3-17.png - - -.. _vyos_installation: - -VyOS installation ------------------ - -* Create a new project. -* Drag the newly created VyOS VM into it. -* Start the VM. -* Open a console. - The console should show the system booting. It will ask for the login - credentials, you are at the VyOS live system. -* `Install VyOS `__ - as normal (that is, using the ``install image`` command). - -* After a successful installation, shutdown the VM with the ``poweroff`` - command. - -* **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -.. _vyos_vm_configuration: - -VyOS VM configuration ---------------------- - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -.. figure:: /_static/images/gns3-20.png - -**CD/DVD** tab: Unmount the installation image file by clearing the -**Image** entry field. - -.. figure:: /_static/images/gns3-21.png - -Set the number of required network adapters, for example **4**. - -.. figure:: /_static/images/gns3-215.png - -**Advanced** settings tab: Mark the checkbox **Use as a linked -base VM** and click ``OK`` to save the changes. - -.. figure:: /_static/images/gns3-22.png - -The VyOS VM is now ready to be deployed. - diff --git a/docs/appendix/virtual/vyos-on-vmware.rst b/docs/appendix/virtual/vyos-on-vmware.rst deleted file mode 100644 index c4299cbf..00000000 --- a/docs/appendix/virtual/vyos-on-vmware.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _vyosonvmware: - -Running on VMware ESXi -###################### - -ESXi 5.5 or later -***************** - -.ova files are available for supporting users, and a VyOS can also be stood up using a generic Linux instance, and attaching the bootable ISO file and installing from the ISO -using the normal process around `install image`. - -.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been advised. - -Memory Contention Considerations --------------------------------- -When the underlying ESXi host is approaching ~92% memory utilisation it will start the balloon process in s a 'soft' state to start reclaiming memory from guest operating systems. -This causes an artificial pressure using the vmmemctl driver on memory usage on the virtual guest. As VyOS by default does not have a swap file, this vmmemctl pressure is unable to -force processes to move in memory data to the paging file, and blindly consumes memory forcing the virtual guest into a low memory state with no way to escape. The balloon can expand to 65% of -guest allocated memory, so a VyOS guest running >35% of memory usage, can encounter an out of memory situation, and trigger the kernel oom_kill process. At this point a weighted -lottery favouring memory hungry processes will be run with the unlucky winner being terminated by the kernel. - -It is advised that VyOS routers are configured in a resource group with adequate memory reservations so that ballooning is not inflicted on virtual VyOS guests. - - - - - -References ----------- - -https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html - diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst deleted file mode 100644 index db618431..00000000 --- a/docs/appendix/vyos-on-baremetal.rst +++ /dev/null @@ -1,411 +0,0 @@ -.. _vyosonbaremetal: - -##################### -Running on Bare Metal -##################### - -Supermicro A2SDi (Atom C3000) -============================= - -I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. -Running VyOS on an UEFI only device is supported as of VyOS release 1.2. - -Shopping Cart -------------- - -* 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) -* 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) -* 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN - with Intel C3000 SoC 1GbE) -* 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) -* 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) -* 1x Supermicro MCP-320-81302-0B (optional FAN tray) - -Optional (10GE) ---------------- -If you want to get additional ethernet ports or even 10GE connectivity -the following optional parts will be required: - -* 1x Supermicro RSC-RR1U-E8 (Riser Card) -* 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) - -Latest VyOS rolling releases boot without any problem on this board. You also -receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no -information about `OpenBMC `_ so far on this -motherboard). - -Pictures --------- - -.. figure:: /_static/images/1u_vyos_back.jpg - :scale: 25 % - :alt: CSE-505-203B Back - -.. figure:: /_static/images/1u_vyos_front.jpg - :scale: 25 % - :alt: CSE-505-203B Front - -.. figure:: /_static/images/1u_vyos_front_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B Open 1 - -.. figure:: /_static/images/1u_vyos_front_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B Open 2 - -.. figure:: /_static/images/1u_vyos_front_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 1 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 2 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open - - -.. _pc-engines-apu4: - -PC Engines APU4 -================ - -As this platform seems to be quite common in terms of noise, cost, power and -performance it makes sense to write a small installation manual. - -This guide was developed using an APU4C4 board with the following specs: - -* AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI - support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. -* 4 GB DDR3-1333 DRAM, with optional ECC support -* About 6 to 10W of 12V DC power depending on CPU load -* 2 miniPCI express (one with SIM socket for 3G modem). -* 4 Gigabit Ethernet channels using Intel i211AT NICs - -The board can be powered via 12V from the front or via a 5V onboard connector. - -Shopping Cart -------------- - -* 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM -* 1x Kingston SUV500MS/120G -* 1x VARIA Group Item 326745 19" dual rack for APU4 - -The 19" enclosure can accommodate up to two APU4 boards - there is a single and -dual front cover. - -Extension Modules -^^^^^^^^^^^^^^^^^ - -WiFi -"""" - -Refer to :ref:`wireless-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform: - -* Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. - -WWAN -"""" - -Refer to :ref:`wwan-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform using VyOS 1.3 (equuleus): - -* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -* Huawei ME909u-521 miniPCIe card (LTE) - -VyOS 1.2 (crux) ---------------- - -Depending on the VyOS versions you intend to install there is a difference in -the serial port settings (:vytask:`T1327`). - -Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. - -Connect serial port to a PC through null modem cable (RXD / TXD crossed over). -Set terminal emulator to 115200 8N1. - -.. code-block:: none - - PC Engines apu4 - coreboot build 20171130 - BIOS version v4.6.4 - 4080 MB ECC DRAM - SeaBIOS (version rel-1.11.0.1-0-g90da88d) - - Press F10 key now for boot menu: - - Select boot device: - - 1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) - 2. USB MSC Drive Generic Flash Disk 8.07 - 3. Payload [memtest] - 4. Payload [setup] - -Now boot from the ``USB MSC Drive Generic Flash Disk 8.07`` media by pressing -``2``, the VyOS boot menu will appear, just wait 10 seconds or press ``Enter`` -to continue. - -.. code-block:: none - - lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk - x VyOS - Boot Menu x - tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu - x Live (amd64-vyos) x - x Live (amd64-vyos failsafe) x - x x - mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj - -The image will be loaded and the last lines you will get will be: - -.. code-block:: none - - Loading /live/vmlinuz... ok - Loading /live/initrd.img... - -The Kernel will now spin up using a different console setting. Set terminal -emulator to 9600 8N1 and after a while your console will show: - -.. code-block:: none - - Loading /live/vmlinuz... ok - Loading /live/initrd.img... - Welcome to VyOS - vyos ttyS0 - - vyos login: - -You can now proceed with a regular image installation as described in -:ref:`installation`. - -As the APU board itself still used a serial setting of 115200 8N1 it is -strongly recommended that you change the VyOS serial interface settings after -your first successful boot. - -Use the following command to adjust the :ref:`serial-console` settings: - -.. code-block:: none - - set system console device ttyS0 speed 115200 - -.. note:: Once you ``commit`` the above changes access to the serial interface - is lost until you set your terminal emulator to 115200 8N1 again. - -.. code-block:: none - - vyos@vyos# show system console - device ttyS0 { - speed 115200 - } - -VyOS 1.2 (rolling) ------------------- - -Installing the rolling release on an APU2 board does not require any change -on the serial console from your host side as :vytask:`T1327` was successfully -implemented. - -Simply proceed with a regular image installation as described in -:ref:`installation`. - -Pictures --------- - -.. note:: Both device types operate without any moving parts and emit zero - noise. - -Rack Mount -^^^^^^^^^^ - -.. figure:: /_static/images/apu4_rack_1.jpg - :scale: 25 % - :alt: APU4 rack closed - -.. figure:: /_static/images/apu4_rack_2.jpg - :scale: 25 % - :alt: APU4 rack front - -.. figure:: /_static/images/apu4_rack_3.jpg - :scale: 25 % - :alt: APU4 rack module #1 - -.. figure:: /_static/images/apu4_rack_4.jpg - :scale: 25 % - :alt: APU4 rack module #2 - -.. figure:: /_static/images/apu4_rack_5.jpg - :scale: 25 % - :alt: APU4 rack module #3 with PSU - -VyOS custom print -""""""""""""""""" - -.. figure:: /_static/images/apu4_rack_vyos_print.jpg - :scale: 25 % - :alt: APU4 custom VyOS powder coat - -Desktop / Bench Top -^^^^^^^^^^^^^^^^^^^ - -.. figure:: /_static/images/apu4_desk_1.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_2.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_3.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. figure:: /_static/images/apu4_desk_4.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. _Rufus: https://rufus.ie/ - -Qotom Q355G4 -============ - -The install on this Q355G4 box is pretty much plug and play. The port numbering -the OS does might differ from the labels on the outside, but the UEFI firmware -has a port blink test built in with MAC addresses so you can very quickly -identify which is which. MAC labels are on the inside as well, and this test -can be done from VyOS or plain Linux too. Default settings in the UEFI will -make it boot, but depending on your installation wishes (i.e. storage type, -boot type, console type) you might want to adjust them. This Qotom company -seems to be the real OEM/ODM for many other relabelling companies like -Protectli. - -Hardware --------- - -There are a number of other options, but they all seem to be close to Intel -reference designs, with added features like more serial ports, more network -interfaces and the likes. Because they don't deviate too much from standard -designs all the hardware is well-supported by mainline. It accepts one LPDDR3 -SO-DIMM, but chances are that if you need more than that, you'll also want -something even beefier than an i5. There are options for antenna holes, and SIM -slots, so you could in theory add an LTE/Cell modem (not tested so far). - -The chassis is a U-shaped alu extrusion with removable I/O plates and removable -bottom plate. Cooling is completely passive with a heatsink on the SoC with -internal and external fins, a flat interface surface, thermal pad on top of -that, which then directly attaches to the chassis, which has fins as well. It -comes with mounting hardware and rubber feet, so you could place it like a -desktop model or mount it on a VESA mount, or even wall mount it with the -provided mounting plate. The closing plate doubles as internal 2.5" mounting -place for an HDD or SSD, and comes supplied with a small SATA cable and SATA -power cable. - -Power supply is a 12VDC barrel jack, and included switching power supply, which -is why SATA power regulation is on-board. Internally it has a NUC-board-style -on-board 12V input header as well, the molex locking style. - -There are WDT options and auto-boot on power enable, which is great for remote -setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled -in enforcement mode, which is good but also means no coreboot option), yet has -most options available to configure (so it's not locked out like most firmwares -are). - -An external RS232 serial port is available, internally a GPIO header as well. -It does have Realtek based audio on board for some reason, but you can disable -that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS -mode and HDMI BIOS mode depends on what is connected at startup; it goes into -serial mode if you disconnect HDMI and plug in serial, in all other cases it's -HDMI mode. - -Partaker i5 -=========== - -.. figure:: ../_static/images/600px-Partaker-i5.jpg - -I believe this is actually the same hardware as the Protectli. I purchased it -in June 2018. It came pre-loaded with pfSense. - -`Manufacturer product page `_. - -Installation ------------- - -* Write VyOS ISO to USB drive of some sort -* Plug in VGA, power, USB keyboard, and USB drive -* Press "SW" button on the front (this is the power button; I don't know what - "SW" is supposed to mean). -* Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, - but with a few tries you should be able to get into the BIOS. -* Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 - (EHCI) to Enabled. Without doing this, the USB drive won't boot. -* Boot to the VyOS installer and install as usual. - -Warning the interface labels on my device are backwards; the left-most "LAN4" -port is eth0 and the right-most "LAN1" port is eth3. - -Acrosser AND-J190N1 -=================== - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg - -This microbox network appliance was build to create OpenVPN bridges. It can -saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN -http://www.acrosser.com/upload/AND-J190_J180N1-2.pdf - -You may have to add your own RAM and HDD/SSD. There is no VGA connector. But -Acrosser provides a DB25 adapter for the VGA header on the motherboard (not -used). - -BIOS Settings: --------------- - -First thing you want to do is getting a more user friendly console to configure -BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. - -For practical issues change speed from 115200 to 9600. 9600 is the default -speed at which both linux kernel and VyOS will reconfigure the serial port -when loading. - -Connect to serial (115200bps). Power on the appliance and press Del in the -console when requested to enter BIOS settings. - -Advanced > Serial Port Console Redirection > Console Redirection Settings: - -* Terminal Type : VT100+ -* Bits per second : 9600 - -Save, reboot and change serial speed to 9600 on your client. - -Some options have to be changed for VyOS to boot correctly. With XHCI enabled -the installer can’t access the USB key. Enable EHCI instead. - -Reboot into BIOS, Chipset > South Bridge > USB Configuration: - -* Disable XHCI -* Enable USB 2.0 (EHCI) Support - -Install VyOS: -------------- - -Create a VyOS bootable USB key. I used the 64-bit ISO (VyOS 1.1.7) and -`LinuxLive USB Creator `_. - -I'm not sure if it helps the process but I changed default option to live-serial -(line “default xxxx”) on the USB key under syslinux/syslinux.cfg. - -I connected the key to one black USB port on the back and powered on. The first -VyOS screen has some readability issues. Press :kbd:`Enter` to continue. - -Then VyOS should boot and you can perform the ``install image`` diff --git a/docs/appendix/vyos-on-clouds.rst b/docs/appendix/vyos-on-clouds.rst deleted file mode 100644 index 33b7011e..00000000 --- a/docs/appendix/vyos-on-clouds.rst +++ /dev/null @@ -1,173 +0,0 @@ -.. _vyos-on-clouds: - -Running on Clouds -################# - -Amazon AWS -********** - -Deploy VM ---------- - -Deploy VyOS on Amazon :abbr:`AWS (Amazon Web Services)` - -1. Click to ``Instances`` and ``Launch Instance`` - -.. figure:: /_static/images/cloud-aws-01.png - -2. On the marketplace search "VyOS" - -.. figure:: /_static/images/cloud-aws-02.png - -3. Choose the instance type. Minimum recommendation start from ``m3.medium`` - -.. figure:: /_static/images/cloud-aws-03.png - -4. Configure instance for your requirements. Select number of instances / network / subnet - -.. figure:: /_static/images/cloud-aws-04.png - -5. Additional storage. You can remove additional storage ``/dev/sdb``. First root device will be ``/dev/xvda``. You can skeep this step. - -.. figure:: /_static/images/cloud-aws-05.png - -6. Configure Security Group. It's recommended that you configure ssh access only from certain address sources. Or permit any (by default). - -.. figure:: /_static/images/cloud-aws-06.png - -7. Select SSH key pair and click ``Launch Instances`` - -.. figure:: /_static/images/cloud-aws-07.png - -8. Find out your public IP address. - -.. figure:: /_static/images/cloud-aws-08.png - -9. Connect to the instance by SSH key. - - .. code-block:: none - - ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3 - vyos@ip-192-0-2-10:~$ - - - - -References ----------- -https://console.aws.amazon.com/ - -Azure -***** - -Deploy VM ---------- - -Deploy VyOS on Azure. - -1. Go to the Azure services and Click to **Add new Virtual machine** - -2. Choose vm name, resource group, region and click **Browse all public and private images** - -.. figure:: /_static/images/cloud-azure-01.png - -3. On the marketplace search ``VyOS`` - -.. figure:: /_static/images/cloud-azure-02.png - -4. Generate new SSH key pair or use existing. - -.. figure:: /_static/images/cloud-azure-03.png - -5. Define network, subnet, Public IP. Or it will be created by default. - -.. figure:: /_static/images/cloud-azure-04.png - -6. Click ``Review + create``. After fiew second your deployment will be complete - -.. figure:: /_static/images/cloud-azure-05.png - -7. Click to your new vm and find out your Public IP address. - -.. figure:: /_static/images/cloud-azure-06.png - -8. Connect to the instance by SSH key. - - .. code-block:: none - - ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3 - vyos@vyos-doc-r1:~$ - -Add interface -------------- - -If instance was deployed with one **eth0** ``WAN`` interface and want to add new one. -To add new interface an example **eth1** ``LAN`` you need shutdown the instance. Attach the interface in the Azure portal and then start the instance. - -.. NOTE:: Azure does not allow you attach interface when the instance in the **Running** state. - -References ----------- -https://azure.microsoft.com - -Google Cloud Platform -********************* - -Deploy VM ---------- - -To deploy VyOS on GCP (Google Cloud Platform) - -1. Generate SSH key pair type **ssh-rsa** from the host that will connect to VyOS. - - Example: - - .. code-block:: none - - ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" - - -.. NOTE:: In name "vyos@mypc" The first value must be "**vyos**". Because default user is vyos and google api uses this option. - - -2. Open GCP console and navigate to the menu **Metadata**. Choose **SSH Keys** and click ``edit``. - -.. figure:: /_static/images/cloud-gcp-01.png - - -Click **Add item** and paste your public ssh key. Click ``Save``. - -.. figure:: /_static/images/cloud-gcp-02.png - - -2. On marketplace search "VyOS" - -3. Change Deployment name/Zone/Machine type and click ``Deploy`` - -.. figure:: /_static/images/cloud-gcp-03.png - -4. After fiew seconds click to ``instance`` - -.. figure:: /_static/images/cloud-gcp-04.png - -5. Find out your external IP address - -.. figure:: /_static/images/cloud-gcp-05.png - -6. Connect to the instance. SSH key was generated in the first step. - - .. code-block:: none - - ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 - vyos@vyos-r1-vm:~$ - -References ----------- -https://console.cloud.google.com/ - -Oracle -***************** - -References ----------- -https://www.oracle.com/cloud/ diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst deleted file mode 100644 index 143d02b2..00000000 --- a/docs/image-mgmt.rst +++ /dev/null @@ -1,193 +0,0 @@ -.. _image-mgmt: - -################ -Image Management -################ - -The VyOS image-based installation is implemented by creating a directory for -each image on the storage device selected during the install process. - -The directory structure of the boot device: - -.. code-block:: none - - / - /boot - /boot/grub - /boot/1.2.0-rolling+201810021347 - -The image directory contains the system kernel, a compressed image of the root -filesystem for the OS, and a directory for persistent storage, such as -configuration. On boot, the system will extract the OS image into memory and -mount the appropriate live-rw sub-directories to provide persistent storage -system configuration. - -This process allows for a system to always boot to a known working state, as -the OS image is fixed and non-persistent. It also allows for multiple releases -of VyOS to be installed on the same storage device. The image can be selected -manually at boot if needed, but the system will otherwise boot the image -configured to be the default. - -.. opcmd:: show system image - - List all available system images which can be bootet on the current system. - - .. code-block:: none - - vyos@vyos:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.2.0-rolling+201810021347 (default boot) - 2: 1.2.0-rolling+201810021217 - 3: 1.2.0-rolling+201809252218 - - -.. opcmd:: delete system image [image-name] - - Delete no longer needed images from the system. You can specify an optional - image name to delete, the image name can be retrieved via a list of available - images can be shown using the :opcmd:`show system image`. - - .. code-block:: none - - vyos@vyos:~$ delete system image - The following image(s) can be deleted: - - 1: 1.3-rolling-201912181733 (default boot) (running image) - 2: 1.3-rolling-201912180242 - 3: 1.2.2 - 4: 1.2.1 - - Select the image to delete: 2 - - Are you sure you want to delete the - "1.3-rolling-201912180242" image? (Yes/No) [No]: y - Deleting the "1.3-rolling-201912180242" image... - Done - -.. opcmd:: show version - - Show current system image version. - - .. code-block:: none - - vyos@vyos:~$ show version - Version: VyOS 1.3-rolling-201912181733 - Built by: autobuild@vyos.net - Built on: Wed 18 Dec 2019 17:33 UTC - Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c - Build Commit ID: f7ce0d8a692f2d - - Architecture: x86_64 - Boot via: installed image - System type: bare metal - - Hardware vendor: VMware, Inc. - Hardware model: VMware Virtual Platform - Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 - Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 - - Copyright: VyOS maintainers and contributors - - -.. _update_vyos: - -Update VyOS -=========== - -New system images can be added using the :opcmd:`add system image` -command. The command will extract the chosen image and will prompt you -to use the current system configuration and SSH security keys, allowing -for the new image to boot using the current configuration. - -.. note:: Only LTS releases are PGP-signed. - -.. opcmd:: add system image [vrf name] [username user [password pass]] - - Use this command to install a new system image. You can reach the - image from the web (http://, https://) or from your local system, - e.g. /tmp/vyos-1.2.3-amd64.iso. - - The `add system image` command also supports installing new versions - of VyOS through an optional given VRF. Also if URL in question requires - authentication, you can specify an optional username and password via - the commandline which will be passed as "Basic-Auth" to the server. - -If there is not enough **free disk space available**, the installation -will be canceled. To delete images use the :opcmd:`delete system image` -command. - -VyOS configuration is associated to each image, and **each image has a -unique copy of its configuration**. This is different than a traditional -network router where the configuration is shared across all images. - -.. note:: If you have any personal files, like some scripts you created, - and you don't want them to be lost during the upgrade, make sure - those files are stored in ``/config`` as this directory is always copied - to newer installed images. - -You can access files from a previous installation and copy them to your -current image if they were located in the ``/config`` directory. This -can be done using the :opcmd:`copy` command. So, for instance, in order -to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the -following command: - -.. code:: - - copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 - - -Example -""""""" - -.. code-block:: none - - vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 - curl: (22) The requested URL returned error: 404 Not Found - - Unable to fetch digital signature file. - Do you want to continue without signature check? (yes/no) [yes] - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [vyos-1.3-rolling-201912201452]: - - OK. This image will be named: vyos-1.3-rolling-201912201452 - - -.. hint:: | The most up-do-date Rolling Release for AMD64 can be accessed using the following URL: - | https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - -After reboot you might want to verify the version you are running with -the :opcmd:`show version` command. - - -System rollback -=============== - -If you need to rollback to a previous image, you can easily do so. First -check the available images through the :opcmd:`show system image` -command and then select your image with the following command: - -.. opcmd:: set system image default-boot [image-name] - - Select the default boot image which will be started on the next boot - of the system. - -Then reboot the system. - -.. note:: VyOS automatically associates the configuration to the image, - so you don't need to worry about that. Each image has a unique copy - of its configuration. - -If you have access to the console, there is a another way to select -your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/cloud/aws.rst b/docs/installation/cloud/aws.rst new file mode 100644 index 00000000..33684bb0 --- /dev/null +++ b/docs/installation/cloud/aws.rst @@ -0,0 +1,54 @@ +########## +Amazon AWS +########## + +Deploy VM +--------- + +Deploy VyOS on Amazon :abbr:`AWS (Amazon Web Services)` + +1. Click to ``Instances`` and ``Launch Instance`` + +.. figure:: /_static/images/cloud-aws-01.png + +2. On the marketplace search "VyOS" + +.. figure:: /_static/images/cloud-aws-02.png + +3. Choose the instance type. Minimum recommendation start from ``m3.medium`` + +.. figure:: /_static/images/cloud-aws-03.png + +4. Configure instance for your requirements. Select number of instances / network / subnet + +.. figure:: /_static/images/cloud-aws-04.png + +5. Additional storage. You can remove additional storage ``/dev/sdb``. First root device will be ``/dev/xvda``. You can skeep this step. + +.. figure:: /_static/images/cloud-aws-05.png + +6. Configure Security Group. It's recommended that you configure ssh access only from certain address sources. Or permit any (by default). + +.. figure:: /_static/images/cloud-aws-06.png + +7. Select SSH key pair and click ``Launch Instances`` + +.. figure:: /_static/images/cloud-aws-07.png + +8. Find out your public IP address. + +.. figure:: /_static/images/cloud-aws-08.png + +9. Connect to the instance by SSH key. + + .. code-block:: none + + ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3 + vyos@ip-192-0-2-10:~$ + + + + +References +---------- +https://console.aws.amazon.com/ \ No newline at end of file diff --git a/docs/installation/cloud/azure.rst b/docs/installation/cloud/azure.rst new file mode 100644 index 00000000..39206f3b --- /dev/null +++ b/docs/installation/cloud/azure.rst @@ -0,0 +1,53 @@ +##### +Azure +##### + +Deploy VM +--------- + +Deploy VyOS on Azure. + +1. Go to the Azure services and Click to **Add new Virtual machine** + +2. Choose vm name, resource group, region and click **Browse all public and private images** + +.. figure:: /_static/images/cloud-azure-01.png + +3. On the marketplace search ``VyOS`` + +.. figure:: /_static/images/cloud-azure-02.png + +4. Generate new SSH key pair or use existing. + +.. figure:: /_static/images/cloud-azure-03.png + +5. Define network, subnet, Public IP. Or it will be created by default. + +.. figure:: /_static/images/cloud-azure-04.png + +6. Click ``Review + create``. After fiew second your deployment will be complete + +.. figure:: /_static/images/cloud-azure-05.png + +7. Click to your new vm and find out your Public IP address. + +.. figure:: /_static/images/cloud-azure-06.png + +8. Connect to the instance by SSH key. + + .. code-block:: none + + ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3 + vyos@vyos-doc-r1:~$ + +Add interface +------------- + +If instance was deployed with one **eth0** ``WAN`` interface and want to add new one. +To add new interface an example **eth1** ``LAN`` you need shutdown the instance. Attach the interface in the Azure portal and then start the instance. + +.. NOTE:: Azure does not allow you attach interface when the instance in the **Running** state. + +References +---------- +https://azure.microsoft.com diff --git a/docs/installation/cloud/gcp.rst b/docs/installation/cloud/gcp.rst new file mode 100644 index 00000000..66e75704 --- /dev/null +++ b/docs/installation/cloud/gcp.rst @@ -0,0 +1,55 @@ +##################### +Google Cloud Platform +##################### + +Deploy VM +--------- + +To deploy VyOS on GCP (Google Cloud Platform) + +1. Generate SSH key pair type **ssh-rsa** from the host that will connect to VyOS. + + Example: + + .. code-block:: none + + ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" + + +.. NOTE:: In name "vyos@mypc" The first value must be "**vyos**". Because default user is vyos and google api uses this option. + + +2. Open GCP console and navigate to the menu **Metadata**. Choose **SSH Keys** and click ``edit``. + +.. figure:: /_static/images/cloud-gcp-01.png + + +Click **Add item** and paste your public ssh key. Click ``Save``. + +.. figure:: /_static/images/cloud-gcp-02.png + + +2. On marketplace search "VyOS" + +3. Change Deployment name/Zone/Machine type and click ``Deploy`` + +.. figure:: /_static/images/cloud-gcp-03.png + +4. After fiew seconds click to ``instance`` + +.. figure:: /_static/images/cloud-gcp-04.png + +5. Find out your external IP address + +.. figure:: /_static/images/cloud-gcp-05.png + +6. Connect to the instance. SSH key was generated in the first step. + + .. code-block:: none + + ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 + vyos@vyos-r1-vm:~$ + +References +---------- +https://console.cloud.google.com/ \ No newline at end of file diff --git a/docs/installation/cloud/index.rst b/docs/installation/cloud/index.rst new file mode 100644 index 00000000..5236f092 --- /dev/null +++ b/docs/installation/cloud/index.rst @@ -0,0 +1,13 @@ +################################## +Running VyOS in Cloud Environments +################################## + + + +.. toctree:: + :caption: Content + + aws + azure + gcp + oracel \ No newline at end of file diff --git a/docs/installation/cloud/oracel.rst b/docs/installation/cloud/oracel.rst new file mode 100644 index 00000000..72c40127 --- /dev/null +++ b/docs/installation/cloud/oracel.rst @@ -0,0 +1,8 @@ +###### +Oracle +###### + + +References +---------- +https://www.oracle.com/cloud/ \ No newline at end of file diff --git a/docs/installation/image.rst b/docs/installation/image.rst new file mode 100644 index 00000000..074a0245 --- /dev/null +++ b/docs/installation/image.rst @@ -0,0 +1,115 @@ +.. _image-mgmt: + +################ +Image Management +################ + +The VyOS image-based installation is implemented by creating a directory for +each image on the storage device selected during the install process. + +The directory structure of the boot device: + +.. code-block:: none + + / + /boot + /boot/grub + /boot/1.2.0-rolling+201810021347 + +The image directory contains the system kernel, a compressed image of the root +filesystem for the OS, and a directory for persistent storage, such as +configuration. On boot, the system will extract the OS image into memory and +mount the appropriate live-rw sub-directories to provide persistent storage +system configuration. + +This process allows for a system to always boot to a known working state, as +the OS image is fixed and non-persistent. It also allows for multiple releases +of VyOS to be installed on the same storage device. The image can be selected +manually at boot if needed, but the system will otherwise boot the image +configured to be the default. + +.. opcmd:: show system image + + List all available system images which can be bootet on the current system. + + .. code-block:: none + + vyos@vyos:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809252218 + + +.. opcmd:: delete system image [image-name] + + Delete no longer needed images from the system. You can specify an optional + image name to delete, the image name can be retrieved via a list of available + images can be shown using the :opcmd:`show system image`. + + .. code-block:: none + + vyos@vyos:~$ delete system image + The following image(s) can be deleted: + + 1: 1.3-rolling-201912181733 (default boot) (running image) + 2: 1.3-rolling-201912180242 + 3: 1.2.2 + 4: 1.2.1 + + Select the image to delete: 2 + + Are you sure you want to delete the + "1.3-rolling-201912180242" image? (Yes/No) [No]: y + Deleting the "1.3-rolling-201912180242" image... + Done + +.. opcmd:: show version + + Show current system image version. + + .. code-block:: none + + vyos@vyos:~$ show version + Version: VyOS 1.3-rolling-201912181733 + Built by: autobuild@vyos.net + Built on: Wed 18 Dec 2019 17:33 UTC + Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c + Build Commit ID: f7ce0d8a692f2d + + Architecture: x86_64 + Boot via: installed image + System type: bare metal + + Hardware vendor: VMware, Inc. + Hardware model: VMware Virtual Platform + Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 + Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 + + Copyright: VyOS maintainers and contributors + + + + + +System rollback +=============== + +If you need to rollback to a previous image, you can easily do so. First +check the available images through the :opcmd:`show system image` +command and then select your image with the following command: + +.. opcmd:: set system image default-boot [image-name] + + Select the default boot image which will be started on the next boot + of the system. + +Then reboot the system. + +.. note:: VyOS automatically associates the configuration to the image, + so you don't need to worry about that. Each image has a unique copy + of its configuration. + +If you have access to the console, there is a another way to select +your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/index.rst b/docs/installation/index.rst index af265121..e5a2a6fd 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -12,7 +12,8 @@ Installation and Image Management iso virtual/index cloud/index + vyos-on-baremetal update image migrate-from-vyatta - ../vyos-on-baremetal \ No newline at end of file + \ No newline at end of file diff --git a/docs/installation/iso.rst b/docs/installation/iso.rst new file mode 100644 index 00000000..f48ad91c --- /dev/null +++ b/docs/installation/iso.rst @@ -0,0 +1,2 @@ +iso +### \ No newline at end of file diff --git a/docs/installation/migrate-from-vyatta.rst b/docs/installation/migrate-from-vyatta.rst new file mode 100644 index 00000000..f15c3d5a --- /dev/null +++ b/docs/installation/migrate-from-vyatta.rst @@ -0,0 +1,164 @@ +.. _migrate_from_vyatta: + +Migrate from Vyatta Core +======================== + +VyOS 1.x line aims to preserve backward compatibility and provide a safe +upgrade path for existing Vyatta Core users. You may think of VyOS 1.0.0 as +VC7.0. + +Vyatta release compatibility +---------------------------- + +Vyatta Core releases from 6.5 to 6.6 should be 100% compatible. + +Vyatta Core 6.4 and earlier may have incompatibilities. In Vyatta 6.5 the +"modify" firewall was removed and replaced with the ``set policy route`` +command family, old configs can not be automatically converted. You will have +to adapt it to post-6.5 Vyatta syntax manually. + +.. note:: Also, in Vyatta Core 6.5 remote access VPN interfaces have been + renamed from ``pppX`` to ``l2tpX`` and ``pptpX``. If you are using + zone based firewalling in Vyatta Core pre-6.5 versions, make sure to change + interface names in rules for remote access VPN. + +Upgrade procedure +----------------- + +You just use ``add system image``, as if it was a new VC release (see +:ref:`update_vyos` for additional information). The only thing you want to do +is to verify the new images digital signature. You will have to add the public +key manually once as it is not shipped the first time. + +.. code-block:: none + + vyatta@vyatta:~$ wget http://wiki.vyos.net/so3group_maintainers.key + Connecting to vyos.net (x.x.x.x:80) + so3group_maintainers 100% |*************************| 3125 --:--:-- ETA + vyatta@vyatta:~$ sudo apt-key add so3group_maintainers.key + OK + vyatta@vyatta:~$ + +For completion the key below corresponds to the key listed in the URL above. + +.. code-block:: none + + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v1.4.12 (GNU/Linux) + + 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 + Pr6fWpIruuc7Gg9rUF0L + =VQTr + -----END PGP PUBLIC KEY BLOCK----- + +Next add the VyOS image. + +This example uses VyOS 1.0.0, however, it's better to install the latest +release. + +.. code-block:: none + + vyatta@vyatta:~$ show system image + The system currently has the following image(s) installed: + 1: VC6.6R1 (default boot) (running image) + + vyatta@vyatta:~$ add system image https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso + Trying to fetch ISO file from https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 223M 100 223M 0 0 960k 0 0:03:57 0:03:57 --:--:-- 657k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 836 100 836 0 0 4197 0 --:--:-- --:--:-- --:--:-- 4287 + Found it. Checking digital signature... + gpg: directory `/root/.gnupg' created + gpg: new configuration file `/root/.gnupg/gpg.conf' created + gpg: WARNING: options in `/root/.gnupg/gpg.conf' are not yet active during this run + gpg: keyring `/root/.gnupg/pubring.gpg' created + gpg: Signature made Sun Dec 22 16:51:42 2013 GMT using RSA key ID A442E6E9 + gpg: /root/.gnupg/trustdb.gpg: trustdb created + gpg: Good signature from "SO3 Group Maintainers " + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: DD5B B405 35E7 F6E3 4278 1ABF B744 E25A A442 E6E9 + Digital signature is valid. + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [1.0.0]: [return] + OK. This image will be named: 1.0.0 + Installing "1.0.0" image. + Copying new release files... + + Would you like to save the current configuration + directory and config file? (Yes/No) [Yes]: [return] + Copying current configuration... + + Would you like to save the SSH host keys from your + current configuration? (Yes/No) [Yes]: [return] + Copying SSH keys... + Setting up grub configuration... + Done. + + vyatta@vyatta:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.0.0 (default boot) + 2: VC6.6R1 (running image) + +Upon reboot, you should have a working installation of VyOS. + +You can go back to your Vyatta install using the ``set system image +default-boot`` command and selecting the your previous Vyatta Core image. + +.. note:: Future releases of VyOS will break the direct upgrade path from + Vyatta core. Please upgrade through an intermediate VyOS version e.g. VyOS + 1.2. After this you can continue upgrading to newer releases once you bootet + into VyOS 1.2 once. diff --git a/docs/installation/upate.rst b/docs/installation/upate.rst new file mode 100644 index 00000000..a3a887f0 --- /dev/null +++ b/docs/installation/upate.rst @@ -0,0 +1,79 @@ +.. _update_vyos: + +Update VyOS +=========== + +New system images can be added using the :opcmd:`add system image` +command. The command will extract the chosen image and will prompt you +to use the current system configuration and SSH security keys, allowing +for the new image to boot using the current configuration. + +.. note:: Only LTS releases are PGP-signed. + +.. opcmd:: add system image [vrf name] [username user [password pass]] + + Use this command to install a new system image. You can reach the + image from the web (http://, https://) or from your local system, + e.g. /tmp/vyos-1.2.3-amd64.iso. + + The `add system image` command also supports installing new versions + of VyOS through an optional given VRF. Also if URL in question requires + authentication, you can specify an optional username and password via + the commandline which will be passed as "Basic-Auth" to the server. + +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the :opcmd:`delete system image` +command. + +VyOS configuration is associated to each image, and **each image has a +unique copy of its configuration**. This is different than a traditional +network router where the configuration is shared across all images. + +.. note:: If you have any personal files, like some scripts you created, + and you don't want them to be lost during the upgrade, make sure + those files are stored in ``/config`` as this directory is always copied + to newer installed images. + +You can access files from a previous installation and copy them to your +current image if they were located in the ``/config`` directory. This +can be done using the :opcmd:`copy` command. So, for instance, in order +to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the +following command: + +.. code:: + + copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 + + +Example +""""""" + +.. code-block:: none + + vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 + curl: (22) The requested URL returned error: 404 Not Found + + Unable to fetch digital signature file. + Do you want to continue without signature check? (yes/no) [yes] + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [vyos-1.3-rolling-201912201452]: + + OK. This image will be named: vyos-1.3-rolling-201912201452 + + +.. hint:: | The most up-do-date Rolling Release for AMD64 can be accessed using the following URL: + | https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + +After reboot you might want to verify the version you are running with +the :opcmd:`show version` command. \ No newline at end of file diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst new file mode 100644 index 00000000..d5134838 --- /dev/null +++ b/docs/installation/virtual/eve-ng.rst @@ -0,0 +1,8 @@ +###### +EVE-NG +###### + +References +========== + +https://www.eve-ng.net/ \ No newline at end of file diff --git a/docs/installation/virtual/gns3.rst b/docs/installation/virtual/gns3.rst new file mode 100644 index 00000000..93ea9ae2 --- /dev/null +++ b/docs/installation/virtual/gns3.rst @@ -0,0 +1,176 @@ +.. _vyos-on-gns3: + +############### +Running on GNS3 +############### + +Sometimes you may want to test VyOS in a lab environment. +`GNS3 `__ is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +Requirements +------------ + +The following items are required: + +* A VyOS installation image (.iso file). + `Here `__ you + can find how to get it. + +* A working GNS3 installation. For further information see the + `GNS3 documentation `__. + +.. _vm_setup: + +VM setup +-------- + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +.. figure:: /_static/images/gns3-01.png + +Select **Quemu VMs** and then click on the ``New`` button. + +.. figure:: /_static/images/gns3-02.png + +Write a name for your VM, for instance "VyOS", and click ``Next``. + +.. figure:: /_static/images/gns3-03.png + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click ``Next``. + +.. figure:: /_static/images/gns3-04.png + +Select **telnet** as your console type and click ``Next``. + +.. figure:: /_static/images/gns3-05.png + +Select **New image** for the base disk image of your VM and click +``Create``. + +.. figure:: /_static/images/gns3-06.png + +Use the defaults in the **Binary and format** window and click +``Next``. + +.. figure:: /_static/images/gns3-07.png + +Use the defaults in the **Qcow2 options** window and click ``Next``. + +.. figure:: /_static/images/gns3-08.png + +Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu +image creator**. + +.. figure:: /_static/images/gns3-09.png + +Click ``Finish`` to end the **New QEMU VM template** wizard. + +.. figure:: /_static/images/gns3-10.png + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the ``Edit`` button. + +.. figure:: /_static/images/gns3-11.png + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +* Click on the ``Browse...`` button to choose the **Symbol** you want to + have representing your VM. +* In **Category** select in which group you want to find your VM. +* Set the **Boot priority** to **CD/DVD-ROM**. + +.. figure:: /_static/images/gns3-12.png + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +.. figure:: /_static/images/gns3-13.png + +At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image +you want to install. + +.. figure:: /_static/images/gns3-14.png + +.. note:: You probably will want to accept to copy the .iso file to your + default image directory when you are asked. + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +.. figure:: /_static/images/gns3-15.png + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click ``OK``, which will save and close the **QEMU VM template +configuration** window. + +.. figure:: /_static/images/gns3-16.png + +At the general **Preferences** window, click ``OK`` to save and close. + +.. figure:: /_static/images/gns3-17.png + + +.. _vyos_installation: + +VyOS installation +----------------- + +* Create a new project. +* Drag the newly created VyOS VM into it. +* Start the VM. +* Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +* `Install VyOS `__ + as normal (that is, using the ``install image`` command). + +* After a successful installation, shutdown the VM with the ``poweroff`` + command. + +* **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +.. _vyos_vm_configuration: + +VyOS VM configuration +--------------------- + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +.. figure:: /_static/images/gns3-20.png + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +.. figure:: /_static/images/gns3-21.png + +Set the number of required network adapters, for example **4**. + +.. figure:: /_static/images/gns3-215.png + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click ``OK`` to save the changes. + +.. figure:: /_static/images/gns3-22.png + +The VyOS VM is now ready to be deployed. + diff --git a/docs/installation/virtual/index.rst b/docs/installation/virtual/index.rst new file mode 100644 index 00000000..808439c7 --- /dev/null +++ b/docs/installation/virtual/index.rst @@ -0,0 +1,12 @@ +#################################### +Running VyOS in Virtual Environments +#################################### + +.. toctree:: + :caption: Content + + libvirt + proxmox + vmware + gns3 + eve-ng \ No newline at end of file diff --git a/docs/installation/virtual/libvirt.rst b/docs/installation/virtual/libvirt.rst new file mode 100644 index 00000000..0d624b94 --- /dev/null +++ b/docs/installation/virtual/libvirt.rst @@ -0,0 +1,160 @@ +.. _libvirt: + +*************************** +Running on Libvirt Qemu/KVM +*************************** + +Libvirt is an open-source API, daemon and management tool for managing platform virtualization. +There are several ways to deploy VyOS on libvirt kvm. Use Virt-manager and native CLI. +In an example we will be use use 4 gigabytes of memory, 2 cores CPU and default network virbr0. + +CLI +=== + +Deploy from ISO +--------------- + +Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, the disk ``qcow2`` will be created automatically. +The ``default`` network is the virtual network (type Virtio) created by the hypervisor with NAT. + +.. code-block:: none + + $ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r1`` + +.. code-block:: none + + $ virsh console vyos_r1 + + Connected to domain vyos_r1 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ install image + +After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. + +Deploy from qcow2 +----------------- +The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + +Create VM with ``import`` qcow2 disk option. + +.. code-block:: none + + $ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r2`` + +.. code-block:: none + + $ virsh console vyos_r2 + + Connected to domain vyos_r2 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ + +The system is fully operational. + +Virt-manager +============ +The virt-manager application is a desktop user interface for managing virtual machines through libvirt. +On the linux open :abbr:`VMM (Virtual Machine Manager)`. + +Deploy from ISO +--------------- + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` + +2. Choose ``Local install media`` (ISO) + +.. figure:: /_static/images/virt-libvirt-01.png + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Disk size + +.. figure:: /_static/images/virt-libvirt-04.png + +6. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +7. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-06.png + +Deploy from qcow2 +----------------- + +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` + +2. Choose ``Import existing disk`` image + +.. figure:: /_static/images/virt-libvirt-qc-01.png + +3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously downloaded . Operation System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-qc-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +6. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-qc-03.png + + + diff --git a/docs/installation/virtual/proxmox.rst b/docs/installation/virtual/proxmox.rst new file mode 100644 index 00000000..3ee9d70a --- /dev/null +++ b/docs/installation/virtual/proxmox.rst @@ -0,0 +1,8 @@ +####### +Proxmox +####### + +References +========== + +https://www.proxmox.com/en/proxmox-ve \ No newline at end of file diff --git a/docs/installation/virtual/vmware.rst b/docs/installation/virtual/vmware.rst new file mode 100644 index 00000000..c4299cbf --- /dev/null +++ b/docs/installation/virtual/vmware.rst @@ -0,0 +1,32 @@ +.. _vyosonvmware: + +Running on VMware ESXi +###################### + +ESXi 5.5 or later +***************** + +.ova files are available for supporting users, and a VyOS can also be stood up using a generic Linux instance, and attaching the bootable ISO file and installing from the ISO +using the normal process around `install image`. + +.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been advised. + +Memory Contention Considerations +-------------------------------- +When the underlying ESXi host is approaching ~92% memory utilisation it will start the balloon process in s a 'soft' state to start reclaiming memory from guest operating systems. +This causes an artificial pressure using the vmmemctl driver on memory usage on the virtual guest. As VyOS by default does not have a swap file, this vmmemctl pressure is unable to +force processes to move in memory data to the paging file, and blindly consumes memory forcing the virtual guest into a low memory state with no way to escape. The balloon can expand to 65% of +guest allocated memory, so a VyOS guest running >35% of memory usage, can encounter an out of memory situation, and trigger the kernel oom_kill process. At this point a weighted +lottery favouring memory hungry processes will be run with the unlucky winner being terminated by the kernel. + +It is advised that VyOS routers are configured in a resource group with adequate memory reservations so that ballooning is not inflicted on virtual VyOS guests. + + + + + +References +---------- + +https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html + diff --git a/docs/installation/vyos-on-baremetal.rst b/docs/installation/vyos-on-baremetal.rst new file mode 100644 index 00000000..db618431 --- /dev/null +++ b/docs/installation/vyos-on-baremetal.rst @@ -0,0 +1,411 @@ +.. _vyosonbaremetal: + +##################### +Running on Bare Metal +##################### + +Supermicro A2SDi (Atom C3000) +============================= + +I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. +Running VyOS on an UEFI only device is supported as of VyOS release 1.2. + +Shopping Cart +------------- + +* 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) +* 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) +* 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN + with Intel C3000 SoC 1GbE) +* 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) +* 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) +* 1x Supermicro MCP-320-81302-0B (optional FAN tray) + +Optional (10GE) +--------------- +If you want to get additional ethernet ports or even 10GE connectivity +the following optional parts will be required: + +* 1x Supermicro RSC-RR1U-E8 (Riser Card) +* 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) + +Latest VyOS rolling releases boot without any problem on this board. You also +receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no +information about `OpenBMC `_ so far on this +motherboard). + +Pictures +-------- + +.. figure:: /_static/images/1u_vyos_back.jpg + :scale: 25 % + :alt: CSE-505-203B Back + +.. figure:: /_static/images/1u_vyos_front.jpg + :scale: 25 % + :alt: CSE-505-203B Front + +.. figure:: /_static/images/1u_vyos_front_open_1.jpg + :scale: 25 % + :alt: CSE-505-203B Open 1 + +.. figure:: /_static/images/1u_vyos_front_open_2.jpg + :scale: 25 % + :alt: CSE-505-203B Open 2 + +.. figure:: /_static/images/1u_vyos_front_open_3.jpg + :scale: 25 % + :alt: CSE-505-203B Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 1 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 2 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open + + +.. _pc-engines-apu4: + +PC Engines APU4 +================ + +As this platform seems to be quite common in terms of noise, cost, power and +performance it makes sense to write a small installation manual. + +This guide was developed using an APU4C4 board with the following specs: + +* AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI + support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. +* 4 GB DDR3-1333 DRAM, with optional ECC support +* About 6 to 10W of 12V DC power depending on CPU load +* 2 miniPCI express (one with SIM socket for 3G modem). +* 4 Gigabit Ethernet channels using Intel i211AT NICs + +The board can be powered via 12V from the front or via a 5V onboard connector. + +Shopping Cart +------------- + +* 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM +* 1x Kingston SUV500MS/120G +* 1x VARIA Group Item 326745 19" dual rack for APU4 + +The 19" enclosure can accommodate up to two APU4 boards - there is a single and +dual front cover. + +Extension Modules +^^^^^^^^^^^^^^^^^ + +WiFi +"""" + +Refer to :ref:`wireless-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform: + +* Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. + +WWAN +"""" + +Refer to :ref:`wwan-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform using VyOS 1.3 (equuleus): + +* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +* Huawei ME909u-521 miniPCIe card (LTE) + +VyOS 1.2 (crux) +--------------- + +Depending on the VyOS versions you intend to install there is a difference in +the serial port settings (:vytask:`T1327`). + +Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. + +Connect serial port to a PC through null modem cable (RXD / TXD crossed over). +Set terminal emulator to 115200 8N1. + +.. code-block:: none + + PC Engines apu4 + coreboot build 20171130 + BIOS version v4.6.4 + 4080 MB ECC DRAM + SeaBIOS (version rel-1.11.0.1-0-g90da88d) + + Press F10 key now for boot menu: + + Select boot device: + + 1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) + 2. USB MSC Drive Generic Flash Disk 8.07 + 3. Payload [memtest] + 4. Payload [setup] + +Now boot from the ``USB MSC Drive Generic Flash Disk 8.07`` media by pressing +``2``, the VyOS boot menu will appear, just wait 10 seconds or press ``Enter`` +to continue. + +.. code-block:: none + + lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk + x VyOS - Boot Menu x + tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu + x Live (amd64-vyos) x + x Live (amd64-vyos failsafe) x + x x + mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj + +The image will be loaded and the last lines you will get will be: + +.. code-block:: none + + Loading /live/vmlinuz... ok + Loading /live/initrd.img... + +The Kernel will now spin up using a different console setting. Set terminal +emulator to 9600 8N1 and after a while your console will show: + +.. code-block:: none + + Loading /live/vmlinuz... ok + Loading /live/initrd.img... + Welcome to VyOS - vyos ttyS0 + + vyos login: + +You can now proceed with a regular image installation as described in +:ref:`installation`. + +As the APU board itself still used a serial setting of 115200 8N1 it is +strongly recommended that you change the VyOS serial interface settings after +your first successful boot. + +Use the following command to adjust the :ref:`serial-console` settings: + +.. code-block:: none + + set system console device ttyS0 speed 115200 + +.. note:: Once you ``commit`` the above changes access to the serial interface + is lost until you set your terminal emulator to 115200 8N1 again. + +.. code-block:: none + + vyos@vyos# show system console + device ttyS0 { + speed 115200 + } + +VyOS 1.2 (rolling) +------------------ + +Installing the rolling release on an APU2 board does not require any change +on the serial console from your host side as :vytask:`T1327` was successfully +implemented. + +Simply proceed with a regular image installation as described in +:ref:`installation`. + +Pictures +-------- + +.. note:: Both device types operate without any moving parts and emit zero + noise. + +Rack Mount +^^^^^^^^^^ + +.. figure:: /_static/images/apu4_rack_1.jpg + :scale: 25 % + :alt: APU4 rack closed + +.. figure:: /_static/images/apu4_rack_2.jpg + :scale: 25 % + :alt: APU4 rack front + +.. figure:: /_static/images/apu4_rack_3.jpg + :scale: 25 % + :alt: APU4 rack module #1 + +.. figure:: /_static/images/apu4_rack_4.jpg + :scale: 25 % + :alt: APU4 rack module #2 + +.. figure:: /_static/images/apu4_rack_5.jpg + :scale: 25 % + :alt: APU4 rack module #3 with PSU + +VyOS custom print +""""""""""""""""" + +.. figure:: /_static/images/apu4_rack_vyos_print.jpg + :scale: 25 % + :alt: APU4 custom VyOS powder coat + +Desktop / Bench Top +^^^^^^^^^^^^^^^^^^^ + +.. figure:: /_static/images/apu4_desk_1.jpg + :scale: 25 % + :alt: APU4 desktop closed + +.. figure:: /_static/images/apu4_desk_2.jpg + :scale: 25 % + :alt: APU4 desktop closed + +.. figure:: /_static/images/apu4_desk_3.jpg + :scale: 25 % + :alt: APU4 desktop back + +.. figure:: /_static/images/apu4_desk_4.jpg + :scale: 25 % + :alt: APU4 desktop back + +.. _Rufus: https://rufus.ie/ + +Qotom Q355G4 +============ + +The install on this Q355G4 box is pretty much plug and play. The port numbering +the OS does might differ from the labels on the outside, but the UEFI firmware +has a port blink test built in with MAC addresses so you can very quickly +identify which is which. MAC labels are on the inside as well, and this test +can be done from VyOS or plain Linux too. Default settings in the UEFI will +make it boot, but depending on your installation wishes (i.e. storage type, +boot type, console type) you might want to adjust them. This Qotom company +seems to be the real OEM/ODM for many other relabelling companies like +Protectli. + +Hardware +-------- + +There are a number of other options, but they all seem to be close to Intel +reference designs, with added features like more serial ports, more network +interfaces and the likes. Because they don't deviate too much from standard +designs all the hardware is well-supported by mainline. It accepts one LPDDR3 +SO-DIMM, but chances are that if you need more than that, you'll also want +something even beefier than an i5. There are options for antenna holes, and SIM +slots, so you could in theory add an LTE/Cell modem (not tested so far). + +The chassis is a U-shaped alu extrusion with removable I/O plates and removable +bottom plate. Cooling is completely passive with a heatsink on the SoC with +internal and external fins, a flat interface surface, thermal pad on top of +that, which then directly attaches to the chassis, which has fins as well. It +comes with mounting hardware and rubber feet, so you could place it like a +desktop model or mount it on a VESA mount, or even wall mount it with the +provided mounting plate. The closing plate doubles as internal 2.5" mounting +place for an HDD or SSD, and comes supplied with a small SATA cable and SATA +power cable. + +Power supply is a 12VDC barrel jack, and included switching power supply, which +is why SATA power regulation is on-board. Internally it has a NUC-board-style +on-board 12V input header as well, the molex locking style. + +There are WDT options and auto-boot on power enable, which is great for remote +setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled +in enforcement mode, which is good but also means no coreboot option), yet has +most options available to configure (so it's not locked out like most firmwares +are). + +An external RS232 serial port is available, internally a GPIO header as well. +It does have Realtek based audio on board for some reason, but you can disable +that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS +mode and HDMI BIOS mode depends on what is connected at startup; it goes into +serial mode if you disconnect HDMI and plug in serial, in all other cases it's +HDMI mode. + +Partaker i5 +=========== + +.. figure:: ../_static/images/600px-Partaker-i5.jpg + +I believe this is actually the same hardware as the Protectli. I purchased it +in June 2018. It came pre-loaded with pfSense. + +`Manufacturer product page `_. + +Installation +------------ + +* Write VyOS ISO to USB drive of some sort +* Plug in VGA, power, USB keyboard, and USB drive +* Press "SW" button on the front (this is the power button; I don't know what + "SW" is supposed to mean). +* Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, + but with a few tries you should be able to get into the BIOS. +* Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 + (EHCI) to Enabled. Without doing this, the USB drive won't boot. +* Boot to the VyOS installer and install as usual. + +Warning the interface labels on my device are backwards; the left-most "LAN4" +port is eth0 and the right-most "LAN1" port is eth3. + +Acrosser AND-J190N1 +=================== + +.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg + +.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg + +This microbox network appliance was build to create OpenVPN bridges. It can +saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN +http://www.acrosser.com/upload/AND-J190_J180N1-2.pdf + +You may have to add your own RAM and HDD/SSD. There is no VGA connector. But +Acrosser provides a DB25 adapter for the VGA header on the motherboard (not +used). + +BIOS Settings: +-------------- + +First thing you want to do is getting a more user friendly console to configure +BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. + +For practical issues change speed from 115200 to 9600. 9600 is the default +speed at which both linux kernel and VyOS will reconfigure the serial port +when loading. + +Connect to serial (115200bps). Power on the appliance and press Del in the +console when requested to enter BIOS settings. + +Advanced > Serial Port Console Redirection > Console Redirection Settings: + +* Terminal Type : VT100+ +* Bits per second : 9600 + +Save, reboot and change serial speed to 9600 on your client. + +Some options have to be changed for VyOS to boot correctly. With XHCI enabled +the installer can’t access the USB key. Enable EHCI instead. + +Reboot into BIOS, Chipset > South Bridge > USB Configuration: + +* Disable XHCI +* Enable USB 2.0 (EHCI) Support + +Install VyOS: +------------- + +Create a VyOS bootable USB key. I used the 64-bit ISO (VyOS 1.1.7) and +`LinuxLive USB Creator `_. + +I'm not sure if it helps the process but I changed default option to live-serial +(line “default xxxx”) on the USB key under syslinux/syslinux.cfg. + +I connected the key to one black USB port on the back and powered on. The first +VyOS screen has some readability issues. Press :kbd:`Enter` to continue. + +Then VyOS should boot and you can perform the ``install image`` -- cgit v1.2.3