refactor: give each rule and value of runplane one owner

.github/workflows/ci.yml

@@ -30,10 +30,13 @@ jobs:
       - run: go vet ./...
       # The non-Linux files must also compile, for development on macOS.
       - run: GOOS=darwin go vet ./...
+      # The tests of internal/initbin examine the runplane-init of make init.
+      - run: make init
       - run: go test ./...
-      # Tests of netlink, nftables, loop devices, and mounts skip without root.
+      # Tests of netlink, nftables, loop devices, mounts, and the debug shell
+      # of runplane-init skip without root.
       - name: go test as root
-        run: sudo --preserve-env=GOCACHE,GOMODCACHE,GOPATH,HOME "$(go env GOROOT)/bin/go" test ./internal/...
+        run: sudo --preserve-env=GOCACHE,GOMODCACHE,GOPATH,HOME "$(go env GOROOT)/bin/go" test ./init/... ./internal/...
         env:
           GOCACHE: /tmp/go-root-cache
 
@@ -53,6 +56,11 @@ jobs:
           cache: pnpm
           cache-dependency-path: web/pnpm-lock.yaml
       - run: pnpm install --frozen-lockfile
+      - uses: actions/setup-go@v7
+        with:
+          go-version-file: go.mod
+      # The committed spec, types, and limits must match the Go API.
+      - run: pnpm gen:api && git diff --exit-code -- src/api
       - run: pnpm typecheck
       - run: pnpm test
       - run: pnpm build
@@ -97,3 +105,18 @@ jobs:
           test ! -e /usr/local/bin/runplane
           test ! -e /etc/systemd/system/runplane.service
           sudo test ! -e /var/lib/runplane
+      # The tests that start real sandboxes, on the Docker and Sysbox that
+      # the uninstall keeps. The service and its firewall rules are gone, so
+      # the tests can own the runplane network. -p 1 runs one package at a
+      # time, because the two packages use the same network. The sandboxes
+      # run the runplane-init that make binary embedded.
+      - name: Sandbox tests on Docker and Sysbox
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y -q --no-install-recommends nftables
+          sudo docker build -q -t runplane-test internal/sandbox/sysbox/sysboxtest
+          sudo --preserve-env=GOCACHE,GOMODCACHE,GOPATH,HOME \
+            RUNPLANE_TEST_DOCKER=1 RUNPLANE_TEST_IMAGE=runplane-test \
+            "$(go env GOROOT)/bin/go" test -count=1 -p 1 -v ./internal/sandbox/sysbox/ ./internal/sandbox/devdocker/
+        env:
+          GOCACHE: /tmp/go-root-cache

.github/workflows/images.yml

@@ -1,17 +1,24 @@
 # Builds the base images for linux/amd64 and linux/arm64 and pushes them to
-# ghcr.io/<owner>/<repo>/runner-ubuntu-24.04 and -26.04. runplane pulls the
-# "latest" tag. A weekly build gets the new packages and tool versions.
+# ghcr.io/<owner>/<repo>/runner-<name>. runplane pulls the "latest" tag. A
+# weekly build gets the new packages and tool versions. The two matrices
+# must name the images and the build args of images/images.go
+# (images_test.go compares them).
 #
 # The builds use the runplane runners. QEMU builds the architecture that the
 # runner does not have, which makes that build much slower.
+#
+# The build context is the images folder, and images/.dockerignore keeps
+# only the Dockerfile in it. A change to images.go, its test, or the README
+# does not change an image, so it starts no build. A new image changes this
+# file too, because the matrices must name it.
 name: Images
 
 on:
   push:
     branches: [main]
-    paths: ['images/**', '.github/workflows/images.yml']
+    paths: ['images/Dockerfile', 'images/.dockerignore', '.github/workflows/images.yml']
   pull_request:
-    paths: ['images/**', '.github/workflows/images.yml']
+    paths: ['images/Dockerfile', 'images/.dockerignore', '.github/workflows/images.yml']
   schedule:
     - cron: '23 4 * * 1'
   workflow_dispatch:
@@ -24,7 +31,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        image: [ubuntu-24.04, ubuntu-26.04]
+        image:
+          - {name: ubuntu-24.04, ubuntu: '24.04', image_os: ubuntu24}
+          - {name: ubuntu-26.04, ubuntu: '26.04', image_os: ubuntu26}
         arch: [amd64, arm64]
     runs-on: runplane
     permissions:
@@ -33,7 +42,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
       - name: Image name
-        run: echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}/runner-${{ matrix.image }}" >> "$GITHUB_ENV"
+        run: echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}/runner-${{ matrix.image.name }}" >> "$GITHUB_ENV"
       - uses: docker/setup-qemu-action@v4
       - uses: docker/setup-buildx-action@v4
       - uses: docker/login-action@v4
@@ -46,20 +55,24 @@ jobs:
         id: build
         uses: docker/build-push-action@v7
         with:
-          context: images/${{ matrix.image }}
+          context: images
           platforms: linux/${{ matrix.arch }}
+          build-args: |
+            UBUNTU=${{ matrix.image.ubuntu }}
+            IMAGE_OS=${{ matrix.image.image_os }}
           labels: |
             org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
             org.opencontainers.image.revision=${{ github.sha }}
           outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=${{ github.event_name != 'pull_request' }}
       # VM mode copies the image into an ext4 root disk, so keep it small.
       - name: Check the size (3 GB or less)
         run: |
-          docker buildx build --platform linux/${{ matrix.arch }} --load -t size-check -q images/${{ matrix.image }} >/dev/null
+          docker buildx build --platform linux/${{ matrix.arch }} --load -t size-check -q \
+            --build-arg UBUNTU=${{ matrix.image.ubuntu }} --build-arg IMAGE_OS=${{ matrix.image.image_os }} images >/dev/null
           mb=$(docker run --rm size-check du -sxm / | cut -f 1)
           echo "Image size: $mb MB"
           if [ "$mb" -gt 3072 ]; then
-            echo "::error::${{ matrix.image }} uses $mb MB. The limit is 3072 MB."
+            echo "::error::${{ matrix.image.name }} uses $mb MB. The limit is 3072 MB."
             exit 1
           fi
       - name: Check that jobs find rustup
@@ -73,7 +86,7 @@ jobs:
       - uses: actions/upload-artifact@v7
         if: github.event_name != 'pull_request'
         with:
-          name: digests-${{ matrix.image }}-${{ matrix.arch }}
+          name: digests-${{ matrix.image.name }}-${{ matrix.arch }}
           path: ${{ runner.temp }}/digests/*
           if-no-files-found: error
 

Makefile

@@ -115,11 +115,11 @@ dev: init
 
 # runner-smoke downloads the latest actions/runner for this arch and starts
 # it in the local base image runplane/runner-ubuntu-24.04:local (docker build
-# --provenance=false -t runplane/runner-ubuntu-24.04:local images/ubuntu-24.04):
-# the .NET libraries must be in the image, and a bad JIT config must end the
-# runner.
+# --provenance=false -t runplane/runner-ubuntu-24.04:local --build-arg
+# UBUNTU=24.04 --build-arg IMAGE_OS=ubuntu24 images): the .NET libraries must
+# be in the image, and a bad JIT config must end the runner.
 runner-smoke:
-	go test -tags integration -count=1 -timeout 20m -v -run TestRealRunnerInBaseImage ./internal/image/
+	go test -tags integration -count=1 -timeout 20m -v -run TestRealRunnerInBaseImage ./internal/runner/
 
 # clean keeps the other files in .dev, such as notes.
 clean:

README.md

@@ -36,8 +36,8 @@ The script does these steps:
 3. It downloads runplane and makes sure that the signature of `SHA256SUMS` and the SHA-256 of each file are correct (refer to [Release](#release)).
 4. In container mode, it installs Docker Engine (only if the server does not have it) and Sysbox.
 5. In VM mode, it installs Firecracker v1.17.0, the jailer, and the guest kernel. It also gives the user `runplane-vm` a range of uids and gids, one for each VM. If the base image of the release repository is not public on GHCR, it installs Docker Engine, because runplane then builds the base image on the server. Docker builds images only, and the jobs operate in VMs.
-6. It writes `/etc/runplane/runplane.env` and the systemd units, then it starts `runplane.service`.
-7. It runs `runplane doctor` and shows the dashboard URL and a one-time setup code.
+6. It writes `/etc/runplane/runplane.env` and the systemd units, and it makes a one-time setup code. Then it starts `runplane.service`.
+7. It runs `runplane doctor` and shows the dashboard URL and the setup code.
 
 To see each step before the install, add `--dry-run`. The dry run changes nothing on the server.
 
@@ -66,7 +66,7 @@ In VM mode, the script installs Firecracker v1.17.0, which the runplane tests us
 curl -fsSL https://github.com/runplane/runplane/releases/latest/download/install.sh | sudo RUNPLANE_FIRECRACKER_VERSION=v1.16.1 sh
 ```
 
-To update runplane, run the install command again. You can also select the update in **Settings > General**, or run `sudo runplane update` on the server. In VM mode, the update also replaces the guest kernel with the kernel of the release. A restart of runplane does not stop the jobs that operate. A shutdown of the server stops the jobs that operate with the result `cancelled`.
+To update runplane, run the install command again. You can also select the update in **Settings > General**, or run `sudo runplane update` on the primary. In VM mode, the update also replaces the guest kernel with the kernel of the release. A restart of runplane does not stop the jobs that operate. A shutdown of the server stops the jobs that operate with the result `cancelled`.
 
 The primary updates its agents. When an agent connects with a different version, the primary sends it the update to its own release. After an update of the primary, the agents connect again and get the new release. The primary tries each version one time on each agent. If the update is not successful, the **Servers** page shows **Update failed** after the name of the server. The page of the server shows the reason. You can start the update again with **Update agent** in the menu of the server. A primary that is not a release build does not update its agents.
 
@@ -76,7 +76,7 @@ You can also update an agent by hand. Run this command on the agent server:
 curl -fsSL http://203.0.113.10:8484/install.sh | sudo sh
 ```
 
-The primary serves this script. Thus the agent gets the version of the primary. On an agent, the script keeps the registration in `/etc/runplane/agent.json` and does not install a primary. On the agent server, `sudo runplane update` installs the latest release.
+The primary serves this script. Thus the agent gets the version of the primary. On an agent, the script keeps the registration in `/etc/runplane/agent.json` and does not install a primary. An agent must run the release of its primary, so `sudo runplane update` does not operate on an agent.
 
 To remove runplane, run this command:
 
@@ -187,7 +187,7 @@ An agent must run the same release as the primary. The primary updates each agen
 
 **Warning:** Use runplane only with private repositories. A pull request from a fork of a public repository can run code on your server.
 
-In container mode, runplane always rejects jobs from public repositories. All Sysbox containers share the host kernel and one ID mapping, thus the isolation between jobs is weaker. In VM mode, runplane rejects jobs from public repositories and from fork pull requests, unless you change these settings. You can let jobs from public repositories run only if each server operates in VM mode.
+In container mode, runplane never runs jobs from public repositories. All Sysbox containers share the host kernel and one ID mapping, thus the isolation between jobs is weaker. In VM mode, runplane rejects jobs from public repositories and from fork pull requests, unless you change these settings. You can turn on the setting for public repositories only if each server operates in VM mode. While the setting is on, a server that connects in a different mode gets no runners, and the **Servers** page tells the cause. To give runners to that server again, turn the setting off.
 
 | Item | Container mode (Sysbox CE) | VM mode (Firecracker) |
 | --- | --- | --- |
@@ -196,7 +196,7 @@ In container mode, runplane always rejects jobs from public repositories. All Sy
 | Network model | One Docker bridge, with the MAC and IP binding in `bridge runplane` | A TAP with a /30 for each VM |
 | AppArmor | The Sysbox profile | Not applicable |
 | Host daemon on the `/proc` path | `sysbox-fs` (Sysbox issue 1018) | None |
-| Public repositories | Rejected | Permitted with the setting |
+| Public repositories | Never | Permitted with the setting |
 
 Sandboxes cannot connect to the host, to other sandboxes, to private networks, to `169.254.169.254`, or to the Azure host endpoint `168.63.129.16`. They can connect only to the public internet and to the runplane cache service on the host.
 
@@ -295,10 +295,10 @@ Other commands:
 | `sh deploy/test-install.sh` | Dry runs of `install.sh` in Ubuntu, Debian, and Fedora containers |
 | `kernel/build.sh --config-only` | A check of the guest kernel config, without a kernel build |
 
-The tests of netlink, nftables, loop devices, and mounts must have root access on Linux. To do these tests on macOS, use a Linux container:
+The tests of netlink, nftables, loop devices, mounts, and the debug shell of `runplane-init` must have root access on Linux. To do these tests on macOS, use a Linux container:
 
 ```sh
-docker run --rm --privileged -v "$PWD":/src -v "$HOME/go/pkg/mod":/go/pkg/mod -w /src golang:1.27 go test ./internal/...
+docker run --rm --privileged -v "$PWD":/src -v "$HOME/go/pkg/mod":/go/pkg/mod -w /src golang:1.27 go test ./init/... ./internal/...
 ```
 
 ## Release
@@ -321,4 +321,4 @@ A person who can change the release files can also change the `install.sh` of th
 
 **Caution:** Do not change the key after the first release. A binary with the earlier key cannot do a self-update to a release with a new key. On these servers, run the install command of the new release again.
 
-The `images.yml` workflow pushes the base images to GHCR each week and after each change in `images/`. The builds use the `runplane` label. QEMU builds the architecture that the runner does not have. After the first push, set the visibility of each image package on GHCR to public. Then servers pull the base images without a login, and VM mode does not need Docker. To do a check, run `docker logout ghcr.io && docker pull ghcr.io/<owner>/<repo>/runner-ubuntu-24.04:latest`.
+The `images.yml` workflow pushes the base images to GHCR each week and after each change of `images/Dockerfile`. The builds use the `runplane` label. QEMU builds the architecture that the runner does not have. After the first push, set the visibility of each image package on GHCR to public. Then servers pull the base images without a login, and VM mode does not need Docker. To do a check, run `docker logout ghcr.io && docker pull ghcr.io/<owner>/<repo>/runner-ubuntu-24.04:latest`.

cmd/runplane/agent.go

@@ -4,30 +4,38 @@ import (
 	"context"
 	"errors"
 	"flag"
-	"net/netip"
-	"slices"
 
 	"github.com/runplane/runplane/internal/agent"
 	"github.com/runplane/runplane/internal/config"
-	"github.com/runplane/runplane/internal/sandbox"
+	"github.com/runplane/runplane/internal/localnode"
+	"github.com/runplane/runplane/internal/policy"
 	"github.com/runplane/runplane/internal/version"
 )
 
 // runAgent operates the sandboxes of this server for the primary in
-// agent.json. The primary sends the settings when the agent connects.
+// agent.json. The primary sends the settings when the agent connects. The
+// agent keeps them, so that after a restart the sandboxes keep their egress
+// allowlist before the primary connects.
 func runAgent(ctx context.Context, args []string) error {
-	cfg, err := config.Parse(flag.NewFlagSet("agent", flag.ContinueOnError), args)
+	cfg, err := config.Parse(flag.NewFlagSet("agent", flag.ContinueOnError), args,
+		config.ServicePort, config.DataDir, config.Mode, config.Dev, config.DevInsecure)
 	if err != nil {
 		return err
 	}
 	log := newLogger(ctx, cfg)
-	if err := checkMode(cfg.Mode, cfg.DevInsecure); err != nil {
+	if err := policy.CheckMode(cfg.Mode, cfg.DevInsecure); err != nil {
 		return err
 	}
 	if err := cfg.EnsureDirs(); err != nil {
 		return err
 	}
-	l, err := newLocal(ctx, cfg, localConfig{mode: cfg.Mode, unit: "runplane-agent", listen: []string{servicePortAddr(cfg)}}, log)
+	settings, err := localnode.ReadSettings(cfg.AgentSettingsPath())
+	if err != nil {
+		log.Warn("the sandboxes have no egress allowlist until the primary connects", "err", err)
+	}
+	l, err := newLocal(ctx, cfg, localConfig{
+		mode: cfg.Mode, settings: settings, settingsFile: cfg.AgentSettingsPath(), doctor: doctorOptions(cfg, cfg.Mode, true, ""),
+	}, log)
 	if err != nil {
 		return err
 	}
@@ -38,18 +46,14 @@ func runAgent(ctx context.Context, args []string) error {
 	defer func() { stopNode(); <-nodeDone }()
 
 	proxy := agent.NewCacheProxy(l.driver, log.With("component", "cache"))
-	hasSandbox := func(ip netip.Addr) bool {
-		list, err := l.driver.List(context.Background())
-		return err == nil && slices.ContainsFunc(list, func(b sandbox.Sandbox) bool { return b.IP == ip.String() })
-	}
-	mir, stopPort, err := serveServicePort(cfg, cfg.Mode, hasSandbox, proxy, log)
+	stopPort, err := serveServicePort(cfg, l.node.Mirror(), proxy, log)
 	if err != nil {
 		return err
 	}
 	defer stopPort()
 
 	log.Info("runplane agent started", "version", version.String(), "mode", cfg.Mode, "config", cfg.AgentConfigPath())
-	err = agent.Run(ctx, agent.Config{Path: cfg.AgentConfigPath(), Node: l.node, CacheProxy: proxy, Mirror: mir.Stats, Logger: log})
+	err = agent.Run(ctx, agent.Config{Path: cfg.AgentConfigPath(), Node: l.node, CacheProxy: proxy, Version: version.Version, Logger: log})
 	if errors.Is(err, agent.ErrUpdated) {
 		// systemd starts the new binary. The sandboxes keep operating, and
 		// the driver takes them over after the restart.