Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions .coderabbit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -211,9 +211,21 @@ reviews:
The Unraid compatibility matrix; CI only, nothing here ships.
- install_test.sh puts the .plg through each Unraid version's own
plugin installer, hooks included, in a fresh Docker container with
no network; it must refuse to run anywhere else. Only Slackware's
upgradepkg and removepkg are stubbed, keeping their file-list
records: flag any other stand-in for Unraid's code.
no network; it must refuse to run anywhere else (lib.sh's guard).
Only Slackware's upgradepkg and removepkg are stubbed, keeping their
file-list records: flag any other stand-in for Unraid's code.
- fake_unraid.sh serves one Unraid version's real webGUI with php -S
and pages_test.php drives FV3 through it. Stand-ins are what the OS
image adds around the webGUI, nothing of the webGUI itself:
router.php (nginx's locations), prepend.php (php.ini's prepend),
docker.php (dockerd's socket and the docker CLI), libvirt.php (the
php-libvirt extension), rc_service.sh (rc.docker and rc.libvirt),
dmidecode.sh and ip.sh (those commands), connect_state.php (the
Connect plugin), the dockerd and libvirtd
processes, and emhttp's state files (var.ini, network.ini, the
docker and domain cfg). A call a stand-in does not answer fails
the run: flag an answer that hides one, and any stand-in for code
the webGUI repo has.
- matrix_check.py keeps ci.yml's Unraid rows at one per minor from the
.plg's min to the newest release; Renovate only moves rows.
- Each step asserts what the user is left with (live files, the
Expand Down
8 changes: 5 additions & 3 deletions .github/unraid-compat/Dockerfile
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# The PHP an Unraid version ships, plus what Unraid has and this image lacks: gawk (the .plg's remove script uses RT), xz
# (the package format) and wget (the installer's downloader, so a download fails on the network, not a missing tool).
# The PHP an Unraid version ships, plus Unraid's gawk (the remove script uses RT), xz (packages), procps (pages call pgrep)
# and wget (the installer's downloader, so a download fails on the network, not a missing tool)
ARG PHP
FROM php:${PHP}-cli
RUN apt-get update && apt-get install -y --no-install-recommends gawk wget xz-utils && rm -rf /var/lib/apt/lists/*
# Unraid's /bin/sh is bash: its exec() strings use &>
RUN apt-get update && apt-get install -y --no-install-recommends gawk procps wget xz-utils && rm -rf /var/lib/apt/lists/* \
&& ln -sf bash /bin/sh
3 changes: 3 additions & 0 deletions .github/unraid-compat/fake/connect_state.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<?php
// Stand-in for the Connect plugin's include/state.php, which the webGUI repo lacks from 7.2 on: 7.4's header requires it
class ServerState { public function getServerStateJsonForHtmlAttr() { return htmlspecialchars('{}'); } }
10 changes: 10 additions & 0 deletions .github/unraid-compat/fake/dmidecode.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
#!/bin/bash
# Stand-in for the OS image's dmidecode: the SMBIOS types Unraid's Dashboard reads, for a synthetic board with 16 GiB
case "$*" in
-qt0) printf 'BIOS Information\n\tVendor: Example BIOS\n\tVersion: 1.00\n\tRelease Date: 01/01/2025\n\n' ;;
-qt2) printf 'Base Board Information\n\tManufacturer: Example Boards\n\tProduct Name: FV3-TEST\n\tVersion: 1.0\n\tSerial Number: FV3-0001\n\n' ;;
-qt4) printf 'Processor Information\n\tSocket Designation: CPU0\n\tManufacturer: Example CPUs\n\tVersion: Example CPU 8-Core\n\tCurrent Speed: 3600 MHz\n\n' ;;
-qt16) printf 'Physical Memory Array\n\tLocation: System Board Or Motherboard\n\tUse: System Memory\n\tError Correction Type: None\n\tMaximum Capacity: 64 GB\n\tNumber Of Devices: 2\n\n' ;;
-qt17) for slot in A1 B1; do printf 'Memory Device\n\tSize: 8 GB\n\tLocator: DIMM_%s\n\tType: DDR4\n\tSpeed: 3200 MT/s\n\n' $slot; done ;;
*) echo "dmidecode UNKNOWN $* ($# arguments)" >> /var/log/fv3-fakes.log; exit 1 ;;
esac
91 changes: 91 additions & 0 deletions .github/unraid-compat/fake/docker.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<?php
// Fake Docker from fixtures/docker.json (Engine API answers of throwaway containers): `serve` answers /var/run/docker.sock,
// `cli <args>` is the docker CLI. A request it does not know is logged as UNKNOWN and refused.
$d = json_decode((string)@file_get_contents(__DIR__ . '/../fixtures/docker.json'), true);
if (!is_array($d)) { fwrite(STDERR, "fixtures/docker.json is unreadable\n"); exit(2); }

function fv3d_log(string $line): void { file_put_contents('/var/log/fv3-fakes.log', "docker $line\n", FILE_APPEND | LOCK_EX); }

function fv3d_container(array $d, string $ref): ?array {
foreach ($d['inspect'] as $ct) {
if (ltrim($ct['Name'], '/') === ltrim($ref, '/') || (strlen($ref) >= 12 && str_starts_with($ct['Id'], $ref))) return $ct;
}
return null;
}

function fv3d_running(array $d): array { return array_values(array_filter($d['containers'], fn($c) => $c['State'] === 'running')); }

function fv3d_answer(array $d, string $method, string $target): array {
$path = (string)parse_url($target, PHP_URL_PATH);
parse_str((string)parse_url($target, PHP_URL_QUERY), $query);
// Only `all` on the two lists is answered; a filter, any other parameter or all[] (Docker's key `all[]`, not `all`) is a
// request this fake does not know
$lists = in_array($path, ['/containers/json', '/images/json'], true);
if ($method !== 'GET' || array_diff(array_keys($query), $lists ? ['all'] : []) || array_filter($query, 'is_array')) return [null, null];
// Docker's httputils.BoolValue: empty, 0, no, false and none are false, any other value true
$all = !in_array(strtolower(trim($query['all'] ?? '')), ['', '0', 'no', 'false', 'none'], true);
if ($path === '/containers/json') return [200, $all ? $d['containers'] : fv3d_running($d)];
if (preg_match('#^/containers/([^/]+)/json$#', $path, $m)) {
$ct = fv3d_container($d, $m[1]);
return $ct ? [200, $ct] : [404, ['message' => "No such container: {$m[1]}"]];
}
if ($path === '/images/json') return [200, $d['images']];
if (preg_match('#^/images/(.+)/json$#', $path, $m)) {
foreach ($d['image_inspect'] as $id => $img) {
if ($m[1] === $id || in_array($m[1], $img['RepoTags'] ?? [], true)) return [200, $img];
}
return [404, ['message' => "No such image: {$m[1]}"]];
}
return [null, null];
}

// The docker CLI lines Unraid and FV3 run, matched argument by argument as the shell split them (--format too), and answered
// in the CLI's own output format
function fv3d_cli(array $d, array $args): ?array {
if ($args === ['network', 'ls', '--format={{.Name}}={{.Driver}}']) return array_map(fn($n) => "{$n['Name']}={$n['Driver']}", $d['networks']);
if ($args === ['ps', '-q', '--no-trunc']) return array_column(fv3d_running($d), 'Id');
// A label's presence only, as Unraid filters: label=key=value is a form this fake does not answer
if (count($args) === 5 && [$args[0], $args[1], $args[3], $args[4]] === ['ps', '--filter', '--format', '{{.Names}}'] && preg_match('/^label=([^\s=]+)$/', $args[2], $m)) {
return array_map(fn($c) => ltrim($c['Names'][0], '/'), array_values(array_filter(fv3d_running($d), fn($c) => isset($c['Labels'][$m[1]]))));
}
if ($args === ['stats', '--no-stream', '--format={{.ID}};{{.CPUPerc}};{{.MemUsage}}']) {
return array_map(fn($c) => substr($c['Id'], 0, 12) . ';0.50%;12.5MiB / 7.7GiB', fv3d_running($d));
}
return null;
}

if (($argv[1] ?? '') === 'cli') {
$args = array_slice($argv, 2);
$out = fv3d_cli($d, $args);
fv3d_log(($out === null ? 'UNKNOWN ' : '') . 'cli ' . implode(' ', $args) . ($out === null ? ' (' . count($args) . ' arguments)' : ''));
if ($out === null) exit(1);
echo $out ? implode("\n", $out) . "\n" : '';
exit(0);
}

if (($argv[1] ?? '') === 'serve') {
// It replaces the host's Docker socket: only inside fake_unraid.sh's container
if (!is_file('/.dockerenv') || !is_file('/var/run/fv3-fake-unraid')) { fwrite(STDERR, "docker.php serve runs only under fake_unraid.sh\n"); exit(2); }
$sock = '/var/run/docker.sock';
@unlink($sock);
$server = stream_socket_server("unix://$sock", $errno, $errstr);
if (!$server) { fwrite(STDERR, "docker.sock: $errstr\n"); exit(2); }
chmod($sock, 0666);
file_put_contents('/var/run/dockerd.pid', getmypid());
while (true) {
$conn = @stream_socket_accept($server, -1);
if (!$conn) continue;
$request = (string)fgets($conn);
while (($line = fgets($conn)) !== false && rtrim($line) !== '');
[$method, $target] = array_pad(explode(' ', trim($request)), 2, '');
[$status, $body] = fv3d_answer($d, $method, $target);
fv3d_log(($status === null ? 'UNKNOWN ' : '') . "socket $method $target");
if ($status === null) [$status, $body] = [404, ['message' => 'page not found']];
// One line of JSON with a length: DockerClient decodes the body line by line
$json = json_encode($body, JSON_UNESCAPED_SLASHES) . "\n";
fwrite($conn, "HTTP/1.1 $status " . ($status === 200 ? 'OK' : 'Not Found') . "\r\nContent-Type: application/json\r\nContent-Length: " . strlen($json) . "\r\nConnection: close\r\n\r\n$json");
fclose($conn);
}
}
fwrite(STDERR, "usage: docker.php serve | cli <docker arguments>\n");
exit(2);
9 changes: 9 additions & 0 deletions .github/unraid-compat/fake/ip.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
#!/bin/bash
# Stand-in for the OS image's ip: eth0's IPv4 address from network.ini, the one form Unraid's ipaddr() asks from 7.1
addr=$(sed -n 's/^IPADDR:0="\(.*\)"$/\1/p' /var/local/emhttp/network.ini 2>/dev/null)
# Matched on the argument count as well as the words, so the same words split another way are not answered
case "$#:$*" in
'7:-4 -br addr show eth0 scope global') [ -n "$addr" ] && echo "eth0 UP $addr/24 " && exit 0 ;;
esac
echo "ip UNKNOWN $* ($# arguments; network.ini address: ${addr:-none})" >> /var/log/fv3-fakes.log
exit 1
154 changes: 154 additions & 0 deletions .github/unraid-compat/fake/libvirt.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
<?php
// Stand-in for the php-libvirt extension, over fixtures/vms.json: reads answer from each domain's XML, and every other
// libvirt_* function the webGUI calls (7.0-7.4) is logged as UNKNOWN; one it never called is an undefined function.

// No function_exists() guard: PHP binds this file's functions before its first line runs, so one would always be true.

const VIR_DOMAIN_NOSTATE = 0;
const VIR_DOMAIN_RUNNING = 1;
const VIR_DOMAIN_BLOCKED = 2;
const VIR_DOMAIN_PAUSED = 3;
const VIR_DOMAIN_SHUTDOWN = 4;
const VIR_DOMAIN_SHUTOFF = 5;
const VIR_DOMAIN_CRASHED = 6;
const VIR_DOMAIN_PMSUSPENDED = 7;
const VIR_DOMAIN_XML_INACTIVE = 2;
const VIR_DOMAIN_DEVICE_MODIFY_LIVE = 1;
const VIR_DOMAIN_DEVICE_MODIFY_CONFIG = 2;
const VIR_CRED_AUTHNAME = 2;
const VIR_CRED_PASSPHRASE = 5;
const VIR_NETWORKS_ACTIVE = 1;
const VIR_NETWORKS_INACTIVE = 2;
const VIR_NETWORKS_ALL = 3;

function fv3l_log(string $line): void { @file_put_contents('/var/log/fv3-fakes.log', "libvirt $line\n", FILE_APPEND | LOCK_EX); }

function fv3l_domains(): array {
static $domains = null;
if ($domains === null) {
$raw = json_decode((string)@file_get_contents(__DIR__ . '/../fixtures/vms.json'), true);
if (!is_array($raw)) throw new RuntimeException('fixtures/vms.json is unreadable');
$domains = array_column($raw['domains'], null, 'name');
}
return $domains;
}

// Real resources, as php-libvirt hands out: Unraid's libvirt.php tells a handle from a name with is_resource()
function fv3l_handle(string $kind, string $name) {
static $handles = [];
$key = "$kind:$name";
return $handles[$key] ??= fopen('php://memory', 'r');
}

function fv3l_domain($dom): ?array {
foreach (fv3l_domains() as $name => $d) if (is_resource($dom) && fv3l_handle('domain', $name) === $dom) return $d;
$GLOBALS['fv3l_error'] = 'invalid domain handle';
return null;
}

function fv3l_lookup(string $field, $value) {
foreach (fv3l_domains() as $name => $d) if ($d[$field] === $value) return fv3l_handle('domain', $name);
$GLOBALS['fv3l_error'] = "Domain not found: no domain with matching $field '$value'";
return false;
}

// Unraid's Libvirt class connects read-write to qemu:///system; another URI or a read-only connection is not this fake
function libvirt_connect($uri = null, $readonly = true, $credentials = []) {
if ($uri !== 'qemu:///system' || $readonly !== false) { fv3l_log('UNKNOWN libvirt_connect to ' . var_export($uri, true) . ($readonly === false ? '' : ' read-only')); return false; }
return fv3l_handle('connection', 'qemu:///system');
}
function libvirt_get_last_error() { return $GLOBALS['fv3l_error'] ?? null; }
function libvirt_logfile_set($filename, $maxsize = 0) { return true; }
function libvirt_connect_get_uri($conn) { return 'qemu:///system'; }
function libvirt_connect_get_hostname($conn) { return 'Tower'; }
function libvirt_list_domains($conn) { return array_keys(fv3l_domains()); }
function libvirt_list_active_domain_ids($conn) { return array_values(array_map(fn($d) => $d['id'], array_filter(fv3l_domains(), fn($d) => $d['id'] > 0))); }
function libvirt_domain_lookup_by_name($conn, $name) { return fv3l_lookup('name', (string)$name); }
function libvirt_domain_lookup_by_uuid_string($conn, $uuid) { return fv3l_lookup('uuid', (string)$uuid); }
function libvirt_domain_get_name($dom) { return fv3l_domain($dom)['name'] ?? false; }
function libvirt_domain_get_uuid_string($dom) { return fv3l_domain($dom)['uuid'] ?? false; }
function libvirt_domain_get_id($dom) { $d = fv3l_domain($dom); return $d ? $d['id'] : false; }
function libvirt_domain_is_active($dom) { $d = fv3l_domain($dom); return $d ? $d['id'] > 0 : false; }
function libvirt_domain_get_autostart($dom) { $d = fv3l_domain($dom); return $d ? (int)$d['autostart'] : false; }
// The live XML only, as Unraid asks for it ($dom, 0): an xpath or flags would be a form this fake does not answer
function libvirt_domain_get_xml_desc($dom, $xpath = null, $flags = 0) {
if (!in_array($xpath, [null, 0, '0', ''], true) || $flags !== 0) { fv3l_log('UNKNOWN libvirt_domain_get_xml_desc with an xpath or flags'); return false; }
return fv3l_domain($dom)['xml'] ?? false;
}
function libvirt_list_domain_snapshots($dom) { return fv3l_domain($dom) ? [] : false; }

function libvirt_domain_get_info($dom) {
$d = fv3l_domain($dom);
if (!$d) return false;
$xml = simplexml_load_string($d['xml']);
return ['maxMem' => (int)$xml->memory, 'memory' => (int)$xml->currentMemory, 'state' => $d['state'], 'nrVirtCpu' => (int)$xml->vcpu, 'cpuUsed' => $d['id'] > 0 ? 12.5 : 0];
}

function libvirt_node_get_info($conn) {
return ['model' => 'x86_64', 'memory' => 16777216, 'cpus' => 8, 'nodes' => 1, 'sockets' => 1, 'cores' => 4, 'threads' => 2, 'mhz' => 3600];
}

// Each disk is a 20 GiB image at the path its XML names
function libvirt_domain_get_block_info($dom, $dev) {
$d = fv3l_domain($dom);
if (!$d) return false;
foreach (simplexml_load_string($d['xml'])->devices->disk as $disk) {
if ((string)$disk->target['dev'] !== (string)$dev) continue;
$size = 21474836480;
return ['device' => (string)$dev, 'file' => (string)$disk->source['file'], 'type' => (string)$disk->driver['type'], 'capacity' => $size, 'allocation' => $size, 'physical' => $size];
}
$GLOBALS['fv3l_error'] = "invalid argument: no disk with target $dev";
return false;
}

// Unraid's VM usage poller asks for every stat of every domain ($conn alone) and reads these keys; a stats or flags selection is
// a form this fake does not answer. An active domain (running or paused) has used some CPU time and holds all its memory
// (balloon.rss, which libvirt reports only for an active domain)
function libvirt_connect_get_all_domain_stats($conn, $stats = 0, $flags = 0) {
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
if ($stats !== 0 || $flags !== 0) { fv3l_log('UNKNOWN libvirt_connect_get_all_domain_stats with a stats or flags selection'); return false; }
$all = [];
foreach (fv3l_domains() as $name => $d) {
$info = libvirt_domain_get_info(fv3l_handle('domain', $name));
$all[$name] = ['state.state' => $d['state'], 'state.reason' => 1, 'cpu.time' => $d['id'] > 0 ? 125000000000 : 0,
'vcpu.current' => $info['nrVirtCpu'], 'vcpu.maximum' => $info['nrVirtCpu'], 'balloon.current' => $info['memory'],
'balloon.maximum' => $info['maxMem'], 'net.count' => 0, 'block.count' => 0] + ($d['id'] > 0 ? ['balloon.rss' => $info['memory']] : []);
}
return $all;
}

function libvirt_domain_get_counts($conn) {
$active = count(array_filter(fv3l_domains(), fn($d) => $d['id'] > 0));
return ['total' => count(fv3l_domains()), 'active' => $active, 'inactive' => count(fv3l_domains()) - $active];
}

// php-libvirt's answer: the matches' text in order, their count under 'num', and false when nothing matches
function libvirt_domain_xml_xpath($dom, $xpath, $flags = 0) {
if ($flags !== 0) { fv3l_log('UNKNOWN libvirt_domain_xml_xpath on the inactive XML'); return false; }
$d = fv3l_domain($dom);
if (!$d) return false;
$doc = new DOMDocument();
$doc->loadXML($d['xml']);
$nodes = @(new DOMXPath($doc))->query($xpath);
if ($nodes === false) { $GLOBALS['fv3l_error'] = "invalid xpath $xpath"; return false; }
if ($nodes->length === 0) return false;
$out = ['xpath' => $xpath, 'num' => $nodes->length];
foreach ($nodes as $i => $node) $out[$i] = $node->nodeValue;
return $out;
}

// Every other libvirt_* function in the webGUI's code at 7.0.1-7.4.0: none has an answer here yet
foreach (['libvirt_connect_get_information', 'libvirt_connect_get_capabilities', 'libvirt_connect_get_machine_types',
'libvirt_connect_get_domain_capabilities', 'libvirt_has_feature',
'libvirt_list_nodedevs', 'libvirt_nodedev_get', 'libvirt_nodedev_get_xml_desc', 'libvirt_nodedev_get_information',
'libvirt_nodedev_capabilities', 'libvirt_list_networks', 'libvirt_network_get', 'libvirt_network_get_xml_desc', 'libvirt_get_net_res',
'libvirt_get_net_list', 'libvirt_get_net_xml', 'libvirt_domain_interface_addresses',
'libvirt_domain_interface_stats', 'libvirt_domain_get_interface_devices', 'libvirt_domain_memory_stats',
'libvirt_domain_get_screen_dimensions', 'libvirt_domain_qemu_agent_command', 'libvirt_domain_define_xml', 'libvirt_domain_create_xml',
'libvirt_domain_undefine', 'libvirt_domain_update_device', 'libvirt_domain_create', 'libvirt_domain_destroy', 'libvirt_domain_shutdown',
'libvirt_domain_reboot', 'libvirt_domain_suspend', 'libvirt_domain_resume', 'libvirt_domain_managedsave', 'libvirt_domain_set_autostart',
'libvirt_domain_change_boot_devices', 'libvirt_domain_disk_remove', 'libvirt_domain_send_keys', 'libvirt_domain_send_pointer_event',
'libvirt_domain_snapshot_create', 'libvirt_domain_snapshot_delete', 'libvirt_domain_snapshot_get_xml', 'libvirt_domain_snapshot_lookup_by_name',
'libvirt_domain_snapshot_revert', 'libvirt_storagevolume_create_xml', 'libvirt_version'] as $fv3lName) {
eval("function $fv3lName(...\$args) { fv3l_log('UNKNOWN $fv3lName'); \$GLOBALS['fv3l_error'] = 'not in the fake'; return false; }");
}
unset($fv3lName);
5 changes: 5 additions & 0 deletions .github/unraid-compat/fake/prepend.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<?php
// auto_prepend_file of the PHP processes here, where Unraid's php.ini names local_prepend.php: the php-libvirt stand-in, then
// Unraid's own prepend. The php -S router does both itself, once it has set the script the request is for.
require_once __DIR__ . '/libvirt.php';
if (PHP_SAPI !== 'cli-server') require_once '/usr/local/emhttp/webGui/include/local_prepend.php';
5 changes: 5 additions & 0 deletions .github/unraid-compat/fake/rc_service.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
#!/bin/bash
# Stand-in for the OS image's /etc/rc.d/rc.docker and rc.libvirt: `status` says running (the Dashboard draws its tiles from it)
[ "$*" = status ] && exit 0
echo "rc UNKNOWN $0 $*" >> /var/log/fv3-fakes.log
exit 1
Loading
Loading