Appearance
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:
| Port | Protocol |
|---|---|
| 21 | FTP |
| 22 | SSH |
| 23 | Telnet |
| 80 | HTTP |
| 443 | HTTPS |
| 445 | SMB |
| 631 | IPP |
| 3389 | RDP |
| 5900 | VNC |
| 8080 | HTTP alternate |
| 8443 | HTTPS alternate |
| 16992 | Intel AMT discovery over HTTP |
| 16993 | Intel 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 kind | Purpose |
|---|---|
| PXE bootstrap | iPXE archive and the BIOS/UEFI boot filenames used by DHCP |
| wimboot | Input for building Windows PE boot images |
| Boot image | Windows PE or the Linux installer used to start installation |
| OS image | Windows 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:
upload the provided
ipxeboot.tar.gzBIOS PXE:
- typically
undionly.kpxe
- typically
UEFI x64:
- typically
ipxe.efi - or
snponly.efiif that works better on your hardware - for Secure Boot, typically
x86_64-sb/snponly-shim.efiorx86_64-sb/ipxe-shim.efi
- typically
wimboot- Download from https://ipxe.org/wimboot
- uploaded separately
- used by the WinPE boot path and by the WinPE build job
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.efiwithsnponly.efito use the firmware SNP network driveripxe-shim.efiwithipxe.efito 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:
linuxas the Linux kernelinitrd.gzas the Linux initrdbootnetx64.efias 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:
PXE boot endpoint- 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.
| Source | Destination | Protocol/port | Purpose |
|---|---|---|---|
| PXE client | Configured DNS resolver | UDP/TCP 53 | Resolve Net, cache, CA, and OCSP hostnames |
| PXE client | ca.ipxe.org | TCP 80 (HTTP) | Download iPXE cross-signed CA certificate sets from /auto/... |
| PXE client | ocsp.ipxe.org | TCP 80 (HTTP) | Validate the iPXE cross-signing chain through /ocsp/root/... and /ocsp/cross/... responders |
| PXE client | Configured Net public base URL | TCP 443 (HTTPS) | Download /ipxe/boot.ipxe and use provisioning endpoints |
| PXE client | Assigned Cache Node/download hostnames | TCP 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.
- 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.
- 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.
- Inspect the deployed Net and cache certificate chains for additional OCSP responder URLs and allow access to their destinations.
- After correcting access, retry HTTPS boot. Check both the initial
/ipxe/boot.ipxeretrieval 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 netCreate the environment file:
bash
cd /opt/ordyn-compose/net
cp .env.example .envCreate 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=infoPull and verify the service image:
bash
docker compose pull
python3 /opt/cosign-docker-verify/verify.pyContinue 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-stdinAfter enrollment succeeds, start the service:
bash
docker compose up -d netTo 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 --forceRun 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_usernamewindows.local_admin_password
Current behavior:
windows.local_admin_usernamehas a system default ofOrdynAdmin; a super administrator can edit that default in Variables, and scoped overrides can select another account name- if
windows.local_admin_passwordis 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_passwordvalue, 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
Administratorpassword, or - create a custom local admin user and add it to the local
Administratorsgroup
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-netor 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.10should be the LAN address of yourordyn-nethost- the exact UEFI architecture matching rules depend on your DHCP server and environment
- if you choose
snponly.efiinstead ofipxe.efi, DHCP must hand outsnponly.efiinstead - 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.