markbase/docs/BOLD_NFS_MACOS_TEST.md

bold-nfs macOS Test Guide

Date: 2026-05-17 13:32 Status: Phase 1 - Testing bold-nfs on macOS

---

1. Test Results (bold-mem startup)

✅ Successful Indicators

Build success:

• bold-mem compiled successfully (14.88s)
• Binary location: /tmp/bold-nfs/target/release/bold-mem
• Dependencies: vfs-0.12.2, tokio, serde_yaml, clap

Server startup success:

INFO bold: Server listening self.bind=127.0.0.1:11112
DEBUG bold::server::filemanager: get_filehandle_by_path: /
DEBUG bold::server::filemanager: created new filehandle id: [128, 0, 0, 0, ...]
DEBUG bold::server::filemanager::filehandle: attr_change: Ok(VfsMetadata { file_type: Directory, len: 0, ... })

Port listening:

COMMAND    PID    USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
bold-mem 70821 accusys    9u  IPv4 0x3f7e929e25b6f696      0t0  TCP localhost:dicom (LISTEN)

Process status:

• PID: 70821
• Command: ./target/release/bold-mem --debug exec/memoryfs.yaml
• Status: Running (server loop active)

---

2. Manual Test Instructions

Step 1: Start bold-mem NFS server

cd /tmp/bold-nfs

# Start server with debug logging
./target/release/bold-mem --debug exec/memoryfs.yaml

# Expected output:
# Loading YAML: "exec/memoryfs.yaml"
# INFO bold: Server listening 127.0.0.1:11112
# (Server will run indefinitely)

Step 2: Create mount directory

sudo mkdir -p /tmp/nfs_demo

Step 3: Mount NFS volume (macOS)

Option A: NFSv4 mount (recommended)

sudo mount_nfs -o vers=4,port=11112,mountport=11112 127.0.0.1:/ /tmp/nfs_demo

Option B: NFSv3 mount (if v4 fails)

sudo mount_nfs -o vers=3,port=11112,mountport=11112 127.0.0.1:/ /tmp/nfs_demo

Option C: Generic NFS mount

sudo mount -t nfs -o port=11112,mountport=11112 127.0.0.1:/ /tmp/nfs_demo

Step 4: Verify mount

# Check mount status
mount | grep nfs_demo

# Expected output:
# 127.0.0.1:/ on /tmp/nfs_demo (nfs, ...

# List files
ls -la /tmp/nfs_demo/

# Expected output (from memoryfs.yaml):
# home/
# etc/
# init

Step 5: Test file operations

# Navigate to home directory
ls -la /tmp/nfs_demo/home/user/

# Read file1
cat /tmp/nfs_demo/home/user/file1

# Expected content:
# This is the content of file1

# Create new file
echo "Test write" > /tmp/nfs_demo/home/user/test_write.txt

# Verify file created
ls -la /tmp/nfs_demo/home/user/test_write.txt

# Read back
cat /tmp/nfs_demo/home/user/test_write.txt

Step 6: Unmount

sudo umount /tmp/nfs_demo

# Or force unmount if needed
sudo umount -f /tmp/nfs_demo

---

3. Expected Debug Output

When mount_nfs connects, bold-mem will show:

DEBUG bold: Client connected addr=127.0.0.1:XXXXX
DEBUG bold::server::filemanager: get_filehandle_by_path: /
DEBUG bold::server::nfs40::op_getattr: getattr request
DEBUG bold::server::nfs40::op_readdir: readdir request
DEBUG bold::server::nfs40::op_lookup: lookup request
DEBUG bold::server::nfs40::op_read: read request

---

4. Troubleshooting

If mount_nfs fails

Error: "mount_nfs: can't mount / from 127.0.0.1"

Solution:

1. Check bold-mem is running: ps aux | grep bold-mem
2. Check port is listening: lsof -i :11112
3. Try different NFS options:

   sudo mount_nfs -o vers=4,port=11112,mountport=11112,soft 127.0.0.1:/ /tmp/nfs_demo
   sudo mount_nfs -o vers=4,port=11112,mountport=11112,fg 127.0.0.1:/ /tmp/nfs_demo
   

Error: "Permission denied"

Solution:

1. NFS requires root permissions for mount
2. Use sudo for mount command
3. Check bold-mem permissions: ls -la /tmp/bold-nfs/target/release/bold-mem

Error: "Connection refused"

Solution:

1. Restart bold-mem server
2. Check firewall: sudo pfctl -s all
3. Try different port: bold-mem --bind 127.0.0.1:2049

---

5. Success Criteria

Phase 1 success criteria:

• ✅ bold-mem compiles and runs
• ✅ Server listens on port 11112
• ⏳ macOS mount_nfs connects (requires manual test)
• ⏳ Files visible in mount directory
• ⏳ File reading works
• ⏳ File writing works

If Phase 1 succeeds → Proceed to Phase 2 (MarkBaseFS implementation)

If Phase 1 fails → Investigate macOS NFS compatibility, consider libnfs-go fallback

---

6. Reference Files

bold-nfs source code:

• /tmp/bold-nfs/lib/src/lib.rs - NFSServer implementation
• /tmp/bold-nfs/lib/src/server/filemanager/mod.rs - FileManager (624 lines)
• /tmp/bold-nfs/lib/src/server/nfs40/*.rs - NFSv4.0 operations

vfs crate documentation:

• https://docs.rs/vfs/0.12.0/vfs/filesystem/trait.FileSystem.html

memoryfs.yaml example:

• /tmp/bold-nfs/exec/memoryfs.yaml - YAML filesystem definition

---

7. Next Steps (After Manual Test)

If mount succeeds:

1. Document mount command that works
2. Note NFS options required for macOS
3. Proceed to Phase 2 (MarkBaseFS implementation)
4. Estimate: Day 2-3 (12-16 hours)

If mount fails:

1. Research macOS NFSv4 compatibility
2. Try NFSv3 mount (vers=3 option)
3. Consider libnfs-go fallback (Go implementation)
4. Estimate: +1 day debugging

---

Test guide prepared by: OpenCode AI Assistant Current status: Waiting for manual mount test (sudo required) Recommendation: Execute manual test, then proceed based on results