docs: add guest image command inventory

docs/guest-image-tools.md

@@ -0,0 +1,97 @@
+# Guest Image Command-Line Tool Inventory
+
+This section documents the command-line tools available inside production dstack guest OS images. The guest image is a minimal Yocto-based Linux environment, not a full general-purpose Linux distribution.
+
+Use this inventory when writing `init_script`, `pre_launch_script`, operational scripts, or troubleshooting instructions that run inside a CVM.
+
+## Version Pages
+
+- [v0.5.1](./guest-image-tools/v0.5.1.md)
+- [v0.5.3](./guest-image-tools/v0.5.3.md)
+- [v0.5.4](./guest-image-tools/v0.5.4.md)
+- [v0.5.4.1](./guest-image-tools/v0.5.4.1.md)
+- [v0.5.5](./guest-image-tools/v0.5.5.md)
+- [v0.5.6](./guest-image-tools/v0.5.6.md)
+- [v0.5.6.1](./guest-image-tools/v0.5.6.1.md)
+- [v0.5.7](./guest-image-tools/v0.5.7.md)
+- [v0.5.8](./guest-image-tools/v0.5.8.md)
+- [v0.5.9](./guest-image-tools/v0.5.9.md)
+- [v0.5.10](./guest-image-tools/v0.5.10.md)
+
+## Compatibility Overview
+
+| Version | Major tool additions / notes |
+|---|---|
+| v0.5.1 | Same core tool set as the v0.5.4 baseline, minus `fusermount3`/`mount.fuse3` and `pigz`; includes `qemu-ga` (removed in later versions). |
+| v0.5.3 | Adds FUSE helpers (`fusermount3`, `mount.fuse3`); drops `qemu-ga`. Still no `pigz`. |
+| v0.5.4 / v0.5.4.1 | Baseline: Bash, BusyBox, curl, jq, systemd tools, Docker, WireGuard, legacy iptables. Adds `pigz` (takes over the `gzip`/`gunzip`/`zcat` names). |
+| v0.5.5 | Adds ext4/XFS tools such as `resize2fs`, `mkfs.ext4`, `mkfs.xfs`, `xfs_growfs`. |
+| v0.5.6 | Adds GPT tools such as `sgdisk`, `gdisk`, `fixparts`. |
+| v0.5.6.1 | Adds `rsync`, FUSE helpers, and Sysbox commands. |
+| v0.5.7 | Adds `parted` and `partprobe`. |
+| v0.5.8 | No major userspace command additions; nftables kernel support exists, but no `nft` command. |
+| v0.5.9 | No major userspace command additions; ipset kernel support exists, but no `ipset` command. |
+| v0.5.10 | Adds `nft` and `python3`; `iptables` remains legacy backend. |
+
+## Stable Baseline for v0.5.4+ Scripts
+
+For scripts that need to work across v0.5.4 and later, the safest baseline is:
+
+```text
+bash + BusyBox userland + curl + jq + systemd tools + docker + WireGuard + legacy iptables
+```
+
+Recommended guard pattern:
+
+```bash
+need() {
+    command -v "$1" >/dev/null 2>&1 || {
+        echo "missing command: $1" >&2
+        exit 1
+    }
+}
+
+need curl
+need jq
+need docker
+need iptables
+```
+
+Do not assume GNU extensions for BusyBox-provided commands, and do not assume optional tools such as `nft`, `parted`, `rsync`, `ipset`, `conntrack`, `ss`, `tc`, or `ethtool` unless the target version page lists them.
+
+## BusyBox Option Caveats
+
+Every 0.5.x image builds BusyBox 1.36.1 from the same pinned poky (kirkstone) defconfig, so applet behavior is identical across versions. A command being listed does NOT mean all of its common options exist — the defconfig disables several sub-features:
+
+| Applet | Missing | Cause | Workaround |
+|---|---|---|---|
+| `head` | `-c` (byte count) | `CONFIG_FEATURE_FANCY_HEAD` off | `dd bs=1 count=N` |
+| `dd` | `ibs=`, `obs=`, `conv=` | `CONFIG_FEATURE_DD_IBS_OBS` off | `bs=`, `count=`, `if=`, `of=`, `skip=`, `seek=` all work |
+| `passwd` | `--stdin` | BusyBox applet has no such option | see Password and Account Management below |
+| — | `chpasswd`, `cryptpw`, `mkpasswd` | `CONFIG_CHPASSWD` / `CONFIG_CRYPTPW` / `CONFIG_MKPASSWD` off | `openssl passwd -6` |
+
+`head -c` under `set -e` is a boot killer: the pipeline fails, the script dies, and the CVM never reaches `running`. This exact failure shipped in Phala Cloud pre-launch script v0.0.17 (see Phala-Network/phala-cloud-monorepo#1936 follow-up).
+
+## Password and Account Management
+
+The images carry only the BusyBox `passwd` applet plus the `su`/`login` binaries from shadow — no `chpasswd`, `usermod`, `chage`, `cryptpw`, or `mkpasswd` in any version. The only reliable non-interactive way to set a password is to write the crypt hash into `/etc/shadow` directly; `openssl` is present in every image (pulled in via ca-certificates):
+
+```bash
+HASH=$(openssl passwd -6 "$PASSWORD")
+sed -i "s|^root:[^:]*:|root:${HASH}:|" /etc/shadow
+```
+
+**Never lock accounts you still need to reach over SSH.** The dev-image sshd is OpenSSH built without PAM (`DISTRO_FEATURES` has no `pam`), and PAM-less OpenSSH treats a locked account (`!` prefix in the `/etc/shadow` password field, what `passwd -l` writes) as *deny all authentication* — public-key login is rejected too, unlike on PAM-enabled distros where locking only disables password auth. This locked users out of their dev CVMs in pre-launch v0.0.17 (Phala-Network/phala-cloud-monorepo#1936).
+
+## Development Images
+
+Development images (`dstack-dev-*`) include additional debugging tools such as `ssh`, `sshd`, `strace`, `tcpdump`, `gdb`, `gdbserver`, and `vim`. These tools are not part of the production image inventory unless listed on a version page.
+
+Two dev-image traits matter for scripts:
+
+- `sshd` is OpenSSH built without PAM — see the locked-account warning in Password and Account Management.
+- The images are built with `debug-tweaks`, so root's `/etc/shadow` password field starts out empty; scripts that key off "is a root password set" will take their empty-password branch on every fresh dev CVM.
+
+## Build Tree Note
+
+Pages up to v0.5.10 reference revisions of the standalone `meta-dstack` repository. From v0.5.11 the Yocto build tree lives inside the dstack repository under `os/yocto/`, so later version pages will reference dstack repository revisions instead.

docs/guest-image-tools/v0.5.1.md

@@ -0,0 +1,224 @@
+# dstack Guest Image Tools: v0.5.1
+
+This page lists command-line tools present in the production dstack guest image for this version. The image is minimal; many commands are BusyBox applets rather than full GNU/Linux utilities.
+
+## Image Metadata
+
+| Field | Value |
+|---|---|
+| Guest image version | `0.5.1` |
+| meta-dstack revision | `a141fc162b9ddeb073dcce0bbd483aabbecdb413` |
+| Image flavor | `prod` |
+
+This page is derived from the build recipes at the revision above (diffed against the verified v0.5.4 inventory); it has not been re-verified against a booted image.
+
+## Quick Availability Summary
+
+| Command | Available | Notes |
+|---|---:|---|
+| `nft` | no | introduced in v0.5.10 |
+| `iptables` | yes | legacy backend (`xtables-legacy-multi`) when present |
+| `ip` | yes | BusyBox implementation, not full iproute2 |
+| `ifconfig` | yes |  |
+| `route` | yes |  |
+| `ping` | yes |  |
+| `nslookup` | yes |  |
+| `curl` | yes |  |
+| `jq` | yes |  |
+| `docker` | yes |  |
+| `wg` | yes |  |
+| `parted` | no | introduced in v0.5.7 |
+| `sgdisk` | no | introduced in v0.5.6 |
+| `rsync` | no | introduced in v0.5.6.1 |
+| `python3` | no | present in v0.5.10 due to nftables dependencies |
+| `sysbox-runc` | no | introduced in v0.5.6.1 |
+
+## Commonly Requested Commands Not Present
+
+`bridge`, `chage`, `chpasswd`, `conntrack`, `cryptpw`, `ethtool`, `ipset`, `mkpasswd`, `nft`,
+`parted`, `python3`, `rsync`, `sgdisk`, `ss`, `ssh`, `sshd`, `tc`, `tcpdump`, `usermod`
+
+## Versioned Tool Groups
+
+### BusyBox 1.36.1
+
+These commands are BusyBox applets in this image. Applet sub-features are trimmed — notably no `head -c`, no `dd ibs=/obs=/conv=`, no `passwd --stdin`, and no `chpasswd`/`cryptpw`/`mkpasswd` applets. See [BusyBox Option Caveats](../guest-image-tools.md#busybox-option-caveats).
+
+`[`, `[[`, `addgroup`, `adduser`, `ascii`, `ash`, `awk`, `base32`, `basename`, `bunzip2`, `busybox`,
+`bzcat`, `bzip2`, `cat`, `chattr`, `chgrp`, `chmod`, `chown`, `chroot`, `clear`, `cmp`, `cp`,
+`cpio`, `crc32`, `cut`, `date`, `dc`, `dd`, `delgroup`, `deluser`, `df`, `diff`, `dirname`,
+`dnsdomainname`, `du`, `dumpkmap`, `dumpleases`, `echo`, `egrep`, `env`, `expr`, `false`, `fbset`,
+`fgrep`, `find`, `free`, `fuser`, `grep`, `gunzip`, `gzip`, `head`, `hostname`, `id`, `ifconfig`, `ifdown`, `ifup`,
+`ip`, `killall`, `less`, `ln`, `loadfont`, `loadkmap`, `logname`, `logread`, `ls`, `lspci`, `lsusb`,
+`lzcat`, `md5sum`, `mdev`, `microcom`, `mkdir`, `mkfifo`, `mknod`, `mktemp`, `mv`, `nc`, `netstat`,
+`nohup`, `nproc`, `nslookup`, `od`, `passwd`, `patch`, `pgrep`, `pidof`, `ping`, `ping6`, `printf`,
+`ps`, `pwd`, `rdate`, `readlink`, `realpath`, `reset`, `resize`, `rm`, `rmdir`, `route`,
+`run-parts`, `sed`, `seq`, `setconsole`, `sha1sum`, `sha256sum`, `shuf`, `sleep`, `sort`,
+`start-stop-daemon`, `stat`, `strings`, `stty`, `sync`, `sysctl`, `tail`, `tar`, `tee`, `telnet`,
+`test`, `tftp`, `time`, `top`, `touch`, `tr`, `traceroute`, `true`, `ts`, `tty`, `uname`, `uniq`,
+`unlink`, `unzip`, `uptime`, `users`, `usleep`, `vi`, `vlock`, `watch`, `wc`, `wget`, `which`,
+`who`, `whoami`, `xargs`, `xzcat`, `yes`, `zcat`
+
+### Bash 5.2.21
+
+`bash`, `bash.bash`, `sh`
+
+### dstack guest components 0.5.4
+
+`app-compose.sh`, `dstack-guest-agent`, `dstack-prepare.sh`, `dstack-util`
+
+### curl 8.7.1
+
+`curl`
+
+### jq 1.7.1
+
+`jq`
+
+### OpenSSL 3.2.3
+
+`openssl`
+
+### systemd 255.4
+
+`bootctl`, `busctl`, `halt`, `hostnamectl`, `init`, `journalctl`, `localectl`, `networkctl`,
+`poweroff`, `reboot`, `resolvconf`, `resolvectl`, `runlevel`, `shutdown`, `systemctl`,
+`systemd-ac-power`, `systemd-hwdb`, `systemd-id128`, `systemd-machine-id-setup`, `systemd-mount`,
+`systemd-notify`, `systemd-resolve`, `systemd-socket-activate`, `systemd-sysusers`,
+`systemd-tmpfiles`, `systemd-umount`, `telinit`, `timedatectl`, `udevadm`, `udevd`, `userdbctl`,
+`varlinkctl`
+
+### chrony 4.5
+
+`chronyc`, `chronyd`
+
+### Docker/Moby 25.0.3 + runc 1.1.12
+
+`docker`, `docker-init`, `docker-proxy`, `docker-runc`, `dockerd`
+
+### containerd v2.0.0-beta.2-204-gb1624c362.m
+
+`containerd`, `containerd-ctr`, `containerd-shim-runc-v2`, `ctr`, `docker-containerd`,
+`docker-containerd-ctr`
+
+### runc 1.1.12+dev
+
+`runc`
+
+### wireguard-tools 1.0.20210914
+
+`wg`, `wg-quick`
+
+### iptables 1.8.10 (legacy backend)
+
+The installed `iptables`, `iptables-save`, and `iptables-restore` commands use the legacy backend. `xtables-nft-multi` is not installed.
+
+`ip6tables`, `ip6tables-legacy`, `ip6tables-legacy-restore`, `ip6tables-legacy-save`,
+`ip6tables-restore`, `ip6tables-save`, `iptables`, `iptables-legacy`, `iptables-legacy-restore`,
+`iptables-legacy-save`, `iptables-restore`, `iptables-save`, `iptables-xml`, `xtables-legacy-multi`
+
+### cryptsetup 2.7.2
+
+`cryptsetup`, `cryptsetup-ssh`, `integritysetup`, `veritysetup`
+
+### OpenZFS 2.2.5
+
+`arc_summary`, `arcstat`, `dbufstat`, `fsck.zfs`, `mpicalc`, `raidz_test`, `zdb`, `zed`, `zfs`,
+`zfs_ids_to_path`, `zgenhostid`, `zhack`, `zilstat`, `zinject`, `zpool`, `zstream`, `zstreamdump`,
+`ztest`, `zvol_wait`
+
+### util-linux 2.39.3
+
+`addpart`, `blkdiscard`, `blkid`, `blkid.util-linux`, `blkpr`, `blkzone`, `blockdev`,
+`blockdev.util-linux`, `cal`, `cal.util-linux`, `cfdisk`, `chcpu`, `chmem`, `choom`, `chrt`,
+`chrt.util-linux`, `col`, `colcrt`, `colrm`, `column`, `ctrlaltdel`, `delpart`, `dmesg`,
+`dmesg.util-linux`, `eject`, `eject.util-linux`, `fadvise`, `fallocate`, `fallocate.util-linux`,
+`fcntl-lock`, `fdisk`, `fdisk.util-linux`, `fincore`, `findfs`, `findfs.util-linux`, `findmnt`,
+`flock`, `flock.util-linux`, `fsck`, `fsck.cramfs`, `fsck.util-linux`, `fsfreeze`,
+`fsfreeze.util-linux`, `fstrim`, `fstrim.util-linux`, `getopt`, `getopt.util-linux`, `hardlink`,
+`hexdump`, `hexdump.util-linux`, `hwclock`, `hwclock.util-linux`, `i386`, `ionice`,
+`ionice.util-linux`, `ipcmk`, `ipcrm`, `ipcrm.util-linux`, `ipcs`, `ipcs.util-linux`, `irqtop`,
+`isosize`, `kill`, `kill.util-linux`, `last`, `last.util-linux`, `lastb`, `lastb.util-linux`,
+`ldattach`, `linux32`, `linux64`, `logger`, `logger.util-linux`, `look`, `losetup`,
+`losetup.util-linux`, `lsblk`, `lscpu`, `lsfd`, `lsipc`, `lsirq`, `lslocks`, `lslogins`, `lsmem`,
+`lsns`, `mcookie`, `mcookie.util-linux`, `mesg`, `mesg.util-linux`, `mkfs`, `mkfs.cramfs`, `mkswap`,
+`mkswap.util-linux`, `more`, `more.util-linux`, `mount`, `mount.util-linux`, `mountpoint`,
+`mountpoint.util-linux`, `namei`, `nologin`, `nologin.util-linux`, `nsenter`, `nsenter.util-linux`,
+`partx`, `pipesz`, `pivot_root`, `pivot_root.util-linux`, `prlimit`, `prlimit.util-linux`,
+`readprofile`, `readprofile.util-linux`, `rename`, `renice`, `renice.util-linux`, `resizepart`,
+`rev`, `rev.util-linux`, `rfkill`, `rfkill.util-linux`, `rtcwake`, `rtcwake.util-linux`, `script`,
+`scriptlive`, `scriptreplay`, `scriptreplay.util-linux`, `setarch`, `setpriv`, `setpriv.util-linux`,
+`setsid`, `setsid.util-linux`, `setterm`, `sfdisk`, `sulogin`, `sulogin.util-linux`, `swaplabel`,
+`swapoff`, `swapoff.util-linux`, `swapon`, `swapon.util-linux`, `switch_root`,
+`switch_root.util-linux`, `taskset`, `taskset.util-linux`, `uclampset`, `ul`, `umount`,
+`umount.util-linux`, `uname26`, `unshare`, `unshare.util-linux`, `utmpdump`, `utmpdump.util-linux`,
+`uuidd`, `uuidgen`, `uuidgen.util-linux`, `uuidparse`, `waitpid`, `wall`, `wall.util-linux`,
+`wdctl`, `whereis`, `wipefs`, `write`, `x86_64`, `zramctl`
+
+### e2fsprogs 1.47.0
+
+`e2fsck`, `fsck.ext2`, `fsck.ext3`, `fsck.ext4`
+
+### QEMU guest agent
+
+`qemu-ga`
+
+### kmod 31
+
+`depmod`, `depmod.kmod`, `insmod`, `insmod.kmod`, `kmod`, `lsmod`, `lsmod.kmod`, `modinfo`,
+`modinfo.kmod`, `modprobe`, `modprobe.kmod`, `rmmod`, `rmmod.kmod`
+
+### kbd 2.6.4
+
+`chvt`, `chvt.kbd`, `deallocvt`, `deallocvt.kbd`, `dumpkeys`, `fgconsole`, `fgconsole.kbd`,
+`getkeycodes`, `kbd_mode`, `kbdinfo`, `kbdrate`, `loadkeys`, `loadunimap`, `mapscrn`, `openvt`,
+`openvt.kbd`, `psfaddtable`, `psfgettable`, `psfstriptable`, `psfxtable`, `resizecons`, `setfont`,
+`setkeycodes`, `setleds`, `setmetamode`, `setvtrgb`, `showconsolefont`, `showkey`, `showkey.kbd`,
+`unicode_start`, `unicode_stop`
+
+### D-Bus 1.14.10
+
+`dbus-cleanup-sockets`, `dbus-daemon`, `dbus-launch`, `dbus-monitor`, `dbus-run-session`,
+`dbus-send`, `dbus-update-activation-environment`, `dbus-uuidgen`
+
+### shadow 4.14.2
+
+`faillock`, `groups`, `groups.shadow`, `login.shadow`, `mkhomedir_helper`, `newgrp`,
+`newgrp.shadow`, `pam_namespace_helper`, `pam_timestamp_check`, `pwhistory_helper`, `sg`, `su`,
+`su.shadow`, `unix_chkpwd`, `unix_update`
+
+### bridge-utils 1.7.1
+
+`brctl`, `brctl.bridge-utils`
+
+### device-mapper tools
+
+`dmsetup`, `dmstats`
+
+### libseccomp tools
+
+`scmp_sys_resolver`
+
+### ca-certificates
+
+`update-ca-certificates`
+
+### GnuPG helper
+
+`yat2m`
+
+### glibc 2.39
+
+`ldconfig`
+
+### mount-copybind helper
+
+`mount-copybind`
+
+## Notes for Scripts
+
+- Prefer `command -v` checks for optional tools.
+- Treat BusyBox applets as BusyBox-compatible, not GNU-compatible.
+- Use `docker compose`, not the standalone `docker-compose` command.
+- For firewall scripts, assume legacy `iptables` unless you explicitly require `nft` and check for it at runtime.
+- Put application-specific tools in your container image instead of relying on the guest OS.