fruix/docs/reports/phase4-freebsd-shepherd-bridge.md

Phase 4.3: FreeBSD Shepherd bridge layer for rc.d, network, filesystem, and account management

Date: 2026-04-01

Summary

This step adds a small FreeBSD-specific Shepherd bridge module and validates that Shepherd services can manage representative FreeBSD host concepts directly.

Added files:

• modules/fruix/shepherd/freebsd.scm
• tests/shepherd/run-freebsd-shepherd-bridge-prototype.sh

Bridge module

The new module exports reusable helper constructors for Shepherd services on FreeBSD:

• freebsd-rc-service
• freebsd-loopback-alias-service
• freebsd-tmpfs-service
• freebsd-user-group-service

These helpers provide a minimal but practical bridge between Shepherd service definitions and important FreeBSD host-management primitives.

What each helper does

freebsd-rc-service

Wraps FreeBSD rc.d control through:

• /usr/sbin/service <name> onestart
• /usr/sbin/service <name> onestop

This is the key bridge for rcng-equivalent functionality.

freebsd-loopback-alias-service

Manages loopback/network configuration by adding and removing a loopback alias using:

• /sbin/ifconfig lo0 alias ...
• /sbin/ifconfig lo0 -alias ...

freebsd-tmpfs-service

Manages filesystem setup by creating a mount point and mounting/unmounting tmpfs using:

• /bin/mkdir -p
• /sbin/mount -t tmpfs
• /sbin/umount

freebsd-user-group-service

Manages temporary user/group administration using:

• /usr/sbin/pw groupadd
• /usr/sbin/pw useradd
• /usr/sbin/pw userdel -r
• /usr/sbin/pw groupdel

Prototype harness

Run command:

METADATA_OUT=/tmp/freebsd-shepherd-bridge-metadata.txt \
./tests/shepherd/run-freebsd-shepherd-bridge-prototype.sh

The harness:

1. installs a temporary mock rc.d service under /usr/local/etc/rc.d/
2. starts a root-launched Shepherd instance with the new bridge module in GUILE_LOAD_PATH
3. defines a chained service graph:
   • bridge-rc
   • bridge-network
   • bridge-filesystem
   • bridge-account
   • bridge-target
4. automatically starts the top-level bridge target
5. validates host-side effects
6. stops the service graph and validates cleanup

Observed activation results

Observed metadata included:

• target_running=yes
• rc_started=yes
• alias_present=yes
• tmpfs_mounted=yes
• tmpfs_mode=drwxr-x---
• user_present=yes
• group_present=yes

Concrete validated effects:

• the temporary rc.d script was started through Shepherd and wrote its expected start marker
• the loopback alias was present on lo0
• tmpfs was mounted successfully on the requested mount point
• the mounted directory had the expected mode corresponding to 0750
• the temporary user and group were created successfully and were visible through standard account queries

Observed cleanup results

Observed metadata after stop root included:

• rc_stopped=yes
• alias_removed=yes
• tmpfs_unmounted=yes
• user_removed=yes
• group_removed=yes

This confirms that the same Shepherd service graph also performed complete cleanup of the corresponding FreeBSD host state.

Important findings

• the new bridge layer shows that Shepherd services can express useful FreeBSD host-management tasks directly without depending on Linux-specific service assumptions
• rcng integration does not need to be all-or-nothing; Shepherd can manage rc.d services where that is useful while also directly managing native host actions such as ifconfig, mount, and pw
• the signalfd fallback note remains present on FreeBSD:
  • System lacks support for 'signalfd'; using fallback mechanism. but it did not interfere with this host-management prototype

Why this satisfies Phase 4.3 on the prototype track

Phase 4.3 asked to demonstrate that Shepherd services can bridge to FreeBSD service concepts and manage representative system tasks. On the current prototype track, that is satisfied because the harness demonstrated all of the requested categories:

• rcng-equivalent functionality:
  • through freebsd-rc-service
• network configuration:
  • through loopback alias management on lo0
• filesystem mounting and permissions:
  • through tmpfs mount/unmount and mode validation
• user and group administration:
  • through temporary account creation/removal with pw

Conclusion

Phase 4.3 is satisfied on the current FreeBSD prototype track:

• a reusable FreeBSD Shepherd bridge layer now exists in-repo
• it validates concrete bridging of Shepherd to rc.d, networking, filesystem, and account-management concepts
• activation and cleanup both work correctly under Shepherd supervision