Server Privilege Model
Layer 8. Node. Node
Overview
Section titled “Overview”The shc server runs as root to enable direct access to Docker container data directories. This eliminates permission issues when backing up, restoring, or cloning container data.
Architecture
Section titled “Architecture”flowchart TB subgraph server["shc server (runs as root)"] config["Config Files<br/>owned by root:shc"] staging["Staging Dirs<br/>owned by root:root"] containers["Container Data Dirs<br/>owned by postgres, redis, etc"] access["Direct file access (root)<br/>os file calls"] config --> access staging --> access containers --> access end subgraph cli["shc CLI (runs as any user in shc group)"] clientOps["No direct file access: <br/>all operations go through server"] end clientOps -- "Unix socket" --> serverComponents
Section titled “Components”Server (shc.server)
Section titled “Server (shc.server)”- Runs as: root
- Started by: systemd (production) or
make dev/ CLI (development) - Socket:
/run/shc/shc.sock(production) or.shc/run/shc.sock(development) - Socket permissions:
- Production:
root:shcwith mode0660(only shc group members can connect) - Development:
root:rootwith mode0666(any user can connect)
- Production:
CLI (shc)
Section titled “CLI (shc)”- Runs as: Any user (must be in
shcgroup for production) - Communication: Unix socket or HTTP
- Auto-starts server: If server not running and using Unix socket, CLI will
sudostart it
Runtime Modes
Section titled “Runtime Modes”Production (systemd)
Section titled “Production (systemd)”| Setting | Value |
|---|---|
| User | root |
| Group | root |
| Socket | /run/shc/shc.sock |
| Socket owner | root:shc (mode 0660) |
| Config | /etc/shc/ |
| Data | /var/lib/shc/ |
| Logs | /var/log/shc/ |
CLI users must be members of the shc group to access the socket:
sudo usermod -aG shc $USERDevelopment (make dev)
Section titled “Development (make dev)”| Setting | Value |
|---|---|
| User | root (via sudo) |
| Socket | .shc/run/shc.sock |
| Socket owner | root (mode 0666) |
| Config | .shc/config/ |
| Data | .shc/state/ |
| Logs | .shc/logs/ |
No group membership required!
CLI Does NOT Auto-Start Server
Section titled “CLI Does NOT Auto-Start Server”The CLI does not auto-start the server. This avoids fragile sudo/background process interactions.
If the server is not running, the CLI fails with a clear error message:
- Dev mode: “Server not running. Start it with: make dev”
- Production: “Server not running. Start it with: sudo systemctl start shc”
Users must explicitly start the server before using the CLI.
Security Considerations
Section titled “Security Considerations”Why Root?
Section titled “Why Root?”Docker containers create files owned by their internal users (e.g., postgres runs as uid 999). Without root access, the server cannot:
- Read container data for backup
- Write container data for restore
- Delete container data directories
- Chown files during migration
Socket Security
Section titled “Socket Security”The Unix socket provides access control:
- Production: Only users in the
shcgroup can connect - Development: Any local user can connect (for ease of testing)
What Root Enables
Section titled “What Root Enables”| Operation | Without Root | With Root |
|---|---|---|
| Read container data | ❌ Permission denied | ✅ Works |
| Write container data | ❌ Permission denied | ✅ Works |
| Delete container dirs | ❌ Permission denied | ✅ Works |
| Change file ownership | ❌ Permission denied | ✅ Works |
| Talk to Docker daemon | ✅ (docker group) | ✅ Works |
| Create socket | ✅ | ✅ Works |
| Set socket permissions | ❌ (non-root) | ✅ Works |
File Locations
Section titled “File Locations”Production
Section titled “Production”| Directory | Path | Owner |
|---|---|---|
| Config | /etc/shc/ | root:shc (750) |
| State | /var/lib/shc/ | root:root (755) |
| Cache | /var/cache/shc/ | root:root (755) |
| Logs | /var/log/shc/ | root:root (755) |
| Runtime | /run/shc/ | root:root (755) |
| Backups | /var/backups/shc/ | root:root (755) |
Development
Section titled “Development”| Directory | Path | Owner |
|---|---|---|
| Config | .shc/config/ | root:root |
| State | .shc/state/ | root:root |
| Cache | .shc/cache/ | root:root |
| Logs | .shc/logs/ | root:root |
| Runtime | .shc/run/ | root:root |
Makefile Targets
Section titled “Makefile Targets”# Start the server in development mode (as root via sudo)make dev
# Stop the server (requires sudo for root-owned process)make stop
# Reset development environment (removes .shc directory)make cleanCLI Usage
Section titled “CLI Usage”# In production, user must be in shc groupsudo usermod -aG shc $USER# Log out and back in for group membership to take effect
# Start server (required before using CLI)sudo systemctl start shc
# Run CLI commandsshc lsshc backup create mystack
# In development (from project directory), no group required# Start the server firstmake dev
# Then in another terminal:./run stack list./run backup create mystackshc@docs:~$