Skip to content
SHC Docs

Server Privilege Model

Layer 8. Node. Node

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.

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" --> 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:shc with mode 0660 (only shc group members can connect)
    • Development: root:root with mode 0666 (any user can connect)
  • Runs as: Any user (must be in shc group for production)
  • Communication: Unix socket or HTTP
  • Auto-starts server: If server not running and using Unix socket, CLI will sudo start it
SettingValue
Userroot
Grouproot
Socket/run/shc/shc.sock
Socket ownerroot: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:

Terminal window
sudo usermod -aG shc $USER
SettingValue
Userroot (via sudo)
Socket.shc/run/shc.sock
Socket ownerroot (mode 0666)
Config.shc/config/
Data.shc/state/
Logs.shc/logs/

No group membership required!

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.

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

The Unix socket provides access control:

  • Production: Only users in the shc group can connect
  • Development: Any local user can connect (for ease of testing)
OperationWithout RootWith 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
DirectoryPathOwner
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)
DirectoryPathOwner
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
# 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 clean
Terminal window
# In production, user must be in shc group
sudo 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 commands
shc ls
shc backup create mystack
# In development (from project directory), no group required
# Start the server first
make dev
# Then in another terminal:
./run stack list
./run backup create mystack