docs: add guest image tool inventory

Author: Leechael

docs/guest-image-tools.md

@@ -0,0 +1,60 @@
+# 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.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.4 / v0.5.4.1 | Baseline: Bash, BusyBox, curl, jq, systemd tools, Docker, WireGuard, legacy iptables. |
+| 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.
+
+## 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.

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

@@ -0,0 +1,260 @@
+# dstack Guest Image Tools: v0.5.10
+
+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.10` |
+| meta-dstack revision | `2f417559793345cb9760abd49004bca1e5d28581` |
+| Image flavor | `prod` |
+
+## Quick Availability Summary
+
+| Command | Available | Notes |
+|---|---:|---|
+| `nft` | yes | 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` | yes | introduced in v0.5.7 |
+| `sgdisk` | yes | introduced in v0.5.6 |
+| `rsync` | yes | introduced in v0.5.6.1 |
+| `python3` | yes | present in v0.5.10 due to nftables dependencies |
+| `sysbox-runc` | yes | introduced in v0.5.6.1 |
+
+## Commonly Requested Commands Not Present
+
+`bridge`, `conntrack`, `ethtool`, `ipset`, `ss`, `ssh`, `sshd`, `tc`, `tcpdump`
+
+## Versioned Tool Groups
+
+### BusyBox 1.36.1
+
+These commands are BusyBox applets in this image.
+
+`[`, `[[`, `addgroup`, `adduser`, `ascii`, `ash`, `awk`, `base32`, `basename`, `bunzip2`, `busybox`,
+`bzcat`, `bzip2`, `cat`, `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`, `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`
+
+### Bash 5.2.21
+
+`bash`, `bash.bash`, `sh`
+
+### dstack guest components 0.5.10
+
+`app-compose.sh`, `dstack-guest-agent`, `dstack-prepare.sh`, `dstack-util`, `wg-checker.sh`
+
+### 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`, `mount.ddi`,
+`networkctl`, `poweroff`, `reboot`, `resolvconf`, `resolvectl`, `runlevel`, `shutdown`, `systemctl`,
+`systemd-ac-power`, `systemd-ask-password`, `systemd-cat`, `systemd-cgls`, `systemd-cgtop`,
+`systemd-creds`, `systemd-delta`, `systemd-detect-virt`, `systemd-dissect`, `systemd-escape`,
+`systemd-hwdb`, `systemd-id128`, `systemd-inhibit`, `systemd-machine-id-setup`, `systemd-mount`,
+`systemd-notify`, `systemd-path`, `systemd-resolve`, `systemd-run`, `systemd-socket-activate`,
+`systemd-stdio-bridge`, `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`
+
+### nftables 1.0.9
+
+`nft`
+
+### 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
+
+`badblocks`, `chattr`, `chattr.e2fsprogs`, `debugfs`, `dumpe2fs`, `e2freefrag`, `e2fsck`, `e2image`,
+`e2mmpstatus`, `e2undo`, `e4crypt`, `e4defrag`, `filefrag`, `fsck.ext2`, `fsck.ext3`, `fsck.ext4`,
+`logsave`, `lsattr`, `lsattr.e2fsprogs`, `mke2fs`, `mke2fs.e2fsprogs`, `mkfs.ext2`,
+`mkfs.ext2.e2fsprogs`, `mkfs.ext3`, `mkfs.ext4`, `mklost+found`, `populate-extfs.sh`, `resize2fs`
+
+### xfsprogs 6.6.0
+
+`fsck.xfs`, `mkfs.xfs`, `xfs_admin`, `xfs_bmap`, `xfs_copy`, `xfs_db`, `xfs_estimate`, `xfs_freeze`,
+`xfs_fsr`, `xfs_growfs`, `xfs_info`, `xfs_io`, `xfs_logprint`, `xfs_mdrestore`, `xfs_metadump`,
+`xfs_mkfile`, `xfs_ncheck`, `xfs_quota`, `xfs_repair`, `xfs_rtcp`, `xfs_spaceman`
+
+### GPT fdisk 1.0.9
+
+`fixparts`, `gdisk`, `sgdisk`
+
+### GNU parted 3.6
+
+`parted`, `partprobe`, `partprobe.parted`
+
+### rsync 3.2.7
+
+`rsync`, `rsync-ssl`
+
+### Sysbox 0.6.7
+
+`sysbox-fs`, `sysbox-mgr`, `sysbox-runc`
+
+### fuse3 3.16.2
+
+`fusermount`, `fusermount3`, `mount.fuse`, `mount.fuse3`, `ulockmgr_server`
+
+### pigz 2.8
+
+`gunzip`, `gzip`, `pigz`, `pigzcat`, `unpigz`, `zcat`
+
+### 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`
+
+### Python 3.12.6
+
+`python3`, `python3.12`
+
+### 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.