Mount Commands

This domain covers local filesystem mounting through K3 mount daemons.

Quick Post-Mount Checklist (5 Commands)

Assuming your bucket is mounted at /mnt/kb-dev, run this fast sanity checklist:

dodil k3 mount list
ls -lah /mnt/kb-dev
find /mnt/kb-dev -maxdepth 2 -type f | head
head -n 20 /mnt/kb-dev/docs/sample.txt
dodil k3 unmount /mnt/kb-dev

Mount Commands

Public commands:

• dodil k3 mount <bucket> <mount-path> --type <fuse|nfs>
• dodil k3 mount list
• dodil k3 unmount <mount-path>

Internal command:

• dodil k3 mount-daemon <bucket> <mount-path> <type> (hidden, started by mount)

Flags

Arguments

Backend Selection

1. fuse:
   • User-space mount backend via go-fuse.
   • Good default for developer workstations.
2. nfs:
   • Starts a local loopback NFS server and mounts it to the target path.
   • Requires local NFS tooling and non-interactive sudo for smooth automation.

Examples

dodil k3 mount kb-dev /mnt/kb-dev --type fuse
dodil k3 mount list
dodil k3 unmount /mnt/kb-dev

NFS example:

dodil k3 mount kb-dev /mnt/kb-dev --type nfs

What You Can Do After Mount

After the mount is active, the bucket path behaves like a local directory for common file workflows.

1. Browse and inspect objects

ls -lah /mnt/kb-dev
find /mnt/kb-dev -maxdepth 2 -type f | head

2. Read files with local tools

head -n 40 /mnt/kb-dev/myproj/src/main.rs
grep -R "invoice" /mnt/kb-dev/docs

3. Use local applications against remote content

1. Open files in editors/IDEs directly from the mount path.
2. Run local scripts and analytics tools against mounted files.
3. Use shell pipelines (cat, awk, sed, jq) without downloading objects first.

4. Export subsets locally

cp /mnt/kb-dev/docs/sample.pdf ./sample.pdf
tar -czf docs-snapshot.tgz /mnt/kb-dev/docs

5. Write behavior guidance

1. Treat mounted paths as read-heavy for production workflows.
2. For critical writes and deletes, prefer explicit CLI/API operations:
   • dodil k3 object create ...
   • dodil k3 object remove ...
3. If you test writes through mount, verify results using dodil k3 object list --bucket <bucket>.

Mount Lifecycle

1. mount validates/creates the mount directory and spawns a background daemon process.
2. The daemon is recorded in the local mount registry at ~/.k3/mounts.json with:
   • bucket
   • absolute mount path
   • mount type
   • daemon PID
   • creation timestamp
3. mount list reads the registry and prints tracked mounts.
4. unmount looks up registry metadata, sends interrupt to the daemon PID, runs backend-specific unmount, and then unregisters the mount path.

Backend Behavior Details

FUSE path

1. Uses StorageService list/info APIs to surface files and metadata.
2. Reads file bytes with ranged HTTP GET requests against object URLs.
3. Unmount cleanup uses fusermount -uz <mount-path>.

NFS path

1. Starts a local NFS server bound to 127.0.0.1 on an ephemeral port.
2. Attempts secure automount with sudo -n mount -t nfs ....
3. If automount fails, CLI prints a manual sudo mount -t nfs ... command.
4. Unmount cleanup attempts sudo -n umount -f and sudo -n umount -l.

Data Sync and Write Expectations

1. Mount runtime includes a local spooler under ~/.k3/spool/<bucket>.
2. Current spooler implementation is best treated as development-grade behavior.
3. For critical write workflows, prefer explicit object create/remove commands or API writes.

Troubleshooting

1. mount list shows entry but directory is not accessible:
   • Check whether daemon PID is still running.
   • Retry unmount then mount again.
2. unmount says path not found:
   • Use the exact path that was mounted (registry is keyed by absolute path).
3. NFS mount fails immediately:
   • Ensure NFS client tools are installed.
   • Ensure non-interactive sudo permissions for mount/umount commands.
4. FUSE unmount fails:
   • Verify fusermount is available on host.

Common Use Cases

1. Local analyst workflows over remote bucket files.
2. Integration tests that need file-system style access.
3. Operational mount lifecycle verification and local daemon tracking.

Next: CLI Gaps and API Fallbacks