Agent Configuration

The agent configuration is stored in /etc/bloqd/agent.yaml.

Configuration File

# Bloqd Agent Configuration
# Location: /etc/bloqd/agent.yaml

# Server connection
server:
  # Bloqd server URL
  url: "https://bloqd.example.com"

  # API key for authentication (from Bloqd web UI)
  api_key: "f2b_your_api_key_here"

  # Enable WebSocket for real-time communication
  websocket: true

  # Verify SSL certificates (disable for self-signed certs)
  verify_ssl: true

# Agent settings
agent:
  # Hostname (use "auto" to detect automatically)
  hostname: "auto"

  # Log level: DEBUG, INFO, WARNING, ERROR
  log_level: "INFO"

  # Log file location
  log_file: "/var/log/bloqd/agent.log"

  # PID file location
  pid_file: "/var/run/bloqd-agent/agent.pid"

# Module configuration
modules:
  # Whitelist synchronization
  sync:
    enabled: true
    interval: 300  # 5 minutes
    whitelist_path: "/etc/fail2ban/bloqd-whitelist.txt"
    reload_on_change: true

  # Ban reporting
  reporter:
    enabled: true
    log_excerpt_max: 2000
    socket_path: "/var/run/bloqd-agent/report.sock"

  # System metrics collection
  metrics:
    enabled: true
    interval: 300  # 5 minutes
    collect:
      cpu: true
      memory: true
      disk: true
      load: true
      network: false

  # Health checks
  health:
    enabled: true
    interval: 60  # 1 minute
    checks:
      - fail2ban_running
      - disk_space
      - memory_usage
    disk_warning_percent: 80
    disk_critical_percent: 90
    memory_warning_percent: 80
    memory_critical_percent: 95

  # Remote command execution
  commands:
    enabled: true
    poll_interval: 30  # seconds
    allowed_commands:
      - jail_enable
      - jail_disable
      - fail2ban_reload
      - ip_ban
      - ip_unban
      - ip_unban_all
      - whitelist_sync
      - list_bans
      - list_jails
      - agent_update
      - agent_uninstall
      - config_update
      - custom_command
      - filter_sync
      - terminal_start
      # SIEM commands
      - siem_enable
      - siem_disable
      - siem_run_audit
      - siem_set_baseline
      - siem_status
      # Port Knocking commands
      - portknock_discover_ports
      - portknock_enable
      - portknock_disable
      - portknock_allow
      - portknock_deny
      - portknock_status

  # Interactive terminal sessions (Personal+)
  terminal:
    enabled: true
    shell: /bin/bash
    max_sessions: 5

  # SIEM - Security auditing (Pro)
  siem:
    enabled: false
    interval: 3600  # 1 hour between audits
    min_audit_interval: 3600  # Minimum interval
    lynis_path: "/usr/bin/lynis"
    baseline_path: "/var/lib/bloqd/siem/baseline.json"
    snapshot_path: "/var/lib/bloqd/siem/snapshots"
    cooldown_seconds: 3600

  # Port Knocking (Pro)
  portknock:
    enabled: true
    interval: 60

Configuration Sections

Server Section

Setting	Description	Default
url	Bloqd server URL	Required
api_key	API key for authentication	Required
websocket	Enable WebSocket connection	true
verify_ssl	Verify SSL certificates	true

Agent Section

Setting	Description	Default
hostname	Server hostname (auto to detect)	auto
log_level	Logging level	INFO
log_file	Log file path	/var/log/bloqd/agent.log
pid_file	PID file path	/var/run/bloqd-agent/agent.pid

Sync Module

Setting	Description	Default
enabled	Enable whitelist sync	true
interval	Sync interval (seconds)	300
whitelist_path	Path to whitelist file	/etc/fail2ban/bloqd-whitelist.txt
reload_on_change	Reload fail2ban on changes	true

Reporter Module

Setting	Description	Default
enabled	Enable ban reporting	true
log_excerpt_max	Max log excerpt length	2000
socket_path	Unix socket path	/var/run/bloqd-agent/report.sock

Metrics Module

Setting	Description	Default
enabled	Enable metrics collection	true
interval	Collection interval (seconds)	300
collect.cpu	Collect CPU metrics	true
collect.memory	Collect memory metrics	true
collect.disk	Collect disk metrics	true
collect.load	Collect load average	true
collect.network	Collect network metrics	false

Health Module

Setting	Description	Default
enabled	Enable health checks	true
interval	Check interval (seconds)	60
checks	List of checks to run	See below
disk_warning_percent	Disk warning threshold	80
disk_critical_percent	Disk critical threshold	90
memory_warning_percent	Memory warning threshold	80
memory_critical_percent	Memory critical threshold	95

Commands Module

Setting	Description	Default
enabled	Enable remote commands	true
poll_interval	Command poll interval (seconds)	30
allowed_commands	List of allowed commands	See config

Terminal Module (Personal+)

Setting	Description	Default
enabled	Enable terminal sessions	true
shell	Shell to use	/bin/bash
max_sessions	Maximum concurrent sessions	5

SIEM Module (Pro)

Setting	Description	Default
enabled	Enable SIEM auditing	false
interval	Audit interval (seconds)	3600
min_audit_interval	Minimum between audits	3600
lynis_path	Path to Lynis binary	/usr/bin/lynis
baseline_path	Baseline storage path	/var/lib/bloqd/siem/baseline.json
cooldown_seconds	Alert cooldown	3600

Command Line Options

# Run agent with custom config
bloqd-agent --config /path/to/config.yaml

# Override log level
bloqd-agent --log-level DEBUG

# Override log file
bloqd-agent --log-file /var/log/custom.log

# Check configuration validity
bloqd-agent --check

# Run single health check
bloqd-agent --health-check

# Show status
bloqd-agent --status

# Show version
bloqd-agent --version

# Uninstall
sudo bloqd-agent --uninstall

Environment Variables

Configuration can also be provided via environment variables:

Variable	Config Equivalent
BLOQD_SERVER_URL	server.url
BLOQD_API_KEY	server.api_key
BLOQD_HOSTNAME	agent.hostname
BLOQD_LOG_LEVEL	agent.log_level

Environment variables take precedence over config file values.

Troubleshooting Configuration

Validate Configuration

bloqd-agent --check

Output shows:

• Configuration validity
• Server URL
• Hostname
• WebSocket status
• Enabled modules
• API key status

Common Issues

SSL Certificate Errors:

server:
  verify_ssl: false  # Only for self-signed certs

Connection Timeouts:

• Check firewall rules
• Verify server URL is accessible
• Check API key is valid

Module Not Loading:

• Ensure module is enabled in config
• Check for syntax errors in YAML
• Review agent logs for errors