.. Reminder for header structure:
  Parts (H1)          : #################### with overline
  Chapters (H2)       : ******************** with overline
  Sections (H3)       : ====================
  Subsections (H4)    : --------------------
  Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^
  Paragraphs (H6)     : """""""""""""""""""""

.. meta::
  :description: Quickstart - Installing WAPT Server on Windows
  :stickwords: Quickstart,WAPT,Server,Install,Windows

.. |date| date::

.. role:: red

.. _quickstart_wads_linux:

###########################
Quickstart - WADS for Linux
###########################

|

****************************************************************
Deploying a Linux machine in the domain, with offline connection
****************************************************************


In this example, we will deploy a Linux machine because the computer is not eligible for Windows 11.
If you have a workstation that does not meet the Windows 11 requirements, you can recycle it as a Linux workstation.
The workstation already exists in the infrastructure, so you will need to retrieve it from the WAPT inventory.

Because your workstation is listed in the inventory, you can export it to OS Deploy using the :ref:`wads button <export_selected_host_button>`.


You can rename the hosts by using :kbd:`F2` keyboard touch

Requirements
============

  - A configured DHCP server.
  - The WAPT server must be able to exchange with the machine to be deployed.
  - Have a dns resolution with a domain controller from the console.
  - User with local administrator rights on the WAPT server.
  - User who signed the exe files ( Tools > Sign deploy file) and configuration files.

.. note::
  Official WADS documentation :ref:`here <wapt_ghosting_hosts>`


|

Creating a XML configuration
============================

- Go to the configuration panel in *OS DEPLOY*.

.. figure:: wapt-resources/WAPT-Configuration_panel.png
  :align: center
  :alt: Configuration panel

  Configuration panel

- Click on the :kbd:`+`.
- Choose a configuration name. (1)
- Uncheck the :guilabel:`For Windows` box (2)
- Don't choose a iso.
- Choose a configuration file by clicking on the document icon (in this quickstart we recommend **djoin**, so we don't have to create the machine account in Active Directory). (3)
- Choose a IPXE File Script ( *\\wapt\\templates\\wads_template\\linux\\ipxescript\\debian\\debian.ipxe*). (4)

.. figure:: wapt-resources/create_a_configuration_in_WADS_linux.png
  :scale: 75%
  :align: center
  :alt: Create a configuration in WADS for Linux

  Create a configuration in WADS for linux

- Save, you have created a configuration in WAPT. (5)

|

ADD the djoin for you desktop
=============================



* Right-click > :guilabel:`Select a Configuration`, take the configuration you have done previously and :kbd:`OK`.

- Right-click on the computer to be deployed → :guilabel:`prepare Djoin` (this allows you to specify in your Active Directory the Organizational Unit where your new machine will be registered).

  * Fill in the domain. (1)
  * Fill in the domain controller. (2)
  * Click on :guilabel:`Connect to Domain and Reload OU`. (3)
  * Prefer the :guilabel:`overwrite` option in order to re-register the computer if necessary. (4)
  * Select your desired Organization Unit. (5)
  * Save. (6)

.. figure:: wapt-resources/Edit_Djoin.png
  :scale: 75%
  :align: center
  :alt: Edit Djoin

  Edit Djoin

- The comment :guilabel:`Exist` appears in the Djoin column.
- Select the computer to be deployed > Right-click start Deploy, an **X** appears in the :guilabel:`waiting to deploy` column.

|

On the computer to be deployed
==============================

* **Turn off the machine**

* Start the computer and **charge the boot menu** (Use F10 or F12 when the computer starts up ), select network or similar.

* Once finished, **the machine will restart automatically**.

* Once the reboot is complete, your machine is ready to go. You can log in with a domain user.

**WADS deployment is complete and your machine is registered in your WAPT inventory.**

.. note::

  If you computer don't appear in the right OU, you can identify in the console, and do a right-click :guilabel:`Windows Computer management` → :guilabel:`Update AD Group Policies on hosts`.

************
How it works
************

Overview
========

Linux deployment with WADS is driven by an iPXE script.
WADS does not need to understand the Linux distribution or the syntax of the
configuration file used by the installer. Its main role is to provide:

- the iPXE script associated with the deployment configuration;
- the automated installation configuration file, after replacing WADS variables.

The general workflow is the following:

#. The machine boots using PXE or iPXE.
#. The WAPT server returns the WADS iPXE entry point.
#. The iPXE entry point calls ``/api/v3/get_host_ipxe`` with the known hardware
   identifiers, for example the MAC address, IP address, UUID, manufacturer,
   product and serial number.
#. WADS identifies the machine in OS Deploy.
#. If the machine is waiting for deployment, WADS returns the iPXE script
   configured for that machine.
#. The iPXE script downloads the Linux kernel and initrd.
#. The iPXE script boots the Linux installer and passes it the WADS endpoint URL
   used to retrieve the installation configuration.
#. The installer downloads its automated configuration from
   ``/api/v3/get_wads_config``.
#. WADS generates this configuration by replacing variables such as
   ``{{hostname}}`` or ``{{djoin}}``.
#. The Linux installer applies the instructions in the generated configuration:
   partitioning, package installation, WAPT agent installation, domain join,
   post-install commands, reboot, and so on.

.. note::

  WADS is not tied to a specific Linux installer. The iPXE script decides which
  kernel, which initrd and which boot parameters are used. The installation
  configuration file then decides what the installer must do after it has
  started.

Role of the iPXE script
=======================

The iPXE script is the central element of the Linux deployment.
It defines how the installer is started.

A typical iPXE script must:

- download the Linux kernel;
- download the initrd or additional boot files;
- pass the required boot parameters to the kernel;
- pass the WADS configuration URL to the installer;
- include the machine identifiers required by the WADS matching mode.

Debian example:

.. code-block::

   #!ipxe
   kernel http://ftp.debian.org/debian/dists/stable/main/installer-amd64/current/images/netboot/debian-installer/amd64/linux initrd=initrd.gz initrd=firmware.cpio.gz auto=true fb=false priority=critical preseed/locale=en_US netcfg/get_hostname={{hostname}} netcfg/choose_interface=auto url={{server_url}}api/v3/get_wads_config?mac_address=${net0/mac}&conf_only=true&ip_address=${net0/ip}&uuid=${uuid} DEBCONF_DEBUG=5
   initrd http://ftp.debian.org/debian/dists/stable/main/installer-amd64/current/images/netboot/debian-installer/amd64/initrd.gz
   initrd http://cdimage.debian.org/cdimage/unofficial/non-free/firmware/stable/current/firmware.cpio.gz
   boot

In this example:

- the iPXE script downloads the kernel and the ``initrd`` files required to boot
  the installer;
- ``{{server_url}}`` is replaced by WADS before the script is returned to iPXE;
- ``{{hostname}}`` is replaced with the hostname configured in OS Deploy;
- ``${net0/mac}``, ``${net0/ip}`` and ``${uuid}`` are iPXE variables evaluated on
  the client side by iPXE;
- ``conf_only=true`` tells WADS to return only the generated installation
  configuration file;
- the ``url=`` parameter passes the address of the WADS-generated configuration
  file to the installer.

.. note::

  Example iPXE scripts and installation configuration files are provided with
  WAPT in the following directory:

  .. code-block:: text

     C:\Program Files (x86)\wapt\templates\wads_template\linux

.. important::

  The example above illustrates the general principle: the iPXE script boots a
  Linux installer and passes it the WADS configuration URL. The exact name of the
  boot parameters depends on the installer used by the template. WADS only
  provides the script and replaces variables; it does not interpret the boot
  parameters.

How WADS provides the iPXE script
=================================

When the machine boots, the first WADS iPXE entry point calls:

.. code-block:: text

   /api/v3/get_host_ipxe

This call contains the information collected by iPXE, for example:

.. code-block:: text

   mac_address=${net0/mac}
   ip_address=${net0/ip}
   uuid=${uuid}
   serial_number=${serial}
   manufacturer=${manufacturer}
   product=${product}
   asset=${asset}

WADS then checks the OS Deploy database:

- if the machine is unknown, WADS returns the default iPXE behavior;
- if the machine is known but is not waiting for deployment, WADS stops the
  deployment workflow;
- if the machine is waiting for deployment and a custom iPXE script is
  configured, WADS returns that script after replacing variables.

Variables replaced in the iPXE script
-------------------------------------

``{{server_url}}``
  Replaced with the WAPT server URL.

``{{secondary_repo}}``
  Replaced with the WAPT repository URL selected for the client's network.

``{{hostname}}``
  Replaced with the hostname configured for the machine in OS Deploy.

``{{isohash}}``
  Replaced with the ISO hash when an ISO is associated with the configuration.
  This variable is usually not required in a generic Linux iPXE workflow.

.. note::

  If WADS is configured to identify machines by serial number, the iPXE script
  must send ``serial_number=${serial}`` to WADS. If matching is done by UUID or
  MAC address, check that the corresponding value is present in the URL.

How WADS provides the installation configuration
================================================

The Linux installer retrieves its automated installation configuration with:

.. code-block:: text

   /api/v3/get_wads_config?mac_address=...&conf_only=true&ip_address=...&uuid=...&serial_number=...

The ``conf_only=true`` parameter is important. It tells WADS to return the
generated configuration file directly, instead of returning a JSON structure.

When WADS receives this request, it:

#. identifies the machine using the configured matching mode;
#. checks that the machine is waiting for deployment;
#. loads the deployment configuration selected for that machine;
#. replaces the WADS variables in the configuration content;
#. returns the generated configuration to the installer.

Variables available in the installation configuration
-----------------------------------------------------

``{{server_url}}``
  WAPT server URL.

``{{secondary_repo}}``
  WADS repository URL selected for the client's network.

``{{hostname}}``
  Hostname configured for the machine in OS Deploy.

``{{djoin}}``
  Offline domain join blob generated for the machine.

``{{url_conf_default}}``
  URL of the default WAPT agent configuration file, coming from the WAPT server
  ``conf.d`` directory.

``{{djoin_netbios_name}}``
  Active Directory domain NetBIOS name extracted from the djoin blob.

``{{djoin_domain}}``
  Active Directory DNS domain extracted from the djoin blob.

``{{djoin_domain_lower}}``
  Active Directory DNS domain in lowercase.

``{{djoin_domain_upper}}``
  Active Directory DNS domain in uppercase.

.. warning::

  After providing the machine configuration, WADS clears the stored djoin value
  for security reasons and removes the machine's ``waiting to deploy`` status. If
  the installer fails after downloading the configuration, the deployment must be
  prepared again before retrying.

Generic structure of a Linux template driven by iPXE
====================================================

A WADS Linux template is usually made of two files.

The iPXE script
---------------

This file is executed by iPXE. It is responsible for starting the installer.

It must contain:

- the kernel URL;
- the initrd URL;
- the boot parameters required by the installer;
- the WADS configuration URL;
- the WADS variables that must be replaced before booting.

The automated installation configuration
----------------------------------------

This file is downloaded by the installer after the kernel has started.
It contains the actual installation logic.

It may contain instructions for:

- disk partitioning and formatting;
- package installation;
- local users and authentication;
- network configuration;
- WAPT agent installation;
- offline domain join;
- post-installation commands;
- reboot or shutdown at the end of the installation.

.. important::

  WADS does not validate the syntax of this file. It only replaces variables and
  returns the generated result to the installer.

Using djoin in a Linux deployment
=================================

The djoin workflow is optional.
When it is used, the WAPT console prepares an offline domain join blob for the
machine. This value is stored in OS Deploy until the installer downloads its
configuration.

In the installation configuration, the ``{{djoin}}`` variable is replaced with
the djoin value specific to the machine. The configuration must then write this
value into the installed system and run the commands required to consume it.

WADS also exposes domain-related variables extracted from the djoin value:

- ``{{djoin_netbios_name}}``;
- ``{{djoin_domain}}``;
- ``{{djoin_domain_lower}}``;
- ``{{djoin_domain_upper}}``.

.. note::

  WADS does not directly join the Linux system to the domain. It only injects the
  djoin data into the generated installation configuration. The template must
  install and configure the required Linux components, then run the domain join
  logic.

Install and configure the WAPT agent
====================================

The automated installation configuration can install the WAPT agent during the
post-installation phase.

The template may use ``{{secondary_repo}}`` to download the agent package from
the repository selected for the client's network.

After installing the agent, the template may use ``{{url_conf_default}}`` to
reset the agent configuration from the WAPT server's default configuration.

Generic example:

.. code-block:: bash

   # Download and install the WAPT agent package according to the URL format used by your template.
   # Then reset the agent configuration from the server default configuration.
   /opt/wapt/wapt-get.bin reset-config-from-url {{url_conf_default}}

.. note::

  The exact package format and installation command depend on the Linux system
  booted by the iPXE script. WADS only provides the repository URL and the
  generated configuration variables.