# 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:

```sh
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