buninu-linux 0.4.0 → 0.5.1

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

@@ -0,0 +1,105 @@
+# chroot — run a command inside another root directory
+
+`/bin/chroot` is a Bun script that calls `chroot(2)` and `mount(2)` through
+`/lib/dlopen.js`.
+
+Unlike the traditional `chroot`, it prepares the new root first, so a
+freshly unpacked root filesystem is usable straight away, and it undoes
+every mount it made when the command exits.
+
+## Synopsis
+
+```sh
+chroot NEWROOT [COMMAND [ARGUMENT...]]
+chroot [-n] [-k] [-v] NEWROOT [COMMAND [ARGUMENT...]]
+chroot -h | --help
+```
+
+With no COMMAND it runs `$SHELL` if that exists inside NEWROOT, otherwise
+`/bin/sh`, interactively when the terminal is one.
+
+## What it mounts
+
+| Inside NEWROOT | What | Why |
+|---|---|---|
+| `/proc` | a fresh `proc` | path resolution, `ps`, anything reading `/proc/self` |
+| `/sys` | a fresh `sysfs` | device and network information |
+| `/dev` | recursive bind of the host's `/dev`, made a slave mount | every device node, including `/dev/ptmx`, without a second devtmpfs |
+| `/dev/pts` | `devpts`, only if the bind brought none | pseudo-terminals for shells and editors |
+| `/run` | `tmpfs` | runtime state |
+| `/tmp` | `tmpfs` | scratch space that does not touch the root filesystem |
+| `/etc/resolv.conf` | bind of the host's file | name resolution, without editing anything inside |
+
+A mount point that already exists as a mount is left alone. A directory that
+is missing is created; if the root filesystem is read-only and that fails,
+that one mount is skipped and the rest still happen — use `-v` to see which.
+
+Making `/dev` a slave mount means mounts appearing inside the root do not
+propagate back to the host, and unmounting it afterwards cannot take the
+host's `/dev` with it.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-n`, `--no-mount` | Do not mount anything: the behaviour of the traditional `chroot`. Note that Bun itself cannot start without `/proc` and `/dev/urandom`, so `-n` suits statically linked programs. |
+| `-k`, `--keep-mounts` | Leave the mounts in place after the command exits, to enter the same root again cheaply. Clean up later with `umount -R`. |
+| `-v`, `--verbose` | Report every mount and unmount. |
+| `--` | End of options; everything after it is NEWROOT and COMMAND. |
+
+## Examples
+
+```sh
+# Mount a disk and enter the system on it
+mount /dev/vda2 /mnt --mkdir
+chroot /mnt
+
+# Run one command and leave
+chroot /mnt /bin/bun --version
+
+# Watch what is set up and taken down
+chroot -v /mnt /bin/sh -c 'ls /proc | head -3'
+
+# Traditional behaviour: nothing is mounted for you
+chroot -n /mnt /bin/sh
+
+# Keep the mounts for repeated visits
+chroot -k /mnt /bin/sh -c 'true'
+chroot -k /mnt
+umount -R /mnt
+```
+
+## Cleanup
+
+When the command exits, every mount this invocation made is unmounted,
+deepest first, including anything that appeared under the recursive `/dev`
+bind. A mount that is still busy — a process left running inside, a shell
+with its working directory there — is detached instead (`MNT_DETACH`), so
+the kernel releases it once its last user goes away. The same cleanup runs
+if `chroot(2)` itself fails or the command cannot be started, and on
+`SIGTERM` or `SIGHUP`.
+
+`Ctrl-C` goes to the command, not to `chroot`, so the mounts are still
+removed after an interrupted program.
+
+## Limits
+
+- Needs to be superuser: `chroot(2)` requires `CAP_SYS_CHROOT`, and the
+  mounts require `CAP_SYS_ADMIN`. Buninu normally runs as root.
+- The new root must contain the program you ask for and whatever it links
+  against; `chroot /mnt /bin/sh` fails with "not found" if `/mnt/bin/sh`
+  is not there.
+- Only the filesystem view changes. Processes, network, users and the
+  hostname are shared with the host; this is not a container.
+- `-k` leaves mounts behind on purpose. `umount -R NEWROOT` removes them.
+
+## Exit status
+
+The command's own status, or `125` if `chroot` itself failed, `126` if the
+command was found but could not be run, and `127` if it was not found.
+
+## See also
+
+- Source: `/bin/chroot`
+- `mount --help`, `umount --help`
+- Shared native binding: `/lib/dlopen.js`

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

@@ -27,7 +27,7 @@ Use `-` as ARCHIVE to read from standard input or write to standard output.
 | `-C DIR`, `--directory=DIR` | Read input files from DIR, or extract into DIR. |
 | `-z`, `--gzip` | Create gzip-compressed tar, or explicitly identify gzip input. |
 | `--zstd` | Create or read a zstd-compressed tar. A `.zst` or `.tzst` input is also detected by name. |
-| `-v` | Print names while creating/extracting; with `-t`, also show each regular file's size and modification time. |
+| `-v` | Print names while creating/extracting; with `-t`, also show each member's size, modification time, kind and link target. |
 
 Short options can be combined, for example `-xzvf` or `-czf`.
 For the traditional first option word, the leading hyphen is optional, so
@@ -42,8 +42,34 @@ tar -xzf source.tar.gz -C /tmp/source
 tar -tf source.tar.gz
 tar --zstd -cf backup.tar.zst home
 tar --zstd -xf backup.tar.zst -C /mnt/restore
+
+# An Alpine root filesystem, symbolic links and all; then enter it
+tar -xzf alpine-minirootfs-3.24.1-x86_64.tar.gz -C /mnt/alpine
+chroot /mnt/alpine
 ```
 
+## Links
+
+Extraction restores symbolic links exactly as the archive records them,
+including absolute targets such as `/bin/busybox` and targets that do not
+exist yet, and it restores hard links. This is what GNU tar does, and it is
+what an unpacked root filesystem needs: an Alpine minirootfs is 335 symbolic
+links, 306 of them absolute, and without them the result has no `/bin/sh`.
+
+`Bun.Archive` creates only the symbolic links whose target is relative and
+stays inside the extraction directory, and skips hard links entirely, so
+this command reads the archive's own headers (ustar, GNU `L`/`K` long names,
+pax `x` records) and creates the rest itself once every file is in place.
+Nothing is ever written through a link, because the links are made last.
+
+A member's own name still follows GNU tar's rule: a leading `/` is dropped
+and a name containing `..` is refused, so an archive cannot write outside
+the extraction directory.
+
+The same header scan backs listing, so `-t` reports every member —
+directories, links, devices — and not just regular files. A symbolic link
+shows its target, a hard link the file it points at.
+
 ## Current Bun.Archive limits
 
 Creation stores regular files only. Symbolic links are rejected rather than
@@ -51,11 +77,9 @@ silently archived as the wrong type; modes, ownership, hard links, and empty
 directories are not preserved. Bun 1.4.3 also requires file contents to be
 materialized in memory before archive creation.
 
-Extraction restores directories and symbolic links, but Bun 1.4.3 skips hard
-links. Listing and verbose extraction use `Archive.files()`, so they report
-regular files only. Verbose listing can show their size and modification time,
-but not the unavailable mode or owner. Bun provides gzip and zstd codecs but no xz or bzip2 codec,
-so this command does not accept `.tar.xz` or `.tar.bz2`.
+Extraction does not restore modes, ownership or timestamps. Bun provides gzip
+and zstd codecs but no xz or bzip2 codec, so this command does not accept
+`.tar.xz` or `.tar.bz2`.
 
 Appending with `-r`/`rvf` is not supported. `Bun.Archive` has no append API;
 rebuilding an existing archive through `Archive.files()` would silently lose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu-linux",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "A Linux distribution running Bun as PID 1 with the Buninu userspace.",
   "type": "module",
   "main": "./index.js",
@@ -37,6 +37,6 @@
     "fetch": "./index.js -f",
     "pack": "./index.js -b",
     "start": "./index.js -r",
-    "check": "for f in ./index.js ./initramfs/init.js ./initramfs/lib/document.js ./initramfs/lib/dlopen.js ./initramfs/lib/fbdev.js ./initramfs/lib/canvas.js ./initramfs/lib/bunterm/glyphs.js ./initramfs/lib/bunterm/renderer.js ./initramfs/lib/bunterm/images.js ./initramfs/lib/bunterm/input.js ./initramfs/lib/bunterm/terminal.js ./initramfs/lib/modprobe.js ./initramfs/lib/power.js ./initramfs/bin/bunterm ./initramfs/bin/mount ./initramfs/bin/umount ./initramfs/bin/ip ./initramfs/bin/ps ./initramfs/bin/top ./initramfs/bin/poweroff ./initramfs/bin/reboot ./initramfs/bin/tar; do node --check \"$f\" || exit 1; done"
+    "check": "for f in ./index.js ./initramfs/init.js ./initramfs/lib/document.js ./initramfs/lib/dlopen.js ./initramfs/lib/fbdev.js ./initramfs/lib/canvas.js ./initramfs/lib/bunterm/glyphs.js ./initramfs/lib/bunterm/renderer.js ./initramfs/lib/bunterm/images.js ./initramfs/lib/bunterm/input.js ./initramfs/lib/bunterm/mouse.js ./initramfs/lib/bunterm/terminal.js ./initramfs/lib/modprobe.js ./initramfs/lib/power.js ./initramfs/bin/bunterm ./initramfs/bin/chroot ./initramfs/bin/mount ./initramfs/bin/umount ./initramfs/bin/ip ./initramfs/bin/ps ./initramfs/bin/top ./initramfs/bin/poweroff ./initramfs/bin/reboot ./initramfs/bin/tar ./initramfs/bin/stripansi; do node --check \"$f\" || exit 1; done"
   }
 }