Skip to content

ordyn-net ​

ordyn-net is the local PXE and network utility service for Ordyn.

It is enrolled through an edge node, so the Ordyn server does not require a direct network connection to it.

Responsibilities ​

  • send Wake-on-LAN packets
  • perform ping checks
  • run IPAM network scans and lightweight service probes
  • provide PXE boot support for OS installations

Runtime configuration ​

Assign a Net node through endpoint, folder, or tenant Service routing. Direct endpoint assignments override inherited routes.

Enable ICMP or common protocol probes on endpoint network interfaces to monitor their addresses. Results appear on the endpoint and in IPAM. The normal probe interval defaults to 60 seconds; unreachable addresses are retried less frequently.

IPAM scans ​

Select a Net node for networks under Inventory > IPAM. Scans find reachable IPv4 addresses and can identify common network services, including unmanaged devices. See IPAM for scan configuration and limits.

Enable ICMP probing for ping reachability checks. Enable common protocol probing to check the following services:

PortProtocol
21FTP
22SSH
23Telnet
80HTTP
443HTTPS
445SMB
631IPP
3389RDP
5900VNC
8080HTTP alternate
8443HTTPS alternate
16992Intel AMT discovery over HTTP
16993Intel AMT discovery over HTTPS

HTTP and HTTPS probes can report the server header and page title to help identify a service. HTTPS probes can identify devices with invalid certificates; a successful probe does not confirm that the certificate is trusted.

AMT address discovery requires the Net node to share the firmware interface's local network. Schedule scans to find changed DHCP addresses while Windows is offline.

PXE ​

When a device reaches iPXE through a Net node, an active waiting PXE job takes priority and starts immediately. A known endpoint without an active PXE job continues normal boot. An unknown device creates a pending PXE request and waits for a decision for up to five minutes. Approval creates a staged endpoint and starts a compatible provisioning job during the current boot. Rejection or expiration stops that boot attempt.

The Endpoints sidebar shows a shortcut while an unknown-device request is waiting. Known-endpoint normal boots and MAC conflicts are recorded in the PXE request audit without appearing in the pending queue.

See Pending PXE Requests for the decision workflow and PXE Request Audit for retained history.

OS image kinds ​

Prepare the assets needed by your deployment:

Image kindPurpose
PXE bootstrapiPXE archive and the BIOS/UEFI boot filenames used by DHCP
wimbootInput for building Windows PE boot images
Boot imageWindows PE or the Linux installer used to start installation
OS imageWindows installation media

See OS Images and the platform setup below.

iPXE ​

For Ordyn PXE boot, the upstream artifacts come from the iPXE release archive published in the official v2.0.0 release:

  • iPXE v2.0.0 release

  • upload the provided ipxeboot.tar.gz

  • BIOS PXE:

    • typically undionly.kpxe
  • UEFI x64:

    • typically ipxe.efi
    • or snponly.efi if that works better on your hardware
    • for Secure Boot, typically x86_64-sb/snponly-shim.efi or x86_64-sb/ipxe-shim.efi
  • wimboot

snponly.efi is also valid. This is a firmware and NIC compatibility choice, not an Ordyn-specific requirement.

Some UEFI firmware requests /ipxe.efi after starting the Secure Boot shim because it cannot identify the original shim filename. For these devices, enable Secure Boot firmware compatibility fallback on the PXE bootstrap image and use one of these supported file pairs in the same archive directory:

  • snponly-shim.efi with snponly.efi to use the firmware SNP network driver
  • ipxe-shim.efi with ipxe.efi to use iPXE's native network driver

Ordyn serves the corresponding signed second stage when the firmware uses the fallback request, preserving the driver selected by the configured shim. After changing the setting, sync the PXE bootstrap image to every affected net node. See iPXE issue #1684 for upstream tracking of the firmware behavior.

iPXE can briefly display Verification failed: Security Policy Violation while loading a kernel under Secure Boot even when the subsequent shim handoff succeeds. If the installer continues after the shim is loaded, this message is cosmetic. See iPXE issue #1653 for upstream tracking.

The ipxeboot.tar.gz archive contains the iPXE boot files. Upload it as an OS image with the PXE bootstrap kind.

After creating the image, select it on the net node detail page and choose Sync PXE bootstrap image.

Debian netboot files ​

For Debian PXE installation, create a Linux boot image and upload the Debian installer netboot files:

  • linux as the Linux kernel
  • initrd.gz as the Linux initrd
  • bootnetx64.efi as the Linux Secure Boot shim

Upload all three files from the same Debian amd64 netboot installer tree. The Linux Secure Boot shim is required for every Linux boot image, including environments where Secure Boot is disabled.

The distribution shim in the Linux boot image is separate from the iPXE bootstrap shim configured in DHCP. The iPXE bootstrap shim starts the signed iPXE binary. The distribution shim authorizes the handoff from iPXE to the selected Linux installer kernel.

Debian publishes these files in its netboot installer tree. See:

Set the Linux boot image kernel arguments to include the install answer file URL placeholder. A typical Debian preseed boot line is:

text
auto=true priority=critical interface=auto netcfg/dhcp_timeout=60 preseed/url={{ ordyn.install_answer_file_url }}

Ordyn replaces {{ ordyn.install_answer_file_url }} with a temporary URL served by the assigned net node for the current PXE run. Debian also accepts url= as the short form of preseed/url=. Keep the complete kernel argument value on one line.

Linux installation jobs use PXE boot endpoint as the installation step. Configure that step with the Linux boot image, operating system, and install answer file. Do not add Install OS image; that step runs Windows installation workflows in WinPE.

A typical Linux job sequence is:

  1. PXE boot endpoint
  2. post-install steps that run on the newly installed agent

The running job shows generated Wait for endpoint enrollment and Wait for agent instruction readiness steps between these authored steps.

Configure each Linux operating-system entry with its distribution, release codename, and architecture. Debian PXE supports amd64 and arm64. Ordyn installs the newest approved Agent DEB for the target architecture.

Linux install answer files can use these placeholders:

  • {{ endpoint.id }}
  • {{ endpoint.hostname }}
  • {{ ordyn.endpoint_id }}
  • {{ ordyn.enrollment_token }}
  • {{ ordyn.edge_host }}
  • {{ ordyn.agent_install_command }}

Include exactly one {{ ordyn.agent_install_command }} placeholder in the install answer file's d-i preseed/late_command directive to install and enroll the Agent. Install answer files are limited to 1 MiB.

For example:

text
d-i preseed/late_command string \
    {{ ordyn.agent_install_command }}

Linux kernel arguments must be a single line without control characters and must include {{ ordyn.install_answer_file_url }}.

Debian 13 (Trixie) amd64 install answer file example ​

The following preseed is a starting point for a Debian 13 server installed through DHCP. It uses LVM on the first disk detected by Debian Installer and installs the standard and SSH server tasks.

Destructive partitioning

This example erases the first disk returned by list-devices disk. Disk discovery order is not a stable hardware identity and can include USB storage, SAN devices, or another unintended disk. Use this selection only when the first detected disk is the intended installation target. For systems where multiple disks may be present, replace the dynamic selection with an explicit d-i partman-auto/disk string /dev/... value after verifying the device. Ordyn does not inspect or validate the selected disk.

Debian Installer documents this dynamic selection in its advanced preseed options.

Before saving the file, replace example.internal and REPLACE_WITH_SHA512_CRYPT_HASH. Generate a SHA-512 crypt password hash with mkpasswd -m sha-512. Adapt locale, keyboard, mirror, time zone, package selection, partitioning, and boot-loader settings to the target environment.

text
### Localization
d-i debian-installer/locale string en_US.UTF-8
d-i keyboard-configuration/xkb-keymap select us

### Network
d-i netcfg/choose_interface select auto
d-i netcfg/hostname string {{ endpoint.hostname }}
d-i netcfg/get_domain string example.internal
d-i netcfg/wireless_wep string

### Debian mirror
d-i mirror/country string manual
d-i mirror/http/hostname string deb.debian.org
d-i mirror/http/directory string /debian
d-i mirror/http/proxy string

### Clock and time zone
d-i clock-setup/utc boolean true
d-i time/zone string UTC
d-i clock-setup/ntp boolean true

### Local user
d-i passwd/root-login boolean false
d-i passwd/user-fullname string Ordyn Administrator
d-i passwd/username string ordynadmin
d-i passwd/user-password-crypted password REPLACE_WITH_SHA512_CRYPT_HASH

### Whole-disk LVM partitioning
d-i partman/early_command string \
    debconf-set partman-auto/disk "$(list-devices disk | head -n1)"
d-i partman-auto/method string lvm
d-i partman-auto-lvm/guided_size string max
d-i partman-lvm/device_remove_lvm boolean true
d-i partman-md/device_remove_md boolean true
d-i partman-lvm/confirm boolean true
d-i partman-lvm/confirm_nooverwrite boolean true
d-i partman-auto/choose_recipe select atomic
d-i partman-partitioning/confirm_write_new_label boolean true
d-i partman/choose_partition select finish
d-i partman/confirm boolean true
d-i partman/confirm_nooverwrite boolean true

### Package selection
d-i apt-setup/cdrom/set-first boolean false
tasksel tasksel/first multiselect standard, ssh-server
d-i pkgsel/include string ca-certificates
d-i pkgsel/upgrade select safe-upgrade
popularity-contest popularity-contest/participate boolean false

### Boot loader and completion
d-i grub-installer/only_debian boolean true
d-i grub-installer/with_other_os boolean true
d-i grub-installer/bootdev string default
d-i finish-install/reboot_in_progress note

### Install and enroll the managed Ordyn Agent
d-i preseed/late_command string \
    {{ ordyn.agent_install_command }}

Use the Debian preseed example for additional settings and architecture-specific guidance.

Building a Windows PE image ​

For licensing reasons Ordyn cannot ship a built Windows PE image. Build it on a dedicated Windows Runner.

Install the Windows ADK and the matching Windows PE add-on on the Runner. Microsoft provides both installers in the Windows ADK downloads.

Create an infrastructure job, select a Runner pool containing that Runner in the job overview, and add the Build WinPE boot image task. Confirm that the Runner has detected the WinPE build tools before starting the job.

The selected pool's Cache Node supplies the build inputs and receives the generated assets.

See Build A Windows PE Image for the complete Runner setup and job fields.

PXE flow ​

Configure DHCP to start the selected iPXE bootstrap from the Net node. The client then loads its boot image from Cache and starts Windows PE or the Linux installer.

The job waits for the installed Agent to enroll and connect before continuing with post-install tasks.

Linux PXE has these operational limits:

  • Linux installation does not run an Ordyn preboot runtime. After the install answer file is retrieved, installer progress is not reported until the installed agent enrolls.
  • Kernel, initrd, and distribution shim architecture, Debian release, preseed, mirror, and target firmware compatibility are operator-managed and are not cross-validated.
  • The Debian installer must trust the TLS certificate used by the net-node install-answer-file URL.
  • A Linux boot image supports one kernel, one initrd, and one distribution shim. Required firmware must be embedded in those assets or obtained by the installer.

Cache certificate trust

During PXE boot, iPXE downloads boot assets from the assigned cache node. If the cache node uses HTTPS with a certificate that is not publicly trusted by iPXE, the download can fail before the selected operating system installer starts. Use a publicly trusted certificate for cache nodes that serve PXE boot assets, or make sure the selected iPXE build trusts the certificate chain used by the cache node. Also allow the client access described in PXE network requirements.

PXE network requirements ​

PXE clients need access to the following destinations while iPXE loads the boot script and boot-image assets. Apply these rules to each PXE client VLAN, including routed and Internet-restricted VLANs. These connections originate from the PXE client, not from the Net node.

SourceDestinationProtocol/portPurpose
PXE clientConfigured DNS resolverUDP/TCP 53Resolve Net, cache, CA, and OCSP hostnames
PXE clientca.ipxe.orgTCP 80 (HTTP)Download iPXE cross-signed CA certificate sets from /auto/...
PXE clientocsp.ipxe.orgTCP 80 (HTTP)Validate the iPXE cross-signing chain through /ocsp/root/... and /ocsp/cross/... responders
PXE clientConfigured Net public base URLTCP 443 (HTTPS)Download /ipxe/boot.ipxe and use provisioning endpoints
PXE clientAssigned Cache Node/download hostnamesTCP 443 (HTTPS)Download boot-image assets from signed cache URLs

The CA and OCSP requests listed above use HTTP over TCP 80. Allowing DNS alone is insufficient. Each client VLAN needs routes and firewall access to these destinations, even when it can already reach the Net HTTPS endpoint.

These requirements supplement the DHCP requirements and TFTP access needed for the initial bootstrap. Plan separately for any additional network access required by the selected operating-system installer.

Even with publicly trusted Net and cache certificates, iPXE must be able to retrieve any certificates and OCSP responses required for validation. Inspect the deployed certificate chains for both HTTPS endpoints when defining a strict allowlist: they can declare additional OCSP responder destinations that also need to be reachable.

HTTPS boot troubleshooting ​

A generic iPXE Permission denied during HTTPS boot can indicate that iPXE could not retrieve a required certificate or OCSP response.

  1. From the affected PXE client VLAN, check DNS resolution and routing to the configured Net HTTPS origin, assigned cache/download hostnames, and CA/OCSP destinations.
  2. Check firewall deny logs for blocked client traffic on the destination ports listed above, especially HTTP CA/OCSP requests on TCP 80. A successful connectivity check from the Net node does not confirm access from the client VLAN.
  3. Inspect the deployed Net and cache certificate chains for additional OCSP responder URLs and allow access to their destinations.
  4. After correcting access, retry HTTPS boot. Check both the initial /ipxe/boot.ipxe retrieval and subsequent downloads of boot-image assets from the assigned cache node.

Installation ​

Prerequisites:

Checkout the Net folder from the Ordyn compose repository:

bash
if [ ! -d /opt/ordyn-compose/.git ]; then
  git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add net

Create the environment file:

bash
cd /opt/ordyn-compose/net
cp .env.example .env

Create the net node in Ordyn and copy the generated runtime values into .env:

The net node's public base URL must use HTTPS. Its certificate chain must be trusted by iPXE, WinPE, and any Linux installer that downloads provisioning data.

dotenv
SERVICE_DOMAIN=ordyn-net.example.com
ORDYN_NET_SERVICE_CLIENT_ID=<service-client-id>
ORDYN_NET_EDGE_HOST=ordyn-edge.example.com
ORDYN_NET_HTTP_BIND=172.17.0.1:8080
ORDYN_NET_SMB_USERNAME=<generated-smb-username>
ORDYN_NET_SMB_PASSWORD=<generated-smb-password>
ORDYN_NET_INSTALL_MEDIA_CACHE_PATH=/var/lib/ordyn-net/install-media-cache
ORDYN_NET_LOG_LEVEL=info

Pull and verify the service image:

bash
docker compose pull
python3 /opt/cosign-docker-verify/verify.py

Continue only when the Net image verifies successfully and no failed verification message appears. Issue a service-client enrollment token scoped to the net node, stop any running Net container, and enroll the persistent service state:

bash
docker compose stop net
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps net enroll --token-stdin

After enrollment succeeds, start the service:

bash
docker compose up -d net

To renew, recover, or replace its service-client certificate, issue a new token and run forced enrollment while the service is stopped:

bash
docker compose stop net
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps net enroll --token-stdin --force

Run docker compose up -d net only after forced enrollment succeeds. Do not use docker compose exec for enrollment.

The Net service uses host networking because PXE, TFTP, and SMB need to be reachable directly on the local network. Public boot handoff is routed through Traefik over HTTPS. The default ORDYN_NET_HTTP_BIND=172.17.0.1:8080 is an internal listener on the Docker host bridge; Traefik terminates HTTPS and forwards to it without exposing that listener on every host interface.

Monitor certificate expiration and follow the service-client renewal workflow before expiry.

Install media cache ​

Enable install-media caching on the Net node to reuse prepared Windows media across installations. Set capacity according to your image sizes; the default is 50 GiB. Less recently used images are removed when capacity is exceeded.

Clearing the cache does not interrupt active installations. Disabling it bypasses cached media for new sessions while retaining existing entries.

Set ORDYN_NET_INSTALL_MEDIA_CACHE_PATH to choose a different storage location. Allow space for the configured cache plus a complete media copy for each active installation.

For troubleshooting, temporarily enable ORDYN_NET_DEBUG_PRESERVE_INSTALL_MEDIA_SESSIONS=true to retain failed installation media for inspection. Remove retained files afterward because they can consume substantial disk space.

Install workflow execution ​

Windows OS image install steps run in WinPE before Windows Setup. Use them to prepare the installation source and customize deployment. See OS image steps.

Installer workflows do not support reboot-and-resume. Exit-code mappings can classify results but cannot add that behavior.

Windows install local admin variables ​

Ordyn supports two system endpoint variables for Windows local-admin provisioning:

  • windows.local_admin_username
  • windows.local_admin_password

Current behavior:

  • windows.local_admin_username has a system default of OrdynAdmin; a super administrator can edit that default in Variables, and scoped overrides can select another account name
  • if windows.local_admin_password is unset, Ordyn generates a random password during installer-session creation and stores it as a retrievable secret endpoint override
  • if an endpoint already has a windows.local_admin_password value, Ordyn reuses that existing password on later installs

The password remains redacted by default. Authorized administrators can deliberately reveal it from the endpoint's Variables view; every reveal is audited.

Available Windows answer file placeholders:

  • {{ hostname }}
  • {{ local_admin_username }}
  • {{ local_admin_password }}

The shipped default Windows answer file uses these values to either:

  • set the built-in Administrator password, or
  • create a custom local admin user and add it to the local Administrators group

WinPE install troubleshooting logging ​

For WinPE OS-install troubleshooting, you can create your own custom endpoint variable definition with this exact key:

  • windows.winpe.debug_logging_enabled

If you create a variable override for this and assign a truthy value through the Variables tabs, the WinPE installer runtime will enable verbose local logging for that install session.

Important constraints:

  • the extra logging is intended for local WinPE troubleshooting only
  • when enabled, WinPE logs sensitive material locally, including the SMB password used for the install-source share mapping
  • those secret-bearing logs are not reported back to ordyn-net or Ordyn, but anyone with local WinPE console or log-file access can read them
  • leave this variable unset or false for normal installs

Prepared endpoints and claim rules ​

To stage a known device, create a prepared endpoint with its network interface MAC addresses and start a compatible PXE installation job before booting it. A saved MAC address alone does not start installation.

For enrollment without PXE, issue a token bound to the prepared endpoint. For unknown PXE devices, follow Pending PXE Requests.

DHCP requirements ​

Ordyn does not manage DHCP. You must configure your DHCP server to point PXE clients at ordyn-net.

At minimum DHCP must provide:

  • next-server / TFTP server address
  • boot filename for BIOS clients
  • boot filename for UEFI x64 clients

Those filenames must exactly match the configured bootstrap paths from the selected pxe_bootstrap_image.

Typical filenames are:

  • BIOS: undionly.kpxe
  • UEFI x64: ipxe.efi

An example isc-dhcpd style configuration looks like:

conf
next-server 192.168.1.10;

if exists user-class and option user-class = "iPXE" {
  filename "";
} elsif option arch = 00:07 or option arch = 00:09 {
  filename "ipxe.efi";
} else {
  filename "undionly.kpxe";
}

Notes:

  • 192.168.1.10 should be the LAN address of your ordyn-net host
  • the exact UEFI architecture matching rules depend on your DHCP server and environment
  • if you choose snponly.efi instead of ipxe.efi, DHCP must hand out snponly.efi instead
  • DHCP must hand out the exact uploaded filename, not a derived alias

If your DHCP server supports separate policies for BIOS and UEFI, that is the simplest model for Ordyn.

Security note ​

Use a trusted provisioning network and protect the Net and Cache hosts that serve installation assets. PXE boot relies on those assets being trustworthy. Ensure the chosen iPXE build trusts the cache's HTTPS certificate chain.

Endpoint power on requests ​

The Net service sends Wake-on-LAN packets when selected by Power on in Automatic mode or by the explicit Wake on LAN mode of the Power on endpoint job step. The service must be connected and assigned to the endpoint, and a host MAC address must be available.

A successful AMT power-on or Hyper-V start does not require a net node. The job step's optional broadcast address and port apply only when a Wake-on-LAN packet is sent. Net-node acceptance confirms the request was handled, not that the endpoint agent is online.