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/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 +++++++ 6 files changed, 396 insertions(+) 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 (limited to 'docs/installation/virtual') 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 + -- cgit v1.2.3