GuardBSD Command-Line Interface (CLI)

GuardBSD provides a minimal but extensible set of command-line tools designed to interact with system services implemented in userland:

• init (service manager)
• logd (logging daemon)
• vfs / guardfs (filesystem server)
• netd (network stack)
• devd (device manager)

CLI tools communicate with these servers primarily through IPC ports, using the same capability-secured primitives exposed in libgbsd.

Design Philosophy

GuardBSD CLI tools follow three principles:

1. Everything is a user-space service
   No privileged kernel commands. All tools speak to servers via IPC.

2. Predictable, script-friendly output
   Tools return plain text, line-based output. Error codes are consistent.

3. POSIX-inspired ergonomics
   Commands mirror familiar UNIX idioms (e.g., ls, cat, ps, kill), but internally rely on capability-secured IPC, not kernel syscalls.

gsh - Guard Shell

gsh is the interactive shell for GuardBSD.
It provides basic command execution, pipelines, redirection, job control, and scripting features.

Typical Usage

gsh

Built-in Commands

| Command      | Description                          |
| ------------ | ------------------------------------ |
| `cd <path>`  | Change directory (IPC to VFS server) |
| `ls [path]`  | List directory contents              |
| `cat <file>` | Print file contents                  |
| `ps`         | List processes                       |
| `kill <pid>` | Send signal to process               |
| `log`        | Show recent kernel/user logs         |
| `help`       | Overview of built-in commands        |

Example

ls /etc
cat /var/log/system.log
ps
kill 42

initctl - System Service Controller

initctl communicates with the init server to manage system services.

Commands

| Command                     | Description           |
| --------------------------- | --------------------- |
| `initctl status`            | Show running services |
| `initctl start <service>`   | Start service         |
| `initctl stop <service>`    | Stop service          |
| `initctl restart <service>` | Restart service       |

Example

initctl status
initctl start netd
initctl restart logd

logdctl - Logging Tools

logd is responsible for collecting and rotating logs. The CLI helper logdctl is used to query and manage logs.

Commands

| Command          | Description             |
| ---------------- | ----------------------- |
| `logdctl show`   | Print active logs       |
| `logdctl tail`   | Stream log output       |
| `logdctl rotate` | Trigger manual rotation |

Example

logdctl tail

Integration Notes

• Log rotation uses rename + unlink syscalls (Quick Reference: sync, rename, unlink).

Filesystem Tools (via GuardFS/VFS)

GuardBSD keeps filesystem metadata and operations in userland servers. CLI tools therefore wrap IPC operations rather than direct syscalls.

Tools

| Command             | Description              |
| ------------------- | ------------------------ |
| `mkdir <path>`      | Create directory         |
| `rm <path>`         | Remove file or directory |
| `stat <path>`       | Show metadata            |
| `touch <path>`      | Create empty file        |
| `mount <src> <dst>` | Mount filesystem         |
| `umount <dst>`      | Unmount filesystem       |

Example

mkdir /tmp/debug
stat /tmp/debug
touch /tmp/debug/log.txt
rm /tmp/debug/log.txt
rmdir /tmp/debug

Network Tools (netd)

Networking is done entirely by the netd user-space server.

Tools

| Command             | Description                     |
| ------------------- | ------------------------------- |
| `ifconfig`          | List network interfaces         |
| `route`             | Show routing table              |
| `netstat`           | Display sockets and connections |
| `ping <host>`       | ICMP test using netd            |
| `dnsquery <domain>` | DNS lookup                      |

Example

ifconfig
ping 8.8.8.8

Process Management Tools

Many commands executed inside gsh map directly to libgbsd process functions:

• ps → enumerate processes
• kill <pid> → sends signal (process_kill)
• wait <pid> → waits for process completion

Relevant syscalls:

process_wait(process_cap);
process_kill(process_cap, Signal::Term);

IPC Tools (Developer Utilities)

GuardBSD supports debugging IPC between components.

Tools

| Command               | Description                      |
| --------------------- | -------------------------------- |
| `portinfo <id>`       | Show port metadata               |
| `msend <port> <data>` | Send raw IPC message             |
| `mrecv <port>`        | Receive message                  |
| `rpc <port> <data>`   | Send RPC call and print response |

ABI based on IPC definitions:

Error Model

CLI tools exit with:

• 0 - success
• 1 - user error
• 2 - IPC failure
• 3 - insufficient capabilities
• 4 - server-side error
• >=100 - tool-specific codes

Future Extensions

Planned additions:

• pkg - package manager (binary & source)
• svc - unified service controller
• guardadm - system integrity checker
• hotplugctl - device hotplug events (via devd)

All extensions will follow the same IPC-first CLI model.

Related Documentation

• libgbsd - high-level system library
• Syscalls - low-level interface
• ABI - binary specifications