> For the complete documentation index, see [llms.txt](https://docs.qpoint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qpoint.io/getting-started/qtap/getting-started.md).

# 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**](/guides/qtap-guides/getting-started/qtap-starter-configuration-stdout-only.md) - 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**](/guides/qtap-guides/getting-started/getting-started-complete-guide.md) - 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**](/guides/qtap-guides/debugging/production-debugging-with-https-visibility.md) - 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](/getting-started/qtap/configuration/devtools.md)
* **Web servers (NGINX, Caddy, etc.):** [NGINX Traffic Capture](/guides/qtap-guides/web-server-integration/capturing-nginx-traffic.md)
* **Ingress traffic:** [Ingress Traffic Capture](/guides/qtap-guides/getting-started/ingress-traffic-capture-with-python.md)
* **All guides:** [Qtap Guides Overview](/guides/qtap-guides.md)

***

## System Requirements

Before getting started, check the [system requirements](/getting-started/qtap/system-requirements.md) for details on Qtap compatibility.

**Quick compatibility check:**

{% code overflow="wrap" fullWidth="false" %}

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

{% endcode %}

### 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:

```bash
# 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

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

```bash
# 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:

```bash
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=info \
  --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:

```bash
# 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:

```bash
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:

{% code overflow="wrap" %}

```
===================================================================
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

```

{% endcode %}

### 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

```bash
# 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

{% code overflow="wrap" %}

```bash
# 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"
```

{% endcode %}

#### Track Slow Responses

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