docs(MAINTAINING): note timesyncd vs networkd/NetworkManager conflict

The base Arch Linux ARM (rpi) tarball ships systemd-networkd enabled while
customize.sh also enables NetworkManager, so both run at once. networkd
claims the unplugged wired end0 and writes ONLINE_STATE=offline, which makes
systemd-timesyncd never send an NTP packet. Combined with the uConsole having
no RTC, the clock ends up badly off after boot.

Document the symptom, root cause, the on-device permanent fix (disable/mask
networkd, drop stale netif state, pin JP NTP servers), and a TODO to fix it
at image-build time in customize.sh. Added to both EN and JA docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: fabiiw05

MAINTAINING.ja.md

@@ -143,6 +143,48 @@ Landlock is not supported by the kernel!` で停止する。自前カーネル
 [archlinuxarm.org](https://archlinuxarm.org/) のフロントページ告知・forum、GitHub の
 [archlinuxarm/PKGBUILDs](https://github.com/archlinuxarm/PKGBUILDs) を監視。
 
+### 時刻同期 (systemd-timesyncd) と networkd / NetworkManager の競合
+
+**症状**: 実機で `timedatectl` が `System clock synchronized: no` のまま、時刻が
+大きくずれる。`systemd-timesyncd` は `active` なのに `timedatectl show-timesync` の
+`PacketCount=0` / `ServerName` 空で、**NTP パケットを 1 つも送っていない**
+（`ping` や手動の UDP 123 クエリは通るのに、である）。
+
+**原因（2 段構え）**:
+
+1. **uConsole にはバッテリバックアップ RTC が無い**（`timedatectl` で `RTC time: n/a`）。
+   起動ごとに時刻がずれるため、ネットワーク同期が事実上必須。
+2. ベースの Arch Linux ARM (rpi) tarball は **`systemd-networkd` が有効**な状態で
+   焼かれている。一方 `scripts/customize.sh` は **NetworkManager を追加で有効化**する
+   （L148 付近）。結果 **両者が二重起動**する。実接続 (`wlan0`) は NetworkManager
+   管理だが、networkd は未接続の有線 (`end0`) を掴んで `configuring` のまま留まり、
+   `/run/systemd/netif/state` に `ONLINE_STATE=offline` を書き込む。
+   `systemd-timesyncd` はこの networkd 由来の online 状態を見て「オフライン」と判断し、
+   **同期を開始しない**。
+
+**恒久対処（実機）**:
+
+```sh
+# NetworkManager を採用しているので networkd 系は無効化して競合を解消
+sudo systemctl disable --now systemd-networkd.socket systemd-networkd \
+  systemd-networkd-wait-online
+sudo systemctl mask systemd-networkd
+sudo rm -rf /run/systemd/netif        # stale な offline 状態を除去
+# 日本の NTP サーバを明示（任意だが確実）
+sudo install -Dm644 /dev/stdin /etc/systemd/timesyncd.conf.d/10-japan.conf <<'CONF'
+[Time]
+NTP=ntp.nict.jp 0.jp.pool.ntp.org 1.jp.pool.ntp.org
+FallbackNTP=0.arch.pool.ntp.org 1.arch.pool.ntp.org 2.arch.pool.ntp.org 3.arch.pool.ntp.org
+CONF
+sudo systemctl restart systemd-timesyncd
+timedatectl timesync-status   # ServerName=ntp.nict.jp / synced になれば OK
+```
+
+**TODO（イメージ側で根治）**: `scripts/customize.sh` の NetworkManager 有効化と
+同じ箇所で `systemctl disable systemd-networkd systemd-networkd.socket
+systemd-networkd-wait-online` を実行し、上記 `timesyncd.conf.d` を配置しておけば、
+以降のイメージはこの問題を最初から回避できる。
+
 ## 今後の方向性
 
 - **カーネルの PKGBUILD 化**（ファイル注入をやめる）。pacman 管理下に入れば、

MAINTAINING.md

@@ -150,6 +150,51 @@ Watch the front-page announcements and forum on
 [archlinuxarm.org](https://archlinuxarm.org/), and
 [archlinuxarm/PKGBUILDs](https://github.com/archlinuxarm/PKGBUILDs) on GitHub.
 
+### Time sync (systemd-timesyncd) vs. networkd / NetworkManager conflict
+
+**Symptom**: on the device `timedatectl` stays at `System clock synchronized: no`
+and the clock is badly off. `systemd-timesyncd` is `active`, yet
+`timedatectl show-timesync` shows `PacketCount=0` and an empty `ServerName` —
+it **never sends a single NTP packet** (even though `ping` and a manual UDP 123
+query succeed).
+
+**Root cause (two layers)**:
+
+1. **The uConsole has no battery-backed RTC** (`timedatectl` reports
+   `RTC time: n/a`), so the clock drifts on every boot and network sync is
+   effectively mandatory.
+2. The base Arch Linux ARM (rpi) tarball ships with **`systemd-networkd`
+   enabled**, while `scripts/customize.sh` additionally enables
+   **NetworkManager** (around L148), so **both run at once**. The real link
+   (`wlan0`) is managed by NetworkManager, but networkd claims the unplugged
+   wired `end0`, stays stuck `configuring`, and writes
+   `ONLINE_STATE=offline` into `/run/systemd/netif/state`.
+   `systemd-timesyncd` reads that networkd-provided online state, concludes it
+   is offline, and **never starts syncing**.
+
+**Permanent fix (on device)**:
+
+```sh
+# NetworkManager is our chosen manager, so disable networkd to remove the conflict
+sudo systemctl disable --now systemd-networkd.socket systemd-networkd \
+  systemd-networkd-wait-online
+sudo systemctl mask systemd-networkd
+sudo rm -rf /run/systemd/netif        # drop the stale offline state
+# Pin Japanese NTP servers (optional but reliable)
+sudo install -Dm644 /dev/stdin /etc/systemd/timesyncd.conf.d/10-japan.conf <<'CONF'
+[Time]
+NTP=ntp.nict.jp 0.jp.pool.ntp.org 1.jp.pool.ntp.org
+FallbackNTP=0.arch.pool.ntp.org 1.arch.pool.ntp.org 2.arch.pool.ntp.org 3.arch.pool.ntp.org
+CONF
+sudo systemctl restart systemd-timesyncd
+timedatectl timesync-status   # ServerName=ntp.nict.jp / synced == OK
+```
+
+**TODO (fix in the image)**: in `scripts/customize.sh`, next to the
+NetworkManager enablement, also run `systemctl disable systemd-networkd
+systemd-networkd.socket systemd-networkd-wait-online` and drop the
+`timesyncd.conf.d` file above, so future images avoid this out of the box.
+
 ## Future directions
 
 - **Package the kernel as a PKGBUILD** instead of file-injection. Under pacman