Installation

This guide covers all installation methods and options for HookProbe.

System Requirements

Operating Systems

OS	Version	Status
Ubuntu	22.04 LTS, 24.04 LTS	Supported
Debian	11, 12	Supported
Raspberry Pi OS	Bookworm 64-bit	Supported

Architecture

Arch	Support
x86_64	Full
ARM64 (ARMv8)	Full
ARMv7 (32-bit)	Not supported

Hardware by Tier

Tier	CPU	RAM	Storage
Sentinel	1 core	256MB	4GB
Guardian	2 cores	1.5GB	16GB
Fortress	4 cores	4GB	64GB
Nexus	8+ cores	16GB	256GB

Kernel

Version	Features
4.8+	Basic XDP
5.4+	Full XDP
5.10+	Advanced eBPF

Quick Installation

# Clone repository
git clone https://github.com/hookprobe/hookprobe.git
cd hookprobe

# Run installer with your tier
sudo ./install.sh --tier guardian

Installation Options

Tier Selection

# IoT validator (256MB)
sudo ./install.sh --tier sentinel

# Travel companion (1.5GB)
sudo ./install.sh --tier guardian

# Business edge (4GB)
sudo ./install.sh --tier fortress

# ML compute (16GB+)
sudo ./install.sh --tier nexus

Feature Flags

# Enable AI orchestration
--enable-aiochi

# Enable LTE failover
--enable-lte

# Enable GPU acceleration (Nexus)
--enable-gpu

# Enable high availability (Nexus)
--enable-ha

# Enable ClickHouse analytics (Nexus)
--enable-clickhouse

# Migrate from previous tier
--migrate

Examples

# Guardian with LTE backup
sudo ./install.sh --tier guardian --enable-lte

# Fortress with all features
sudo ./install.sh --tier fortress --enable-aiochi --enable-lte

# Nexus with GPU and HA
sudo ./install.sh --tier nexus --enable-gpu --enable-ha --enable-clickhouse

# Upgrade Guardian to Fortress
sudo ./install.sh --tier fortress --migrate

What the Installer Does

Phase 1: Detection

Identify OS and version
Detect CPU architecture
Check kernel version
Discover network interfaces
Verify resources

Phase 2: Dependencies

# Packages installed (Ubuntu/Debian)
podman
openvswitch-switch
nftables
python3-pip
libpcap-dev
libbpf-dev

Phase 3: Directory Structure

/opt/hookprobe/
├── scripts/         # Management scripts
├── agent/           # Monitoring agent
├── xdp/             # XDP programs
├── config/          # Configuration
└── data/            # Runtime data

/etc/hookprobe/
└── network-config.sh

/var/log/hookprobe/
├── agent.log
├── provision.log
└── update.log

Phase 4: Services

# Systemd units installed
hookprobe-provision.service  # Runs at boot
hookprobe-agent.service      # Main daemon
hookprobe-update.service     # Manual updates
hookprobe-update.timer       # Auto-updates (optional)

Phase 5: Provisioning

Configure network interfaces
Load XDP programs (if enabled)
Set up firewall rules
Initialize databases
Generate certificates

Phase 6: Startup

Start monitoring agent
Verify health endpoints
Enable auto-start

Manual Installation

For advanced control:

# 1. Install dependencies
sudo apt update
sudo apt install -y \
    podman \
    openvswitch-switch \
    nftables \
    python3-pip \
    libpcap-dev

# 2. Install Python packages
pip3 install -r requirements.txt

# 3. Create directories
sudo mkdir -p /opt/hookprobe/{scripts,agent,xdp,config,data}
sudo mkdir -p /var/log/hookprobe
sudo mkdir -p /etc/hookprobe

# 4. Copy files
sudo cp -r Scripts/autonomous/install/* /opt/hookprobe/scripts/
sudo cp -r Scripts/autonomous/qsecbit/* /opt/hookprobe/agent/

# 5. Install systemd units
sudo cp Scripts/autonomous/install/systemd/*.service /etc/systemd/system/
sudo cp Scripts/autonomous/install/systemd/*.timer /etc/systemd/system/

# 6. Reload and start
sudo systemctl daemon-reload
sudo systemctl start hookprobe-provision.service
sudo systemctl enable --now hookprobe-agent.service

Post-Installation

Verify Installation

# Check status
hookprobe-ctl status

# Check health
hookprobe-ctl health

# View logs
hookprobe-ctl logs -f

Enable Auto-Updates

sudo hookprobe-ctl enable-autoupdate

Enable XDP

# Edit service
sudo systemctl edit hookprobe-agent.service

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

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

Firewall Configuration

UFW (Ubuntu)

sudo ufw allow 8888/tcp  # Health endpoint

Guardian (Hotspot)

sudo ufw allow 67/udp    # DHCP
sudo ufw allow 53/udp    # DNS

Mesh Ports

sudo ufw allow 8144/udp  # HTP protocol
sudo ufw allow 7946/tcp  # Gossip
sudo ufw allow 7946/udp  # Gossip

Troubleshooting

Installation Fails

# Check logs
cat /var/log/hookprobe/provision.log

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

Service Won’t Start

# Check status
systemctl status hookprobe-agent.service

# View errors
journalctl -u hookprobe-agent.service -n 50

# Check dependencies
sudo apt install -y podman openvswitch-switch

Port Conflicts

# Check port usage
sudo ss -tlnp | grep 8888

# Kill conflicting process or change port

Next Steps

Configuration - Customize settings
CLI Reference - Management commands
Debugging - Troubleshoot issues