Version: 2.8.1

🐳 Docker

Running Jibril as a Docker container provides consistent, isolated deployments with minimal setup. This method is ideal for containerized environments, cloud deployments, and development workflows.

📦 Overview

Docker deployment offers several advantages:

🔒 Isolation: Contained environment with minimal host dependencies
📦 Portability: Run anywhere Docker is supported
🔄 Consistency: Same behavior across dev, staging, and production
⚡ Quick Setup: No manual binary installation required
🎯 Version Control: Easy rollback and version management

🚀 Quick Start

1️⃣ Pull Docker Image

# Pull daily version
docker pull docker.io/garnetlabs/jibril:v0.0

# Or pull the latest version
docker pull docker.io/garnetlabs/jibril:v2.8.1

2️⃣ Create Configuration

# Create config directory
sudo mkdir -p /etc/jibril

# Create configuration file
sudo vi /etc/jibril/config.yaml

📖 See Configuration Guide for configuration options.

3️⃣ Run Container

docker run -d \
  --name jibril \
  --privileged \
  --pid host \
  --network host \
  -v /sys:/sys:ro \
  -v /sys/fs/bpf:/sys/fs/bpf:rw \
  -v /var/log/jibril:/var/log/jibril:rw \
  docker.io/garnetlabs/jibril:v2.8.1

Add options to the docker command:

  # Bind mount /etc/jibril into the container.
  -v /etc/jibril:/etc/jibril:rw

  # Append Jibril cmdline arguments to the docker command.
  --config /etc/jibril/config.yaml

📋 Required Flags

`--privileged`

Required for eBPF

Grants full access to host devices and capabilities needed for eBPF program loading.

`--pid host`

Shared PID namespace

Access host processes for comprehensive monitoring.

`--network host`

Host networking

Monitor all network activity without network namespace isolation.

📂 Volume Mounts

Essential volume mounts for Jibril operation:

Required Mounts

Host Path	Container Path	Mode	Purpose
`/sys`	`/sys`	`ro`	System information
`/sys/fs/bpf`	`/sys/fs/bpf`	`rw`	eBPF filesystem

Optional Mounts (depending on configuration)

Host Path	Container Path	Mode	Purpose
`/etc/jibril`	`/etc/jibril`	`rw`	Configuration files
`/var/log/jibril`	`/var/log/jibril`	`rw`	Event output files (when using `varlog` printer)

🖨️ Output Configuration

Jibril supports multiple output methods (printers) for events. Understanding these options is crucial for proper Docker configuration.

📺 Stdout Printer

Events are printed to stdout/stderr and captured by Docker.

Configuration:

printers:
  stdout:
    enabled: true

Docker Requirements:

✅ No volume mounts needed
✅ Use docker logs to view events
✅ Integrates with Docker logging drivers
✅ Perfect for Docker/systemd log management

Example:

docker run -d \
  --name jibril \
  --privileged \
  --pid host \
  --network host \
  -v /sys:/sys:ro \
  -v /sys/fs/bpf:/sys/fs/bpf:rw \
  -v /etc/jibril:/etc/jibril:rw \
  docker.io/garnetlabs/jibril:v2.8.1 \
  --config /etc/jibril/config.yaml

# View events
docker logs -f jibril

📝 Varlog Printer

Events are written to specific files on disk.

Configuration:

printers:
  varlog:
    enabled: true
    path: /var/log/jibril/events.log

Docker Requirements:

⚠️ Must mount the log directory
📂 Volume: -v /var/log/jibril:/var/log/jibril:rw
📁 Ensure directory exists on host
🔒 Proper permissions required

Example:

# Create log directory
sudo mkdir -p /var/log/jibril
sudo chmod 755 /var/log/jibril

# Run container with varlog
docker run -d \
  --name jibril \
  --privileged \
  --pid host \
  --network host \
  -v /sys:/sys:ro \
  -v /sys/fs/bpf:/sys/fs/bpf:rw \
  -v /etc/jibril:/etc/jibril:rw \
  -v /var/log/jibril:/var/log/jibril:rw \
  docker.io/garnetlabs/jibril:v2.8.1 \
  --config /etc/jibril/config.yaml

# View events directly on host
tail -f /var/log/jibril/events.log

🔧 Choosing the Right Printer

📺 Use Stdout When

🐳 Using Docker logging drivers (json-file, syslog, etc.)
📤 Forwarding logs to external systems via Docker
☸️ Running in Kubernetes (logs collected by kubelet)
⚡ Want simpler Docker configuration
🔄 Need dynamic log routing

📝 Use Varlog When

📂 Need direct file access on the host
🔄 Using custom log rotation tools
💾 Want persistent logs independent of container lifecycle
📊 Integrating with file-based log collectors
🔍 Need high-performance file I/O

🔀 Use Both When

🛡️ Need redundancy and failover
🔧 Different systems consume logs differently
🐛 Debugging + production logging simultaneously
📈 Real-time monitoring + persistent storage
⚖️ Compliance requires multiple outputs

💡 Tip

Multiple printers can be enabled simultaneously. Events will be sent to all enabled printers.

Printers can be tailored to your needs. Contact us at support@garnet.ai for custom configurations.

🎯 Common Usage Examples

🔍 Foreground Mode

Run interactively with logs:

docker run --rm \
  --name jibril \
  --privileged \
  --pid host \
  --network host \
  -v /sys:/sys:ro \
  -v /sys/fs/bpf:/sys/fs/bpf:rw \
  docker.io/garnetlabs/jibril:v2.8.1

📝 Custom Output

Direct output to specific location:

docker run -d \
  --name jibril \
  --privileged \
  --pid host \
  --network host \
  -v /sys:/sys:ro \
  -v /sys/fs/bpf:/sys/fs/bpf:rw \
  -v /custom/log:/var/log/jibril:rw \
  docker.io/garnetlabs/jibril:v2.8.1

🧪 Testing Configuration

Test config without daemon mode:

docker run --rm \
  --privileged \
  --pid host \
  --network host \
  -v /sys:/sys:ro \
  -v /sys/fs/bpf:/sys/fs/bpf:rw \
  -v ./test-config.yaml:/config.yaml:ro \
  docker.io/garnetlabs/jibril:v2.8.1 \
  --config /config.yaml

📊 Container Management

🔍 Monitor Container

# View container status
docker ps | grep jibril

# View resource usage
docker stats jibril

# Follow logs
docker logs -f jibril

# View last 100 lines
docker logs --tail 100 jibril

🔄 Control Container

# Stop container
docker stop jibril

# Start container
docker start jibril

# Restart container
docker restart jibril

# Remove container
docker rm -f jibril

🐳 Docker Compose

For easier management, use Docker Compose:

version: '3.8'

services:
  jibril:
    image: docker.io/garnetlabs/jibril:v2.8.1
    container_name: jibril
    privileged: true
    pid: host
    network_mode: host
    restart: unless-stopped
    volumes:
      - /sys:/sys:ro
      - /sys/fs/bpf:/sys/fs/bpf:rw
      - /etc/jibril:/etc/jibril:rw
      - /var/log/jibril:/var/log/jibril:rw
    command: --config /etc/jibril/config.yaml

Usage:

# Start service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop service
docker-compose down

🔄 Upgrading

To upgrade to a newer version:

# Stop and remove current container
docker stop jibril
docker rm jibril

# pull the daily version
docker pull docker.io/garnetlabs/jibril:v0.0

# Or pull the latest released version
docker pull docker.io/garnetlabs/jibril:v2.8.1

# Run new container with same configuration
docker run -d \
  --name jibril \
  --privileged \
  --pid host \
  --network host \
  -v /sys:/sys:ro \
  -v /sys/fs/bpf:/sys/fs/bpf:rw \
  -v /etc/jibril:/etc/jibril:rw \
  -v /var/log/jibril:/var/log/jibril:rw \
  docker.io/garnetlabs/jibril:v2.8.1 \
  --config /etc/jibril/config.yaml

🎓 Tips & Best Practices

✅ Best Practices

📝 Use Docker Compose for production deployments if not using Kubernetes.
🏷️ Pin specific image versions to avoid unexpected behavior.
🔄 Use restart: unless-stopped policy to ensure the container is always running.
📊 Monitor container resource usage to ensure the container is not consuming too many resources. Configure the cadences section in the configuration file to reduce the number of events and resources usage.
🔒 Keep configuration on a dedicated host volume to avoid conflicts with other containers.

⚠️ Common Issues

❌ Permission denied → Ensure the container is running as privileged and has the required capabilities.
❌ Can't load eBPF → Check if /sys/fs/bpf is mounted for both the host and the container.
❌ Events have bad content → Verify if Jibril is running on the host PID namespaces.
❌ Network not monitored → Verify if Jibril is running on the host network namespace and if network related features and events are enabled.

☸️ Kubernetes Deployment

For Kubernetes, use the dedicated Helm chart instead of plain Docker:

Recommended for K8s

helm install jibril jibril/jibril --namespace jibril-system --create-namespace

📖 See Kubernetes Guide for detailed Kubernetes deployment using the Helm chart.

🚀 Next Steps

⚙️

Configuration

Customize Jibril's behavior

☸️

Kubernetes

Deploy on K8s clusters

🎨

Customization

Create custom detections

📦 Overview​

🚀 Quick Start​

1️⃣ Pull Docker Image​

2️⃣ Create Configuration​

3️⃣ Run Container​

📋 Required Flags​

--privileged​

--pid host​

--network host​

📂 Volume Mounts​

🖨️ Output Configuration​

📺 Stdout Printer​

📝 Varlog Printer​

🔧 Choosing the Right Printer​

📺 Use Stdout When​

📝 Use Varlog When​

🔀 Use Both When​

🎯 Common Usage Examples​

🔍 Foreground Mode​

📝 Custom Output​

🧪 Testing Configuration​

📊 Container Management​

🔍 Monitor Container​

🔄 Control Container​

🐳 Docker Compose​

🔄 Upgrading​

🎓 Tips & Best Practices​

✅ Best Practices​

⚠️ Common Issues​

☸️ Kubernetes Deployment​

🚀 Next Steps​