6 files changed, 417 insertions, 0 deletions
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..e9977f0f
--- /dev/null
+++ b/docs/installation/virtual/gns3.rst
@@ -0,0 +1,175 @@
+.. _vyos-on-gns3:
+
+###############
+Running on GNS3
+###############
+
+Sometimes you may want to test VyOS in a lab environment.
+`GNS3 <http://www.gns3.com>`__ 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). You
+  can find how to get it on the :ref:`installation` page
+
+* A working GNS3 installation. For further information see the
+  `GNS3 documentation <https://docs.gns3.com/>`__.
+
+.. _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 <https://docs.vyos.io/en/latest/install.html#install>`__
+  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..ff896d07
--- /dev/null
+++ b/docs/installation/virtual/libvirt.rst
@@ -0,0 +1,168 @@
+.. _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..28614573
--- /dev/null
+++ b/docs/installation/virtual/vmware.rst
@@ -0,0 +1,46 @@
+.. _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
+----------
+
+.. stop_vyoslinter
+
+https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html
+
+.. start_vyoslinter
+\ No newline at end of file