Building from Source

Compile Zentinel and agents from source code.

Prerequisites

Rust Toolchain

Install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Verify installation
rustc --version  # 1.75.0 or later
cargo --version

System Dependencies

macOS:

brew install openssl pkg-config

Ubuntu/Debian:

sudo apt update
sudo apt install build-essential pkg-config libssl-dev

RHEL/Fedora:

sudo dnf install gcc openssl-devel pkg-config

Optional Dependencies

For the ModSecurity agent:

# macOS
brew install libmodsecurity

# Ubuntu/Debian
sudo apt install libmodsecurity-dev

Building Zentinel

Clone the Repository

git clone https://github.com/zentinelproxy/zentinel.git
cd zentinel

Debug Build

cargo build

Binary location: target/debug/zentinel

Release Build

cargo build --release

Binary location: target/release/zentinel

Build with Features

# All features
cargo build --release --all-features

# Specific features
cargo build --release --features "metrics,tracing"

Available Features

FeatureDescriptionDefault
metricsPrometheus metrics endpointYes
tracingOpenTelemetry tracingYes
tlsTLS/HTTPS supportYes
http2HTTP/2 supportYes
websocketWebSocket proxyingYes

Building Agents

WAF Agent

git clone https://github.com/zentinelproxy/zentinel-agent-waf.git
cd zentinel-agent-waf
cargo build --release

ModSecurity Agent

Requires libmodsecurity:

git clone https://github.com/zentinelproxy/zentinel-agent-modsec.git
cd zentinel-agent-modsec

# Set library paths if needed (macOS)
export CPLUS_INCLUDE_PATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

cargo build --release

JavaScript Agent

git clone https://github.com/zentinelproxy/zentinel-agent-js.git
cd zentinel-agent-js
cargo build --release

AI Gateway Agent

git clone https://github.com/zentinelproxy/zentinel-agent-ai-gateway.git
cd zentinel-agent-ai-gateway
cargo build --release

WebSocket Inspector

git clone https://github.com/zentinelproxy/zentinel-agent-websocket-inspector.git
cd zentinel-agent-websocket-inspector
cargo build --release

Cross-Compilation

Linux from macOS

# Add target
rustup target add x86_64-unknown-linux-gnu

# Install cross-compiler
brew install filosottile/musl-cross/musl-cross

# Build
cargo build --release --target x86_64-unknown-linux-gnu

Using Cross

For easier cross-compilation:

cargo install cross

# Build for Linux
cross build --release --target x86_64-unknown-linux-gnu

# Build for ARM64
cross build --release --target aarch64-unknown-linux-gnu

Static Linking (musl)

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

Build Profiles

Cargo.toml Settings

[profile.release]
lto = true           # Link-time optimization
codegen-units = 1    # Better optimization
panic = "abort"      # Smaller binary
strip = true         # Strip symbols

[profile.release-debug]
inherits = "release"
debug = true         # Include debug symbols
strip = #false

Build with custom profile:

cargo build --profile release-debug

Verification

Check Binary

# Version
./target/release/zentinel --version

# Help
./target/release/zentinel --help

# Validate config
./target/release/zentinel validate -c zentinel.kdl

Run Tests

cargo test
cargo test --release

Check for Issues

# Formatting
cargo fmt --check

# Lints
cargo clippy -- -D warnings

# Security audit
cargo audit

Troubleshooting

OpenSSL Not Found

# macOS
export OPENSSL_DIR=$(brew --prefix openssl)

# Linux
export OPENSSL_DIR=/usr

cargo build --release

libmodsecurity Not Found

# Check installation
pkg-config --libs modsecurity

# Set paths manually
export CPLUS_INCLUDE_PATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

Out of Memory

For large builds:

# Reduce parallelism
cargo build --release -j 2

Slow Builds

Use sccache for faster rebuilds:

cargo install sccache
export RUSTC_WRAPPER=sccache
cargo build --release

Next Steps