Configure a Proxy Server for Edge Device Onboarding

Introduction

When an edge device reaches Edge Infrastructure Services through an HTTP proxy, the proxy must be configured before the device onboards. A device that cannot reach Edge Infrastructure Services cannot register, so there is no opportunity to configure the proxy from the GUI afterward.

This article describes how to bake the proxy configuration into the EVE-OS (Edge Virtualization Engine) installer image with a Docker command. The command writes a network configuration file into the installer, and EVE-OS reads that file the first time the edge device starts.

A few alternatives exist. You can edit the network configuration file by hand on the installation medium, you can set the proxy from the Local UI on the edge device, or you can use the single-use EVE-OS installer to prepare the proxy configuration and download the installer.

How It Works

The lfedge/eve container image accepts a local folder mounted at /in. Any file in that folder is copied into the EVE-OS config partition of the image the command produces. The installer then writes that config partition to the edge device.

At first start, EVE-OS reads every file with a .json extension in /config/DevicePortConfig/ and uses it to configure the network ports. This is how the proxy setting reaches the device before it contacts Edge Infrastructure Services.

Proxy fields

The type field in each Proxies entry takes one of the following values.

Port and file fields

The Dhcp field takes one of the following values. Use 4 for a port that obtains its address by DHCP, and 1 for a port with a static address.

Prerequisites

• Docker installed and running on the machine where you build the installer image.
• The EVE-OS version to install. This method is available in EVE-OS 11.0.12-lts and greater.
• The hostname or IP address of the proxy server, and the port it listens on.
• The hostname of your Edge Infrastructure Services cluster, for example zedcloud.zededa.net.
• The interface name of the management port on the edge device, for example eth0.
• If the proxy intercepts TLS, the proxy's certificate in PEM format.

Create the Network Configuration File

1. Create a folder for your override files, with a DevicePortConfig subfolder.

mkdir -p $HOME/eve-overrides/DevicePortConfig

2. Create a file named override.json in the DevicePortConfig subfolder.

vi $HOME/eve-overrides/DevicePortConfig/override.json

3. Paste the following content and substitute your own values. This example obtains an address by DHCP, sends both HTTP and HTTPS traffic through proxy.example.com on port 1080, and bypasses the proxy for example.com.

{
    "Version": 1,
    "TimePriority": "2000-01-01T00:00:00Z",
    "Ports": [
        {
            "IfName": "eth0",
            "IsMgmt": true,
            "Dhcp": 4,
            "Cost": 0,
            "NetworkProxyEnable": false,
            "Exceptions": "example.com",
            "Proxies": [
                { "server": "proxy.example.com", "port": 1080, "type": 0 },
                { "server": "proxy.example.com", "port": 1080, "type": 1 }
            ]
        }
    ]
}

The file name must end in .json. EVE-OS reads every JSON file in the folder, so use one file unless you intend to supply several port configurations.

The field names inside each Proxies entry are lowercase, while the field names outside them begin with a capital letter. This difference is intentional and matches what EVE-OS expects. Do not change the casing.

Use a WPAD file

To retrieve the proxy settings with WPAD instead of listing them, set NetworkProxyEnable to true and omit Proxies. To use a fixed WPAD URL, also set NetworkProxyURL. To let EVE-OS discover the WPAD file through DNS, leave NetworkProxyURL empty.

"NetworkProxyEnable": true,
"NetworkProxyURL": "http://wpad.example.com/wpad.dat"

To supply the contents of a proxy auto-configuration file directly, base64 encode the file and set the result as Pacfile.

base64 -w 0 proxy.pac

"Pacfile": "ZnVuY3Rpb24gRmluZFByb3h5Rm9yVVJMKHVybCxob3N0KSB7..."

Use a proxy that intercepts TLS

Many enterprise proxies terminate and re-sign TLS connections. An edge device cannot validate the Edge Infrastructure Services certificate through such a proxy unless it trusts the proxy's certificate, and onboarding fails with a certificate error.

Add the proxy's certificate to ProxyCertPEM. The field takes an array, so you can add more than one certificate.

1. Base64 encode the certificate.

base64 -w 0 proxy-ca.pem

2. Add the result to the port configuration.

"NetworkProxyEnable": false,
"Proxies": [
    { "server": "proxy.example.com", "port": 3129, "type": 0 },
    { "server": "proxy.example.com", "port": 3129, "type": 1 }
],
"ProxyCertPEM": [
    "Ci0tLS0tQkVHSU4gQ0VSVElGSUNBVEUtLS0tLQpNSUlEMURDQ0FyeWdBd0lC..."
]

EVE-OS adds these certificates to its TLS trust store when it applies the configuration.

Assign a static IP address

Sites that require a proxy often require static addressing as well. To assign a static address, set Dhcp to 1 and add the address fields.

{
    "Version": 1,
    "TimePriority": "2026-09-29T00:00:00.000000000Z",
    "Ports": [
        {
            "IfName": "eth0",
            "IsMgmt": true,
            "Dhcp": 1,
            "AddrSubnet": "192.168.1.44/24",
            "Gateway": "192.168.1.1",
            "DNSServers": ["192.168.1.1"],
            "DomainName": "example.com",
            "Cost": 0,
            "NetworkProxyEnable": false,
            "Exceptions": "example.com",
            "Proxies": [
                { "server": "proxy.example.com", "port": 1080, "type": 0 },
                { "server": "proxy.example.com", "port": 1080, "type": 1 }
            ]
        }
    ]
}

AddrSubnet is in CIDR format. If you omit DNSServers, EVE-OS uses the gateway as the DNS server.

Build the Installer Image With the Proxy Configuration

Run the following command, substituting your EVE-OS version. The -v option mounts your override folder at /in, which is what copies the configuration into the image.

docker run --rm -v $HOME/eve-overrides:/in lfedge/eve:17.0.0-lts-kvm-amd64 installer_raw > installer.raw

The same -v option works with the other installer formats.

Write the resulting image to your installation medium and install EVE-OS on the edge device as you normally would.

Verify the Configuration

1. Start the edge device and let the installation finish.
2. Confirm that the edge device appears in Edge Infrastructure Services. A device that registers has reached the cluster through the proxy.
3. If the device does not appear, connect to its console and confirm that the configuration file is present in /config/DevicePortConfig/.

When the Configuration Is Ignored

EVE-OS skips the files in /config/DevicePortConfig/ in two situations. Both are intentional, and both are easy to trigger by accident.

• A bootstrap configuration is present. If the installer also carries /config/bootstrap-config.pb, EVE-OS uses that file and ignores the DevicePortConfig folder. A single-use EVE-OS installer generated from Edge Infrastructure Services contains a bootstrap configuration, so do not combine the two methods. Configure the proxy in the bootstrap configuration instead, or use a generic installer with this method.
• The edge node has already received configuration from Edge Infrastructure Services. After the first successful configuration download, EVE-OS records it and stops reading the folder. This method configures a proxy for initial onboarding only.

Note that override.json is used only to bootstrap connectivity to the Edge Infrastructure Services. After it is connected, the device applies and uses the configuration provided by Edge Infrastructure Services. Therefore, the proxy configuration must also be prepared on the Edge Infrastructure Services side.

Change the Proxy on a Device That Cannot Reach Edge Infrastructure Services

After an edge node onboards, change its proxy by updating the port configuration in Edge Infrastructure Services. That approach requires the edge node to be reachable.

If a proxy change has already cut the edge node off, deliver a new configuration on a USB stick instead. Build the stick with the tools/makeusbconf.sh script in the EVE-OS repository, which takes a JSON file in the same format as this article describes. The file on the stick must be named usb.json, unlike the file on the config partition, which can have any name.

An edge node that has already onboarded reads a USB stick only when the USB controller is enabled with the debug.enable.usb configuration property.

Next Steps

• Onboard an Edge Node
• Get EVE-OS
• Troubleshoot EVE-OS Installation