Installation, Customization & Network Configuration

Before getting started, ensure the following are available:

—

There are two methods to obtain and create an EVE OS image:

Download pre-built assets directly from the EVE OS GitHub releases page:

• https://github.com/lf-edge/eve/releases
• https://github.com/lf-edge/eve/tags

After downloading, mount the .raw file using the following command:

hdiutil attach -imagekey diskimage-class=CRawDiskImage 16.12.0-k-amd64.raw

This mounts two volumes:

Navigate to /Volumes/EVE to find the following structure:

/Volumes/EVE
├── DevicePortConfig/
│   └── override.json.template
├── grub.cfg
├── grub.cfg.tmpl
├── onboard.cert.pem
├── onboard.key.pem
├── origin.2026-04-14.16.12.0
├── root-certificate.pem
├── server
└── v2tlsbaseroot-certificates.pem

hdiutil detach /dev/diskX
 
# If the volume is busy:
hdiutil detach /dev/diskX -force

<note warning> Replace diskX with the disk identifier assigned at mount time (e.g. disk4). Run diskutil list to confirm. </note>

—

The Docker Run method provides more control over image creation and allows customization to be injected at build time.

• Docker Desktop on macOS
• On Windows: WSL + Docker Desktop with WSL filesystem navigation
• A Docker Hub tag for the desired EVE OS version — browse available images at: https://hub.docker.com/r/lfedge/eve
• Example tag: 16.10.0-k-amd64

Create a local folder (e.g. ~/overrides) that maps into the container at /in. Customization files placed here are injected into the image at build time:

overrides/                    ← your local folder
├── DevicePortConfig/
│   └── override.json         ← static network configuration
├── grub.cfg                  ← grub tweaks
└── server                    ← controller URL

docker run --platform linux/amd64 \
  --rm \
  -v $HOME/overrides:/in \
  lfedge/eve:16.10.0-k-amd64 \
  -f raw installer_raw > 16.10.0-k-amd64.raw

docker run --platform linux/amd64 \
  --rm \
  -v $HOME/overrides:/in \
  lfedge/eve:16.10.0-k-amd64 \
  -f raw installer_iso > 16.10.0-k-amd64.iso

—

Static network settings are configured in DevicePortConfig/override.json. Rename the included template file to override.json before editing.

<note> Source of truth for all available fields: https://github.com/lf-edge/eve/blob/master/pkg/pillar/types/zedroutertypes.go </note>

The following example demonstrates a configuration with a static IP on a VLAN subinterface and WiFi management:

{
  "TimePriority": "2000-01-01T00:00:00Z",
  "Version": 1,
  "Ports": [
    {
      "IfName": "eth0",
      "IsMgmt": false,
      "IsL3Port": false
    },
    {
      "Dhcp": 1,
      "IfName": "eth0.250",
      "IsMgmt": true,
      "IsL3Port": true,
      "Type": 4,
      "AddrSubnet": "192.168.0.100/24",
      "Gateway": "192.168.0.1",
      "DnsServers": ["1.1.1.1"],
      "L2Type": 1,
      "VLAN": {
        "ParentPort": "eth0",
        "ID": 250
      }
    },
    {
      "Dhcp": 4,
      "Free": true,
      "IfName": "wlan0",
      "Name": "Management2",
      "IsMgmt": true,
      "IsL3Port": true,
      "Type": 4,
      "WirelessCfg": {
        "WType": 2,
        "Wifi": [
          {
            "KeyScheme": 1,
            "Password": "<pbkdf2-hex-password>",
            "SSID": "WIFI-SSID"
          }
        ]
      }
    }
  ]
}

The WiFi password field must be in WPA2 PSK (Pairwise Master Key) format — a 64-character lowercase hex string derived using PBKDF2:

PBKDF2(HMAC-SHA1, password, ssid, iterations=4096, keylen=32)

Use the following Go Playground tool to generate a valid password hash: https://go.dev/play/p/EGyJ7PDU4rn

<note warning> The WiFi password in override.json is base64-encoded after PBKDF2 derivation. Ensure both encoding steps are applied correctly. </note>

—