feat: enhance guest network configuration and recovery process for UVM

2026-09-23 08:20:35 +05:30
parent dca3cbde2f
commit 660ba9efee
9 changed files with 474 additions and 12 deletions
@@ -1203,6 +1203,48 @@ without a reboot. Use the updated CLI checkout, or restart the API server to
 load the updated code before using its start endpoint. Subsequent host
 disconnects, reconnects, and route changes require no UVM command.

+### Guest Reports `Network is Unreachable`
+
+An immediate `ping: connect: Network is unreachable` inside the VM indicates
+that the guest has no usable route to that destination. Inspect the guest's
+networking from its SSH shell:
+
+```sh
+ip -4 address show dev eth0
+ip -4 route
+```
+
+For the default UVM subnet, the route must include `default via 10.42.0.1 dev
+eth0`. The guest gateway is the **UVM bridge address**, even when the host's
+own uplink uses a different gateway.
+
+Older UVM Ubuntu images used `KeepConfiguration=static`. Ubuntu's network
+manager could preserve the guest address but remove its kernel-created
+`proto boot` default route. Inside the running guest, restore it immediately:
+
+```sh
+sudo ip -4 route replace default via 10.42.0.1 dev eth0 proto static
+ping -c 3 1.1.1.1
+```
+
+For a persistent repair, run the updated CLI **on the host**:
+
+```sh
+sudo ./uvm.py restart 10.42.0.2
+```
+
+This stops the VM, repairs its original UVM network profile on the retained
+disk, and boots it with explicit address/gateway settings. A stopped VM's
+`start` applies the same repair; `start` on an already-running VM refreshes
+host rules only. Per-VM provisioning also repairs cached older Ubuntu
+templates when creating new VMs. Use the configured `UVM_GATEWAY` and guest IP
+in place of these defaults for a custom subnet.
+
+Guest-edited profiles and custom images are preserved. For those, persist the
+correct `Address=` and `Gateway=` in the guest's own network configuration.
+
+### Verify Guest Internet Access
+
 Check DNS and HTTPS from the guest:

 ```sh
@@ -1215,6 +1257,7 @@ Common issues:
 | Symptom | First checks |
 |---|---|
 | Guest cannot reach the internet | Confirm the host can reach the same destination, bridge/TAP are up, and `uvm-egress` NAT/FORWARD rules exist; use `start VM` to refresh sharing. |
+| Guest immediately reports `Network is unreachable` | Inspect the guest's default route and apply the guest route recovery steps above. |
 | IP connectivity works but DNS fails | Check guest `/etc/resolv.conf` and DNS reachability. The Ubuntu template uses `1.1.1.1` and `8.8.8.8`; host loopback resolvers such as `127.0.0.53` are not reachable as guest loopback addresses. |
 | Requested guest IP is rejected | Confirm it is inside the configured subnet and not used, gateway, network, or broadcast. |
 | Create says TAP already exists | Inspect the interface; do not delete it unless you know it is stale UVM state. |