====== EVE OS Image Customization ======

Installation, Customization & Network Configuration

===== Prerequisites =====

Before getting started, ensure the following are available:

^ Requirement ^ Details ^
| EVE OS Image | KVM or K variant, in ''.raw'' or ''.iso'' format |
| Hardware Serial Number | Required for device registration |
| Installation Media | USB drive (simplest method) |
| IP Addressing | DHCP or Static (static requires additional configuration) |

---

===== Creating an EVE OS Image =====

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

==== Method 1: Direct Download ====

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

=== Mounting and Customizing the Raw Image (macOS) ===

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

<code bash>
hdiutil attach -imagekey diskimage-class=CRawDiskImage 16.12.0-k-amd64.raw
</code>

This mounts two volumes:

^ Volume ^ Purpose ^
| ''/Volumes/EVE'' | Where all customizations are performed |
| ''/Volumes/INVENTORY'' | Empty on creation. Populated post-install with device info (model, serial, etc.) |

=== EVE Volume — File & Folder Structure ===

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

<code>
/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
</code>

=== Key Files for Customization ===

^ File ^ Purpose ^
| ''DevicePortConfig/override.json'' | Network configuration (rename from ''override.json.template''). Defines static IPs, VLANs, WiFi, etc. |
| ''grub.cfg'' | Boot configuration and kernel parameters. See EVE OS GRUB documentation for full reference. |
| ''server'' | Controller URL that EVE phones home to — e.g. ''zedcloud.gmwtus.zededa.net'' |

=== Ejecting the Image ===

<code bash>
hdiutil detach /dev/diskX

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

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

---

==== Method 2: Docker Run ====

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

=== Requirements ===

  * 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''

=== Overrides Folder Structure ===

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:

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

=== Creating a RAW Image ===

<code bash>
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
</code>

=== Creating an ISO Image ===

<code bash>
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
</code>

---

===== Network Configuration — override.json =====

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>

==== Example: Static IP, VLAN, and WiFi Configuration ====

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

<code json>
{
  "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"
          }
        ]
      }
    }
  ]
}
</code>

==== WiFi Password Format ====

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

<code>
PBKDF2(HMAC-SHA1, password, ssid, iterations=4096, keylen=32)
</code>

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>

---

===== Reference Links =====

^ Resource ^ URL ^
| EVE OS Releases | https://github.com/lf-edge/eve/releases |
| Docker Hub — EVE Images | https://hub.docker.com/r/lfedge/eve |
| EVE Networking Docs | https://github.com/lf-edge/eve/blob/master/docs/NETWORKING.md |
| DevicePortConfig Source of Truth | https://github.com/lf-edge/eve/blob/master/pkg/pillar/types/zedroutertypes.go |
| EVE Example Config Files | https://github.com/lf-edge/eve/tree/master/conf |
| WiFi Password Generator | https://go.dev/play/p/EGyJ7PDU4rn |