SwiftOS Administration Guide

This guide explains how to administer the current SwiftOS image. It is written for operators and release owners who maintain guest accounts, capability masks, base-image configuration, package attachments, service launch procedures, and verification evidence.

SwiftOS administration is image-centered today. Most durable changes are made on the host, repacked into the immutable base image, and verified by booting the guest. The running guest can use /tmp for scratch state, but it cannot persist system configuration changes across reboot.

Use this guide with:

• User Guide for interactive shell behavior.
• Security Guide for the authority model and guarantees.
• Update And Rollback Guide for artifact promotion and rollback.
• Service Guide for service lifecycle and health checks.
• Package Guide for package payload and package-store workflows.
• Support Guide for evidence collection.

Administrative Model

The current product profile is serial-first. There is no SSH server, web admin console, target-side user database editor, or service supervisor yet.

Choose An Administrative Workflow

Start from the administrative object you need to change. Durable changes are host-side inputs until a future target-side administration surface lands.

Example evidence bundle for an account change:

git log -1 --oneline
git diff -- base/etc/swos/passwd base/etc/passwd base/etc/group
make base-image
./tests/console_login_test.sh

After booting manually, log in as the changed account and capture:

id
cat /etc/motd
echo ok >/tmp/admin-check.txt

Admin Account Basics

The authoritative identity store is:

base/etc/swos/passwd

It is packed into the guest as:

/etc/swos/passwd

Each non-comment line has this shape:

name:principal:session:caps:salt$sha256hex:shell

The checked-in accounts are:

Compatibility views live in:

base/etc/passwd
base/etc/group

Those files help userland tools print names. They are not the kernel security policy source.

Capability Masks

Capability masks are decimal values in base/etc/swos/passwd. Combine the bits you want to grant.

Common masks:

Grant capConsole only to the boot/login context or to deliberately privileged admin flows. Ordinary service accounts should not need it.

Inspect Current Authority

Inside the guest, run:

id

Expected examples:

principal=1(root) session=1 caps=0x3f
principal=2(user) session=2 caps=0xe
principal=3 session=3 caps=0x2

If the process cannot read /etc/swos/passwd, id still prints numeric values. That is expected for restricted accounts without capFsRead.

Add Or Change An Account

Account changes are host-side image changes.

1. Choose a login name, principal id, session id, capability mask, salt, and shell.
2. Generate sha256(salt + password) in lowercase hex.
3. Edit base/etc/swos/passwd.
4. Optionally update base/etc/passwd and base/etc/group so tools can display names.
5. Rebuild build/base.img.
6. Boot and verify the login path.

Generate a password field:

salt=swos-netuser
password='change-me'
hash=$(printf '%s' "${salt}${password}" | shasum -a 256 | awk '{print $1}')
printf '%s$%s\n' "$salt" "$hash"

Example account with filesystem, tmpfs, and networking authority:

netuser:4:4:46:swos-netuser$REPLACE_WITH_HASH:/bin/sh

The decimal mask 46 is:

capSpawn + capFsRead + capTmpWrite + capNet
2 + 4 + 8 + 32

Optional compatibility view:

netuser:x:4:4:netuser:/home/netuser:/bin/sh

Optional group view:

netuser:x:4:

Rebuild and verify:

make base-image
./tests/console_login_test.sh

For a manual check, boot, log in as the new account, and run:

id
cat /etc/motd
echo ok >/tmp/netuser.txt
/bin/nslookup example.com

Use a QEMU network profile before testing networking.

Disable Or Restrict An Account

Because the identity store is immutable at runtime, disabling an account means editing base/etc/swos/passwd and repacking the image.

Options:

• Remove or comment out the account line.
• Change the password hash to a value no user knows.
• Reduce the capability mask.
• Change the shell to a known test shell when such a shell exists in the image.

Example: keep user readable but remove tmpfs write authority:

user:2:2:6:swos-user$REPLACE_WITH_HASH:/bin/sh

The mask 6 is capSpawn + capFsRead.

Verification:

make base-image
./tests/console_login_test.sh

Manual guest checks:

id
cat /etc/motd
echo should-fail >/tmp/restricted.txt

The read should work and the write should fail.

Administer Files And Configuration

Durable system files live in the base image:

After editing host-side base files:

make base-image
./tests/boot_test.sh

Inside the guest, system directories are read-only:

echo no >/etc/motd

Use /tmp only for runtime scratch:

mkdir /tmp/admin
echo ok >/tmp/admin/check.txt
cat /tmp/admin/check.txt

A reboot clears /tmp.

Administer Installed Software

There are two current install paths.

Base Image Programs

Use the base image for first-party tools and boot-critical content.

Typical flow:

make build base-image
./tests/boot_test.sh

If the change adds a command, add or run the focused command test that proves the new behavior.

Package Payloads

Use package payloads for software that should be tested without baking it into the base /bin.

Build and test the sample payload:

make package-fixture
make package-overlay-test

Build and test the package-store fixture:

make package-store-fixture
make package-store-test

Build and test the signed repository fixture:

make package-repo-fixture
make package-repo-install-test

Package payloads are read-only once active. The current system also has a narrow local target-side install path: pkg install FILE can append a local .swpkg to a writable package-store image and live-mount it. Signed repository install can run pkg repo set URL, pkg update [URL], pkg search, pkg info, and pkg install NAME against the static HTTP fixture while rejecting expired or incompatible catalogs, invalid dependency entries, and package hash mismatches. Name-based dependency resolution and streamed repository package installs into the package store are implemented; version-constraint solving, remove, upgrade, rollback, and public hosted package channels remain roadmap work.

Administer Services

Services currently run in the foreground from the serial shell. They inherit the current login principal and capability mask.

Common service commands:

Use the seeded root account for service validation unless you have created a service-specific account with capNet.

Important current limits:

• There is no service supervisor yet.
• A service stops when its foreground process exits.
• /bin/httpd and /bin/llmd both bind guest TCP 8080; run one at a time.
• Service logs are primarily serial output and in-guest command output.

Verification examples:

./tests/httpd_test.sh
./tests/tcp_echo_test.sh
./tests/udp_echo_test.sh
./tests/llm_serve_test.sh

Process And Resource Administration

Inside the guest:

ps
top -b -n 2 -d 1
id

Use Observability Guide for structured boot markers, process snapshots, service metrics, and panic evidence.

Current limits:

• No persistent process accounting database.
• No per-cell administrative control surface yet.
• No production daemon restart policy yet.

Network Administration

Networking requires both a QEMU virtio-net device and a process with capNet.

Operational checks:

/bin/nslookup example.com
/bin/tcpget 10.0.2.2 8080 /
/bin/tcpecho
/bin/udpecho

Use Networking Guide for full QEMU commands, host forwarding, IPv4, IPv6, TCP, UDP, DNS, and TLS test coverage.

Current limits:

• No target-side network configuration command.
• No persistent network profile store.
• No firewall or routing administration surface.
• TLS client trust validation is still a smoke path, not production policy.

Administrative Verification Matrix

For broad confidence:

make test

Support Handoff Checklist

When handing an administrative issue to support, include:

1. git log -1 --oneline.
2. git status --short --branch.
3. The boot profile used.
4. The account or principal used.
5. The output of id.
6. The exact file or service changed.
7. The rebuild commands run.
8. The acceptance test that failed or passed.
9. The serial log around the failure.
10. Whether /tmp, base image files, package images, or model files were involved.

Redact any non-test passwords, salts, private keys, model keys, or local tokens before sharing logs.

Roadmap Notes

The administration surface is intentionally small while the OS hardens its application-hosting profile. Future work includes:

• Stronger password KDF and rotation workflow.
• Target-side account management.
• Service manifests and a supervisor.
• Remote administration through an SSH or equivalent package.
• Persistent package install, upgrade, rollback, and repository metadata.
• Production update channels and key rotation beyond the checked A/B validation paths.
• Per-cell resource accounting and administrative policy.

Until those land, administer SwiftOS by treating signed images as the source of truth: edit host-side inputs, rebuild immutable artifacts, stage through the checked A/B paths when appropriate, boot, verify, and keep rollback artifacts available.

Edit this page on GitHub