vxn: add Docker/Podman integration and CLI frontends

Add vdkr/vpdmn as Dom0 target packages with Xen auto-detection,
native Docker/Podman config sub-packages, and OCI runtime fixes
for Docker compatibility (JSON logging, root.path, kill --all,
monitor PID lifecycle).

Signed-off-by: Bruce Ashfield <bruce.ashfield@gmail.com>

2 files changed, 195 insertions, 0 deletions

diff --git a/recipes-core/vxn/README.md b/recipes-core/vxn/README.md
new file mode 100644
index 00000000..35802e31
--- /dev/null
+++ b/recipes-core/vxn/README.md
@@ -0,0 +1,159 @@
+# vxn — Docker CLI for Xen DomU Containers
+
+vxn runs OCI containers as Xen DomU guests. The VM IS the container — no
+Docker/Podman daemon runs inside the guest. The guest boots a minimal Linux,
+mounts the container's filesystem, and directly executes the entrypoint.
+
+## Packages
+
+| Package | Contents | Usage |
+|---------|----------|-------|
+| `vxn` | CLI, OCI runtime, blobs, containerd config | Base package (required) |
+| `vxn-vdkr` | `vdkr` — Docker-like CLI frontend | `IMAGE_INSTALL:append = " vxn-vdkr"` |
+| `vxn-vpdmn` | `vpdmn` — Podman-like CLI frontend | `IMAGE_INSTALL:append = " vxn-vpdmn"` |
+| `vxn-docker-config` | `/etc/docker/daemon.json` (vxn as default runtime) | `IMAGE_INSTALL:append = " vxn-docker-config"` |
+| `vxn-podman-config` | `/etc/containers/containers.conf.d/50-vxn-runtime.conf` | `IMAGE_INSTALL:append = " vxn-podman-config"` |
+
+## Execution Paths
+
+### 1. containerd (vctr/ctr) — recommended
+
+No additional packages needed beyond `vxn`. containerd is configured
+automatically via `/etc/containerd/config.toml`.
+
+```bash
+ctr image pull docker.io/library/alpine:latest
+vctr run --rm docker.io/library/alpine:latest test1 /bin/echo hello
+ctr run -t --rm --runtime io.containerd.vxn.v2 docker.io/library/alpine:latest tty1 /bin/sh
+```
+
+### 2. vdkr/vpdmn (Docker/Podman-like CLI, no daemon)
+
+Install `vxn-vdkr` or `vxn-vpdmn`. These are standalone frontends that
+auto-detect Xen (via `xl`) and manage containers without any daemon process.
+They handle OCI image pull/unpack on the host via skopeo.
+
+```bash
+vdkr run --rm alpine echo hello        # Docker-like
+vpdmn run --rm alpine echo hello       # Podman-like
+```
+
+Persistent DomU (memres) for faster subsequent runs:
+```bash
+vdkr vmemres start                     # Boot persistent DomU (~10s)
+vdkr run --rm alpine echo hello        # Hot-plug container (~1s)
+vdkr vmemres stop                      # Shutdown DomU
+```
+
+### 3. Native Docker with vxn runtime
+
+Install `vxn-docker-config` to register vxn-oci-runtime as Docker's default
+OCI runtime. Docker manages images (pull/tag/rmi) natively.
+
+```bash
+docker run --rm --network=none alpine echo hello
+docker run --rm --network=host alpine echo hello
+```
+
+**IMPORTANT: Networking** — Docker's default bridge networking is incompatible
+with VM-based runtimes. Docker tries to create veth pairs and move them into
+a Linux network namespace, but vxn containers are Xen DomUs with their own
+kernel network stack. You MUST use `--network=none` or `--network=host`.
+
+This is the same limitation as kata-containers. The long-term fix is a TAP
+bridge that connects Docker's network namespace to the DomU's vif (see TODO).
+
+For selective use (keep runc as default, use vxn per-run):
+```bash
+docker run --rm --runtime=vxn --network=none alpine echo hello
+```
+
+### 4. Native Podman with vxn runtime
+
+Install `vxn-podman-config` to register vxn-oci-runtime as Podman's default
+OCI runtime. Same networking constraints as Docker.
+
+```bash
+podman run --rm --network=none alpine echo hello
+```
+
+## Build Instructions
+
+```bash
+# Prerequisites in local.conf:
+DISTRO_FEATURES:append = " xen virtualization vcontainer"
+BBMULTICONFIG = "vruntime-aarch64 vruntime-x86-64"
+
+# Build (mcdepends auto-builds vruntime blobs)
+bitbake vxn
+
+# Dom0 image with containerd + Docker-like CLI
+IMAGE_INSTALL:append = " vxn vxn-vdkr"
+
+# Dom0 image with native Docker integration
+IMAGE_INSTALL:append = " vxn vxn-docker-config docker"
+
+bitbake xen-image-minimal
+```
+
+## Architecture
+
+```
+Docker/Podman/containerd → vxn-oci-runtime → xl create/unpause/destroy → Xen DomU
+                                                                            ↓
+                                                                      vxn-init.sh
+                                                                        mount rootfs
+                                                                        chroot + exec
+```
+
+The OCI runtime (`/usr/bin/vxn-oci-runtime`) implements the standard
+create/start/state/kill/delete lifecycle by mapping to xl commands:
+
+| OCI Command | xl Equivalent |
+|-------------|---------------|
+| create | xl create -p (paused) |
+| start | xl unpause |
+| state | xl list + monitor PID check |
+| kill SIGTERM | xl shutdown (10s grace) + xl destroy |
+| kill SIGKILL | xl destroy |
+| delete | xl destroy + cleanup state |
+
+## Networking Constraints (Native Docker/Podman)
+
+Docker and Podman's default bridge networking creates Linux veth pairs and
+moves one end into a container network namespace. This is fundamentally
+incompatible with VM-based runtimes where the "container" is a VM with its
+own kernel networking.
+
+**Current workarounds:**
+- `--network=none` — DomU uses its own xenbr0 networking
+- `--network=host` — Tells Docker/Podman to skip namespace setup
+
+**Future fix (TODO):**
+TAP bridge integration — read Docker's network namespace config from
+config.json, create a TAP device bridged to the DomU's vif. This is the
+approach kata-containers uses to provide Docker-compatible networking with
+VM isolation.
+
+**Not affected:**
+- `vctr`/`ctr` (containerd) — CNI is separate and opt-in
+- `vdkr`/`vpdmn` — Handle networking independently via xenbr0
+
+## Debugging
+
+```bash
+# OCI runtime log (all invocations)
+cat /var/log/vxn-oci-runtime.log
+
+# Per-container console capture (persists after container exit)
+ls /var/log/vxn-oci-runtime/containers/
+
+# Xen domain status
+xl list
+
+# Watch domain console
+xl console <domname>
+
+# Kill stuck domain
+xl destroy <domname>
+```
diff --git a/recipes-core/vxn/vxn_1.0.bb b/recipes-core/vxn/vxn_1.0.bb
index d16cbc77..a08dac09 100644
--- a/recipes-core/vxn/vxn_1.0.bb
+++ b/recipes-core/vxn/vxn_1.0.bb
@@ -67,6 +67,8 @@ SRC_URI = "\
     file://containerd-config-vxn.toml \
     file://containerd-shim-vxn-v2 \
     file://vctr \
+    file://vdkr.sh \
+    file://vpdmn.sh \
 "
 
 FILESEXTRAPATHS:prepend := "${THISDIR}/../../recipes-containers/vcontainer/files:"
@@ -221,6 +223,24 @@ do_install() {
     # Install vctr convenience wrapper
     install -m 0755 ${S}/vctr ${D}${bindir}/vctr
 
+    # Docker/Podman CLI frontends (sub-packages)
+    install -m 0755 ${S}/vdkr.sh ${D}${bindir}/vdkr
+    install -m 0755 ${S}/vpdmn.sh ${D}${bindir}/vpdmn
+
+    # Docker daemon config: register vxn-oci-runtime (vxn-docker-config sub-package)
+    # no-new-privileges=false is needed because vxn ignores Linux security features.
+    # Users must use --network=none or --network=host with vxn containers since
+    # Xen DomUs have their own kernel network stack and Docker's veth/namespace
+    # setup is incompatible with VM-based runtimes.
+    install -d ${D}${sysconfdir}/docker
+    printf '{\n  "runtimes": {\n    "vxn": {\n      "path": "/usr/bin/vxn-oci-runtime"\n    }\n  },\n  "default-runtime": "vxn"\n}\n' \
+        > ${D}${sysconfdir}/docker/daemon.json
+
+    # Podman config: register vxn-oci-runtime (vxn-podman-config sub-package)
+    install -d ${D}${sysconfdir}/containers/containers.conf.d
+    printf '[engine]\nruntime = "vxn"\n\n[engine.runtimes]\nvxn = ["/usr/bin/vxn-oci-runtime"]\n' \
+        > ${D}${sysconfdir}/containers/containers.conf.d/50-vxn-runtime.conf
+
     # Install shared scripts into libdir
     install -d ${D}${libdir}/vxn
     install -m 0755 ${S}/vrunner.sh ${D}${libdir}/vxn/
@@ -253,6 +273,22 @@ do_install() {
     fi
 }
 
+# Sub-packages for CLI frontends and native runtime config
+PACKAGES =+ "${PN}-vdkr ${PN}-vpdmn ${PN}-docker-config ${PN}-podman-config"
+
+FILES:${PN}-vdkr = "${bindir}/vdkr"
+FILES:${PN}-vpdmn = "${bindir}/vpdmn"
+FILES:${PN}-docker-config = "${sysconfdir}/docker/daemon.json"
+FILES:${PN}-podman-config = "${sysconfdir}/containers/containers.conf.d/50-vxn-runtime.conf"
+
+RDEPENDS:${PN}-vdkr = "${PN} bash"
+RDEPENDS:${PN}-vpdmn = "${PN} bash"
+RDEPENDS:${PN}-docker-config = "${PN} docker"
+RDEPENDS:${PN}-podman-config = "${PN} podman"
+
+# daemon.json conflicts with docker-registry-config (only one provider)
+RCONFLICTS:${PN}-docker-config = "docker-registry-config"
+
 FILES:${PN} = "\
     ${bindir}/vxn \
     ${bindir}/vxn-oci-runtime \