zosbuilder/docs/depmod-behavior.md

depmod behavior, impact on lazy-mounted module stores, and flist store rewriting

Summary (short answer)

• depmod builds the modules dependency/alias databases by scanning the modules tree under /lib/modules/. It reads metadata from each .ko file (.modinfo section) to generate:
  • modules.dep(.bin), modules.alias(.bin), modules.symbols(.bin), modules.devname, modules.order, etc.
• It does not load modules; it opens many files for small reads. On a lazy store, the first depmod run can trigger many object fetches.
• If modules metadata files are already present and consistent (as produced during build), modprobe can work without re-running depmod. Use depmod -A (update only) or skip depmod entirely if timestamps and paths are unchanged.
• For private S3 (garage) without anonymous read, post-process the .fl manifest to replace the store URI with your HTTPS web endpoint for that bucket, so runtime mounts fetch over the web endpoint instead of signed S3.

Details

1. What depmod actually reads/builds

• Inputs scanned under /lib/modules/:
  • .ko files: depmod reads ELF .modinfo to collect depends=, alias=, vermagic, etc. It does not execute or load modules.
  • modules.builtin and modules.builtin.modinfo: indicate built-in drivers so they are excluded from dep graph.
  • Optional flags:
    • depmod -F <System.map> and -E <Module.symvers> allow symbol/CRC checks; these are typically not required on target systems for generating dependency/alias maps.
• Outputs (consumed by modprobe/kmod):
  • modules.dep and modules.dep.bin: dependency lists and fast index
  • modules.alias and modules.alias.bin: modalias to module name mapping
  • modules.symbols(.bin), modules.devname, modules.order, etc.

Key property: depmod’s default operation opens many .ko files to read .modinfo, which on a lazy FUSE-backed store causes many small reads.

2. Recommended strategy with lazy flists

• Precompute metadata during build:
  • In the dev container, your pipeline already runs depmod (see kernel_build_modules()). Ensure the resulting metadata files in /lib/modules/ are included in the modules flist.
• At runtime after overmounting the modules flist:
  • Option A: Do nothing. If your path is the same (/lib/modules/), modprobe will use the precomputed .bin maps and will not need to rescan .ko files. This minimizes object fetches (only when a module is actually loaded).
  • Option B: Run depmod -A (update only if any .ko newer than modules.dep). This typically performs stats on files and only rebuilds if needed, avoiding a full read of all .ko files.
  • Option C: Run depmod -a only if you changed the module set or path layout. Expect many small reads on first run.

3. Firmware implications

• No depmod impact, but udev coldplug will probe devices. Keep firmware files accessible via the firmware flist mount (e.g., /lib/firmware).
• Since firmware loads on-demand by the kernel/driver, the lazy store will fetch only needed blobs.

4. Post-processing .fl to use a web endpoint (garage S3 private)

• Goal: Pack/upload blobs to private S3 using credentials, but ship a manifest (.fl) that references a public HTTPS endpoint (or authenticated gateway) that your rfs mount can fetch from without S3 signing.
• Approach A: Use rfs CLI (if supported) to edit store URIs within the manifest.
  • Example (conceptual): rfs flist edit-store -m dist/flists/modules-...fl --set https://web.example.com/bucket/prefix
• Approach B: Use sqlite3 to patch the manifest directly (the .fl is sqlite):
  • Inspect stores:
    • sqlite3 dist/flists/modules-...fl "SELECT id, uri FROM stores;"
  • Replace s3 store with web endpoint:
    • sqlite3 dist/flists/modules-...fl "UPDATE stores SET uri='https://web.example.com/bucket/prefix' WHERE uri LIKE 's3://%';"
  • Validate:
    • rfs flist inspect dist/flists/modules-...fl
• Notes:
  • The web endpoint you provide must serve the same content-addressed paths that rfs expects. Confirm the object path layout (e.g., /bucket/prefix/ab/cd/abcdef...).
  • You can maintain multiple store rows to provide fallbacks (if rfs supports trying multiple stores).

5. Suggested runtime sequence after overmount (with precomputed metadata)

• Mount modules flist read-only at /lib/modules/.
• Optionally depmod -A (cheap; no full scan).
• udevadm control --reload; udevadm trigger --action=add; udevadm settle
• Load required baseline modules (stage1) if needed; the lazy store ensures only requested .ko files are fetched.

6. Practical checklist for our scripts

• Ensure pack-modules includes:
  • /lib/modules//.ko
  • All modules.* metadata files (dep, alias, symbols, order, builtin, *.bin)
• After pack completes and blobs are uploaded to S3, patch the .fl manifest’s stores table to the public HTTPS endpoint of your garage bucket/web gateway.
• Provide verify utilities:
  • rfs flist inspect/tree
  • Optional local mount test against the web endpoint referenced in the manifest.

Appendix: Commands and flags

• Generate/update metadata (build-time): depmod -a
• Fast update at boot: depmod -A # only if newer/changed
• Chroot/base path (useful for initramfs image pathing): depmod -b -a
• Modprobe uses *.bin maps when present, which avoids parsing large text maps on every lookup.