8. Quickstart - WADS for Linux¶

8.1. 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 wads button.

You can rename the hosts by using F2 keyboard touch

8.1.1. 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 here

8.1.2. Creating a XML configuration¶

Go to the configuration panel in OS DEPLOY.

Click on the +.
Choose a configuration name. (1)
Uncheck the 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)

Create a configuration in WADS for Linux — Create a configuration in WADS for linux¶

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

8.1.3. ADD the djoin for you desktop¶

Right-click > Select a Configuration, take the configuration you have done previously and OK.

Right-click on the computer to be deployed → 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 Connect to Domain and Reload OU. (3)
- Prefer the overwrite option in order to re-register the computer if necessary. (4)
- Select your desired Organization Unit. (5)
- Save. (6)

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

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

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.

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:

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.

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.

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.

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.