---
title: "Key Configuration Files"
description: "This document describes the configuration files that control WendyOS service behaviour, where they live on the device, and what they do."
---

# Key Configuration Files

This document describes the configuration files that control WendyOS service behaviour, where they live on the device, and what they do.

## Identity and device files

| Path | Persistence | Description |
|------|-------------|-------------|
| `/etc/wendyos/device-uuid` | Persistent (`/data/etc/wendyos/`) | RFC 4122 UUID generated once on first boot by `wendyos-uuid-generate.service`; at enrollment (both startup pre-provisioning and live re-enrollment) the agent replaces it with the device UUID in its certificate, the device's one id, and rewrites the `id=` TXT record of the `_wendyos._udp` Avahi service to match (a device with neither a non-empty explicit hostname nor a device name first pins its current hostname to `/etc/wendy-agent/hostname`). A legacy asset certificate carries no device UUID and leaves both untouched. Survives OTA updates via bind mount. |
| `/etc/wendyos/device-name` | Persistent (`/data/etc/wendyos/`) | Human-readable name in `adjective-noun` format (e.g. `brave-dolphin`), generated by `wendyos-device-name-generate.service`. Used as the mDNS hostname and USB gadget product string. |
| `/etc/wendyos/device-type` | Persistent (`/data/etc/wendyos/`) | Board identifier string (e.g. `raspberry-pi-5`, `raspberry-pi-4`). Seeded from the rootfs on first boot and kept on `/data` thereafter. |
| `/etc/wendyos/version.txt` | Symlink to `/usr/lib/wendyos/version.txt`, refreshed via bind mount | OS version string (e.g. `WendyOS-RPi-0.13.2`). Updated on every OTA. |

All files under `/etc/wendyos/` are bind-mounted from `/data/etc/wendyos/` by `wendyos-etc-binds.service` early in boot.

## Agent configuration

| Path | Description |
|------|-------------|
| `/etc/wendy-agent/device-key.pem` | Device enrollment private key, mode `0600`. Internal agent state; see [Credential persistence](../../pki/README.md#credential-persistence). |
| `/etc/wendy-agent/provisioning.json` | Enrollment details, certificate (`certPem`) and CA chain (`chainPem`), mode `0600`. New writes exclude the private key. |
| `/etc/wendy-agent/hostname` | Literal hostname set by `wendy device rename`. Backed by `/data`, it survives reboots and OTA updates and takes precedence over `/etc/wendyos/device-name` in hostname generation. At agent startup, `ReassertHostnameAdvertisement` also uses it to restore hostname-derived Avahi TXT records that were replaced during boot or by a fresh OTA slot. |
| `/etc/default/wendy-agent` | Shell-format environment file sourced by both `wendyos-agent.service` and `wendyos-agent-updater.sh`. Supports `WENDYOS_AGENT_GITHUB_REPO`, `WENDYOS_AGENT_VERSION`. Not created by default; create it to override release channel. |
| `/var/lib/wendy-agent/` | Runtime state directory for the agent (current-version file, working data). |
| `/opt/wendyos/bin/wendy-agent` | Agent binary. Installed at build time; overwritten in-place by `wendyos-agent-updater.service`. Outside `/usr` on purpose: a merged sysext replaces that hierarchy, which would hide an updated binary. |
| `/opt/wendyos/bin/wendyos-agent-updater.sh` | Updater logic: checks GitHub releases API, downloads, replaces binary, restarts service. The timer and service are temporarily stopped during `wendy os update` to prevent interference with the in-flight OTA operation (wendyos-update on current images). |
| `/opt/wendyos/bin/download-wendyos-agent.sh` | Low-level downloader used by the updater. Fetches `wendy-agent-linux-arm64-*.tar.gz` from the latest stable GitHub release. |

## Network configuration

All files under `/etc/NetworkManager/system-connections/` are bind-mounted from `/data/etc/NetworkManager/system-connections/` by `wendyos-etc-binds.service`.

| Path | Description |
|------|-------------|
| `/usr/lib/NetworkManager/system-connections/usb-gadget.nmconnection` | Distro-managed profile for the `usb0` interface. Read-only on the rootfs; updated on OTA. IPv4 mode is set at build time by `WENDYOS_USB_NET_MODE` (`link-local`, `dhcp-client`, or `dhcp-server`). High route-metric (700) keeps WiFi/Ethernet preferred as the default route. |
| `/etc/NetworkManager/system-connections/` | User-added connections (WiFi, VPN). Persisted on `/data`. NM gives `/etc` priority over `/usr/lib` for same-named files. |
| `/etc/NetworkManager/NetworkManager.conf` | Main NM config: keyfile plugin, DNS managed by NM (not systemd-resolved), random MAC scan disabled, INFO-level logging to journal. |
| `/etc/NetworkManager/conf.d/00-manage-usb0.conf` | Ensures NM manages the `usb0` interface. |
| `/etc/NetworkManager/conf.d/10-usb-gadget.conf` | Additional per-interface settings for the USB gadget connection. |
| `/etc/NetworkManager/conf.d/99-interface-metrics.conf` | Sets route metrics so wired/WiFi interfaces are preferred over USB gadget (`usb0`). |

## systemd journal configuration

| Path | When present | Description |
|------|-------------|-------------|
| `/usr/lib/systemd/journald.conf.d/10-wendyos-persistent.conf` | `WENDYOS_PERSIST_JOURNAL_LOGS=1` | Sets `Storage=persistent` so journald writes to `/var/log/journal` instead of `/run/log/journal`. |
| `/etc/systemd/journald.conf.d/10-persistent.conf` | RPi5, `journal_persist-on` feature | Same persistence setting, installed by the RPi-specific `rpi-systemd.inc` bbclass. |

See [logging.md](logging.md) for the full journald configuration and how to access logs.

## USB gadget configuration

`gadget-setup.service` runs `/usr/sbin/gadget-setup.sh` which uses Linux configfs to build the gadget. Environment variables that control it can be set system-wide (e.g. via `/etc/default/wendy-agent` or a drop-in for `gadget-setup.service`):

| Variable | Default | Description |
|----------|---------|-------------|
| `USB_VID` | `0x1d6b` | USB Vendor ID (Linux Foundation) |
| `USB_PID` | `0x0104` | USB Product ID (Multifunction Composite Gadget) |
| `USB_MFR` | `Wendy Labs Inc` | Manufacturer string |
| `USB_PROD` | `WendyOS Device <name>` | Product string shown on host |
| `USB_SERIAL` | device serial number | Serial number string |
| `GADGET_FUNC_ORDER` | `ncm ecm` | Network function preference; `ncm` is tried first, `ecm` is the fallback |

The gadget always includes an ACM serial function (`/dev/ttyGS0` on device, `ttyACMx` on host).

## Boot configuration (RPi)

| Path | Description |
|------|-------------|
| `/boot/config.txt` | RPi firmware configuration. WendyOS adds `enable_uart=1` and either `dtoverlay=uart0-pi5` (RPi 5) or `dtoverlay=uart0` (RPi 4). Also adds `dtoverlay=dwc2` when `ENABLE_DWC2_PERIPHERAL=1`. |
| `/boot/cmdline.txt` | Kernel command line. WendyOS appends `console=tty1` to keep a HDMI console alongside the serial console. |

## fstab

`/etc/fstab` is populated from a board-specific template at build time:

- **RPi 4/5** (`rpi-fstab`): mounts partitions by PARTUUID.
- **RPi 3** (`rpi-mbr-fstab`): mounts partitions by filesystem label. Under MBR the kernel exposes PARTUUIDs as `<disk-signature>-<partno>` rather than UUIDv4, so label-based references are used instead.

RPi 4/5 fstab mounts:

| Partition | Mount point | Options |
|-----------|-------------|---------|
| `PARTUUID=<boot>` | `/boot` | vfat, defaults |
| `PARTUUID=<root>` | `/` | ext4, noatime |
| `LABEL=config` | `/config` | vfat, nofail |

RPi 3 fstab mounts:

| Partition | Mount point | Options |
|-----------|-------------|---------|
| `LABEL=boot` | `/boot` | vfat, defaults |
| `LABEL=root` | `/` | ext4, noatime |
| `LABEL=config` | `/config` | vfat, nofail |

The `nofail` option on `/config` means a missing or unformatted config partition does not block boot. See [Config Partition](../config-partition.md) for details.

## Disk layout

The partition table format depends on the board:

### RPi 4/5 — GPT (`rpi-partuuid.wks`)

| Partition | Label | Size | Filesystem | Mount |
|-----------|-------|------|------------|-------|
| 1 | `boot` | 128 MB | FAT32 | `/boot` |
| 2 | `config` | 64 MB (default) | FAT32 | `/config` |
| 3 | `root` | 8 GB | ext4 | `/` |

### RPi 3 — MBR (`rpi-mbr.wks`)

The BCM2837 GPU bootrom on the Pi 3 can only read MBR-partitioned FAT32. The GPT layout used on Pi 4/5 leaves the board unable to find `bootcode.bin` and the system never boots.

| Partition | Label | Size | Filesystem | Mount |
|-----------|-------|------|------------|-------|
| 1 | `boot` | 128 MB | FAT32 | `/boot` |
| 2 | `config` | 64 MB (default) | FAT32 | `/config` |
| 3 | `root` | 8 GB | ext4 | `/` |

The config partition size can be adjusted at build time with `WENDYOS_CONFIG_PART_SIZE_MB` in `local.conf` or the distro conf.

There is no pre-provisioned `/data` partition in the SD image. Machines that need persistent data (Tegra/Jetson) add a `/data` partition via their own WKS files.