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 console afterward. The recommended approach for proxy and static IP scenarios is the single-use EVE-OS installer, which bakes a bootstrap configuration directly into the installer for that specific device. Use the method in this article when the single-use installer is not an option — for example, when you need to embed network configuration into a generic image that will be reused across multiple devices. This article describes how to bake the proxy configuration into a generic 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. You can also set the proxy from the Local UI on the edge device itself.

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

Field	Type	Description
`Proxies`	array	An explicit list of proxy servers. Each entry has a server, a port, and a type.
`Exceptions`	string	A comma-separated list of destinations that bypass the proxy, for example `example.com`.
`NetworkProxyEnable`	boolean	Set to `true` to retrieve proxy settings automatically with WPAD. Set to `false` when you list proxies in `Proxies`.
`NetworkProxyURL`	string	The URL of a WPAD file, for example `http://wpad.example.com/wpad.dat`. Leave empty to let EVE-OS discover the WPAD file through DNS.
`Pacfile`	string	The contents of a proxy auto-configuration file, base64 encoded. Use this when your site supplies the file contents rather than a URL.
`ProxyCertPEM`	array	The certificates of a proxy that intercepts TLS, each in PEM format and base64 encoded. EVE-OS adds these to its TLS trust store.

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

Value	Proxy type
`0`	HTTP
`1`	HTTPS
`2`	SOCKS
`3`	FTP
`4`	No proxy

Port and file fields

Field	Description
`Version`	The configuration format version. Use `1`, which requires `IsMgmt` to be set on management ports.
`TimePriority`	A timestamp that sets the priority of this configuration. A later timestamp takes priority over an earlier one. A value of all zeros is the lowest priority. The all-zeros priority is reserved for Last Resort config. Use a non-zero value here, lower than the config prepared by Edge Infrastructure Services, such as `2000-01-01T00:00:00Z`.
`IfName`	The interface name of the port, for example `eth0`.
`IsMgmt`	Set to `true` on the port that reaches Edge Infrastructure Services.
`Dhcp`	How the port obtains its IP address. Refer to the following table.
`Cost`	The relative cost of using this port. Zero is free.

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.

Value	Meaning
`0`	Undefined.
`1`	Static IP configuration. Requires `AddrSubnet` and `Gateway`.
`2`	DHCP passthrough, for switch network instances only.
`3`	Deprecated. Do not use.
`4`	Run a DHCP client to obtain an 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

Create a folder for your override files, with a DevicePortConfig subfolder.
mkdir -p $HOME/eve-overrides/DevicePortConfig
Create a file named override.json in the DevicePortConfig subfolder.
vi $HOME/eve-overrides/DevicePortConfig/override.json

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.

Base64 encode the certificate.
base64 -w 0 proxy-ca.pem

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.

Command	Produces
`installer_raw`	A raw disk image to write to a USB drive.
`installer_iso`	An ISO image.
`installer_net`	A netboot archive for a PXE server.

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

Verify the Configuration

Start the edge device and let the installation finish.
Confirm that the edge device appears in Edge Infrastructure Services. A device that registers has reached the cluster through the proxy.
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.

override.json bootstraps connectivity to Edge Infrastructure Services only. After the device connects, it applies and uses the configuration provided by Edge Infrastructure Services. The proxy configuration must also be set in Edge Infrastructure Services for the device to continue routing traffic correctly after onboarding.

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

Create a Network

Configure the proxy settings in Edge Infrastructure Services for ongoing connectivity.

Get EVE-OS

Download EVE-OS images and installer archives.

Troubleshoot EVE-OS Installation

Diagnose installation and onboarding failures.

Start Here

Infrastructure Services Overview

Core infrastructure

Build

Applications and delivery

Edge Kubernetes

Operations

Monitor

Administration and Security

Troubleshooting

Partnerships

Configure a Proxy Server for Edge Device Onboarding

Introduction

How It Works

Proxy fields

Port and file fields

Prerequisites

Create the Network Configuration File

Use a WPAD file

Use a proxy that intercepts TLS

Assign a static IP address

Build the Installer Image With the Proxy Configuration

Verify the Configuration

When the Configuration Is Ignored

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

Next Steps

Onboard an Edge Node

Create a Network

Get EVE-OS

Troubleshoot EVE-OS Installation

​Introduction

​How It Works

​Proxy fields

​Port and file fields

​Prerequisites

​Create the Network Configuration File

​Use a WPAD file

​Use a proxy that intercepts TLS

​Assign a static IP address

​Build the Installer Image With the Proxy Configuration

​Verify the Configuration

​When the Configuration Is Ignored

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

​Next Steps

Onboard an Edge Node

Create a Network

Get EVE-OS

Troubleshoot EVE-OS Installation

Introduction

How It Works

Proxy fields

Port and file fields

Prerequisites

Create the Network Configuration File

Use a WPAD file

Use a proxy that intercepts TLS

Assign a static IP address

Build the Installer Image With the Proxy Configuration

Verify the Configuration

When the Configuration Is Ignored

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

Next Steps