config.example.toml

# Ferrix Configuration Example
# Copy to ~/.config/ferrix/config.toml and customize

[general]
default_shell = "/bin/bash"
escape_key = "ctrl-b"
mouse = true
clipboard = true
term = "xterm-256color"
scrollback_lines = 10000
automatic_rename = true
display_panes_time = 2000
auto_detach_on_exit = true

[keybindings]
prefix = "ctrl-b"

[status_bar]
enabled = true
position = "bottom"
left = "[#{session_name}] #{windows} #{git_branch}"
center = "#{cpu} #{memory} #{battery}"
right = "#{user}@#{host} #{time}"
refresh_rate = 1000
height = 1

[colors]
background = "#1e1e1e"
foreground = "#d4d4d4"
pane_border = "#444444"
pane_active_border = "#569cd6"
status_bg = "darkgreen"
status_fg = "black"
status_current_bg = "#569cd6"
status_current_fg = "#ffffff"

[windows]
renumber = true
base_index = 0
aggressive_resize = false

[panes]
base_index = 0
display_borders = true
border_style = "single"

[copy_mode]
mode = "vi"
use_system_clipboard = true
exit_after_selection = false

[plugins]
enabled = true
directory = "~/.ferrix/plugins"
autoload = true
plugins = []

[advanced]
auto_save_session = true
auto_save_interval = 300
enable_crash_recovery = true
recovery_backup_dir = "~/.ferrix/recovery"
allow_remote = false
remote_port = 7755
remote_encryption = true
log_level = "info"
log_file = "~/.ferrix/ferrix.log"

# ============================================================================
# Resource Limits & Backpressure Management
# ============================================================================
# These limits prevent resource exhaustion and ensure fairness across clients

[limits]
# Per-Session Limits
max_windows_per_session = 100    # Maximum windows per session
max_panes_per_window = 50         # Maximum panes per window
max_scrollback_lines = 10000      # Maximum scrollback lines per pane
max_raw_buffer_bytes = 50000      # Maximum buffer size per pane (50KB)

# Server-Wide Limits
max_concurrent_sessions = 1000    # Maximum total sessions
max_clients = 2000                # Maximum concurrent client connections

# Memory Management
# max_memory_mb = 4096            # Optional: Maximum server memory (MB)
memory_pressure_threshold = 0.85  # Trigger backpressure at 85% memory usage

# Rate Limiting
max_sessions_per_minute = 10      # Maximum new sessions per client per minute

# ============================================================================
# Backpressure Behavior
# ============================================================================
# When limits are approached:
# - At 85% (Warning): Log warnings, apply flow control
# - At 95% (Critical): Reject new non-essential operations
# - Emergency mode: Reject all new operations
#
# Example pressure scenarios:
# - 850 sessions active → Warning level (log warnings)
# - 950 sessions active → Critical level (reject new sessions)
# - Emergency mode → Manually activated via ferrix emergency-mode

# ============================================================================
# Security Hardening (Remote Access)
# ============================================================================
# These settings protect against attacks when remote access is enabled
# (when advanced.allow_remote = true)
#
# NOTE: Authentication rate limiting and session timeouts are currently
# hardcoded in the server. Future versions may make these configurable.

# [security]  # Not yet configurable - documented for reference only
#
# # Authentication Rate Limiting (HARDCODED)
# # Current implementation: 5 failed attempts, 15 minute lockout
# # Prevents brute-force password attacks by locking out IPs after failed attempts
# # auth_max_attempts = 5              # Maximum failed auth attempts before lockout
# # auth_lockout_duration = 900        # Lockout duration in seconds (15 minutes)
#
# # Session Timeout Configuration (HARDCODED)
# # Current implementation: 1 hour idle timeout, 24 hour absolute timeout
# # Automatically disconnect idle or long-running sessions
# # session_idle_timeout = 3600        # Idle timeout in seconds (1 hour)
# # session_absolute_timeout = 86400   # Absolute timeout in seconds (24 hours)

# TLS/mTLS Configuration
# Remote connections use TLS by default when certificates are provided
# TLS modes:
#   - "server-only": Server authenticates to client (default)
#   - "mutual-auth": Both server and client authenticate with certificates
#
# To enable remote access with TLS:
# 1. Generate server certificate and key
# 2. Set allow_remote = true in [advanced] section
# 3. Start server with: ferrix serve --cert server.pem --key server-key.pem
#
# For mutual TLS (recommended for production):
# 1. Generate CA certificate for client verification
# 2. Generate client certificates signed by the CA
# 3. Start server with: ferrix serve --cert server.pem --key server-key.pem \
#                                     --tls-mode mutual-auth --client-ca ca.pem
#
# TLS configuration is set via command-line flags, not this config file

# ============================================================================
# Security Best Practices
# ============================================================================
# For production deployments:
# 1. Enable mTLS (mutual-auth mode) for strong authentication
# 2. Use strong passwords or key-based authentication
# 3. Keep auth_max_attempts low (3-5) with long lockout (15-30 minutes)
# 4. Set reasonable session timeouts based on your use case
# 5. Monitor failed authentication attempts in logs (log_level = "info")
# 6. Run server behind a firewall, only exposing necessary ports
# 7. Regularly rotate certificates and credentials