8. Quickstart - WADS for Linux


8.1. Déploiement d’une machine Linux dans le domaine, avec jonction de domaine hors ligne

Dans cet exemple, nous allons déployer une machine Linux parce que l’ordinateur n’est pas éligible pour Windows 11. Si vous avez un poste de travail qui ne répond pas aux exigences de Windows 11, vous pouvez le recycler en poste de travail Linux. Le poste de travail existe déjà dans l’infrastructure, vous devrez donc le récupérer dans l’inventaire WAPT.

Puisque votre station de travail est listée dans l’inventaire, vous pouvez l’exporter vers OS Deploy en utilisant le wads button.

Vous pouvez renommer les hôtes en utilisant la touche clavier F2

8.1.1. Prérequis

  • Un serveur DHCP configuré.

  • Le serveur WAPT doit pouvoir échanger avec la machine à déployer.

  • Avoir une résolution DNS avec un contrôleur de domaine à partir de la console.

  • Utilisateur ayant des droits d’administrateur local sur le serveur WAPT.

  • Utilisateur qui a signé les fichiers exe ( Outils > Signer le fichier de déploiement) et les fichiers de configuration.

Note

Documentation officielle de WADS ici


8.1.2. Création d’une configuration XML

  • Allez dans le panneau de configuration dans Déploiement d’OS.

Panneau de configuration

Panneau de configuration

  • Cliquez sur le +.

  • Choisissez un nom de configuration. (1)

  • Décochez la case Pour Windows (2)

  • Ne choisissez pas d’ISO (2)

  • Choisissez un fichier de configuration en cliquant sur l’icône du document (dans ce quickstart, nous recommandons le mode hors ligne, afin de ne pas avoir à créer le compte de la machine dans Active Directory). (3)

  • Choisissez le fichier de script IPXE ( \wapt\templates\wads_template\linux\ipxescript\debian\debian.ipxe). (4)

Créer une configuration dans WADS pour Linux

Créer une configuration dans WADS pour Linux

  • Sauvegardez, vous avez créé une configuration dans WAPT. (5)


8.1.3. Ajouter le djoin sur votre poste

  • Faites un clic droit > Select a Configuration, prenez la configuration que vous avez faite précédemment et OK.

  • Cliquez avec le bouton droit de la souris sur l’ordinateur à déployer → prepare Djoin (cela vous permet de spécifier dans votre Active Directory l’unité organisationnelle où votre nouvelle machine sera enregistrée).

    • Complétez le domaine. (1)

    • Indiquez le contrôleur de domaine. (2)

    • Cliquez sur Connecter au domaine et recharger l’OU. (3)

    • Préférez l’option overwrite afin de réenregistrer l’ordinateur si nécessaire. (4)

    • Sélectionnez l’unité organisationationnelle de votre choix. (5)

    • Enregistrer. (6)

Edit Djoin

Edit Djoin

  • Le commentaire Exist apparaît dans la colonne Djoin.

  • Sélectionnez l’ordinateur à déployer > Cliquez avec le bouton droit de la souris sur Démarrer le déploiement, un X apparaît dans la colonne En Attente de déploiement.


8.1.4. Sur l’ordinateur à déployer

  • Éteignez la machine

  • Démarrez l’ordinateur et chargez le menu de démarrage (utilisez F10 ou F12 au démarrage de l’ordinateur), sélectionnez LAN ou similaire.

  • Une fois l’opération terminée, la machine redémarre automatiquement.

  • Une fois le redémarrage terminé, votre machine est prête à fonctionner. Vous pouvez vous connecter avec un utilisateur du domaine.

Le déploiement de WADS est terminé et votre machine est enregistrée dans votre inventaire WAPT.

Note

Si votre ordinateur n’apparaît pas dans la bonne OU, vous pouvez vous identifier dans la console, et faire un clic droit Windows Computer management → Update AD Group Policies on hosts.

8.2. How it works

8.2.1. 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:

  1. The machine boots using PXE or iPXE.

  2. The WAPT server returns the WADS iPXE entry point.

  3. 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.

  4. WADS identifies the machine in OS Deploy.

  5. If the machine is waiting for deployment, WADS returns the iPXE script configured for that machine.

  6. The iPXE script downloads the Linux kernel and initrd.

  7. The iPXE script boots the Linux installer and passes it the WADS endpoint URL used to retrieve the installation configuration.

  8. The installer downloads its automated configuration from /api/v3/get_wads_config.

  9. WADS generates this configuration by replacing variables such as {{hostname}} or {{djoin}}.

  10. 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.

8.2.2. 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:

#!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:

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.

8.2.3. How WADS provides the iPXE script

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

/api/v3/get_host_ipxe

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

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.

8.2.3.1. 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.

8.2.4. How WADS provides the installation configuration

The Linux installer retrieves its automated installation configuration with:

/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:

  1. identifies the machine using the configured matching mode;

  2. checks that the machine is waiting for deployment;

  3. loads the deployment configuration selected for that machine;

  4. replaces the WADS variables in the configuration content;

  5. returns the generated configuration to the installer.

8.2.4.1. 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.

Avertissement

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.

8.2.5. Generic structure of a Linux template driven by iPXE

A WADS Linux template is usually made of two files.

8.2.5.1. 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.

8.2.5.2. 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.

8.2.6. 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.

8.2.7. 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:

# 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.