=========================
Installing a node via ISO
=========================

SD-WAN ISOs are available on the management server for use in
provisioning nodes. These images contain a full version of SD-WAN
pre-installed on one of our supported distributions. Before you can make use of
these images, you must first use a tool such as `balenaEtcher
<https://etcher.balena.io/>`__ or the Linux ``dd`` command to write the ISO to
a removable storage medium such as a USB key.

.. note::

    An internet connection is only required when installing a node with a node
    key. In this case, the connection is used to grab the configuration from
    the management server and update the software if a newer version is
    available.

    Default nodes require no internet connection to be installed.

.. warning::

    If you intend to install and configure a node using a node key, ensure that
    a corresponding node record with a working interface and address
    configuration has been created on the management server before continuing.
    More information about adding, editing, and deleting node records and
    configuring interfaces and addresses can be found in the `node management
    <../node-management/index.html>`__ and `interfaces and addressing
    <../../interfaces-and-addressing/index.html>`__ documentation.

Downloading the ISO
===================

1. SD-WAN ISOs are available by clicking the **Install** button located
   underneath a node's name on the node details page:

|installing-a-node-via-iso-1|

2. Clicking the **Install** button will open up a modal with further
   instructions:

|installing-a-node-via-iso-2|

3. From here you can select the version of SD-WAN you would like to
   download for any of the supported distributions.

Note that you do not need to click a particular node's **Install** button to
get the ISO for that node; all node ISOs are identical and work for installing
any node.

Mounting the ISO
================

Once the ISO has been downloaded, you must write it to a bootable medium such
as a USB stick using one of the following tools.

Etcher
------

balenaEtcher is a free, open-source tool for creating bootable USB sticks on
Windows, macOS, and Linux. You can find balenaEtcher at the following link:
https://etcher.balena.io/

Linux CLI
---------

``dd`` is a command built-in to most Linux distributions that can be used to
write an ISO file to a USB stick.

First, plug the USB stick into the device.

Then, get the disk filename assigned to the USB stick. You can do this by running
``dmesg`` on the command line:

::

    root@host:~ # dmesg
    ...
    [88787.078204] usb 2-1: new SuperSpeed USB device number 4 using xhci_hcd
    [88787.099364] usb 2-1: New USB device found, idVendor=0781, idProduct=5591, bcdDevice= 1.00
    [88787.099383] usb 2-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
    [88787.099391] usb 2-1: Product:  SanDisk 3.2Gen1
    [88787.099397] usb 2-1: Manufacturer:  USB
    [88787.099402] usb 2-1: SerialNumber: 0101f35a1440f403baac922e74032cb1617e0ea6825e80586a124a3c277cc08f07d7000000000000000000008c9ea993ff0a4a00915581073ab20b6b
    [88787.101351] usb-storage 2-1:1.0: USB Mass Storage device detected
    [88787.102006] scsi host4: usb-storage 2-1:1.0
    [88788.119267] scsi 4:0:0:0: Direct-Access      USB      SanDisk 3.2Gen1 1.00 PQ: 0 ANSI: 6
    [88788.120093] sd 4:0:0:0: Attached scsi generic sg2 type 0
    [88788.120468] sd 4:0:0:0: [sdb] 120164352 512-byte logical blocks: (61.5 GB/57.3 GiB)
    [88788.121540] sd 4:0:0:0: [sdb] Write Protect is off
    [88788.121557] sd 4:0:0:0: [sdb] Mode Sense: 43 00 00 00
    [88788.122012] sd 4:0:0:0: [sdb] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA
    [88788.129510]  sdb: sdb1
    [88788.129955] sd 4:0:0:0: [sdb] Attached SCSI removable disk

The line ``[88788.129510]  sdb: sdb1`` shows that the disk has been given the
filename ``/dev/sdb``.

Next, use the ``dd`` command to write the image. Ensure that ``if=`` points to
the location of the SD-WAN ISO:

::

    dd if=laywire-7.0-opensuse-leap-15.6.x86_64.install.iso of=/dev/sdb

You can now safely remove the device:

::

    eject /dev/sdb

Using the terminal interface
============================

You should now be able to mount the USB key on the node hardware. Note that
the installation medium may not mount automatically if it does not have a high
enough priority in the device's boot order. In that case, you may have to press
a common key on startup such as ``tab``, ``F12``, ``F10``, ``F8`` or ``F2`` to
locate the BIOS's boot menu, and use it to select or reorder the boot order. If
none of those keys work, consult your device's manufacturer documentation.

|installing-a-node-via-iso-3|

After selecting ``Install Laywire``, you will be presented with three console
options:

|installing-a-node-via-iso-4|

``Console: Graphical``
    Install using a physical display and keyboard connected to the device.

``Console: Serial 1 (ttyS0)``
    Install using the first serial interface of the device with:

    - 115,200 baud
    - No parity
    - 8 data bits
    - 1 stop bit
    - No flow control

``Console: Serial 2 (ttyS1)``
    Install using the second serial interface of the device, with all of the
    same serial options as Serial 1.

.. note::
    Devices come with a variety of default serial settings. You may need to
    update the serial settings of the device to 115,200 baud. To change the
    settings, refer to the manufacturer's documentation or read `these examples
    <../../../nodes/updating-hardware-bios-serial-and-boot-settings.html>`__.

After selecting your console option, you will need to configure networking:

|installing-a-node-via-iso-5|

``Network: DHCP``
    Set up addressing on the node using DHCP.

``Network: Static``
    Set a static IP on the node, usually used when setting up core nodes.
    See the :ref:`instructions below
    <setting-a-static-address-during-installation>` to set it up.

``Network: None``
    No network will be configured and it will need to be set up manually after
    install.

Once the networking option has been determined, you will need to choose your
configuration option:

|installing-a-node-via-iso-6|

``With node key``
    The install will prompt for a node key and download the node's
    configuration from the management server.

``Default laywire``
    The install will not prompt for a node key and will provision the device as
    a default node.

Once this has been selected, you will be asked to confirm your selections.
Press ``ESC`` if you need to make any changes.

|installing-a-node-via-iso-7|

Next, you will be asked to set the root password on the device:

|installing-a-node-via-iso-8|

After confirming the root password, if you selected the ``With node key``
configuration option, you will be asked to enter the node key associated with
the node record of the device on the management server:

|installing-a-node-via-iso-9|

From here you will be prompted to destroy all existing data on the device.
Select "Yes" to continue with installation. If there are multiple disks, a
selection menu will display to choose which one to use.

.. _setting-a-static-address-during-installation:

Setting a static address during installation
============================================

If a DHCP server is not available on the device's network, or if you are
setting up a core node, you can configure a static address on the device by
selecting the ``Network: Static`` option during installation. This will present
you with the following screen:

|installing-a-node-via-iso-10|

.. |installing-a-node-via-iso-1| image:: /attachments/laywire/nodes/installing-a-node-via-iso-1.png
    :scale: 75%
.. |installing-a-node-via-iso-2| image:: /attachments/laywire/nodes/installing-a-node-via-iso-2.png
    :scale: 75%
.. |installing-a-node-via-iso-3| image:: /attachments/laywire/nodes/installing-a-node-via-iso-3.png
    :scale: 75%
.. |installing-a-node-via-iso-4| image:: /attachments/laywire/nodes/installing-a-node-via-iso-4.png
    :scale: 75%
.. |installing-a-node-via-iso-5| image:: /attachments/laywire/nodes/installing-a-node-via-iso-5.png
    :scale: 75%
.. |installing-a-node-via-iso-6| image:: /attachments/laywire/nodes/installing-a-node-via-iso-6.png
    :scale: 75%
.. |installing-a-node-via-iso-7| image:: /attachments/laywire/nodes/installing-a-node-via-iso-7.png
    :scale: 75%
.. |installing-a-node-via-iso-8| image:: /attachments/laywire/nodes/installing-a-node-via-iso-8.png
    :scale: 75%
.. |installing-a-node-via-iso-9| image:: /attachments/laywire/nodes/installing-a-node-via-iso-9.png
    :scale: 75%
.. |installing-a-node-via-iso-10| image:: /attachments/laywire/nodes/installing-a-node-via-iso-10.png
    :scale: 75%
