How to Configure Distributed Peer Update with IGEL OS 12 Devices

The Distributed Peer Update feature in IGEL OS 12 (formerly known as Buddy Update in IGEL OS 11) allows IGEL OS 12 devices to act as local update servers. Instead of each device downloading applications and firmware updates from a central repository (for example, UMS app proxy, Distributed App Repository, IGEL App Portal), devices in the same local network can share the download load between them.

Using the Distributed Peer Update mechanism reduces:

• bandwidth usage across WAN links

• load on central repositories

• time until all devices in a subnet receive the assigned updates

Starting from IGEL OS 12.7.4, the IGEL Discovery service allows endpoint devices on the same local network to automatically find and obtain updates from one another. For details, see the section How IGEL Discovery Works.

Starting with IGEL OS 12.10.0, Distributed Peer Update also supports a helper-address configuration using HTTPS, also called Non-Broadcast Mode. In this mode, devices do not rely on UDP broadcast discovery to find peers. Instead, administrators configure a specific Distributed Peer Update Server as a repository by using its helper address. This is useful in segmented networks, networks with blocked broadcast traffic, and environments that follow zero-trust network policies.

Limitations and Known Issues

Devices Managed by Multiple UMS Servers on the Same Subnet

Currently, IGEL Discovery does not distinguish between devices managed by different UMS servers within the same subnet. When HTTPS communication is enabled, this limitation can result in SSL certificate validation errors.

For example, if a device managed by UMS-A attempts to download content from a device managed by UMS-B, the certificate mismatch will cause the connection to fail and the peer to be blacklisted. As a result, the update distribution will be delayed.

To prevent this issue, configure devices managed by different UMS servers to use separate communication ports. For example, devices managed by UMS-A should use a different port for IGEL Discovery than devices managed by UMS-B.

Downloads Fail with Many Simultaneous Clients in Non-Broadcast Mode

When many client devices simultaneously download an app or update from a single Distributed Peer Update Server, some downloads may fail because the server cannot provide sufficient bandwidth to every client. Devices that cannot be served immediately are not placed in a queue.

The issue can have the following symptoms:

• The app download times out. The device may require a restart before the download can be started again.

• The update does not start and no error message is displayed. This can occur when the device cannot retrieve the app metadata from the Distributed Peer Update Server.

To mitigate the issue, limit the update bandwidth on the client devices by applying the following through a profile:

1. Go to System > Update.

2. Enable Use a bandwidth limit while updating.

3. Under Limit bandwidth used for updating, enter a suitable per-device limit. The following values are recommended starting points for up to 50 simultaneous client devices:

For more simultaneous clients or additional network traffic, reduce the per-device limit. A lower limit increases the total time required to distribute the update.

For larger deployments, configure more than one Distributed Peer Update Server repository. If the first server cannot respond to an app metadata request, the client can try another configured server.

Community Applications

Starting from IGEL OS 12.8.3 and 12.9.0, Distributed Peer Update can be used with community applications. When using community applications with Distributed Peer Update, consider the following:

• The application metadata must be available in a repository.

• The required certificate must be installed on the devices before the application can be installed or distributed.

Components

Distributed Peer Update can work in two modes:

Peer-to-peer distribution relies on two components that run on IGEL OS devices:

• IGEL Discovery

• Distributed Peer Update Server (also known as “Buddy”)

Together, these components allow peer-to-peer distribution of applications and updates within the same subnet.

Requirements

IGEL OS Version

IGEL OS 12 devices need to run IGEL OS Base System version 12.7.4 or higher.

To use non-broadcast mode, IGEL OS 12 devices need to run IGEL OS Base System version 12.10.0 or higher.

UMS Enrollment for HTTPS

To use HTTPS peer downloads, the devices must be enrolled by UMS, otherwise the internal trust-store will be not initialized.

To use non-broadcast mode, both the client device and the Distributed Peer Update Server must be enrolled in the same UMS. Otherwise, HTTPS certificate validation fails.

Port Requirements

The IGEL Discovery service and the Distributed Peer Update Server use separate ports, as described in the table below:

When configuring the ports, consider the following:

• The Distributed Peer Update Server and the IGEL Discovery service must run on different ports.

• The same Discovery port must be configured on all devices that should discover each other.

• The same Distributed Peer Update Server port must be configured on all devices that should act as peers for each other.

• The configured ports must be open and allowed by any host firewall on the endpoint and by any network firewalls between devices.

Network Requirements

Some network configurations may prevent discovery from working correctly. In these environments, devices may not be able to discover peers automatically.

For example:

• Wi-Fi networks with client isolation

• Networks that block broadcast traffic

Repository Configuration

When using non-broadcast mode, the configured peer repository must use a priority higher than 110 if Disable default repositories is enabled.

Protocol Selection for Peer Downloads

IGEL Discovery searches for possible buddies depending on:

• the download protocols allowed in the IGEL Discovery configuration

• the protocols provided by the available buddies, HTTP and/or HTTPS

The following Discovery settings control which peer protocols are allowed:

If both Allow HTTP and Allow HTTPS are disabled, every search request returns FALLBACK.

Fallback Behavior with Repositories

Peer-to-peer distribution relies on IGEL Discovery to locate a device that already has the requested application. If no device in the subnet can provide the application, Discovery elects one device to download the application from a configured repository. This device becomes the fallback candidate. Once the application is downloaded and installed, the device can serve it to other devices as the Distributed Peer Update Server.

The fallback device downloads the application from the repository with the highest priority that contains the application. Supported repository types include:

• UMS App Proxy

• WebDAV repositories

• IGEL App Portal

• Other repositories configured under System > Update > Repositories

Can Fallback Be Disabled?

When you configure clients to use a fixed Distributed Peer Update Server repository (non-broadcast mode), you can enable Disable default repositories under System > Update. This prevents clients from falling back to automatically available repositories if the configured peer cannot provide the application.

When this setting is enabled, the device ignores:

• Built-in repositories

• Repositories automatically provided by the UMS as an update proxy

• All repositories with a priority value of 110 or lower

Repositories with a priority value higher than 110 remain available and can still be used as fallback repositories.

Enabling Disable default repositories automatically disables Use only repositories provided by the management system (update.use_only_manager_repos).

Recommended Configuration - Intended Use Case

The intended use case is to operate Distributed Peer Update as a peer‑to‑peer network, where all devices both discover and serve updates.

To do this, you can configure devices through profiles:

1. Create a profile.
   

2. In the profile configurator, configure IGEL Discovery and Distributed Peer Update Server on all devices according to the table:

3. Save and assign the profile to the devices.

With this configuration:

• You can assign applications to devices without considering server roles.

• Discovery ensures that only one device at a time in a subnet uses the fallback to fetch the application from a repository.

• Once a device that is configured as a Distributed Peer Update Server has the application, it becomes a peer server for other devices.

• The distribution speed ramps up quickly due to exponential growth:

  • 1 Distributed Peer Update Server with the application → 1 device can download and become Peer Update Server

  • 2 Distributed Peer Update Servers → 2 devices can download and become Peer Update Server

  • 4 Distributed Peer Update Servers → 4 devices can download and become Peer Update Server

  • 8 Distributed Peer Update Servers … and so on …

Rollout Considerations for Large Environment

In very large environments or networks with limited bandwidth, application deployments can be performed in waves as a best practice.

Example rollout:

• First wave: 100 devices

• Second wave: next 100 devices

• Third wave: remaining devices

This prevents excessive simultaneous downloads and reduces network congestion.

How IGEL Discovery Works

Once IGEL Discovery and Distributed Peer Update are enabled, application distribution is automated.

Distribution Process

1. A management system (for example UMS) assigns an application to a device.

2. The device’s update daemon checks whether Discovery is enabled.

3. If Discovery is enabled, the update daemon asks Discovery to find a peer with the requested application.

4. IGEL Discovery broadcasts a UDP request within the subnet asking for the application.

5. Devices respond depending on their state.

Discovery Responses

Update Daemon Behavior

The update daemon reacts to Discovery responses as follows.

Update Progress Indicator Behavior

During peer discovery and fallback selection, the update progress indicator may temporarily remain at 0%.

This can occur while:

• Discovery searches for a peer server

• A fallback device downloads the application

• A peer disappears (for example powered off, network loss) and the update daemon has to request another server.

Once a peer becomes available, the download proceeds normally.

Blacklisting Faulty or Invalid Peers

To handle faulty or invalid peers, IGEL Discovery provides an interface to blacklist IP addresses. Blacklisted IP addresses are ignored during peer selection.

If an unexpected download error occurs, the update daemon blacklists the IP address of the peer. The peer is then no longer considered as a possible candidate for download.

The blacklist can be reset by:

• rebooting the device, or

• restarting IGEL Discovery:

systemctl restart igel-discovery-daemon

The IGEL Discovery log shows a message when an IP address is blacklisted. To view the log, run:

journalctl -u igel-discovery-daemon

Blacklisted IP: 192.168.1.123

Proxy Considerations

IGEL Discovery and the update daemon behave differently when a proxy is configured.

This difference can lead to connectivity issues. For example:

1. Discovery identifies a peer that has the required application.

2. The update daemon attempts to download the application.

3. The request is routed through the configured proxy.

4. The proxy cannot route the request back to the local network.

Result: the peer update fails.

Workaround

To prevent peer-to-peer traffic from being routed through the proxy, add the local subnet(s) to the No Proxy for configuration:

1. Go to Network > Proxy > Manual proxy configuration.

2. Find the No Proxy for parameter.

3. Add the CIDR of the subnet, for example:

192.168.1.0/24
10.0.0.0/16

This ensures that peer-to-peer HTTP and HTTPS traffic is sent directly to local devices.

Configure Distributed Peer Update with Non-Broadcast Mode

You can configure clients to use a specific Distributed Peer Update Server as a repository. This mode does not use IGEL Discovery broadcast requests to find peers.

Use this configuration when:

• Broadcast traffic is blocked.

• Devices are in segmented networks.

• You want deterministic peer selection.

• You want clients to use only defined peer update repositories.

Configure the Distributed Peer Update Server

1. Create a profile for the device or devices that should act as Distributed Peer Update Servers.

2. Configure the following in the profile:

3. Save and assign the profile.

Configure the Clients

1. Create a profile for the client devices.

2. Configure the following in the profile:

3. Save and assign the profile.

Alternative Configurations

Using Only a Subset of Devices as Peer Servers

You can configure a subset of devices as servers and the rest as clients.

Efficiency drawbacks of this configuration:

• The UMS assigns applications without considering which devices are servers.

• It is more likely that a client‑only device is elected first to use fallback.

• Due to the election protocol:

  • only one device at a time downloads from the fallback repository

  • if the elected device is client‑only, it cannot share the application with others

  • this significantly slows down distribution

To configure this model:

1. Create a profile for the servers.

2. Apply the following configurations:

3. Create a profile for the clients.

4. Apply the following configurations:

5. Save and assign the profiles to the selected devices.

Troubleshooting

Check Whether the HTTPS Buddy Is Running

To check whether the HTTPS Buddy is running, run:

systemctl status buddy-update-server-ssl

If an error occurs, check the service log:

journalctl -u buddy-update-server-ssl

Check IGEL Discovery Logs

To check IGEL Discovery activity, run:

journalctl -u igel-discovery-daemon -f

To check whether peers were blacklisted, run:

journalctl -u igel-discovery-daemon

Reset the Discovery Blacklist

To reset the peer blacklist, restart IGEL Discovery:

systemctl restart igel-discovery-daemon

HTTPS Download from a Helper Address Fails

Problem

The client cannot download an application from the configured HTTPS Distributed Peer Update Server.

Possible Cause

The client and the Distributed Peer Update Server are not enrolled in the same UMS, or the UMS trust store is not initialized.

Solution

1. Verify that both devices are enrolled in the same UMS.

2. Verify that both devices have contacted UMS successfully.

3. Check the Distributed Peer Update Server service.

4. Check the update daemon logs for certificate validation errors.

Update Fails When Disable Default Repositories Is Enabled

Problem

The client does not install the assigned application.

Possible Cause

Disable default repositories is enabled, and the configured Distributed Peer Update Server cannot provide the application.

Solution

1. Verify that the application is available on the configured Distributed Peer Update Server.

2. Verify that the helper address repository URL is correct.

3. Verify that the repository priority is higher than 110.

4. If fallback is required, disable Disable default repositories or add another repository with a priority higher than 110.

Further Information

You can find more information how to

Distributed Peer Update Server Configuration in IGEL OS 12

IGEL Discovery Service Configuration in IGEL OS

You might also find the following IGEL Community article useful: FAQ - Distributed Peer Update (Buddy Update).