Configuration Guide

2. Configuration Guide

This guide provides detailed information about the configuration parameters available in the CompassVPN Web Panel. The Web Panel saves these settings to the env_file in the root directory of the CompassVPN agent.

Use this guide as a reference for understanding the different options you can set within the Web Panel.

Complete Configuration File

Below is the complete example of the env_file with all available settings:

# Metric push method - pushgateway or grafana_agent
METRIC_PUSH_METHOD=grafana_agent

# METRIC_PUSH_METHOD: grafana_agent
GRAFANA_AGENT_REMOTE_WRITE_URL=https://prometheus-prod-XXX-grafana.grafana.net/api/prom/push
GRAFANA_AGENT_REMOTE_WRITE_USER=XXX
GRAFANA_AGENT_REMOTE_WRITE_PASSWORD=glc_XXX

# METRIC_PUSH_METHOD: pushgateway
#PUSHGATEWAY_URL=https://your-pushgateway-url:9091
#PUSHGATEWAY_AUTH_USER=username
#PUSHGATEWAY_AUTH_PASSWORD=password

# name of the donor - will appear in all metrics as a label
DONOR=compass

# How often configurations are reset (e.g., 1d for daily, 14d for 14 days, 1m for 1 month)
REDEPLOY_INTERVAL=1m

# Authentication token for Cloudflare API access
CF_API_TOKEN=YOUR_CF_API_TOKEN

# Cloudflare zone identifier for your domain
CF_ZONE_ID=YOUR_CF_ZONE_ID

# Domain or IP address used for clean IP testing
CF_CLEAN_IP_DOMAIN=npmjs.com

# How outbound connections are routed (direct or through Warp)
XRAY_OUTBOUND=direct

# Selected inbound configurations (comma-separated)
XRAY_INBOUNDS=vless-tcp-tls-direct,vless-hu-tls-direct,vless-hu-tls-cdn,vless-xhttp-quic-direct,vless-xhttp-quic-cdn

# Which SSL certificate provider to use (letsencrypt or zerossl)
SSL_PROVIDER=letsencrypt

# Controls whether the system automatically updates itself
AUTO_UPDATE=on

# The URL path used in NGINX configuration
NGINX_PATH=compass

# Website to mimic for obfuscation purposes
NGINX_FAKE_WEBSITE=www.google.com

# DNS provider to use (default, cf, controld, or custom URL)
CUSTOM_DNS=controld

# Whether to enable debug logging mode
DEBUG=disable

Detailed Parameter Explanations

Below is a comprehensive breakdown of each configuration parameter in the env_file:

METRIC_PUSH_METHOD

Value options: grafana_agent or pushgateway
Description: Defines how metrics are collected and sent. Choose the method that best suits your monitoring infrastructure.

grafana_agent:
- Uses Grafana’s free cloud tier
- Simpler to set up and manage
- Recommended for most users
pushgateway:
- Runs on your own server
- More complex to configure but provides better control
- Better for advanced users who need full control over their metrics

GRAFANA_AGENT_REMOTE_WRITE_URL

Required if: METRIC_PUSH_METHOD=grafana_agent
Example: https://prometheus-prod-XXX-grafana.grafana.net/api/prom/push
Description: The endpoint URL where Grafana Agent will send metrics data.

GRAFANA_AGENT_REMOTE_WRITE_USER

Required if: METRIC_PUSH_METHOD=grafana_agent
Example: XXX
Description: Username for authenticating with the Grafana metrics endpoint.

GRAFANA_AGENT_REMOTE_WRITE_PASSWORD

Required if: METRIC_PUSH_METHOD=grafana_agent
Example: glc_XXX
Description: Password for authenticating with the Grafana metrics endpoint.

Note:
All Grafana credential values (URL, username, and password) can be obtained from the Grafana Cloud platform.
See the Manager Setup Guide for detailed instructions on obtaining these credentials.

PUSHGATEWAY_URL

Required if: METRIC_PUSH_METHOD=pushgateway
Example: https://your-pushgateway-url:9091
Description: The URL of the Pushgateway server for sending metrics.

PUSHGATEWAY_AUTH_USER

Required if: METRIC_PUSH_METHOD=pushgateway
Example: username
Description: Username for Pushgateway authentication.

PUSHGATEWAY_AUTH_PASSWORD

Required if: METRIC_PUSH_METHOD=pushgateway
Example: password
Description: Password for Pushgateway authentication.

Note:
Pushgateway requires setting up your own Prometheus instance and Pushgateway server.
Refer to the Prometheus documentation and Manager Setup Guide for setting up Pushgateway on your server.
You’ll need to configure basic authentication for security and ensure the server is accessible to your CompassVPN agent.

DONOR

Example: your_identifier
Default: compass
Description: An identifier used as a label in all metrics. This helps identify this specific server instance in your monitoring system.

REDEPLOY_INTERVAL

Example: 7d (7 days)
Format: 1d (1 day), 14d (14 days), 1m (1 month)
Default: 1m
Description: How often CompassVPN will reset its configuration and generate new identifiers. This helps maintain security and freshness of the configuration.

CF_API_TOKEN

Example: YOUR_CF_API_TOKEN
Description: Authentication token for Cloudflare API access. This token is required to manage DNS records and SSL certificates through Cloudflare’s API when using CDN-proxied configurations.

Note:
Keep your API token secure and never share it. The token has permissions to modify DNS records and SSL certificates for your domain.

To create this token:

Log in to your Cloudflare dashboard
Select your domain
Navigate to My Profile > API Tokens
Click Create Token > Create Custom Token
Set a descriptive name (e.g., “CompassVPN”)
Add these permissions:
- Zone - DNS - Edit
- Zone - SSL and Certificates - Edit
Under Zone Resources, select:
- Include - Specific zone - [your-domain.com]
Set expiration time (optional)
Create token and copy the value

CF_ZONE_ID

Example: YOUR_CF_ZONE_ID
Description: Cloudflare zone identifier for your domain. This unique identifier is required for managing your domain’s DNS and SSL settings through Cloudflare’s API when using CDN-proxied configurations.

Note:
To find your Zone ID:

Log in to your Cloudflare dashboard
Select your domain
Scroll down on the overview page
Look for Zone ID in the right sidebar
Copy the value for your CompassVPN configuration

CF_CLEAN_IP_DOMAIN

Example: npmjs.com or 104.17.223.1
Default: npmjs.com
Description: Domain or IP address used for clean IP testing when CDN configurations are enabled. This must be either a domain behind Cloudflare CDN or a Cloudflare IP address to ensure accurate testing.

Note:
You can use either a domain or a Cloudflare IP address. To verify:
For domains:
Visit browserleaks.com/ip
Check the ISP and Organization fields
They should show “Cloudflare” or “Cloudflare, Inc.”
For IP addresses:
Open the IP in your browser with /cdn-cgi/trace/ suffix
Example: http://104.17.69.69/cdn-cgi/trace/
If you see a response with IP, user-agent, and other info, it’s a valid Cloudflare IP
You can find the complete list of Cloudflare IP ranges at cloudflare.com/ips .
Examples:
npmjs.com
speed.cloudflare.com
104.17.69.69
172.66.0.69

XRAY_OUTBOUND

Value options: direct or warp
Default: direct
Description: How outbound connections are routed. Choose between direct connections or routing through Cloudflare WARP.

Note:
Each option has its tradeoffs:
Feature Direct WARP
Throughput Your Server Port 1 Gbps cap
Latency Lower Slightly higher
IP Restrictions May face restrictions Bypasses most restrictions
CAPTCHAs May encounter more Reduced frequency
Bandwidth Cost Standard rates May be reduced via Bandwidth Alliance
The Bandwidth Alliance is particularly beneficial if your server is hosted with a participating provider, as it can significantly reduce or eliminate data transfer fees.

Feature	Direct	WARP
Throughput	Your Server Port	1 Gbps cap
Latency	Lower	Slightly higher
IP Restrictions	May face restrictions	Bypasses most restrictions
CAPTCHAs	May encounter more	Reduced frequency
Bandwidth Cost	Standard rates	May be reduced via Bandwidth Alliance

XRAY_INBOUNDS

Example: vless-tcp-tls-direct,vless-hu-tls-cdn (Select desired types in the Web Panel)
Default: vless-tcp-tls-direct,vless-hu-tls-direct,vless-hu-tls-cdn,vless-xhttp-quic-direct,vless-xhttp-quic-cdn (all inbounds)
Description: Comma-separated list of the specific inbound configurations you want to enable. You select these from the available options in the Web Panel.

Available Inbound Types (Select in Web Panel):

Direct Connections:
- vless-tcp-tls-direct: VLESS over TCP with TLS
- vless-hu-tls-direct: VLESS over HTTPUpgrade (WebSocket) with TLS
- vless-xhttp-quic-direct: VLESS over XHTTP with QUIC
CDN-Proxied Connections: (Route traffic via Cloudflare CDN)
- vless-hu-tls-cdn: VLESS over HTTPUpgrade (WebSocket) with TLS (via Cloudflare CDN)
- vless-xhttp-quic-cdn: VLESS over XHTTP with QUIC (via Cloudflare CDN)

Note: If your server’s direct IP address is blocked by firewalls, it is recommended to select only the desired -cdn configurations (e.g., vless-hu-tls-cdn,vless-xhttp-quic-cdn) and leave out all -direct configurations. This ensures clients only receive connection options that bypass the direct IP block.

SSL_PROVIDER

Value options: letsencrypt or zerossl
Default: letsencrypt
Description: Which SSL certificate provider to use for securing connections. This setting determines which Certificate Authority (CA) will issue your SSL certificates.

Note:
Let’s Encrypt: Free, automated, and open certificate authority. Provides 90-day certificates with automatic renewal. Best for most users.
ZeroSSL: Alternative free CA with 90-day certificates. Offers additional features like wildcard certificates and better support for older systems.

AUTO_UPDATE

Value options: on or off
Default: on
Description: Controls whether the system automatically updates itself. When enabled, CompassVPN will automatically check for and apply updates to its core components.

Note:
Keeping auto-updates enabled is recommended for security and feature improvements. The system will only update when a new version is available and will maintain your existing configuration.

NGINX_PATH

Example: example_path
Default: compass
Description: The URL path used in NGINX’s internal routing system. This path is used by NGINX to properly route traffic to the VPN service and must be set to a valid value. The specific value doesn’t affect security or visibility to firewalls and DPIs, as it’s only used internally by NGINX for routing purposes.

NGINX_FAKE_WEBSITE

Example: www.example.com
Default: www.google.com
Description: Website to mimic for obfuscation purposes. When someone visits your domain, they will see content from this website instead of the VPN service. This helps maintain a low profile and avoid detection.

Note:
Choose a website that:
Is NOT behind Cloudflare, Fastly, or other major CDN services
Is commonly accessed in your server’s region
Has similar content to what you’re hosting
Is stable and reliable
Doesn’t raise suspicion
Security Warning: Using CDN-backed websites can create security vulnerabilities with SSL-stealing proxy solutions like XTLS/REALITY. Others could potentially use your server’s IP/domain as their CF_CLEAN_IP_DOMAIN, compromising your server’s security. Always use websites hosted directly on their own servers.

CUSTOM_DNS

Value options: default, cf, controld, or custom URL
Default: controld
Description: DNS provider to use for name resolution. This setting determines how your server resolves domain names, affecting both security and performance.

Note:
Each option has different features:
default: Uses your VPS provider’s DNS servers. Basic but reliable.
cf: CloudFlare’s secure DNS with malware blocking. Better than default and good for general use.
controld: ControlD’s free DNS with comprehensive content filtering:
Blocks ads, dating sites, drugs, gambling, malware
Can potentially save bandwidth and reduce costs
Generally recommended over default or cf for most users
Custom URLs: Support for various DNS protocols:
DoU (DNS over UDP): 76.76.2.2
DoT (DNS over TLS): tls+local://p2.freedns.controld.com
DoH (DNS over HTTPS): https+local://freedns.controld.com/p2
DoQ (DNS over QUIC): quic+local://p2.freedns.controld.com
Note on +local in Custom DNS URLs: The +local prefix in DoT, DoH, and DoQ URLs is essential. It instructs the system to first use the default server DNS to find the IP address of the custom DNS provider (e.g., p2.freedns.controld.com). Once the IP is found, the secure connection (TLS or QUIC) to the custom DNS server can be established. Always include +local when using DoT, DoH, or DoQ URLs to ensure they work correctly.

DEBUG

Value options: enable or disable
Default: disable
Description: Whether to enable debug logging mode. When enabled, the system will provide detailed logs about Xray-core operations and DNS resolution, which is useful for troubleshooting connection issues or diagnosing problems.

Note:
Debug mode should only be enabled when:
Troubleshooting connection issues
Diagnosing DNS problems
Working with support
Disable debug mode in production as it can impact performance and generate large log files.

Applying Configuration Changes

Configuration changes are applied automatically when you use the Save, Save & Close, or Save, Close, Start buttons within the Web Panel.

Next, proceed to the Manager Setup Guide to configure monitoring for your CompassVPN installation.