Skip to content
HookProbe Docs

Quick Start Guide

Quick Start Guide

Get HookProbe protecting your network in under 5 minutes.

Prerequisites

Before you begin, ensure you have:

  • Operating System: Ubuntu 22.04+, Debian 11+, or Raspberry Pi OS (Bookworm)
  • Architecture: x86_64 or ARM64 (ARMv8)
  • Minimum RAM: 1.5GB (Guardian), 4GB (Fortress), 16GB (Nexus)
  • Kernel: Linux 5.4+ recommended for full XDP features

Installation

  1. Clone the Repository

    Terminal window
    git clone https://github.com/hookprobe/hookprobe.git
    cd hookprobe

  2. Run the Bootstrap Installer

    Terminal window
    sudo ./install.sh --tier guardian

    For Raspberry Pi 4/5 with 1.5GB+ RAM. Creates a secure WiFi hotspot.

    The installer will:

    • Detect your environment (OS, architecture, kernel, NICs)
    • Install dependencies (Podman, OVS, Python packages)
    • Deploy systemd services
    • Run initial provisioning
    • Start the monitoring agent

  3. Verify Installation

    Terminal window
    # Check status
    hookprobe-ctl status
    

    # View logs
    hookprobe-ctl logs -f
    

    # Check health
    hookprobe-ctl health

  4. Access the Dashboard

    For Guardian deployments:

    For Fortress/Nexus:

    • Access the web dashboard at your configured IP

What Happens During Installation

The installer performs a complete environment setup:

StepDescription
DetectionIdentifies OS, CPU architecture, kernel version, and network interfaces
DependenciesInstalls Podman, OpenVSwitch, Python packages, security tools
DirectoriesCreates /opt/hookprobe/, /etc/hookprobe/, /var/log/hookprobe/
ServicesDeploys systemd units for provision, agent, and update services
ProvisioningConfigures network interfaces, XDP programs, firewall rules
Agent StartLaunches the monitoring daemon with QSecBit scoring

Post-Installation

Enable Auto-Updates (Optional)

Terminal window
sudo hookprobe-ctl enable-autoupdate

Updates run weekly on Sundays at 3:00 AM with automatic rollback on failure.

Configure XDP DDoS Mitigation

Terminal window
# Edit systemd environment
sudo systemctl edit hookprobe-agent.service


# Add:
[Service]
Environment="XDP_ENABLED=true"


# Restart
sudo systemctl daemon-reload
sudo systemctl restart hookprobe-agent.service

Verify XDP is Active

Terminal window
# Check XDP program attachment
ip link show | grep xdp


# View statistics
hookprobe-ctl metrics | grep xdp

Service Management

CommandDescription
hookprobe-ctl statusShow service status
hookprobe-ctl startStart all services
hookprobe-ctl stopStop all services
hookprobe-ctl restartRestart all services
hookprobe-ctl logs -fFollow agent logs
hookprobe-ctl healthCheck health endpoints
hookprobe-ctl metricsView current metrics

Health Endpoints

Terminal window
# Local health check
curl http://localhost:8888/health


# Metrics in JSON
curl http://localhost:8888/metrics | jq .

Troubleshooting

Services Won’t Start

Terminal window
# Check detailed status
systemctl status hookprobe-agent.service


# View error logs
journalctl -u hookprobe-agent.service --no-pager -n 50


# Re-run provisioning
sudo systemctl start hookprobe-provision.service

Port Conflicts

Terminal window
# Check if port 8888 is in use
sudo ss -tlnp | grep 8888

Permission Issues

Terminal window
sudo chown -R root:root /opt/hookprobe
sudo chmod 755 /opt/hookprobe

Next Steps