buninu-linux 0.2.1 → 0.3.1

package/initramfs/lib/dlopen.js

@@ -0,0 +1,121 @@
+// /lib/dlopen.js — the shared libc binding for Buninu Linux commands.
+//
+// init.js opens musl on its own because it runs before /proc exists and must
+// not import anything. Every other command imports this module instead, so
+// the symbol table, the errno plumbing and the error messages live in one
+// place. The library is located relative to this file (/lib in the guest),
+// which also lets the commands run from a checkout for testing.
+
+import { dlopen, FFIType, ptr, read, CString } from "bun:ffi";
+
+export { ptr, read };
+
+// Everything that differs per CPU lives in this table: the musl file name
+// and the syscall numbers musl has no wrapper for. Struct layouts used by
+// the commands (ifreq, rtentry) are the LP64 ones and hold on both.
+const architectures = {
+  x64: { libc: "libc.musl-x86_64.so.1", SYS_finit_module: 313 },
+  arm64: { libc: "libc.musl-aarch64.so.1", SYS_finit_module: 273 },
+};
+export const arch = architectures[process.arch]
+  ?? (() => { throw new Error(`unsupported CPU architecture ${process.arch}`); })();
+
+// BUNINU_LIBC lets the commands run on a glibc host for testing:
+//   BUNINU_LIBC=/lib/aarch64-linux-gnu/libc.so.6 bun initramfs/bin/ip addr
+export const libcPath = process.env.BUNINU_LIBC ?? `${import.meta.dir}/${arch.libc}`;
+
+export const libc = dlopen(libcPath, {
+  mount: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.u64, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  umount2: {
+    args: [FFIType.ptr, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  reboot: {
+    args: [FFIType.i32],
+    returns: FFIType.i32,
+  },
+  sync: {
+    args: [],
+    returns: FFIType.void,
+  },
+  __errno_location: {
+    args: [],
+    returns: FFIType.ptr,
+  },
+  strerror: {
+    args: [FFIType.i32],
+    returns: FFIType.ptr,
+  },
+  open: {
+    args: [FFIType.ptr, FFIType.i32, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  close: {
+    args: [FFIType.i32],
+    returns: FFIType.i32,
+  },
+  ioctl: {
+    args: [FFIType.i32, FFIType.u64, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  socket: {
+    args: [FFIType.i32, FFIType.i32, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  syscall: {
+    args: [FFIType.i64, FFIType.i64, FFIType.ptr, FFIType.i64],
+    returns: FFIType.i32,
+  },
+  waitpid: {
+    args: [FFIType.i32, FFIType.ptr, FFIType.i32],
+    returns: FFIType.i32,
+  },
+});
+
+export const cString = (value) => new TextEncoder().encode(`${value}\0`);
+
+// musl reports failure as -1 plus errno; the raw syscall() wrapper does too.
+const errnoLocation = libc.symbols.__errno_location();
+export const errno = () => read.i32(errnoLocation);
+export const strerror = (code) => new CString(libc.symbols.strerror(code)).toString();
+
+export const Errno = {
+  EPERM: 1, ENOENT: 2, ESRCH: 3, EIO: 5, ENXIO: 6, EBADF: 9, EAGAIN: 11, ENOMEM: 12,
+  EACCES: 13, EBUSY: 16, EEXIST: 17, ENODEV: 19, ENOTDIR: 20, EISDIR: 21,
+  EINVAL: 22, EROFS: 30, ENOTEMPTY: 39, ENOPKG: 65, ENOTSUP: 95,
+  EADDRNOTAVAIL: 99, ENETUNREACH: 101,
+};
+
+export class SysError extends Error {
+  constructor(operation, code = errno()) {
+    super(`${operation}: ${strerror(code)}`);
+    this.name = "SysError";
+    this.operation = operation;
+    this.errno = code;
+  }
+}
+
+// Wraps a libc call: throws SysError on -1 unless errno is in `allowed`,
+// in which case the negated errno comes back so the caller can tell.
+export const check = (operation, result, allowed = []) => {
+  if (result !== -1) return result;
+  const code = errno();
+  if (allowed.includes(code)) return -code;
+  throw new SysError(operation, code);
+};
+
+// An AF_INET datagram socket is the handle every SIOC* interface and route
+// ioctl wants. `use` receives an ioctl(request, buffer, operation) closure.
+export const withInetSocket = (use) => {
+  const fd = check("socket(AF_INET, SOCK_DGRAM)", libc.symbols.socket(2, 2, 0));
+  try {
+    const ioctl = (request, buffer, operation, allowed) =>
+      check(operation, libc.symbols.ioctl(fd, request, ptr(buffer)), allowed);
+    return use(ioctl, fd);
+  } finally {
+    libc.symbols.close(fd);
+  }
+};

package/initramfs/lib/document.js

@@ -0,0 +1,6 @@
+// Shared renderer for /usr/share/doc/buninu-linux/<name>.md command manuals.
+export const showDocument = async (name) => {
+  const path = `${import.meta.dir}/../usr/share/doc/buninu-linux/${name}.md`;
+  const rendered = Bun.markdown.ansi(await Bun.file(path).text(), { hyperlinks: true });
+  process.stdout.write(rendered.endsWith("\n") ? rendered : `${rendered}\n`);
+};

package/initramfs/lib/modprobe.js

@@ -0,0 +1,235 @@
+// /lib/modprobe.js — kernel module loading shared by the Buninu Linux commands.
+//
+// There is no /sbin/modprobe for the kernel to call, so anything that needs a
+// driver (a filesystem, a block device, a NIC) has to load it, and its
+// dependencies, itself. fetch-alpine.sh ships the modules under
+// /lib/modules/<release>/ together with a modules.dep trimmed to that set and
+// the `fs-*` lines of modules.alias, and this module reads those.
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { libc, cString, check, ptr, Errno, arch } from "./dlopen.js";
+
+export const kernelRelease = () => {
+  if (process.env.KERNEL_RELEASE) return process.env.KERNEL_RELEASE;
+  try {
+    return readFileSync("/proc/sys/kernel/osrelease", "utf8").trim();
+  } catch {
+    return "unknown";
+  }
+};
+
+// /lib/modules/<release> in the guest; resolved relative to this file so a
+// checkout can be tested the same way.
+export const modulesDirectory = () => `${import.meta.dir}/modules/${kernelRelease()}`;
+
+// Module names are canonical with underscores: usb-common.ko is usb_common in
+// /proc/modules.
+const canonical = (name) => name.replaceAll("-", "_");
+
+const readIndex = (file) => {
+  try {
+    return readFileSync(`${modulesDirectory()}/${file}`, "utf8");
+  } catch {
+    return "";
+  }
+};
+
+// name -> { path, dependencies: [names] } from modules.dep.
+let dependencyTable;
+const dependencies = () => {
+  if (dependencyTable) return dependencyTable;
+  dependencyTable = new Map();
+  for (const line of readIndex("modules.dep").split("\n")) {
+    const separator = line.indexOf(":");
+    if (separator < 0) continue;
+    const path = line.slice(0, separator);
+    const deps = line.slice(separator + 1).trim().split(/\s+/).filter(Boolean);
+    dependencyTable.set(canonical(moduleName(path)), {
+      path,
+      dependencies: deps.map((dep) => canonical(moduleName(dep))),
+    });
+  }
+  return dependencyTable;
+};
+
+const moduleName = (path) => path.slice(path.lastIndexOf("/") + 1).replace(/\.ko(\.gz)?$/, "");
+
+// modules.alias: exact names (fs-ntfs -> ntfs3) in a map, and the device
+// patterns (pci:v000010ECd00008168sv*sd*bc*sc*i* -> r8169) as regexps.
+let aliasTable;
+const aliases = () => {
+  if (aliasTable) return aliasTable;
+  aliasTable = { exact: new Map(), patterns: [] };
+  for (const line of readIndex("modules.alias").split("\n")) {
+    const [keyword, pattern, target] = line.trim().split(/\s+/);
+    if (keyword !== "alias" || !target) continue;
+    const module = canonical(target);
+    if (/[*?]/.test(pattern)) {
+      const source = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*").replaceAll("?", ".");
+      aliasTable.patterns.push({ regexp: new RegExp(`^${source}$`), module });
+    } else {
+      aliasTable.exact.set(pattern, module);
+    }
+  }
+  return aliasTable;
+};
+
+export const resolveAlias = (alias) => {
+  const { exact } = aliases();
+  return exact.get(alias) ?? exact.get(canonical(alias)) ?? canonical(alias);
+};
+
+// The modules whose alias patterns match a device's modalias string.
+export const modulesForModalias = (modalias) => {
+  const found = [];
+  for (const { regexp, module } of aliases().patterns) {
+    if (regexp.test(modalias) && !found.includes(module)) found.push(module);
+  }
+  return found;
+};
+
+// What udev's coldplug does: read each device's modalias under
+// /sys/bus/<bus>/devices and load the drivers that claim it. `accept`
+// filters by modalias (e.g. PCI class 02 = network: /bc02/), `acceptModule`
+// by module name and path (e.g. only kernel/drivers/net/). A driver built
+// into the kernel has no alias line, so its device simply goes unreported.
+// Returns one
+// entry per device with the modules loaded, or the error, for it.
+export const modulePath = (name) => dependencies().get(resolveAlias(name))?.path ?? null;
+
+export const autoload = ({ buses = ["pci", "virtio", "usb"], accept = () => true, acceptModule = () => true } = {}) => {
+  const report = [];
+  for (const bus of buses) {
+    let devices;
+    try {
+      devices = readdirSync(`/sys/bus/${bus}/devices`);
+    } catch {
+      continue;
+    }
+    for (const device of devices) {
+      let modalias;
+      try {
+        modalias = readFileSync(`/sys/bus/${bus}/devices/${device}/modalias`, "utf8").trim();
+      } catch {
+        continue;
+      }
+      if (!accept(modalias, device)) continue;
+      const modules = modulesForModalias(modalias).filter((module) => acceptModule(module, modulePath(module) ?? ""));
+      if (modules.length === 0) continue;
+      const entry = { bus, device, modalias, modules, loaded: [], error: null };
+      for (const module of modules) {
+        try {
+          entry.loaded.push(...modprobe(module));
+        } catch (error) {
+          entry.error = error.message;
+        }
+      }
+      report.push(entry);
+    }
+  }
+  return report;
+};
+
+export const loadedModules = () => {
+  const loaded = new Set();
+  try {
+    for (const line of readFileSync("/proc/modules", "utf8").split("\n")) {
+      const name = line.split(" ")[0];
+      if (name) loaded.add(name);
+    }
+  } catch {}
+  return loaded;
+};
+
+export const isLoaded = (name) => loadedModules().has(canonical(name));
+
+// Built-in drivers are absent from /proc/modules and from modules.dep, so
+// the ones that matter to callers are listed in modules.builtin.
+let builtinTable;
+export const isBuiltin = (name) => {
+  if (!builtinTable) {
+    builtinTable = new Set(
+      readIndex("modules.builtin").split("\n").filter(Boolean).map((path) => canonical(moduleName(path))),
+    );
+  }
+  return builtinTable.has(canonical(name));
+};
+
+// finit_module(2) on one .ko file. EEXIST (loaded meanwhile, or built in
+// and registered under the same name) is not an error.
+export const insertModule = (path, parameters = "") => {
+  const fd = check(`open(${path})`, libc.symbols.open(ptr(cString(path)), 0, 0));
+  try {
+    const flags = path.endsWith(".gz") ? 4 : 0; // MODULE_INIT_COMPRESSED_FILE
+    // musl has no finit_module wrapper, so use its generic syscall(2).
+    const result = check(
+      `finit_module(${path})`,
+      libc.symbols.syscall(arch.SYS_finit_module, fd, ptr(cString(parameters)), flags),
+      [Errno.EEXIST],
+    );
+    return result === 0;
+  } finally {
+    libc.symbols.close(fd);
+  }
+};
+
+export class ModuleNotFound extends Error {
+  constructor(name) {
+    super(`module ${name} not found in ${modulesDirectory()}`);
+    this.name = "ModuleNotFound";
+    this.module = name;
+  }
+}
+
+// Loads `name` (a module name or a modules.alias key) and, first, whatever
+// modules.dep says it needs. Returns the list of modules actually inserted.
+export const modprobe = (name, parameters = "", { loaded = loadedModules(), inserted = [] } = {}) => {
+  const module = resolveAlias(name);
+  if (loaded.has(module) || isBuiltin(module)) return inserted;
+
+  const entry = dependencies().get(module);
+  if (!entry) throw new ModuleNotFound(module);
+
+  // modules.dep lists dependencies in reverse load order; recursing on each
+  // one covers the deps-of-deps case no matter how the line is ordered.
+  for (const dependency of [...entry.dependencies].reverse()) {
+    modprobe(dependency, "", { loaded, inserted });
+  }
+
+  const path = `${modulesDirectory()}/${entry.path}`;
+  if (!existsSync(path)) throw new ModuleNotFound(module);
+  if (insertModule(path, parameters)) inserted.push(module);
+  loaded.add(module);
+  return inserted;
+};
+
+// Load every selected module shipped in the initramfs (all modules by
+// default). This is useful on the small real-machine image, where there is no
+// userspace modprobe helper to satisfy a driver's later request for an
+// optional PHY or bus module. Keep going after an individual failure: a
+// module for absent hardware commonly rejects initialization, and that must
+// not prevent the remaining modules loading.
+export const modprobeAll = ({ accept = () => true } = {}) => {
+  const loaded = loadedModules();
+  const inserted = [];
+  const errors = [];
+  for (const [module, entry] of dependencies()) {
+    if (!accept(module, entry.path)) continue;
+    try {
+      modprobe(module, "", { loaded, inserted });
+    } catch (error) {
+      errors.push({ module, error: error.message });
+    }
+  }
+  return { inserted, errors };
+};
+
+// Best-effort variant for optional drivers: a missing module is not an error.
+export const tryModprobe = (name, parameters = "") => {
+  try {
+    return modprobe(name, parameters);
+  } catch (error) {
+    if (error instanceof ModuleNotFound) return null;
+    throw error;
+  }
+};

package/initramfs/lib/power.js

@@ -0,0 +1,35 @@
+// Shared implementation for /bin/poweroff and /bin/reboot.
+
+import { libc, check } from "./dlopen.js";
+import { showDocument } from "./document.js";
+
+export const LINUX_REBOOT_CMD_RESTART = 0x01234567;
+export const LINUX_REBOOT_CMD_POWER_OFF = 0x4321fedc;
+
+export const runPowerCommand = async ({ name, command, action }) => {
+  const arguments_ = process.argv.slice(2);
+
+  if (arguments_.length === 1 && (arguments_[0] === "-h" || arguments_[0] === "--help")) {
+    await showDocument(name);
+    return;
+  }
+
+  if (arguments_.length !== 0) {
+    console.error(`Usage: ${name} [-h | --help]`);
+    process.exit(1);
+  }
+
+  console.log(`${name}: syncing filesystems`);
+  libc.symbols.sync();
+  console.log(`${name}: ${action}`);
+  try {
+    check(`reboot(${command.name})`, libc.symbols.reboot(command.value));
+  } catch (error) {
+    console.error(`${name}: ${error.message}`);
+    process.exit(1);
+  }
+
+  // A successful reboot(2) never returns.
+  console.error(`${name}: reboot returned without ${action}`);
+  process.exit(1);
+};

package/initramfs/usr/share/doc/buninu-linux/ip.md

@@ -0,0 +1,155 @@
+# ip — show and configure network interfaces, addresses and routes
+
+`/bin/ip` is a Bun script with the iproute2 command grammar. It reads
+`/sys/class/net` and `/proc/net`, and configures the kernel through the
+classic `SIOC*` ioctls on an AF_INET socket bound in `/lib/dlopen.js` — the
+same calls `init.js` uses to bring up `lo` and `eth0` at boot. It does not
+speak rtnetlink, which keeps it small; the limits that come with that are
+listed at the end.
+
+## Synopsis
+
+```sh
+ip [-4 | -6] [-br] OBJECT [COMMAND] [ARGUMENTS]
+ip -h | --help | help                  # this page
+OBJECT  := link | address | route | neighbour
+```
+
+Any unambiguous prefix works, as in iproute2: `ip a`, `ip addr`, `ip li`,
+`ip r`, `ip n`, and `show`/`list`/`ls`, `del`/`delete`.
+
+## Global options
+
+| Option | Meaning |
+|---|---|
+| `-4` / `-6` | Show only IPv4 / IPv6 addresses. |
+| `-br`, `-brief` | One line per interface. |
+| `-f inet\|inet6` | Same as `-4` / `-6`. |
+| `-c`, `-s`, `-d`, `-o`, `-p` | Accepted for muscle memory, no effect. |
+
+## Links
+
+```sh
+ip link                        # every interface: flags, mtu, state, MAC
+ip -br link                    # eth0   UP   52:54:00:12:34:56 <BROADCAST,...>
+ip link show eth0
+ip link set eth0 up
+ip link set eth0 down
+ip link set eth0 mtu 1400
+ip link set eth0 address 02:00:00:00:00:01   # interface must be down
+ip link set eth0 name lan0
+ip link set eth0 promisc on
+ip link set eth0 up mtu 9000                 # several changes at once
+```
+
+`ip link add`/`delete` (vlan, bridge, dummy, ...) need rtnetlink and are not
+available.
+
+## Addresses
+
+```sh
+ip addr                        # links plus their inet / inet6 addresses
+ip -br addr                    # eth0   UP   10.0.2.15/24 fec0::5054:ff:fe12:3456/64
+ip -4 addr show eth0
+ip addr add 10.0.2.15/24 dev eth0
+ip addr add 192.168.1.10/24 brd + dev eth0
+ip addr replace 192.168.1.11/24 dev eth0     # change the address in place
+ip addr del 10.0.2.15/24 dev eth0
+ip addr flush dev eth0
+```
+
+One IPv4 address per interface: `add` refuses when one is already set (use
+`replace`, or `del` first). IPv6 addresses are shown from
+`/proc/net/if_inet6` but cannot be added or removed here.
+
+## Routes
+
+```sh
+ip route                       # default via 10.0.2.2 dev eth0
+                               # 10.0.2.0/24 dev eth0 proto kernel scope link src 10.0.2.15
+ip route add default via 10.0.2.2
+ip route add default via 10.0.2.2 dev eth0 metric 100
+ip route add 192.168.5.0/24 via 10.0.2.1
+ip route add 10.10.0.0/16 dev eth0           # on-link, no gateway
+ip route add 10.0.2.99 dev eth0              # host route (/32)
+ip route replace default via 10.0.2.1
+ip route del default
+ip route del 192.168.5.0/24
+```
+
+Without `dev`, the interface whose subnet contains the gateway is picked.
+IPv6 routes and `ip route get` are not available.
+
+## Neighbours
+
+```sh
+ip neigh                       # 10.0.2.2 dev eth0 lladdr 52:55:0a:00:02:02 REACHABLE
+```
+
+Read from `/proc/net/arp`. Entries cannot be added or flushed here.
+
+## Bringing up a wired network by hand
+
+The QEMU user-mode network `init.js` configures at boot, done manually:
+
+```sh
+ip link set eth0 up
+ip addr add 10.0.2.15/24 dev eth0
+ip route add default via 10.0.2.2
+echo 'nameserver 10.0.2.3' > /etc/resolv.conf
+ip -br addr && ip route
+```
+
+A real Ethernet port is the same three commands once its driver is loaded
+and the cable shows `LOWER_UP` in `ip link`; the address and gateway come
+from your network (there is no DHCP client yet). If `ip link` shows no
+`eth0`, load the driver first from the Bun REPL:
+
+```js
+cfg.net       // loads network modules and matches PCI/USB network devices
+```
+
+It uses `/lib/modprobe.js`'s `autoload()`, which reads each device's
+`modalias` under `/sys/bus/{pci,virtio,usb}/devices` and loads whatever
+`modules.alias` says claims it. An image built with `--real` carries Intel
+`e1000`/`e1000e`/`igb`/`igc`, Realtek `r8169` (+ PHY), Atheros `alx`,
+Broadcom `tg3` and the USB dongles `r8152`, `ax88179_178a`, `cdc_ether`.
+A single module by name: `require("/lib/modprobe.js").modprobe("e1000e")`.
+
+## Output format
+
+`ip link` / `ip addr` print the iproute2 layout:
+
+```
+2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 state UP qlen 1000
+    link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
+    inet 10.0.2.15/24 brd 10.0.2.255 scope global eth0
+    inet6 fe80::5054:ff:fe12:3456/64 scope link
+```
+
+`NO-CARRIER` appears when the link is up but has no carrier (unplugged, or
+the driver never attached).
+
+## Limits of the ioctl approach
+
+- One IPv4 address per interface, no secondary addresses, no labels.
+- IPv6: display only.
+- No `link add`/`del`, no `route get`, no `neigh add`, no policy routing,
+  no netns.
+- Route `proto`, `scope`, `src` and `table` words are accepted and ignored.
+
+## Exit status
+
+`0` ok, `1` bad usage or unknown object, `2` the kernel refused
+(`RTNETLINK answers: ...` style messages, plus the errno text).
+
+## See also
+
+- `mount --help`, `umount --help`
+- [ip(8)](https://man7.org/linux/man-pages/man8/ip.8.html),
+  [netdevice(7)](https://man7.org/linux/man-pages/man7/netdevice.7.html),
+  [route(7)](https://man7.org/linux/man-pages/man7/route.7.html)
+- [/proc/net/route](https://docs.kernel.org/filesystems/proc.html#networking-info-in-proc-net),
+  [sysfs net class](https://docs.kernel.org/ABI/testing/sysfs-class-net.html)
+- Source: `initramfs/bin/ip`, `initramfs/lib/dlopen.js` in
+  [buninu-linux](https://github.com/jjtseng93/buninu-linux)