FAQ

Frequently Asked Questions

General Questions

What is CompassVPN?

CompassVPN is an open-source, self-hosted VPN solution designed for security, reliability, scalability, and ease of deployment. It provides complete control over your VPN infrastructure, offering features like detailed monitoring, automated management (including configuration rotation and process monitoring), and enhanced security.

How is CompassVPN different from commercial VPN services?

Unlike commercial VPN services that operate on a subscription model and control the infrastructure, CompassVPN gives you full ownership of your VPN server. This means:

  • No monthly fees (you only pay for your VPS)
  • Complete privacy (you control all data)
  • Customizable security settings
  • No artificial speed limits
  • No user logs (unless you configure them)

Is CompassVPN free to use?

Yes, CompassVPN is open-source and free to use. You only need to pay for the server infrastructure that you deploy it on, such as a VPS from a cloud provider.

What protocols does CompassVPN support?

CompassVPN uses Xray-core, which primarily supports the VLESS protocol over various transports. The specific inbounds enabled can be configured using the XRAY_INBOUNDS variable in the Web Panel. Supported types include:

  • VLESS over TCP with TLS (vless-tcp-tls-direct)
  • VLESS with HTTPUpgrade (WebSocket) and TLS (vless-hu-tls-direct, vless-hu-tls-cdn)
  • VLESS with HTTP/2 (QUIC) and TLS (vless-xhttp-quic-direct, vless-xhttp-quic-cdn)

Technical Questions

What are the hardware requirements for CompassVPN?

  • VPS, Bare metal, Dedicated server with AMD64 or ARM64 architecture
  • Recommended: at least 2 vCPUs and 2GB RAM. (Minimum: at least 1 vCPU and 1GB RAM)
  • Approximately 5GB of storage space

Which operating systems are supported?

CompassVPN officially supports:

  • Ubuntu 20.04 LTS or newer
  • Debian 10 or newer

Can I run CompassVPN on other Linux distributions?

While CompassVPN is optimized for Ubuntu and Debian, advanced users might be able to adapt it for other distributions. However, we only provide official support and testing for Ubuntu and Debian to ensure reliability and security.

Can I run CompassVPN on a Raspberry Pi?

Yes, as long as your Raspberry Pi is running a supported operating system (like Ubuntu or Debian for ARM64) and has sufficient resources, you can run CompassVPN on it.

How does CompassVPN handle connections behind restrictive firewalls (like the GFW)?

CompassVPN offers several strategies to improve connectivity:

  • Cloudflare CDN Configurations: You can select specific inbound configurations in the Web Panel that route traffic through Cloudflare’s CDN (e.g., vless-hu-tls-cdn). This helps bypass direct IP blocks and can improve reliability. Selecting these requires providing Cloudflare API credentials.
  • Multiple Protocols: Support for different transport protocols (TCP, WS, QUIC) provides alternatives if one is blocked.
  • Obfuscation: Using NGINX and mimicking a standard website can help disguise traffic.

How does the Cloudflare integration work?

Selecting inbound configurations ending in -cdn (like vless-hu-tls-cdn) in the Web Panel enables routing traffic through Cloudflare’s CDN. For these configurations to function correctly with your domain, CompassVPN needs to automatically manage the necessary DNS records and SSL certificates within your Cloudflare account.

Therefore, providing your Cloudflare API Token (CF_API_TOKEN) and Zone ID (CF_ZONE_ID) in the Web Panel is required whenever you select one or more -cdn inbound types. CompassVPN uses these credentials to:

  • Create and manage the required DNS records (e.g., for subdomains used by CDN configurations) in your Cloudflare zone.
  • Obtain and manage the necessary SSL certificates for those subdomains.

This ensures seamless setup and operation when using Cloudflare CDN configurations.

What does Fail2ban do in CompassVPN?

Fail2ban is integrated to enhance server security. It monitors server logs (like NGINX access logs and Xray error logs) for suspicious activity, such as repeated failed login attempts or potential scanning patterns. If malicious patterns are detected, Fail2ban automatically updates the server’s firewall (UFW) rules to block the offending IP address for a period, preventing brute-force attacks and reducing server load.

What does Monit do in CompassVPN?

Monit is used for process monitoring and management within the CompassVPN agent setup. It constantly checks the status of critical services (like Xray, NGINX, metric exporters). If a service crashes or stops responding, Monit automatically attempts to restart it, ensuring higher availability and resilience of the VPN services.

Security Questions

Is CompassVPN secure?

CompassVPN is designed with security as a core principle and implements several modern practices:

  • TLS encryption for all standard VLESS connections.
  • Automatic SSL certificate management (ZeroSSL or Let’s Encrypt)
  • Built-in blocking of malicious content using curated lists.
  • Integrated Fail2ban for brute-force protection.
  • Automatic UFW firewall configuration.
  • Optional automatic updates for security patches.
  • Configuration rotation for enhanced security.

Does CompassVPN keep logs?

CompassVPN prioritizes user privacy: only you, the server administrator, have access to logs. Any minimal operational logs generated (e.g., NGINX access/error logs, or Xray logs if DEBUG=enable) reside solely on your own server; CompassVPN as a service does not collect or transmit these logs anywhere. This is distinct from the anonymized performance and usage metrics (collected by components like node-exporter, v2ray-exporter, and user-metrics), which are sent via metric-forwarder exclusively to your own configured monitoring destination (like Grafana Cloud or a self-hosted setup) and do not contain detailed user activity. Ultimately, you retain full control over all local logging levels and retention policies on your server.

Can CompassVPN block ads and malware?

Yes, CompassVPN includes multi-layered blocking capabilities:

  • DNS-Level Blocking: By setting CUSTOM_DNS to providers like cf (Cloudflare Security) or controld, or using a custom DNS server, you can block domains associated with malware, ads, etc., at the DNS resolution stage.
  • Xray Routing Rules: CompassVPN utilizes Xray’s routing engine with curated blocklists (sourced from projects like Chocolate4U/Iran-v2ray-rules ) to block traffic to:
    • Ads & Trackers
    • Malware & Phishing sites
    • Torrents
    • Specific regional content (e.g., Iranian websites)

This multi-layered approach helps block significant amounts (approx. 30%) of malicious and unwanted traffic through both DNS-level filtering (based on your CUSTOM_DNS selection) and Xray routing rules utilizing curated blocklists that are typically updated daily.

Deployment Questions

Can I deploy multiple CompassVPN servers?

Yes, the agent is designed for horizontal scalability. You can deploy multiple CompassVPN agent instances, potentially behind a load balancer for high availability, to handle increased user load. Each agent operates independently but can report metrics to a shared, central Manager component (like Grafana Cloud or a self-hosted setup) for unified monitoring.

How do I share VPN access with others?

After successfully setting up CompassVPN, run the ./show_configs.sh command in the agent directory. This script outputs shareable configuration links (URIs). These URIs can be directly copied and imported into various compatible Xray/V2Ray client applications, such as:

  • v2rayNG (Android)
  • v2rayN (Windows)
  • Streisand (iOS/macOS)
  • And many others…

For a more detailed list of clients and import instructions, please see the User Guide . Additionally, if you have set up the monitoring components, these configuration links are also conveniently displayed on your Grafana dashboard.

How does CompassVPN handle maintenance and updates?

CompassVPN includes several automated management features to ensure smooth operation and security:

  • Process Monitoring: Monit automatically monitors and restarts critical services if they fail.
  • Configuration Rotation: Periodically rotates configurations for enhanced security.
  • Configuration Self-Testing: Verifies new configurations before applying them.
  • Optional Automatic Updates: You can enable automatic updates (AUTO_UPDATE in the Web Panel) to keep the agent software current with the latest features, bug fixes, and security patches.

What should I do if my server IP gets blocked?

If your server’s direct IP address gets blocked by firewalls:

  1. Use Cloudflare CDN Configurations: In the Web Panel, ensure you have selected at least one inbound configuration ending in -cdn (e.g., vless-hu-tls-cdn). Provide the required Cloudflare API credentials (CF_API_TOKEN, CF_ZONE_ID, CF_CLEAN_IP_DOMAIN). Save the configuration and use the Restart/Update action in the panel. This will generate configurations that route traffic through Cloudflare, hiding your server’s direct IP.
  2. New Server: Deploy CompassVPN on a new server with a different IP address.

Monitoring Questions

What metrics does CompassVPN collect?

CompassVPN uses several exporters to collect detailed metrics:

  • node-exporter: Collects host system metrics (CPU, memory, disk I/O, network traffic).
  • v2ray-exporter: Collects Xray-core specific metrics (active connections, traffic per inbound/outbound).
  • xray-config: Provides status metrics about configuration generation.
  • user-metrics: Tracks approximate unique active users and blocked request counts.

How can I view the collected metrics?

Collected metrics are sent by the metric-forwarder service to your configured Manager setup:

  1. Grafana Cloud: Provides a managed Grafana instance and Prometheus-compatible storage.
  2. Self-hosted Grafana + Prometheus: Requires setting up your own Prometheus, Pushgateway (optional), and Grafana instances.

The Manager setup provides dashboards to visualize these metrics.

Is metric collection mandatory?

While highly recommended for monitoring health and performance, metric collection is not strictly mandatory. If you wish to disable it, you would need to manually edit the docker-compose.yml file to comment out or remove the metric-related services (node-exporter, v2ray-exporter, metric-forwarder, user-metrics) and potentially adjust Xray configuration if metrics API is enabled.

Note: Disabling metric collection is generally recommended only for advanced users who are comfortable modifying Docker Compose configurations and understand the potential impact on monitoring capabilities. If you are new to CompassVPN or rely on the dashboards, it’s best to leave the default metric services enabled.

Contributing Questions

How can I contribute to CompassVPN?

You can contribute to the CompassVPN project by:

  • Reporting bugs or suggesting features on the Agent or Manager GitHub repositories.
  • Submitting pull requests with code improvements, bug fixes, or new features.
  • Improving the documentation (like this website!).

Where can I report bugs or request features?

Please use the GitHub Issues section of the relevant repository: