Migrate new file structure to crux (#435)

* order workflows and add submodule

* rename gitmodules file

* delete docs/.gitignore

* add vyos custom linter

* correct __pycache__ in gitignore

* add test-coverage.py

* move draw.io folder

* arrange changelog, install history and about

* arrange: firewall

* arrange: highavailability

* arrange: loadbalancing

* arrange: nat

* arrange: services

* sort configexamples and configuration interfaces

* wireles: rename wireless

* rearrange: Protocols and Policy

* rearrange: Firewall and Zone Policy

* rearrange: Interfaces

* rearrange: Interfaces

* rearrange: dynamic DNS

* hostinfo: add page to index

* rearrange: appendix

* venv: add Pipfile

* rearrange: contributing

* index: remove debugging

* rearrange: fix all figure and refs

* rearrange: commandtree

* fix: cli, openvpn, install headline level

* protocols: change headline

* firewall: move mss clamping

* ip: separate ipv4 and ipv6

* arp: move to static page

* igmp: rename multicast page

* Update to year 2021

10 files changed, 1494 insertions, 0 deletions

diff --git a/docs/installation/cloud/index.rst b/docs/installation/cloud/index.rst
new file mode 100644
index 00000000..f6060762
--- /dev/null
+++ b/docs/installation/cloud/index.rst
@@ -0,0 +1,9 @@
+##################################
+Running VyOS in Cloud Environments
+##################################
+
+
+
+.. toctree::
+   :caption: Content
+
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
new file mode 100644
index 00000000..187f3bf1
--- /dev/null
+++ b/docs/installation/index.rst
@@ -0,0 +1,17 @@
+#################################
+Installation and Image Management
+#################################
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Content
+
+   install
+   virtual/index
+   cloud/index
+   vyos-on-baremetal
+   update
+   image
+   migrate-from-vyatta
\ No newline at end of file
diff --git a/docs/installation/install.rst b/docs/installation/install.rst
new file mode 100644
index 00000000..8b567752
--- /dev/null
+++ b/docs/installation/install.rst
@@ -0,0 +1,514 @@
+.. _installation:
+
+############
+Installation
+############
+
+VyOS installation requires to download a VyOS .iso file. That file is
+a live install image that lets you boot a live VyOS. From that live
+system you can proceed to the permanent installation on a hard drive or
+any other type of storage.
+
+
+Hardware requirements
+=====================
+
+The minimum system requirements are 512 MiB RAM and 2 GiB storage.
+Depending on your use you might need additional RAM and CPU resources e.g.
+when having multiple BGP full tables in your system.
+
+Download
+========
+
+Registered Subscribers
+----------------------
+
+Registered subscribers can log into https://support.vyos.io/ to have access to
+a variety of different downloads via the "Downloads" link. These downloads
+include LTS (Long-Term-Support) and associated hot-fix releases, early public
+access releases, pre-built VM images, as well as device specific installation
+ISOs.
+
+.. figure:: /_static/images/vyos-downloads.png
+
+Building from source
+----------------------
+
+Non-subscribers can always get the LTS release by building it from source.
+Instruction can be found in the :ref:`build` section of this manual. VyOS
+source code repository is available for everyone at
+https://github.com/vyos/vyos-build.
+
+Rolling Release
+---------------
+
+Everyone can download bleeding-edge VyOS rolling images from:
+https://downloads.vyos.io/
+
+.. note:: Rolling releases contain all the latest enhancements and fixes. This
+   means that there will be new bugs of course. If you think you hit a bug
+   please follow the guide at :ref:`issues_features`. To improve VyOS we depend on
+   your feedback!
+
+The following link will always fetch the most recent VyOS build for AMD64
+systems from the current branch:
+https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso
+
+
+Download Verification
+---------------------
+
+LTS images are signed by VyOS lead package-maintainer private key. With
+the official public key, the authenticity of the package can be
+verified. :abbr:`GPG (GNU Privacy Guard)` is used for verification.
+
+.. note:: This subsection only applies e applies to LTS images, for
+   Rolling images please jump to :ref:`live_installation`.
+
+Preparing for the verification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First, install GPG or another OpenPGP implementation. On most GNU+Linux
+distributions it is installed by default as package managers use it to
+verify package signatures. If not pre-installed, it will need to be
+downloaded and installed.
+
+The official VyOS public key can be retrieved in a number of ways. Skip
+to :ref:`gpg-verification` if the key is already present.
+
+It can be retrieved directly from a key server:
+
+``gpg --recv-keys FD220285A0FE6D7E``
+
+Or it can be accessed via a web browser:
+
+https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E
+
+Or from the following block:
+
+.. code-block:: none
+
+  -----BEGIN PGP PUBLIC KEY BLOCK-----
+  Version: GnuPG v1.4.12 (GNU/Linux)
+
+  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
+  8vzPzaWHhkOkU8/J/Ci7+vNtUOZb
+  =Ld8S
+  -----END PGP PUBLIC KEY BLOCK-----
+
+Store the key in a new text file and import it into GPG via: ``gpg --import
+file_with_the_public_key``
+
+The import can be verified with:
+
+.. code-block:: none
+
+  $ gpg --list-keys
+  ...
+  pub   rsa4096 2015-08-12 [SC]
+      0694A9230F5139BF834BA458FD220285A0FE6D7E
+  uid           [ unknown] VyOS Maintainers (VyOS Release) <maintainers@vyos.net>
+  sub   rsa4096 2015-08-12 [E]
+
+.. _gpg-verification:
+
+GPG verification
+^^^^^^^^^^^^^^^^
+
+With the public key imported, the signature for the desired image needs
+to be downloaded.
+
+.. note:: The signature can be downloaded by appending `.asc` to the URL of the
+   downloaded VyOS image. That small *.asc* file is the signature for the
+   associated image.
+
+Finally, verify the authenticity of the downloaded image:
+
+.. code-block:: none
+
+  $ gpg2 --verify vyos-1.2.1-amd64.iso.asc  vyos-1.2.1-amd64.iso
+  gpg: Signature made So 14 Apr 12:58:07 2019 CEST
+  gpg:                using RSA key FD220285A0FE6D7E
+  gpg: Good signature from "VyOS Maintainers (VyOS Release) <maintainers@vyos.net>" [unknown]
+  Primary key fingerprint: 0694 A923 0F51 39BF 834B  A458 FD22 0285 A0FE 6D7E
+
+.. _live_installation:
+
+Live installation
+=================
+
+.. note:: A permanent VyOS installation always requires to go first
+   through a live installation.
+
+VyOS, as other GNU+Linux distributions, can be tasted without installing
+it in your hard drive. **With your downloaded VyOS .iso file you can
+create a bootable USB drive that will let you boot into a fully
+functional VyOS system**. Once you have tested it, you can either decide
+to begin a :ref:`permanent_installation` in your hard drive or power
+your system off, remove the USB drive, and leave everythng as it was. 
+
+
+If you have a GNU+Linux system, you can create your VyOS bootable USB
+stick with with the ``dd`` command:
+
+ 1. Open your terminal emulator.
+
+ 2. Find out the device name of your USB drive (you can use the ``lsblk``
+    command)
+
+ 3. Unmount the USB drive. Replace X in the example below with the
+    letter of your device and keep the asterisk (wildcard) to unmount
+    all partitions.
+
+ .. code-block:: none
+ 
+  $ umount /dev/sdX* 
+
+ 4. Write the image (your VyOS .iso file) to the USB drive.
+    Note that here you want to use the device name (e.g. /dev/sdb), not
+    the partition name (e.g. /dev/sdb1).
+
+  **Warning**: This will destroy all data on the USB drive!
+
+ .. code-block:: none
+ 
+   # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync
+
+ 5. Wait until you get the outcome (bytes copied). Be patient, in some
+    computers it might take more than one minute.
+
+ 6. Once ``dd`` has finished, pull the USB drive out and plug it into
+    the powered-off computer where you want to install (or test) VyOS.
+
+ 7. Power the computer on, making sure it boots from the USB drive (you
+    might need to select booting device or change booting settings).
+
+ 8. Once VyOS is completely loaded, enter the default credentials
+    (login: vyos, password: vyos).
+
+
+If you find difficulties with this method, prefer to use a GUI program,
+or have a different operating system, there are other programs you can
+use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux,
+macOS and Windows), Rufus_ (for Windows) and `many others`_. You can
+follow their instructions to create a bootable USB drive from an .iso
+file.
+
+.. hint:: The default username and password for the live system is *vyos*.
+
+
+.. _permanent_installation:
+
+Permanent installation
+======================
+
+.. note:: Before a permanent installation, VyOS requires a :ref:`live_installation`.
+
+Unlike general purpose Linux distributions, VyOS uses "image installation" that
+mimics the user experience of traditional hardware routers and allows keeping
+multiple VyOS versions installed simultaneously. This makes it possible to
+switch to a previous version if something breaks or miss-behaves after an image
+upgrade.
+
+Every version is contained in its own squashfs image that is mounted in a union
+filesystem together with a directory for mutable data such as configurations,
+keys, or custom scripts.
+
+.. note:: Older versions (prior to VyOS 1.1) used to support non-image
+   installation (``install system`` command). Support for this has been removed
+   from VyOS 1.2 and newer releases. Older releases can still be upgraded via
+   the general ``add system image <image_path>`` upgrade command (consult
+   :ref:`image-mgmt` for further information).
+
+
+In order to proceed with a permanent installation:
+
+ 1. Log into the VyOS live system (use the default credentials: vyos,
+    vyos)
+
+ 2. Run the ``install image`` command and follow the wizard:
+
+ .. code-block:: none
+
+   vyos@vyos:~$ install image
+   Welcome to the VyOS install program.  This script
+   will walk you through the process of installing the
+   VyOS image to a local hard drive.
+   Would you like to continue? (Yes/No) [Yes]: Yes
+   Probing drives: OK
+   Looking for pre-existing RAID groups...none found.
+   The VyOS image will require a minimum 2000MB root.
+   Would you like me to try to partition a drive automatically
+   or would you rather partition it manually with parted?  If
+   you have already setup your partitions, you may skip this step
+   
+   Partition (Auto/Parted/Skip) [Auto]:
+   
+   I found the following drives on your system:
+    sda    4294MB
+   
+   Install the image on? [sda]:
+   
+   This will destroy all data on /dev/sda.
+   Continue? (Yes/No) [No]: Yes
+   
+   How big of a root partition should I create? (2000MB - 4294MB) [4294]MB:
+   
+   Creating filesystem on /dev/sda1: OK
+   Done!
+   Mounting /dev/sda1...
+   What would you like to name this image? [1.2.0-rolling+201809210337]:
+   OK.  This image will be named: 1.2.0-rolling+201809210337
+   Copying squashfs image...
+   Copying kernel and initrd images...
+   Done!
+   I found the following configuration files:
+       /opt/vyatta/etc/config.boot.default
+   Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]:
+   
+   Copying /opt/vyatta/etc/config.boot.default to sda.
+   Enter password for administrator account
+   Enter password for user 'vyos':
+   Retype password for user 'vyos':
+   I need to install the GRUB boot loader.
+   I found the following drives on your system:
+    sda    4294MB
+   
+   Which drive should GRUB modify the boot partition on? [sda]:
+   
+   Setting up grub: OK
+   Done!
+
+
+ 3. After the installation is complete, remove the live USB stick or
+    CD.
+
+ 4. Reboot the system.
+
+ .. code-block:: none
+
+  vyos@vyos:~$ reboot
+  Proceed with reboot? (Yes/No) [No] Yes
+
+ You will boot now into a permanent VyOS system.
+
+
+PXE Boot
+========
+
+VyOS can also be installed through PXE. This is a more complex
+installation method which allows deploying VyOS through the network.
+
+**Requirements**
+
+* Clients (where VyOS is to be installed) with a PXE-enabled NIC
+* DHCP Server 
+* TFTP Server
+* Webserver (HTTP) - optional, but we will use it to speed up installation
+* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3)
+* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution <https://kernel.org/pub/linux/utils/boot/syslinux/>`_
+
+Configuration
+-------------
+
+Step 1: DHCP
+^^^^^^^^^^^^
+
+Configure a DHCP server to provide the client with:
+
+* An IP address
+* The TFTP server address (DHCP option 66). Sometimes referred as *boot server*
+* The *bootfile name* (DHCP option 67), which is *pxelinux.0*
+
+In this example we configured an existent VyOS as the DHCP server:
+
+.. code-block:: none
+
+  vyos@vyos# show service dhcp-server
+   shared-network-name mydhcp {
+       subnet 192.168.1.0/24 {
+           bootfile-name pxelinux.0
+           bootfile-server 192.168.1.50
+           default-router 192.168.1.50
+           range 0 {
+               start 192.168.1.70
+               stop 192.168.1.100
+           }
+       }
+   }
+
+.. _install_from_tftp:
+
+Step 2: TFTP
+^^^^^^^^^^^^
+
+Configure a TFTP server so that it serves the following:
+
+* The *pxelinux.0* file from the Syslinux distribution
+* The *ldlinux.c32* file from the Syslinux distribution
+* The kernel of the VyOS software you want to deploy. That is the
+  *vmlinuz* file inside the */live* directory of the extracted
+  contents from the ISO file.
+* The initial ramdisk of the VyOS ISO you want to deploy. That is the
+  *initrd.img* file inside the */live* directory of the extracted
+  contents from the ISO file. Do not use an empty (0 bytes) initrd.img
+  file you might find, the correct file may have a longer name.
+* A directory named pxelinux.cfg which must contain the configuration
+  file. We will use the configuration_ file shown below, which we named
+  default_.
+
+.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config
+.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration
+
+In the example we configured our existent VyOS as the TFTP server too:
+
+.. code-block:: none
+
+  vyos@vyos# show service tftp-server
+   directory /config/tftpboot
+   listen-address 192.168.1.50
+
+Example of the contents of the TFTP server:
+
+.. code-block:: none
+
+  vyos@vyos# ls -hal /config/tftpboot/
+  total 29M
+  drwxr-sr-x 3 tftp tftp      4.0K Oct 14 00:23 .
+  drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 ..
+  -r--r--r-- 1 root vyattacfg  25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos
+  -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32
+  -rw-r--r-- 1 root vyattacfg  46K Oct 13 23:24 pxelinux.0
+  drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg
+  -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz
+
+  vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg
+  total 12K
+  drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 .
+  drwxr-sr-x 3 tftp tftp      4.0K Oct 14 00:23 ..
+  -rw-r--r-- 1 root root       191 Oct 14 01:10 default
+
+Example of simple (no menu) configuration file:
+
+.. code-block:: none
+
+  vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default
+  DEFAULT VyOS123
+
+  LABEL VyOS123
+   KERNEL vmlinuz
+   APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs
+
+Step 3: HTTP
+^^^^^^^^^^^^
+
+We also need to provide the *filesystem.squashfs* file. That is a heavy
+file and TFTP is slow, so you could send it through HTTP to speed up the
+transfer. That is how it is done in our example, you can find that in
+the configuration file above.
+
+**First** run a web server - you can use a simple one like
+`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs`
+file. The file can be found inside the `/live` directory of the
+extracted contents of the ISO file.
+
+**Second**, edit the configuration file of the :ref:`install_from_tftp`
+so that it shows the correct URL at
+``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``.
+
+.. note:: Do not change the name of the *filesystem.squashfs* file. If 
+   you are working with different versions, you can create different
+   directories instead.
+
+And **third**, restart the TFTP service. If you are using VyOS as your
+TFTP Server, you can restart the service with
+``sudo service tftpd-hpa restart``.
+
+.. note::  Make sure the available directories and files in both TFTP
+   and HTTP server have the right permissions to be accessed from the
+   booting clients.
+
+.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html
+
+Client Boot
+-----------
+
+Finally, turn on your PXE-enabled client or clients. They will
+automatically get an IP address from the DHCP server and start booting
+into VyOS live from the files automatically taken from the TFTP and HTTP
+servers.
+
+Once finished you will be able to proceed with the ``install image``
+command as in a regular VyOS installation.
+
+
+
+Known Issues
+============
+
+This is a list of known issues that can arise during installation.
+
+Black screen on install
+-----------------------
+
+GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts.
+This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a 
+black screen after selecting the `Live system` option from the installation image.
+
+The workaround is to type `e` when the boot menu appears and edit the GRUB boot options.  Specifically, remove the:
+
+`console=ttyS0,115200` 
+
+option, and type CTRL-X to boot. 
+
+Installation can then continue as outlined above.
+
+.. _SYSLINUX: http://www.syslinux.org/
+.. _balenaEtcher: https://www.balena.io/etcher/
+.. _Rufus: https://rufus.ie/
+.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems
diff --git a/docs/installation/migrate-from-vyatta.rst b/docs/installation/migrate-from-vyatta.rst
new file mode 100644
index 00000000..eba9dc59
--- /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 compatiblity
+---------------------------
+
+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 <maintainers@so3group.net>"
+   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/update.rst b/docs/installation/update.rst
new file mode 100644
index 00000000..a3a887f0
--- /dev/null
+++ b/docs/installation/update.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 <url | path> [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/gns3.rst b/docs/installation/virtual/gns3.rst
new file mode 100644
index 00000000..f17715b2
--- /dev/null
+++ b/docs/installation/virtual/gns3.rst
@@ -0,0 +1,175 @@
+.. _vyos-on-gns3:
+
+VyOS 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).
+  `Here <https://docs.vyos.io/en/latest/install.html#download>`__ you
+  can find how to get it.
+
+* 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..dab5bc59
--- /dev/null
+++ b/docs/installation/virtual/index.rst
@@ -0,0 +1,9 @@
+####################################
+Running VyOS in Virtual Environments
+####################################
+
+.. toctree::
+   :caption: Content
+
+   gns3
+   vmware
\ 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..6feb95ba
--- /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 artifical 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..14ba2adf
--- /dev/null
+++ b/docs/installation/vyos-on-baremetal.rst
@@ -0,0 +1,380 @@
+.. _vyosonbaremetal:
+
+Running on Bare Metal
+#####################
+
+Intel 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 wan't 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 <https://www.openbmc.org/>`_ 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
+***************
+
+As this platform seems to be quiet 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 rack for APU4
+* 1x Compex WLE900VX (Optional mini PCIe WiFi module)
+
+The 19" enclosure can accomodate up to two APU4 boards - there is a single and
+dual front cover.
+
+.. note:: Compex WLE900VX is only supported in mPCIe slot 1.
+
+VyOS 1.2 (crux)
+---------------
+
+Depending on the VyOS versions you intend to install there is a difference in
+the serial port settings (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 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/apu4c4_rack_1.jpg
+   :scale: 25 %
+   :alt: APU4C4 rack closed
+
+.. figure:: /_static/images/apu4c4_rack_2.jpg
+   :scale: 25 %
+   :alt: APU4C4 rack front
+
+.. figure:: /_static/images/apu4c4_rack_3.jpg
+   :scale: 25 %
+   :alt: APU4C4 rack module #1
+
+.. figure:: /_static/images/apu4c4_rack_4.jpg
+   :scale: 25 %
+   :alt: APU4C4 rack module #2
+
+.. figure:: /_static/images/apu4c4_rack_5.jpg
+   :scale: 25 %
+   :alt: APU4C4 rack module #3 with PSU
+
+
+Desktop
+^^^^^^^
+
+.. figure:: /_static/images/apu4c4_desk_1.jpg
+   :scale: 25 %
+   :alt: APU4C4 desktop closed
+
+.. figure:: /_static/images/apu4c4_desk_2.jpg
+   :scale: 25 %
+   :alt: APU4C4 desktop closed
+
+.. figure:: /_static/images/apu4c4_desk_3.jpg
+   :scale: 25 %
+   :alt: APU4C4 desktop back
+
+.. figure:: /_static/images/apu4c4_desk_4.jpg
+   :scale: 25 %
+   :alt: APU4C4 desktop back
+
+.. _Rufus: https://rufus.ie/
+.. _T1327: https://phabricator.vyos.net/T1327
+
+
+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 adresses 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
+from `Amazon <https://www.amazon.com/gp/product/B073F9GHKL/>`_ in June 2018.
+It came pre-loaded with pfSense.
+
+`Manufacturer product page <http://www.inctel.com.cn/product/detail/338.html>`_.
+
+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
+
+11/22/2016. 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 <http://www.linuxliveusb.com/>`_.
+
+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``