buninu-linux 0.2.1 → 0.3.0

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)

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

@@ -0,0 +1,155 @@
+# mount — mount a filesystem
+
+`/bin/mount` is a Bun script. It calls `mount(2)` through `/lib/dlopen.js`
+and loads the kernel modules a filesystem or a disk needs through
+`/lib/modprobe.js`, because on Buninu Linux there is no `/sbin/modprobe` for
+the kernel to ask.
+
+## Synopsis
+
+```sh
+mount                                   # list mounted filesystems
+mount [-fv] [-t TYPE] [-o OPTIONS] SOURCE TARGET
+mount -L LABEL | -U UUID [-o OPTIONS] TARGET
+mount --bind | --rbind | --move OLD NEW
+mount -o remount[,ro|rw] TARGET
+mount -h | --help                       # this page
+```
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-t TYPE` | Filesystem type. Omitted or `auto`: read the superblock of SOURCE and pick one. |
+| `-o OPTIONS` | Comma-separated list, see below. May be repeated. |
+| `-r`, `--read-only` | Same as `-o ro`. |
+| `-w`, `--rw` | Same as `-o rw`. |
+| `-L LABEL`, `-U UUID` | Find the block device by label or UUID (ext2/3/4, FAT, exFAT, NTFS serial). |
+| `-B`, `--bind` | Bind-mount a directory or file somewhere else. |
+| `-R`, `--rbind` | Bind, including everything mounted below OLD. |
+| `-M`, `--move` | Move a mount to a new place. |
+| `--make-shared`, `--make-private`, `--make-rshared`, `--make-rprivate` | Change mount propagation of TARGET. |
+| `--mkdir` | Create TARGET first. |
+| `-v` | Say what is being loaded and mounted. |
+| `-f`, `--fake` | Show the `mount(2)` call and stop. |
+
+`-f` and `-v` may be combined as `-fv` or `-vf`; this probes and reports the
+filesystem without performing the mount.
+
+### `-o` words
+
+Flags: `ro` `rw` `nosuid` `suid` `nodev` `dev` `noexec` `exec` `sync` `async`
+`dirsync` `noatime` `atime` `nodiratime` `relatime` `strictatime` `lazytime`
+`nosymfollow` `remount` `bind` `rbind` `move` `shared` `private` `slave`
+`unbindable` `defaults`.
+
+Anything else (`size=64M`, `iocharset=utf8`, `uid=1000`, `force`, ...) goes
+to the filesystem driver unchanged.
+
+## Examples
+
+### tmpfs
+
+```sh
+mount -t tmpfs tmpfs /mnt/scratch
+mount -t tmpfs -o size=64M,mode=1777 tmpfs /tmp/big
+mount -t tmpfs -o remount,size=256M tmpfs /tmp/big   # grow it later
+```
+
+### ext4 (a Linux disk or partition)
+
+```sh
+mount /dev/vda2 /mnt                  # type detected, ext4 + jbd2 loaded
+mount -t ext4 -o ro,noatime /dev/vda2 /mnt
+mount -L rootfs /mnt                  # by label
+mount -U 3f2a...-...  /mnt            # by UUID
+mount -o remount,rw /mnt              # flip an ro mount to rw
+```
+
+`ext3` volumes mount with the ext4 driver; `ext2` uses its own module.
+
+### A Windows disk (NTFS)
+
+```sh
+mount /dev/sda3 /mnt/windows                     # ntfs3, read-write
+mount -t ntfs3 -o ro /dev/sda3 /mnt/windows      # look, don't touch
+mount -t ntfs3 -o force /dev/sda3 /mnt/windows   # volume left dirty by Windows
+mount -t ntfs3 -o windows_names,uid=1000,gid=1000 /dev/sda3 /mnt/windows
+```
+
+Windows Fast Startup and hibernation leave the volume marked dirty; ntfs3
+then refuses to mount read-write. Either boot Windows and shut it down
+fully, mount `-o ro`, or pass `force`. `windows_names` rejects names Windows
+could not open. The type name `ntfs` is accepted as an alias for `ntfs3`.
+
+### The EFI system partition, USB sticks, SD cards (FAT / exFAT)
+
+```sh
+mount /dev/vda1 /mnt/efi                                 # vfat, detected
+mount -t vfat -o iocharset=utf8,umask=022 /dev/sdb1 /mnt/usb
+mount -t exfat -o uid=1000,gid=1000 /dev/sdb1 /mnt/card
+```
+
+FAT and exFAT need NLS tables (`nls_utf8`, `nls_cp437`, `nls_iso8859-1`);
+`mount` loads them before calling the kernel, and also whatever
+`iocharset=`/`codepage=` names, if the module is shipped.
+
+### Bind mounts and moves
+
+```sh
+mount --bind /tmp/home /buninu/home
+mount --bind -o ro /usr/share/doc /mnt/doc   # bind, then remount read-only
+mount --rbind / /mnt/root                    # with all submounts
+mount --move /mnt/usb /media/usb
+```
+
+### Pseudo filesystems
+
+```sh
+mkdir -p /dev/pts && mount -t devpts -o gid=5,mode=620,ptmxmode=666 devpts /dev/pts
+mount -t proc proc /proc
+mount -t sysfs sysfs /sys
+mount -t devtmpfs devtmpfs /dev
+mount -t cgroup2 none /sys/fs/cgroup
+mount -t debugfs none /sys/kernel/debug
+```
+
+`/dev/pts` matters: since Linux 4.7 opening `/dev/ptmx` goes through
+`/dev/pts/ptmx`, so without this mount every pty open fails with `ENODEV`.
+`init.js` mounts it at boot.
+
+### Listing
+
+```sh
+mount                     # SOURCE on TARGET type TYPE (OPTIONS), from /proc/self/mounts
+cat /proc/self/mountinfo  # the long form
+```
+
+## How devices and drivers are found
+
+- A missing `/dev/vd*`, `/dev/sd*` or `/dev/nvme*` node makes `mount` load
+  `virtio_blk`, `sd_mod` (+ `ahci`, `usb_storage`) or `nvme` and wait up to
+  3 s for devtmpfs to create it.
+- The filesystem driver is loaded when `/proc/filesystems` does not list the
+  type; `modules.alias` turns `fs-ntfs` into `ntfs3`, `fs-ext3` into `ext4`.
+- Which modules are in the image is decided by `fetch-alpine.sh` in the
+  build tree; `--real` adds `sd_mod`, `ahci`, `nvme` and `usb-storage`.
+
+## Exit status
+
+`0` mounted, `1` bad usage, `32` the mount itself failed. Messages follow
+util-linux wording, and `dmesg` usually has the kernel's reason for `EINVAL`.
+
+## See also
+
+- `umount --help`, `ip --help`
+- [mount(2)](https://man7.org/linux/man-pages/man2/mount.2.html),
+  [mount(8)](https://man7.org/linux/man-pages/man8/mount.8.html)
+- [tmpfs](https://docs.kernel.org/filesystems/tmpfs.html),
+  [ext4](https://docs.kernel.org/admin-guide/ext4.html),
+  [ntfs3](https://docs.kernel.org/filesystems/ntfs3.html),
+  [vfat](https://docs.kernel.org/filesystems/vfat.html),
+  [devpts](https://docs.kernel.org/filesystems/devpts.html)
+- Source: `initramfs/bin/mount`, `initramfs/lib/dlopen.js`,
+  `initramfs/lib/modprobe.js` in
+  [buninu-linux](https://github.com/jjtseng93/buninu-linux)

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

@@ -0,0 +1,15 @@
+# poweroff — power off Buninu Linux
+
+`poweroff` flushes pending filesystem writes with `sync(2)`, then requests
+`LINUX_REBOOT_CMD_POWER_OFF` through Linux `reboot(2)`. It does not invoke a
+service manager or another command.
+
+## Usage
+
+```sh
+poweroff
+poweroff --help
+```
+
+The caller needs the kernel's `CAP_SYS_BOOT` capability. Buninu's root shell
+has it; otherwise the command reports `Operation not permitted` and exits.

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

@@ -0,0 +1,48 @@
+# umount — unmount a filesystem
+
+`/bin/umount` is a Bun script that calls `umount2(2)` through
+`/lib/dlopen.js`.
+
+## Synopsis
+
+```sh
+umount [-f] [-l] [-R] [-v] TARGET...
+umount -h | --help
+```
+
+TARGET is a mount point. Naming the device (`umount /dev/vda1`) is not
+supported; use `mount` with no arguments to see where it is mounted.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-l`, `--lazy` | Detach now, clean up when the last user goes away (`MNT_DETACH`). |
+| `-f`, `--force` | Force, for unreachable network filesystems (`MNT_FORCE`). |
+| `-R`, `--recursive` | Also unmount everything mounted below TARGET, deepest first. |
+| `-v` | Report each successful unmount. |
+
+## Examples
+
+```sh
+umount /mnt
+umount -l /mnt/windows        # something still has a file open
+umount -R /mnt/root           # a tree made with mount --rbind
+umount /tmp/big /mnt/usb      # several at once
+```
+
+"target is busy" means a process has its working directory or an open file
+inside the mount. On the Bun REPL, `process.chdir("/")` is usually the fix;
+`-l` is the escape hatch.
+
+## Exit status
+
+`0` all targets unmounted, `1` bad usage, `32` at least one failed.
+
+## See also
+
+- `mount --help`
+- [umount(2)](https://man7.org/linux/man-pages/man2/umount.2.html),
+  [umount(8)](https://man7.org/linux/man-pages/man8/umount.8.html)
+- Source: `initramfs/bin/umount` in
+  [buninu-linux](https://github.com/jjtseng93/buninu-linux)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu-linux",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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": "node --check ./index.js && node --check ./initramfs/init.js"
+    "check": "for f in ./index.js ./initramfs/init.js ./initramfs/lib/dlopen.js ./initramfs/lib/modprobe.js ./initramfs/bin/mount ./initramfs/bin/umount ./initramfs/bin/ip ./initramfs/bin/poweroff; do node --check \"$f\" || exit 1; done"
   }
 }