Skip to content

Client Configuration

The R-VPN client is configured via a TOML configuration file.

Configuration File Location

Default locations (checked in order): 1. Path specified via --config flag 2. client.toml in current directory 3. ~/.config/rvpn/client.toml

Configuration Reference

Server Section

The [server] section configures the connection to the VPN server.

[server]
# Server WebSocket URL (default: "wss://localhost:443/connect")
server_address = "wss://vpn.example.com/connect"

# TLS SNI hostname for stealth connections (optional)
sni_hostname = "www.example.com"

# Path to identity key file (default: "identity.key")
identity_key_file = "identity.key"

# Server public key for additional authentication (optional)
server_public_key = "base64encodedkey..."

# Path to server prekey bundle JSON file (optional)
prekey_bundle = "prekey-bundle.json"
Option Type Default Description
server_address string "wss://localhost:443/connect" WebSocket URL of the VPN server
sni_hostname string (none) TLS SNI hostname for stealth connections
identity_key_file string "identity.key" Path to client identity key file
server_public_key string (none) Server's public key for authentication
prekey_bundle string (none) Path to prekey bundle JSON file

SOCKS5 Section

The [socks5] section configures the SOCKS5 proxy server.

[socks5]
# Listen address for SOCKS5 proxy (default: "127.0.0.1:1080")
listen_address = "127.0.0.1:1080"

# Enable UDP associate support (default: true)
udp_associate = true

# Enable authentication (default: false)
auth_enabled = false

# Authentication username (required if auth_enabled = true)
auth_username = "user"

# Authentication password (required if auth_enabled = true)
auth_password = "password"
Option Type Default Description
listen_address string "127.0.0.1:1080" SOCKS5 server bind address
udp_associate boolean true Enable UDP associate support
auth_enabled boolean false Require authentication
auth_username string (none) Username for authentication
auth_password string (none) Password for authentication

TUN Section

The [tun] section configures the TUN device for full VPN mode.

[tun]
# Interface name (default: "rvpn0")
interface_name = "rvpn0"

# Virtual IP address with CIDR notation (default: "10.200.0.2/24")
ip_address = "10.200.0.2/24"

# DNS servers (default: ["1.1.1.1", "8.8.8.8"])
dns_servers = ["1.1.1.1", "8.8.8.8"]

# Routes to route through VPN (default: ["0.0.0.0/0"])
routes = ["0.0.0.0/0"]

# MTU - Maximum Transmission Unit (default: 1420)
mtu = 1420
Option Type Default Description
interface_name string "rvpn0" TUN interface name
ip_address string "10.200.0.2/24" Virtual IP address (CIDR notation)
dns_servers array ["1.1.1.1", "8.8.8.8"] DNS servers to use
routes array ["0.0.0.0/0"] Networks to route through VPN (CIDR)
mtu integer 1420 Maximum Transmission Unit

Performance Section

The [performance] section tunes performance parameters.

[performance]
# Number of worker threads (default: 4)
worker_threads = 4

# Receive buffer size in bytes (default: 262144)
recv_buffer_size = 262144

# Send buffer size in bytes (default: 262144)
send_buffer_size = 262144
Option Type Default Description
worker_threads integer 4 Number of async worker threads
recv_buffer_size integer 262144 Socket receive buffer size (bytes)
send_buffer_size integer 262144 Socket send buffer size (bytes)

Split Tunnel Section

The [split_tunnel] section configures split tunneling behavior.

[split_tunnel]
# Enable split tunneling (default: false)
enabled = true

# Path to file with bypass networks in CIDR format (optional)
bypass_networks_file = "bypass_networks.txt"

# Path to file with bypass domains (optional)
bypass_domains_file = "bypass_domains.txt"

# Path to file with tunnel networks in CIDR format (optional)
tunnel_networks_file = "tunnel_networks.txt"

# Path to file with tunnel domains (optional)
tunnel_domains_file = "tunnel_domains.txt"

# Auto-reload interval in seconds, 0 to disable (default: 300)
auto_reload_interval = 300

# Built-in bypass countries (default: ["CN"])
builtin_bypass_countries = ["CN", "HK"]

# Enable ad blocking (default: false)
block_ads = false

# Path to custom ad block list file (optional)
ad_block_file = "ad_block.txt"
Option Type Default Description
enabled boolean false Enable split tunneling
bypass_networks_file string (none) File with networks to bypass VPN
bypass_domains_file string (none) File with domains to bypass VPN
tunnel_networks_file string (none) File with networks to force through VPN
tunnel_domains_file string (none) File with domains to force through VPN
auto_reload_interval integer 300 Auto-reload interval in seconds (0 = disable)
builtin_bypass_countries array ["CN"] Country codes for built-in bypass
block_ads boolean false Enable built-in ad blocking
ad_block_file string (none) Custom ad block list file

See Split Tunneling for detailed documentation.

Network Section

The [network] section configures network behavior.

[network]
# Enable IPv6 support (default: true)
ipv6_enabled = true

# Prefer IPv4 over IPv6 when both available (default: true)
prefer_ipv4 = true

# Enable DNS caching (default: true)
dns_cache_enabled = true

# DNS cache TTL in seconds (default: 300)
dns_cache_ttl = 300

# Maximum DNS cache entries (default: 1000)
dns_cache_size = 1000

# Custom DNS servers, overrides system default (optional)
dns_servers = ["1.1.1.1", "8.8.8.8"]
Option Type Default Description
ipv6_enabled boolean true Enable IPv6 support
prefer_ipv4 boolean true Prefer IPv4 over IPv6
dns_cache_enabled boolean true Enable DNS caching
dns_cache_ttl integer 300 DNS cache TTL in seconds
dns_cache_size integer 1000 Maximum DNS cache entries
dns_servers array [] Custom DNS servers (overrides system)

Complete Example

# Server connection
[server]
server_address = "wss://vpn.example.com/connect"
identity_key_file = "identity.key"
prekey_bundle = "prekey-bundle.json"

# SOCKS5 proxy mode
[socks5]
listen_address = "127.0.0.1:1080"
udp_associate = true

# TUN device configuration
[tun]
interface_name = "rvpn0"
ip_address = "10.200.0.2/24"
dns_servers = ["1.1.1.1", "8.8.8.8"]
routes = ["0.0.0.0/0"]
mtu = 1420

# Split tunneling for China/HK traffic
[split_tunnel]
enabled = true
builtin_bypass_countries = ["CN", "HK"]
auto_reload_interval = 300

# Performance tuning
[performance]
worker_threads = 4
recv_buffer_size = 262144
send_buffer_size = 262144

# Network settings
[network]
ipv6_enabled = true
prefer_ipv4 = true
dns_cache_enabled = true
dns_cache_ttl = 300

Command Line Options

# Connect with custom config
rvpn --config /path/to/config.toml

# Connect to specific server (overrides config)
rvpn --server wss://vpn.example.com/connect

# Specify prekey bundle (overrides config)
rvpn --bundle /path/to/prekey-bundle.json

# Run in TUN mode (default is SOCKS5)
rvpn --tun

# Verbose output
rvpn -v        # Debug level
rvpn -vv       # Trace level

# Show help
rvpn --help

# Show version
rvpn --version

Environment Variables

Variable Description
RVPN_CONFIG Path to configuration file
RVPN_LOG Log level (error, warn, info, debug, trace)

Configuration Precedence

Configuration is applied in this order (later overrides earlier):

  1. Default values
  2. Configuration file
  3. Environment variables
  4. Command line arguments

Next Steps