Set up opsi server
This manual provides a detailed description of the process for setting up an opsi server to efficiently deploy Windows installations and automate device enrollment into Relution. The goal is to configure a functioning opsi server that can install Windows operating systems on client devices via netboot while seamlessly integrating them into Relution for centralized management.
The guide covers all essential steps, including installation and configuration of the opsi server, preparation of Windows and Windows Preinstallation Environment (WinPE) installation files. Additionally, it explains the process of automating Relution enrollment using local opsi products.
Glossary
| Term | Explanation |
|---|---|
| admin console | Refers to the UI which is included in the opsi server and runs on https://localhost:4447 |
| configed | Refers to the additional Java application which may run on any device to connect to the opsi server |
| client debug console | Refers to the opsi agent UI which runs on https://<opsi-client-IP>:4441 |
Setup opsi server
This section describes the process of setting up the opsi server, providing a detailed walkthrough of the necessary configurations, installation steps, and preparation of critical packages.
Server installation
It is recommended to use the Docker-based installation for setting up the opsi server on Linux environments. However, it is important to note that the Docker setup cannot be used on macOS devices due to compatibility issues with the integrated TFTP server. For macOS systems, the preconfigured VirtualBox → option should be used instead.
The opsi config server is set up according to the opsi documentation below. After the installation, the admin console is available at https://localhost:4447. The Java application → for configed is also required.
Documentation
Install required opsi-packages
The required opsi packages are installed in the Terminal tab of the admin console with the following command:
opsi-package-updater -v install <package-name>
An overview of all available local and netboot products can be found in the opsi repository →.
The following packages need to be installed:
| Package | Description |
|---|---|
| opsi-client-agent | Client installed on the device to execute commands |
| opsi-script | Used by the client agent to execute opsi scripts |
| opsi-uefi-netboot | Required for UEFI netboot to change boot order |
| opsi-winpe | Creates a WinPE on the device |
| hwaudit (optional) | Inventory tool which gathers information about the device |
Client registration
This section covers the process of registering devices that already have a Windows operating system installed with the opsi server. The opsi client agent is installed on the device to establish communication with the server, enabling centralized control and execution of actions.
For clients that do not yet have Windows installed, additional steps are required to initialize and install the operating system using netboot. In such cases, users should refer to the official opsi documentation below for detailed instructions on initial client setup.
The opsi client agent can be downloaded from https://<opsi-server-ip>:4447/public/opsi-client-agent/. After the client was installed on the device, the opsi server address and admin account credentials have to be entered.
Once the registration is complete, the client will appear in the device inventory of the configed. To check the connection between opsi server and client a pop-up message can be sent (Top menu → Client → Send pop-up message).
The UEFI netboot product is installed on the device by setting the Requested action to once.
The Log files tab provides detailed information for troubleshooting installed opsi-client agent and linux-boot-image. This is helpful for debugging the installation of local and netboot products.

Documentation
Prepare Windows installation files
This section provides instructions for acquiring the necessary Windows ISO file, creating a compatible WinPE environment, and organizing these files into the required directory structure for netboot products. In this setup, Windows 11 was installed on the device.
Windows ISO and WinPE
To prepare the opsi server for deploying Windows installations, several key components are required. First, the Windows ISO file is required for the specific version to be installed, such as Windows 11. The ISO file can be downloaded from the official Microsoft website.
Next, a WinPE must be created. The WinPE must match the Windows image version being deployed. This can be achieved by using the opsi-winpe package, which requires the installation of Windows ADK and the PE plugin. Alternatively, the WinPE can be created directly with Windows ADK, as described in the opsi documentation.
The documentation on netboot products → describes two options to prepare a WinPE:
- Using
opsi-winpepackage (Windows ADK and the PE plugin → need to be installed!) - Using Windows ADK
Setup directory structure for netboot product
The matching wrapper package for the Windows image is installed from the opsi Netboot Repository → via the package manager, e.g. opsi-local-image-win11-x64_4.3.0.2-13 for Windows 11.
A new directory will be added on the opsi server (e.g. /var/lib/opsi/depot/win11-x64). The Windows Image and the WinPE have to be placed in the correct directories (see Directory Tree overview → for reference).
Install files
The contents of the Windows ISO have to be placed at the installfiles directory.
WinPE
The WinPE needs to be placed in the winpe directory.
setup.exe, the directories are placed here as well.In the end, all files and all directories of the WinPE are at the root level in this directory:
Show full configuration example
/var/lib/opsi/depot/win11-x64/winpe/
├── fwfiles
├── media
├── mount
├── bg-bg
├── Boot
├── bootmgr
├── bootmgr.efi
├── cs-cz
├── da-dk
├── de-de
├── EFI
├── el-gr
├── en-gb
├── en-us
├── es-es
├── es-mx
├── et-ee
├── fi-fi
├── fr-ca
├── fr-fr
├── hr-hr
├── hu-hu
├── it-it
├── ja-jp
├── ko-kr
├── lt-lt
├── lv-lv
├── nb-no
├── nl-nl
├── pl-pl
├── pt-br
├── pt-pt
├── ro-ro
├── ru-ru
├── sk-sk
├── sl-si
├── sources
├── sr-latn-rs
├── sv-se
├── tr-tr
├── uk-ua
├── zh-cn
└── zh-tw
Documentation
Configure DHCP server
To configure a DHCP server for PXE boot, specific options need to be provided that supply PXE boot clients with the information they need to locate the TFTP server and download the bootloader file. These are commonly defined as DHCP options 66 (TFTP server) and 67 (bootloader file).
If the router does not provide a UI to set these options, e.g. when using a Linux or Windows DHCP server, the following options have to be added to the dhcpd.conf file:
next-server <opsi-server-IP>;
filename "opsi/opsi-linux-bootimage/loader/opsi-netboot.efi";
Start netboot
To initiate the installation of a netboot product, the Netboot products tab in the configed interface is opened. The Requested action for the selected product is set to setup and saved by clicking the save icon located in the top-left corner.
Once the action is sent, the process can be monitored by checking the logs in the configed client details and the client debug console. These logs will indicate whether the opsi client has successfully received and processed the action.
After completing these steps, the Windows client will check for netboot sources on the next reboot, initiating the installation process.

For troubleshooting, the following commands can be run to view the TFTP traffic on the opsi server:
sudo tcpdump -i lo0 port 69
journalctl -f
Relution enrollment
This section outlines the process of enrolling devices into the Relution platform using the relution-enrollment local boot product. This product automates the installation of a provisioning package via PowerShell, ensuring seamless integration of devices into Relution.
Prepare provisioning package
A provisioning package must be prepared according to the instructions for Windows bulk enrollment →.
Install Relution-enrollment opsi package
The relution-enrollment package is available as a stable version in the public opsi repository →.
The relution-enrollment_<package-version>.opsi file is downloaded using the wget command. The following command installs the opsi package so that it becomes available in configed as a localboot product:
opsi-cli package install relution-enrollment_<package-version>.opsi
After the installation, the package is available in the depot folder (/var/lib/opsi/depot/relution-enrollment). The generated provisioning package is placed in this folder, and opsi-set-rights is run in this directory.
/var/lib/opsi/depot/relution-enrollment/
├── enrollment.opsiscript
├── relution.ppkg
├── relution-enrollment.files

Install product
To install the package, the client is selected and the Localboot products tab is opened. For the relution-enrollment product, the Requested action is set to once. The state is then saved and an on_demand action is triggered (Menu → Client → Trigger opsiclientd event → on_demand).
As the PowerShell command that installs the provisioning package always marks the action as successful, the logs should be checked for errors.
Error Package installation failed, error code -2147024713 (800700B7) indicates that a package with the same id is already installed.
If the provisioning package was installed already, it needs to be removed first.

Common issues
This section highlights common issues encountered during the opsi server setup and netboot installation and provides solutions or references to relevant documentation for troubleshooting.
- Unable to get geometry for disk ‘/dev/nvme0n1’ →
- The password for the root user is set via the host parameter
netboot.linux-bootimage.cmdline.pwh. - When the error occurs,
Ctrl + Alt + F3/F4/F5switches to the active terminal. - There, the root user logs in with the password.
- The command
sgdisk --zap-all /dev/nvme0deletes the partition. - After switching back to the other terminal, the netboot is retried.
- More information is available in the documentation on netboot products →
- The password for the root user is set via the host parameter
- opsi winPE is empty →: all files from the WinPE subdirectories (e.g. media) are moved to the root level
- WinPe init does not work →