# Settings

This guide walks through the Settings section of Qplane, explaining how to configure your Qtap agents, manage data services, and control what traffic gets captured. Settings apply globally to all connected agents in your organization.

***

### Overview

**Location:** Settings (top navigation)

The Settings area is organized into three main sections:

**Organizations**

* General: Organization details
* Team: User management (covered in Teams & RBAC guide)
* Views: Filtered dashboards and RBAC (covered in Teams & RBAC guide)
* SSO: Single sign-on configuration

**Qtap**

* Config: Core capture settings
* Filters: Process filtering to reduce noise

**Deploy**

* Environments: Registration token management
* Services: Data destinations (event stores, object stores, Qscan)
* Releases: Configuration version control (covered in Releases guide)
* Snapshot: View auto-generated YAML

***

### Qtap Configuration

**Location:** Settings → Qtap → Config

This page controls what traffic Qtap captures and where event metadata goes.

#### Audit Log Destination

**What it is:** Where anonymized event metadata (connection info, status codes, timing) gets sent.

**Default:** Pulse (Qpoint Cloud event store)

**Options:**

* **Pulse**: Qpoint's managed ClickHouse-based event store. Required for Qplane dashboards, traffic analysis, and alerting to work.
* **Stdout**
* **Disabled**

**When to change:** Rarely. Keep Pulse enabled unless you have a specific requirement to send events to your own infrastructure.

**YAML mapping:**

```yaml
services:
  event_stores:
    - id: qpoint_cloud
      type: pulse
      url: https://api-pulse.qpoint.io
```

#### Traffic Direction

**What it is:** Which network connections Qtap monitors.

**Default:** Egress (Only External)

**Options:**

* **Egress (Only External)**: Only outbound traffic to external/public IPs. Ignores internal/private IP ranges.
* **Egress (All)**: All outbound traffic including internal services.
* **Egress (Only Internal):** Only outbound traffic to internal IPs.

{% hint style="warning" %}
**Qplane Limitation:** Ingress and bidirectional (all) traffic capture are not supported through Qplane configuration. To capture ingress or all traffic, you must use [local YAML configuration](/getting-started/qtap/configuration/traffic-capture-settings.md) with standalone Qtap deployment.
{% endhint %}

**YAML mapping:**

```yaml
tap:
  direction: egress-external  # or egress, or egress-internal
  # Note: ingress and all are only available with local YAML config
```

#### Advanced Settings

**Local Loopback Traffic**

**What it is:** Capture traffic on loopback devices (127.0.0.1, localhost)

**Default:** Disabled (toggle off)

**When to enable:**

* Debugging local development
* Monitoring services that communicate via localhost
* Testing Qtap configuration locally

**Note:** Usually redundant. Most production traffic doesn't use loopback.

**YAML mapping:**

```yaml
tap:
  ignore_loopback: true  # false to capture loopback
```

**Capture DNS**

**What it is:** Log and capture DNS queries

**Default:** Disabled (toggle off)

**When to enable:**

* Security investigations (DNS tunneling detection)
* Troubleshooting DNS resolution issues
* Understanding what domains your services resolve

**Warning:** Very noisy. Generates a lot of events. Enable only when specifically needed.

**YAML mapping:**

```yaml
tap:
  audit_include_dns: false  # true to capture DNS
```

***

### Qtap Filters

**Location:** Settings → Qtap → Filters

Filters reduce noise by ignoring traffic from known processes you don't need to monitor. This improves performance and reduces data volume.

#### Ignore Process Groups

Pre-defined groups of processes you can toggle on/off:

**Kubernetes**

**What it ignores:** Standard Kubernetes processes (kube-proxy, kubelet, kube-dns, etc.)

**When to enable:** Always, unless specifically debugging Kubernetes control plane issues.

**Why:** Kubernetes processes generate constant internal traffic that's rarely relevant for application monitoring.

**Container Runtimes**

**What it ignores:** Container runtime processes (containerd, dockerd, runc, etc.)

**When to enable:** Always, unless debugging container runtime issues.

**Why:** Container runtime traffic is infrastructure-level and not application-relevant.

**Google Kubernetes Engine (GKE)**

**What it ignores:** Built-in GKE processes and system services.

**When to enable:** Always when running on GKE.

**Why:** GKE-specific processes create noise without providing application insights.

**Amazon Elastic Kubernetes Service (EKS)**

**What it ignores:** Built-in EKS processes and system services.

**When to enable:** Always when running on EKS.

**Why:** EKS-specific processes create noise without providing application insights.

**Qpoint**

**What it ignores:** Qpoint self-auditing (Qtap agent's own traffic)

**When to enable:** Always.

**Why:** Prevents Qtap from monitoring itself, which would create recursive capture loops.

**Best Practice:** Enable all relevant filters for your environment. Start with all enabled, then disable selectively only if you need to investigate specific infrastructure issues.

**YAML mapping:**

```yaml
tap:
  filters:
    ignore_processes:
      groups:
        - kubernetes
        - container
        - qpoint
        - gke
        - eks
```

#### Custom Filters

**What it is:** Manually specify executable paths to ignore.

**Use cases:**

* Internal monitoring tools that generate noise
* Backup agents
* Log shippers
* CI/CD runners
* Any process that creates traffic you don't need to monitor

**How to add:**

1. Click "+ Add Filter"
2. Enter the full executable path (e.g., `/usr/bin/prometheus-node-exporter`)
3. Save

**Finding executable paths:** Look at the Process column in your Traffic or Inventory pages to identify noisy processes.

**YAML mapping:**

```yaml
tap:
  filters:
    ignore_processes:
      executables:
        - /usr/bin/sshd
        - /usr/sbin/nginx
```

***

### Environments

**Location:** Settings → Deploy → Environments

Environments manage registration tokens for connecting Qtap agents to Qplane. Each environment has its own token for tracking which agents belong to which deployment (dev, staging, prod).

#### Default Environment

Created automatically with your organization. Contains a pre-generated registration token.

#### Viewing a Token

Click "Manage" on an environment to see:

**Name:** The environment identifier

**Auth Token:** The registration token used to connect agents

**Actions:**

* **Copy button**: Copy token to clipboard

#### Creating Additional Environments

**Why create multiple environments:**

* Separate dev, staging, and production agents
* Track different clusters or regions
* Isolate teams or projects
* Facilitate troubleshooting by identifying which agents belong where

**How to create:**

1. Click "+ Environment"
2. Enter a name (e.g., "Production", "Staging-US-West", "Team-Payments")
3. A new token is generated automatically
4. Copy the token
5. Deploy agents with this token using `--registration-token=<token>`

**Viewing agents by environment:** In Settings → Installations, you can see which environment each agent belongs to.

**Best Practices:**

* Use descriptive names: "Production-US-East-1" not "prod"
* Create environments before deploying agents, not after
* Store tokens securely (Kubernetes Secrets, AWS Secrets Manager, etc.)
* Never commit tokens to version control
* Document which token goes with which deployment

**YAML impact:** Environments don't appear in YAML. The token is passed at agent startup:

```bash
sudo qtap --registration-token=<your-token-here>
```

***

### Data Services

**Location:** Settings → Deploy → Services

Services define where Qtap sends different types of data: anonymized events, sensitive payloads, and data for classification.

#### Object Stores

**What they store:** Request/response headers and bodies (sensitive payloads)

📖 **See the** [**Object Storage Configuration Guide**](/getting-started/qplane/configuration/object-storage.md) **for complete setup instructions, understanding when data is stored, and security best practices.**

**Default:** Qpoint Cloud (managed object store for preview and testing)

**Important Security Note:**

> Payloads may contain sensitive data. Configure an object store to ensure your data never leaves your network and is accessible only from those with proper access.

**Qpoint Cloud (Default)**

**Purpose:** Preview and testing only

**When to use:**

* Initial setup and testing
* Proof of concept
* Development environments

**When NOT to use:**

* Production environments
* Any traffic containing real customer data
* Compliance-sensitive deployments (GDPR, HIPAA, PCI-DSS)

**Why:** Qpoint Cloud is a managed service for convenience, but your production data should stay in your infrastructure.

**YAML mapping:**

```yaml
services:
  object_stores:
    - id: qpoint_cloud
      type: qpoint
      url: https://warehouse.qpoint.io
```

**Adding Your Own Object Store**

**Recommended for production.** Configure your own S3-compatible storage:

**Supported:**

* AWS S3
* Google Cloud Storage
* MinIO
* Any S3-compatible API

**How to add:**

1. Click "+ Add Object Store"
2. Choose type (S3, GCS, etc.)
3. Configure:
   * Endpoint (e.g., `s3.amazonaws.com`)
   * Bucket name
   * Region
   * Access credentials (use environment variables recommended)
   * Access URL template

**Example configuration:**

```yaml
object_stores:
  - id: production_s3
    type: s3
    endpoint: s3.amazonaws.com
    bucket: my-company-qpoint-data
    region: us-west-2
    access_url: https://s3.amazonaws.com/{{BUCKET}}/{{DIGEST}}
    access_key:
      type: env
      value: AWS_ACCESS_KEY_ID
    secret_key:
      type: env
      value: AWS_SECRET_ACCESS_KEY
```

**Security Best Practice:** Rotate access keys regularly and store them in a secrets manager. IAM roles and workload identity are not currently supported for S3 authentication.

#### Event Stores

**What they store:** Anonymized connection metadata (IPs, ports, status codes, timing)

**Qpoint Cloud (Default)**

**Purpose:** Powers Qpoint's dashboards, traffic analysis, and alerting

**Description:** "Qpoint's managed cloud event store, powering events and analytics"

**When to use:** Always, unless you have specific compliance requirements requiring all data to stay internal.

**Why:** Qplane's Traffic, Inventory, Dashboard, and Alerting features depend on event data in Pulse.

**Data sent:**

* Source/destination IPs and ports
* HTTP methods and status codes
* Response times and sizes
* Process and container names
* Anonymized metadata only (no payloads)

**YAML mapping:**

```yaml
services:
  event_stores:
    - id: qpoint_cloud
      type: pulse
      url: https://api-pulse.qpoint.io
```

**Adding Custom Event Stores**

**Use cases:**

* Send events to your existing observability platform
* Compliance requirements (data residency)
* Custom analytics pipelines

**How to add:**

1. Click "+ Add Event Store"
2. Configure endpoint and credentials

**Note:** Even with custom event stores, keep Pulse enabled if you want to use Qplane's dashboards and alerting.

#### Qscans

**What they do:** Scan payloads for sensitive data classification (PII, credentials, secrets)

**Default:** Qpoint Cloud (managed Qscan for preview and testing)

**Important Note:**

> Scan payloads and data for sensitive data like PII, PCI, PHI, etc. Run internally or leverage Qpoint's managed service.

**Qpoint Cloud (Default)**

**Purpose:** Preview and testing only

**Description:** "Qpoint's managed cloud qscan service, for preview and testing only"

**When to use:**

* Testing the Scan Payloads & Data plugin
* Proof of concept
* Understanding what data types Qscan detects

**When NOT to use:**

* Production environments
* Real customer data
* Compliance-sensitive use cases

**YAML mapping:**

```yaml
services:
  qscan:
    type: client
    url: https://api-s.qpoint.io
```

**Adding Your Own Qscan**

**Recommended for production.** Run Qscan in your environment:

**Deployment:**

* Docker container in your VPC
* Kubernetes pod in your cluster
* VM in your network

**How to add:**

1. Deploy Qscan container in your environment
2. Click "+ Add Qscan"
3. Configure:
   * URL (e.g., `https://qscan.internal.company.com`)
   * Authentication token

**Example configuration:**

```yaml
services:
  qscan:
    type: client
    url: https://qscan.internal.company.com
    token:
      type: env
      value: QSCAN_TOKEN
```

**Using Qscan:** After configuring, add the "Scan Payloads & Data" plugin to stacks where you need sensitive data classification.

***

### Snapshot

**Location:** Settings → Deploy → Snapshot

The Snapshot page shows the complete auto-generated YAML configuration that Qplane sends to your connected agents.

#### What You See

**Title:** Auto-Generated Config

**Content:** Full `qpoint.yaml` with:

* Version
* Services (event stores, object stores, qscan)
* Stacks (with all plugins and configurations)
* Tap settings (direction, filters, routing)

**Copy button:** Click to copy the entire YAML to clipboard

#### Why It's Useful

**Verify UI Changes:** After making changes in Qplane (creating stacks, modifying plugins, adjusting filters), check the Snapshot to see the resulting YAML before it deploys to agents.

**Version Control:** Copy the Snapshot YAML and commit to Git to track configuration changes over time.

**Bootstrap New Environments:** Download Snapshot YAML to bootstrap a local deployment or test environment.

**Debugging:** Compare the Snapshot with what an agent is actually running to identify configuration drift or propagation issues.

**Learning:** Understand how UI actions translate to YAML structure. Great for learning the relationship between Qplane and Qtap configuration.

**Migration:** If you need to migrate from Qplane to local YAML deployment, use the Snapshot as your starting point.

#### Example Snapshot

```yaml
version: 2
services:
  event_stores:
    - id: qpoint_cloud
      type: pulse
      url: https://api-pulse.qpoint.io
      token:
        type: text
        value: eyJhbGci...
  object_stores:
    - id: qpoint_cloud
      type: qpoint
      url: https://warehouse.qpoint.io
      token:
        type: text
        value: eyJhbGci...
  qscan:
    type: client
    url: https://api-s.qpoint.io

stacks:
  basic_reporting_and_error_detection:
    plugins:
      - type: report_usage
      - type: detect_errors
        config:
          rules:
            - name: App Error
              trigger_status_codes: ['500']
              only_categories: [app]
              report_as_issue: true
              record_req_headers: true
              record_req_body: true
              record_res_headers: true
              record_res_body: true
            # ... additional error rules

tap:
  direction: egress-external
  ignore_loopback: true
  audit_include_dns: false
  filters:
    ignore_processes:
      groups:
        - kubernetes
        - container
        - qpoint
  http:
    stack: basic_reporting_and_error_detection
```

#### What's NOT in the Snapshot

These features exist only in Qplane UI and don't appear in YAML:

* Alerting rules and integrations
* Team members and permissions
* Views (filtered dashboards)
* SSO configuration
* Environment tokens


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qpoint.io/getting-started/qplane/configuration/settings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.