Files
maggesandClaude Sonnet 5 7e2ed451e3
Lint / ShellCheck (push) Successful in 14s
Lint / Validate .plg XML (push) Successful in 11s
Lint / EditorConfig (push) Successful in 6s
Add Apps/Store tab, template WebUI/URL import, container RO volumes/device passthrough/run-as-user, and in-app confirm dialogs
Replaces every native confirm() with a shared P.confirm() modal (a hung
native dialog was found live to block the whole tab, including
auto-refresh, and once even double-confirmed an unrelated deletion).
Also fixes Edit Container silently resetting to Bridge/blanking the
Static IP for any container on a custom network, and a context menu
losing its anchor to a mid-read auto-refresh.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-19 19:24:32 +00:00

570 lines
23 KiB
PHP

<?php
/**
* ajax/containers.php
*
* Backs the Containers panel (and the container rows nested inside the
* Pods panel — see ajax/pods.php). All actions go through PodmanClient,
* i.e. the real libpod REST API over podman.sock; nothing here shells out.
*
* Actions (?action=...):
* list GET -> normalized array of containers for the table view
* inspect GET (&id=...) -> raw inspect JSON, for a detail dialog
* start POST {"id": "..."}
* stop POST {"id": "...", "timeout": 10}
* restart POST {"id": "...", "timeout": 10}
* remove POST {"id": "...", "force": false}
* pause POST {"id": "..."}
* unpause POST {"id": "..."}
* kill POST {"id": "...", "signal": "SIGKILL"}
* rename POST {"id": "...", "name": "..."}
* logs GET (&id=...&tail=200) -> plain text
* events GET (&id=...&since=<unix seconds, default 7d ago>) -> array
* of this one container's already-happened events (create,
* start, stop, died, ...) — a bounded historical query, not a
* live stream; see PodmanClient::containerEvents()'s own doc
* comment for why that distinction matters here.
* list_gpus GET -> detected AMD/Intel GPUs (/dev/dri), for the Create Container form's optional passthrough toggle
* check_updates GET -> {"<image ref>": {"updateAvailable": bool, "error": "..."?}} for every image currently in use
* create POST {"image": "...", "name": "...", "networkMode": "bridge"|"host"|"none"|"<custom-network-name>",
* "staticIp": "10.1.1.222" (only meaningful with a custom/macvlan networkMode),
* "ports": [{"hostPort": 8080, "containerPort": 80, "protocol": "tcp"}],
* "volumes": [{"kind": "named"|"path", "source": "myvol"|"/mnt/...", "containerPath": "/data",
* "readOnly": false}],
* "env": [{"key": "...", "value": "..."}], "restartPolicy": "no", "pod": "<existing-pod-name>",
* "gpuDevices": ["/dev/dri/renderD128", "/dev/dri/card0"],
* "devices": [{"path": "/dev/ttyACM0"}] (arbitrary host device passthrough, same path on both
* sides — see build_container_spec()'s comment on why "same path both sides" is
* the only shape supported here),
* "privileged": false, "startAfterCreate": true, "icon": "https://..." (optional),
* "webuiUrl": "http://10.1.1.1:8080/" (optional),
* "user": "99:100" (optional — overrides the image's own default user; a real container
* migrated from Docker with an explicit --user needs this, since without it
* podman falls back to whatever USER the image itself declares, which may not
* own the bind-mounted appdata directory)}
*/
declare(strict_types=1);
require __DIR__ . '/../include/bootstrap.php';
$action = $_GET['action'] ?? '';
switch ($action) {
case 'list':
podman_json_response(containers_list($client));
break;
case 'inspect':
$id = (string) ($_GET['id'] ?? '');
if ($id === '') {
podman_json_error('Missing id', 400);
}
podman_json_response($client->inspectContainer($id));
break;
case 'logs':
$id = (string) ($_GET['id'] ?? '');
if ($id === '') {
podman_json_error('Missing id', 400);
}
$tail = (int) ($_GET['tail'] ?? 200);
podman_json_response(['text' => $client->containerLogs($id, $tail)]);
break;
case 'events':
$id = (string) ($_GET['id'] ?? '');
if ($id === '') {
podman_json_error('Missing id', 400);
}
$since = (int) ($_GET['since'] ?? (time() - 7 * 86400));
podman_json_response($client->containerEvents($id, $since));
break;
case 'start':
$body = podman_read_json_body();
$client->startContainer(require_id($body));
podman_json_response(['status' => 'started']);
break;
case 'stop':
$body = podman_read_json_body();
$client->stopContainer(require_id($body), (int) ($body['timeout'] ?? $podmanConfig->stopTimeoutSeconds));
podman_json_response(['status' => 'stopped']);
break;
case 'restart':
$body = podman_read_json_body();
$client->restartContainer(require_id($body), (int) ($body['timeout'] ?? $podmanConfig->stopTimeoutSeconds));
podman_json_response(['status' => 'restarted']);
break;
case 'remove':
$body = podman_read_json_body();
$client->removeContainer(require_id($body), (bool) ($body['force'] ?? false));
podman_json_response(['status' => 'removed']);
break;
case 'pause':
$body = podman_read_json_body();
$client->pauseContainer(require_id($body));
podman_json_response(['status' => 'paused']);
break;
case 'unpause':
$body = podman_read_json_body();
$client->unpauseContainer(require_id($body));
podman_json_response(['status' => 'unpaused']);
break;
case 'kill':
$body = podman_read_json_body();
$client->killContainer(require_id($body), (string) ($body['signal'] ?? 'SIGKILL'));
podman_json_response(['status' => 'killed']);
break;
case 'rename':
$body = podman_read_json_body();
$newName = trim((string) ($body['name'] ?? ''));
if ($newName === '') {
podman_json_error('Missing name in request body', 400);
}
$client->renameContainer(require_id($body), $newName);
podman_json_response(['status' => 'renamed']);
break;
case 'list_gpus':
podman_json_response(gpu_list());
break;
case 'check_updates':
podman_json_response(check_image_updates($client));
break;
case 'create':
$body = podman_read_json_body();
$image = trim((string) ($body['image'] ?? ''));
if ($image === '') {
podman_json_error('Missing image in request body', 400);
}
$spec = build_container_spec($image, $body);
// Unlike `podman run`, /containers/create does NOT auto-pull a
// missing image — it fails outright with a 404 "no such image"
// (found by live-testing the Create Container form against a
// freshly-typed image reference that wasn't pulled yet). Retry
// once after an explicit pull rather than always pulling
// up-front, so re-creating with an image the user already has
// stays fast and offline-friendly.
try {
$id = $client->createContainer($spec);
} catch (PodmanApiException $e) {
if ($e->httpStatus !== 404) {
throw $e;
}
$client->pullImage($image);
$id = $client->createContainer($spec);
}
if ($body['startAfterCreate'] ?? true) {
$client->startContainer($id);
}
podman_json_response(['id' => $id, 'status' => ($body['startAfterCreate'] ?? true) ? 'started' : 'created']);
break;
default:
podman_json_error("Unknown action '{$action}'", 400);
}
/**
* Checks every image currently backing a (non-infra) container against its
* origin registry — see RegistryClient for how, and why this isn't a
* podman/libpod feature at all. Deduplicated per unique image reference
* first (several containers commonly share the same image), so a host
* with e.g. five containers all on the same base image only makes one
* real registry request for it, not five.
*
* @return array<string,array<string,mixed>> keyed by image reference
*/
function check_image_updates(PodmanClient $client): array
{
$digestByImageId = [];
foreach ($client->listImages() as $img) {
$digestByImageId[(string) ($img['Id'] ?? '')] = (string) ($img['Digest'] ?? '');
}
$localDigestByRef = [];
foreach ($client->listContainers(true) as $c) {
if ($c['IsInfra'] ?? false) {
continue;
}
$ref = (string) ($c['Image'] ?? '');
$imageId = (string) ($c['ImageID'] ?? '');
if ($ref === '' || !isset($digestByImageId[$imageId])) {
continue;
}
$localDigestByRef[$ref] = $digestByImageId[$imageId];
}
$out = [];
foreach ($localDigestByRef as $ref => $localDigest) {
$out[$ref] = $localDigest === ''
? ['error' => 'No local digest recorded for this image.']
: RegistryClient::checkForUpdate($ref, $localDigest);
}
return $out;
}
/**
* Detects AMD/Intel GPUs via /dev/dri + sysfs — NOT via any podman/libpod
* API (libpod has no GPU inventory endpoint; this is plain host hardware
* detection). NVIDIA is deliberately excluded: it needs the separate
* nvidia-container-toolkit runtime, not a plain /dev/dri device passthrough,
* so listing it here would offer a checkbox that doesn't actually work.
* Verified live: card/render pairs from the same GPU share a "device"
* symlink target under /sys/class/drm, which is how they're grouped below;
* vendor 0x1002 = AMD, 0x8086 = Intel (PCI SIG IDs).
*
* @return array<int,array<string,mixed>>
*/
function gpu_list(): array
{
if (!is_dir('/sys/class/drm')) {
return [];
}
$byDevice = [];
foreach (scandir('/sys/class/drm') ?: [] as $entry) {
if (!preg_match('/^(card\d+|renderD\d+)$/', $entry)) {
continue;
}
$devicePath = "/sys/class/drm/{$entry}/device";
$target = @readlink($devicePath);
if ($target === false) {
continue;
}
$vendorFile = "{$devicePath}/vendor";
if (!is_file($vendorFile)) {
continue;
}
$vendorId = trim((string) @file_get_contents($vendorFile));
$byDevice[$target]['vendorId'] ??= $vendorId;
$byDevice[$target][str_starts_with($entry, 'card') ? 'card' : 'render'] = "/dev/dri/{$entry}";
}
$vendorNames = ['0x1002' => 'AMD', '0x8086' => 'Intel', '0x10de' => 'NVIDIA'];
$out = [];
foreach ($byDevice as $group) {
$vendorId = $group['vendorId'] ?? '';
$vendorName = $vendorNames[$vendorId] ?? $vendorId;
// NVIDIA needs the nvidia-container-toolkit runtime, not a plain
// /dev/dri passthrough — excluded so the checkbox we offer always
// actually works (see function comment).
if ($vendorName === 'NVIDIA' || !isset($group['render'])) {
continue;
}
$out[] = [
'vendor' => $vendorName,
'card' => $group['card'] ?? null,
'render' => $group['render'],
];
}
return $out;
}
/**
* Builds a libpod SpecGenerator body (POST /containers/create) from the
* WebUI's Create Container form fields. Field names/shapes here
* (portmappings, netns, networks, mounts, volumes, restart_policy) were
* verified live against a real podman system service — see
* PodmanClient::createContainer()'s header comment.
*
* @param array<string,mixed> $body
* @return array<string,mixed>
*/
function build_container_spec(string $image, array $body): array
{
$spec = ['image' => $image];
$name = trim((string) ($body['name'] ?? ''));
if ($name !== '') {
// Same character set podman itself enforces (define.NameRegex in
// libpod) — validated here too so a space/invalid character gets
// a clear message instead of podman's raw "running container
// create option: names must match ...: invalid argument" (found
// live: a template-derived container name with a space in it hit
// exactly this).
if (preg_match('/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/', $name) !== 1) {
podman_json_error(
"Container name (\"{$name}\") can only contain letters, digits, \".\", \"_\", \"-\" — no spaces. Try \"" .
preg_replace('/[^a-zA-Z0-9_.-]+/', '-', $name) . '" instead.',
400
);
}
$spec['name'] = $name;
}
$icon = trim((string) ($body['icon'] ?? ''));
$webuiUrl = trim((string) ($body['webuiUrl'] ?? ''));
$labels = [];
if ($icon !== '') {
$labels['podman-webui.icon'] = $icon;
}
if ($webuiUrl !== '') {
$labels['podman-webui.weburl'] = $webuiUrl;
}
if ($labels !== []) {
$spec['labels'] = $labels;
}
$env = [];
foreach (($body['env'] ?? []) as $row) {
$key = trim((string) ($row['key'] ?? ''));
if ($key !== '') {
$env[$key] = (string) ($row['value'] ?? '');
}
}
if ($env !== []) {
$spec['env'] = $env;
}
$ports = [];
foreach (($body['ports'] ?? []) as $row) {
$hostPort = (int) ($row['hostPort'] ?? 0);
$containerPort = (int) ($row['containerPort'] ?? 0);
if ($hostPort > 0 && $containerPort > 0) {
$ports[] = [
'host_ip' => '',
'host_port' => $hostPort,
'container_port' => $containerPort,
'protocol' => (string) ($row['protocol'] ?? 'tcp'),
];
}
}
if ($ports !== []) {
$spec['portmappings'] = $ports;
}
$mounts = [];
$volumes = [];
foreach (($body['volumes'] ?? []) as $row) {
$source = trim((string) ($row['source'] ?? ''));
$containerPath = trim((string) ($row['containerPath'] ?? ''));
if ($source === '' || $containerPath === '') {
continue;
}
// Verified live against a real bind mount (RW:false in the
// resulting inspect) that appending "ro" to the mount's own
// options is all read-only takes — no separate top-level flag.
$readOnly = (bool) ($row['readOnly'] ?? false);
if (($row['kind'] ?? 'named') === 'path') {
$options = ['rbind'];
if ($readOnly) {
$options[] = 'ro';
}
$mounts[] = ['destination' => $containerPath, 'type' => 'bind', 'source' => $source, 'options' => $options];
} else {
$volume = ['name' => $source, 'dest' => $containerPath];
if ($readOnly) {
$volume['options'] = ['ro'];
}
$volumes[] = $volume;
}
}
if ($mounts !== []) {
$spec['mounts'] = $mounts;
}
if ($volumes !== []) {
$spec['volumes'] = $volumes;
}
// "bridge"/"host"/"none" are podman's own reserved netns modes; any
// other value is an existing custom podman network's name, attached
// via the "networks" field instead (verified live: passing a
// network name through "networks" attaches it without needing an
// explicit netns mode at all).
$networkMode = (string) ($body['networkMode'] ?? 'bridge');
if (in_array($networkMode, ['bridge', 'host', 'none'], true)) {
$spec['netns'] = ['nsmode' => $networkMode];
} elseif ($networkMode !== '') {
// A static IP only makes sense on a custom (typically macvlan)
// network — verified live that "networks":{"<name>":{"static_ips":
// [...]}} assigns it, same as podman itself does for --ip. Basic
// IPv4-shape validation only (not full RFC-correctness) — this
// goes straight into a create request against the local podman
// socket, not anywhere it could reach untrusted input otherwise.
$staticIp = trim((string) ($body['staticIp'] ?? ''));
if ($staticIp !== '') {
if (preg_match('/^(\d{1,3}\.){3}\d{1,3}$/', $staticIp) !== 1) {
podman_json_error("Static IP (\"{$staticIp}\") doesn't look like a valid IPv4 address.", 400);
}
$spec['networks'] = [$networkMode => ['static_ips' => [$staticIp]]];
} else {
$spec['networks'] = [$networkMode => new \stdClass()];
}
}
if (isset($body['restartPolicy']) && $body['restartPolicy'] !== '') {
$spec['restart_policy'] = (string) $body['restartPolicy'];
}
if ($body['privileged'] ?? false) {
$spec['privileged'] = true;
}
$user = trim((string) ($body['user'] ?? ''));
if ($user !== '') {
// "99:100" (Unraid's own nobody:users, the overwhelming majority of
// real-world cases — a migrated container whose bind-mounted
// appdata was written by that user needs this override, since
// without it podman falls back to whatever USER the image itself
// declares), a bare UID, or a username — never anything that could
// be interpreted as a shell/path fragment, even though this goes
// straight into a podman API JSON body, not a shell.
if (preg_match('/^[a-zA-Z0-9_.-]+(:[a-zA-Z0-9_.-]+)?$/', $user) !== 1) {
podman_json_error("\"Run as user\" (\"{$user}\") must look like \"99:100\", \"1000\", or a username.", 400);
}
$spec['user'] = $user;
}
$devices = [];
foreach (($body['gpuDevices'] ?? []) as $path) {
// Only ever pass through paths matching the exact shape gpu_list()
// itself reports — the client only ever gets those as checkbox
// values, but this is the boundary where a tampered/malicious
// request body gets rejected rather than handing arbitrary host
// device paths (e.g. "/dev/sda") straight into the container spec.
if (is_string($path) && preg_match('#^/dev/dri/(card|renderD)\d+$#', $path) === 1) {
$devices[] = ['path' => $path];
}
}
// Generic device passthrough (e.g. a USB serial adapter like
// /dev/ttyACM0) — unlike the curated GPU list above, this comes
// straight from a free-text field, so it's restricted to a path
// actually under /dev/ (verified live against podman's own API that
// {"path": "/dev/x"} maps that host device at the SAME path inside
// the container — there's no separate "container path" field to
// remap it, matching how the overwhelming majority of real-world
// USB/serial passthrough is done anyway, e.g. this plugin's own
// migrated aoostar-rs template using `--device=/dev/ttyACM0:/dev/ttyACM0`,
// identical on both sides).
foreach (($body['devices'] ?? []) as $row) {
$path = trim((string) ($row['path'] ?? ''));
if ($path === '') {
continue;
}
if (preg_match('#^/dev/[A-Za-z0-9_./-]+$#', $path) !== 1 || str_contains($path, '..')) {
podman_json_error("Device path (\"{$path}\") must be an absolute path under /dev/.", 400);
}
$devices[] = ['path' => $path];
}
if ($devices !== []) {
$spec['devices'] = $devices;
}
$pod = trim((string) ($body['pod'] ?? ''));
if ($pod !== '') {
// "pod" joins an existing pod's shared network namespace — verified
// live that it can be sent alongside "netns" above without
// conflict (podman just defers to the pod's namespace).
$spec['pod'] = $pod;
}
return $spec;
}
/** @param array<string,mixed> $body */
function require_id(array $body): string
{
$id = (string) ($body['id'] ?? '');
if ($id === '') {
podman_json_error('Missing id in request body', 400);
}
return $id;
}
/**
* Normalizes libpod's /containers/json entries into exactly what the
* Containers table (javascript/containers.js) renders — keeping this
* shaping logic server-side means the frontend never has to know libpod's
* raw field names/quirks (e.g. Names is an array, State vs Status, etc).
*
* @return array<int,array<string,mixed>>
*/
function containers_list(PodmanClient $client): array
{
$raw = $client->listContainers(true);
$out = [];
foreach ($raw as $c) {
// Every pod has a hidden "infra" container managing its shared
// network namespace — not something a user creates or can
// meaningfully stop/remove on its own (found live: it always
// shows "running" with no independent lifecycle, so Containers
// panel gets a permanently un-removable row once any pod exists;
// it already appears as its own row in the Pods panel). See
// ajax/pods.php for actual pod lifecycle management.
if ($c['IsInfra'] ?? false) {
continue;
}
$names = $c['Names'] ?? [];
$name = is_array($names) && count($names) > 0 ? ltrim((string) $names[0], '/') : podman_short_id((string) ($c['Id'] ?? ''));
$ports = [];
foreach (($c['Ports'] ?? []) as $p) {
if (isset($p['host_port'], $p['container_port'])) {
$ports[] = "{$p['host_port']}:{$p['container_port']}/" . ($p['protocol'] ?? 'tcp');
} elseif (isset($p['container_port'])) {
$ports[] = "{$p['container_port']}/" . ($p['protocol'] ?? 'tcp');
}
}
$startedAt = podman_parse_time($c['StartedAt'] ?? null);
$state = strtolower((string) ($c['State'] ?? 'unknown'));
// One extra local-socket round trip per running container (~15ms
// each, verified live — negligible for a home host's container
// count). Best-effort: a container that stops between the list
// call above and this one shouldn't blank out the whole table.
$cpuPercent = null;
$memUsageBytes = null;
$memLimitBytes = null;
if ($state === 'running') {
try {
$stats = $client->containerStats((string) ($c['Id'] ?? ''));
$cpuPercent = isset($stats['cpu_stats']['cpu']) ? round((float) $stats['cpu_stats']['cpu'], 1) : null;
$memUsageBytes = isset($stats['memory_stats']['usage']) ? (int) $stats['memory_stats']['usage'] : null;
$memLimitBytes = isset($stats['memory_stats']['limit']) ? (int) $stats['memory_stats']['limit'] : null;
} catch (PodmanApiException $e) {
// leave stats null
}
}
$out[] = [
'id' => (string) ($c['Id'] ?? ''),
'shortId' => podman_short_id((string) ($c['Id'] ?? '')),
'name' => $name,
'image' => (string) ($c['Image'] ?? ''),
'state' => $state,
'status' => (string) ($c['Status'] ?? ''),
'health' => $c['Health']['Status'] ?? null,
'ports' => $ports,
'pod' => $c['Pod'] ?? null,
'podName' => $c['PodName'] ?? null,
'uptimeSeconds' => ($state === 'running' && $startedAt !== null) ? (time() - $startedAt) : null,
'createdAt' => podman_parse_time($c['Created'] ?? null),
'cpuPercent' => $cpuPercent,
'memUsageBytes' => $memUsageBytes,
'memLimitBytes' => $memLimitBytes,
// Set at create time (see build_container_spec()) from either
// the template it was created from or a manually-entered URL —
// this plugin's own label, not Unraid's real Docker manager's
// net.unraid.docker.icon (this isn't Docker, so reusing that
// name would misleadingly imply real interop with tools that
// read it).
'icon' => $c['Labels']['podman-webui.icon'] ?? null,
'webUrl' => $c['Labels']['podman-webui.weburl'] ?? null,
];
}
usort($out, static fn($a, $b) => strcmp($a['name'], $b['name']));
return $out;
}