> ## Documentation Index > Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL. > Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other. > Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking. > Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify. # Configure a Proxy Server for Edge Device Onboarding > Bake an HTTP proxy configuration into an EVE-OS installer image so that an edge device can reach Edge Infrastructure Services through a proxy on first boot. ## 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](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/onboard-nodes.md), 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](https://zededa.mintlify.site/new-ui/infrastructure-services/manage-nodes-with-local-ui.md) 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 1. Create a folder for your override files, with a `DevicePortConfig` subfolder. ```bash theme={"dark"} mkdir -p $HOME/eve-overrides/DevicePortConfig ``` 2. Create a file named `override.json` in the `DevicePortConfig` subfolder. ```bash theme={"dark"} 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`. ```json theme={"dark"} { "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. ```json theme={"dark"} "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`. ```bash theme={"dark"} base64 -w 0 proxy.pac ``` ```json theme={"dark"} "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. ```bash theme={"dark"} base64 -w 0 proxy-ca.pem ``` 2. Add the result to the port configuration. ```json theme={"dark"} "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. ```json theme={"dark"} { "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. ```bash theme={"dark"} 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 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. `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](https://zededa.mintlify.site/new-ui/infrastructure-services/networks/create-a-network.md) 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 > [card] [Onboard an Edge Node](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/onboard-nodes.md) > > Register the edge node in Edge Infrastructure Services after installation. > [card] [Create a Network](https://zededa.mintlify.site/new-ui/infrastructure-services/networks/create-a-network.md) > > Configure the proxy settings in Edge Infrastructure Services for ongoing connectivity. > [card] [Get EVE-OS](https://zededa.mintlify.site/new-ui/infrastructure-services/eve-os-installation/get-eve-os.md) > > Download EVE-OS images and installer archives. > [card] [Troubleshoot EVE-OS Installation](https://zededa.mintlify.site/new-ui/infrastructure-services/eve-os-installation/troubleshoot-eve-os-installation.md) > > Diagnose installation and onboarding failures.