Configuration
Every ghostshell config key with defaults and env overrides, plus environment variables, the filesystem layout, and daemon management.
Ghost Shell reads /etc/ghostshell/ghostshell.conf on startup (override the path with GHOSTSHELL_CONFIG). The file ships with all defaults active — uncommented — so it is immediately editable. Validate any change with:
bash
ghostshell --checktext
ghostshell: reading config from /etc/ghostshell/ghostshell.conf
socket_path = /run/ghostshell-daemon.sock
central_dir = /var/lib/ghostshell
key_file = .ghostshell.key (resolved: /var/lib/ghostshell/.ghostshell.key)
dial_timeout_sec = 1s
eof_grace_ms = 500ms
ansible_output_cap = 8192
scroll_buffer = 32768
log_level = 3 (0=off 1=error 2=warn 3=info 4=debug 5=trace)
log_file = /var/log/ghostshell/ghostshell.log
ghostshell: config OKConfig keys
| Key | Default | Env override | Purpose |
|---|---|---|---|
socket_path |
/run/ghostshell-daemon.sock |
GHOSTSHELL_DAEMON_SOCK |
Daemon Unix socket |
central_dir |
/var/lib/ghostshell |
GHOSTSHELL_CENTRAL_DIR |
Root of central session store |
key_file |
.ghostshell.key |
GHOSTSHELL_KEY_FILE |
Encryption key path (relative to central_dir or absolute) |
dial_timeout_sec |
1 |
GHOSTSHELL_DIAL_TIMEOUT_SEC |
Seconds to wait when connecting to the daemon |
eof_grace_ms |
500 |
GHOSTSHELL_EOF_GRACE_MS |
Ms before force-closing the PTY on stdin EOF |
ansible_output_cap |
8192 |
GHOSTSHELL_ANSIBLE_OUTPUT_CAP |
Max bytes stored per Ansible task output |
scroll_buffer |
32768 |
GHOSTSHELL_SCROLL_BUFFER |
PTY read buffer size in bytes (min 4096) |
log_level |
3 |
GHOSTSHELL_LOG_LEVEL |
Daemon log verbosity (0 off through 5 trace) |
log_file |
/var/log/ghostshell/ghostshell.log |
GHOSTSHELL_LOG_FILE |
Daemon logfile path; empty disables file logging |
Restart the daemon after editing: sudo systemctl restart ghostshell-daemon.
Environment variables
| Variable | Default | Used by | Description |
|---|---|---|---|
GHOSTSHELL_DIR |
~/.local/share/ghostshell |
ghostshell |
User-local recordings dir (fail-open fallback + local ls/play) |
GHOSTSHELL_QUIET |
unset | ghostshell rec |
Any non-empty value suppresses the banner and saved-path message |
SHELL |
/bin/bash |
ghostshell rec |
Shell launched when no command is given |
Filesystem layout
| Path | Owner / mode | Purpose |
|---|---|---|
/usr/bin/ghostshell |
root 0755 |
CLI |
/usr/libexec/ghostshell-daemon |
root 0755 |
Daemon |
/etc/ghostshell/ghostshell.conf |
root 0644 |
Runtime config (conffile — preserved on upgrade) |
/var/lib/ghostshell/ |
root:root 0700 |
Central store |
/var/lib/ghostshell/<user>/<id>.cast |
root:root 0600 |
Encrypted recording |
/var/lib/ghostshell/.ghostshell.key |
root:root 0600, chattr +i |
Per-server AES key (immutable) |
/var/log/ghostshell/ |
root:root 0750 |
Daemon log directory |
/var/log/ghostshell/ghostshell.log |
root:root 0640 |
Daemon logfile |
/run/ghostshell-daemon.sock |
root 0666 |
Recorder connect socket |
/etc/profile.d/ghostshell-autorec.sh |
root 0644 |
Optional auto-record login hook |
~/.local/share/ghostshell/ |
the user | Local fail-open recordings |
Daemon service
bash
sudo systemctl status ghostshell-daemon
sudo systemctl restart ghostshell-daemon
sudo tail -f /var/log/ghostshell/ghostshell.log
sudo journalctl -u ghostshell-daemon --no-pagerTo override settings at the systemd level (takes precedence over the config file):
bash
sudo systemctl edit ghostshell-daemon
# [Service]
# Environment=GHOSTSHELL_CENTRAL_DIR=/srv/ghostshellSomething not behaving? See troubleshooting. Backup settings (backup_type/backup_target) are covered in backup and prune.