Getting Started

Qtap is Qpoint's lightweight eBPF agent that captures network traffic at the Linux kernel level. It can run standalone (configured via YAML) or connected to Qplane for centralized management.

Choose Your Quick Start Path

We have several getting started guides tailored to different needs:

For First-Time Users

5-Minute Quickstart - Fast preview with console output

• Time: 5 minutes

• Best for: Testing if Qtap works on your system, quick demo

• You'll get: Real-time console output of HTTP/HTTPS traffic

For Production Deployment

Complete Guide: Hello World to Production - Progressive 4-level tutorial

• Time: 50 minutes (pauseable between levels)

• Best for: Learning Qtap systematically, production deployment planning

• You'll learn: Basic setup → Filtering → Rules → S3 storage

For Urgent Debugging

Production Debugging with HTTPS Visibility - Emergency troubleshooting

• Time: 30 seconds to 5 minutes

• Best for: Active production issues requiring immediate visibility

• You'll get: HTTPS traffic inspection without certificates

For Specific Use Cases

• Interactive debugging: DevTools UI - Browser-Based Traffic Inspection

• Web servers (NGINX, Caddy, etc.): NGINX Traffic Capture

• Ingress traffic: Ingress Traffic Capture

• All guides: Qtap Guides Overview

---

System Requirements

Before getting started, check the system requirements for details on Qtap compatibility.

Quick compatibility check:

curl -sSL https://github.com/qpoint-io/preflight/releases/latest/download/preflight.sh | sudo bash

Minimum Requirements

• Linux kernel 5.10+ (check with uname -r)

• Docker installed (for Docker-based deployment)

• root/sudo permissions

• eBPF support enabled

---

Quick Demo

Want to see Qtap in action right now? Run this one-liner:

# Run Qtap in demo mode (captures traffic to console)
curl -s https://get.qpoint.io/demo | sudo sh

This starts Qtap with a basic configuration that outputs captured traffic to your console. Generate some traffic with curl to see it in action.

Docker Demo

Step 1: Create a Simple Qpoint Configuration File

# Create a directory for your configuration
mkdir -p ~/qpoint-demo/config

# Create the configuration file
cat > ~/qpoint-demo/config/qpoint.yaml << 'EOF'
version: 2

services:
  event_stores:
    - id: console_stdout
      type: stdout
  
  object_stores:
    - id: console_stdout
      type: stdout

stacks:
  default_stack: # Stack Name
    plugins:
      - type: access_logs
        config:
          mode: details # Default action (summary|details|full)
          format: console # (json|console)

tap:
  direction: egress
  ignore_loopback: false
  audit_include_dns: true
  http:
    stack: default_stack
EOF

Step 2: Run the Qpoint Tap Agent

Now, deploy the Qtap agent:

docker run -d \
  --name qtap \
  --user 0:0 \
  --privileged \
  --cap-add CAP_BPF \
  --cap-add CAP_SYS_ADMIN \
  --pid=host \
  --network=host \
  -v /sys:/sys \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/qpoint-demo/config:/app/config \
  -e TINI_SUBREAPER=1 \
  --ulimit=memlock=-1 \
  us-docker.pkg.dev/qpoint-edge/public/qtap:v0 \
  tap \
  --log-level=warn \
  --log-encoding=console \
  --config=/app/config/qpoint.yaml

Step 3: Generate Some Test Traffic

Let's create some test traffic to see Qpoint in action:

# Create a test container and send HTTP requests
docker run --rm --name test-client curlimages/curl \
  sh -c "curl -v https://httpbin.org/get && \
         curl -v https://httpbin.org/status/404 && \
         curl -v https://httpbin.org/status/500"

Step 4: View the Captured Traffic

Check the Qtap logs to see the traffic being captured:

docker logs qtap -f

You should see log entries showing:

• Connection details (source, destination, protocol)

• HTTP request and response metadata

• Full request and response payloads in the console

• Error information for the 404 and 500 responses

Example output snippet:

===================================================================
curl → GET https://httpbin.org/status/500 503 Service Unavailable
===================================================================

------------------ META ------------------
PID: 194603
Exe: /usr/bin/curl
Container ID: 6f4fccfae3f7
Direction: egress-external
Bytes Sent: 46
Bytes Received: 232

------------------ REQUEST ------------------
GET httpbin.org http2
Accept: */*
Qpoint-Request-Id: cvct1q87p3qj89ieqtlg
:authority: httpbin.org
:method: GET
:path: /status/500
:scheme: https
User-Agent: curl/8.12.1

------------------ RESPONSE ------------------
503 Service Unavailable
:status: 503
Server: awselb/2.0
Date: Tue, 18 Mar 2025 20:00:41 GMT
Content-Type: text/html
Content-Length: 162

Step 5: Test Specific Use Cases

Now that Qpoint is running, you can try various use cases to see more capabilities:

Capture API Authentication Issues

# Test missing or invalid API key
docker run --rm --name test-auth curlimages/curl \
  -v https://httpbin.org/bearer -H "Authorization: Bearer invalid-token"

Monitor Third-Party API Health

# Create a loop to periodically check an API
docker run --rm --name test-health curlimages/curl \
  sh -c "for i in {1..5}; do curl -s https://httpbin.org/status/200,200,200,500 > /dev/null; sleep 2; done"

Track Slow Responses

# Test a delayed response
docker run --rm --name test-delay curlimages/curl \
  https://httpbin.org/delay/2