# Policy > Built-in policies, proxy configuration, WireGuard, SSH [← Back to index](/llms.txt) --- # Proxy Policy ## Overview Surge can forward requests to another proxy server or connect to the host directly, depending on customized rules. A policy indicates how Surge will deal with the requests. ## Policy Types The system supports three distinct categories of policies: 1. **Proxy policies** - Direct proxy forwarding configurations 2. **Policy groups** - Grouped policy management 3. **Built-in policies** - Pre-configured default policies ## Built in # Built-in Policy ## Overview Surge provides several built-in policies for routing requests. The two most fundamental are: - **DIRECT**: Routes requests directly to the destination host - **REJECT**: Blocks incoming requests ## Available Built-in Policies ### DIRECT Sends the request directly to the target host without proxy routing. ### CELLULAR (iOS Only) Prioritizes cellular network connectivity over Wi-Fi connections. ### CELLULAR-ONLY (iOS Only) Routes exclusively through cellular networks. The connection fails if cellular is unavailable. ### HYBRID (iOS Only) Establishes simultaneous connections across both Wi-Fi and cellular networks. This option is only relevant when the "All Hybrid" setting is disabled. ### NO-HYBRID (iOS Only) Prevents cellular network usage when Wi-Fi is available. This applies only when either "All Hybrid" or "Wi-Fi Assist" is enabled. ## Creating Policy Aliases Built-in policies can be referenced directly in rules and policy groups, or you can create custom aliases for convenience: ``` [Proxy] On = direct Off = reject ``` This allows using "On" and "Off" as policy names throughout your configuration. **Note**: For information on REJECT variations (REJECT-DROP, REJECT-NO-DROP), see the dedicated REJECT Policy documentation. ## External proxy # External Proxy Program ## Overview Surge Mac supports the External Proxy Program policy, enabling integration with other proxy software. This feature is Mac-only and allows Surge to manage external proxy processes. ## Configuration The policy type keyword is `external`. Here's an SSH example: ``` [Proxy] external = external, exec = "/usr/bin/ssh", args = "11.22.33.44", args = "-D", args = "127.0.0.1:1080", local-port = 1080, addresses = 11.22.33.44 ``` ### Required Parameters - `exec`: Path to the external executable - `local-port`: Local port for SOCKS5 forwarding ### Optional Parameters - `args`: Command arguments (can be repeated) - `addresses`: Proxy server IPs to exclude from VIF routes ## How It Works 1. Surge launches the external process using the specified `exec` and `args` parameters, then forwards requests to SOCKS5 at `127.0.0.1:[local-port]` 2. If the process terminates, Surge automatically restarts it when needed 3. In Enhanced Mode, Surge excludes specified addresses from VIF routing (only IP addresses supported) 4. External process requests always route through DIRECT policy 5. All external processes terminate when Surge exits ## Important Notes - Logs from external processes appear in `/tmp/Surge-External-xxxxxx.log` - Surge retries failed connections up to 6 times with 500ms intervals if the process needs startup time - Surge iOS treats external policies as REJECT (unsupported) - Address exclusions reduce processing overhead compared to relying solely on DIRECT policy defaults ## Parameters # Common Policy Parameters ## Egress Parameters Available for both built-in and proxy policies. ### `interface` (Default: automatically) Specifies a particular outgoing network interface for connections. ``` ProxyHTTP = http, 1.2.3.4, 443, username, password, interface = en2 ``` The Direct policy also supports this parameter: ``` [Proxy] Corp-VPN = direct, interface = utun0 WiFi = direct, interface = en2, allow-other-interface=true ``` Ensure the interface has valid routing to the destination. ### `allow-other-interface` (Boolean, Default: false) When enabled, the system may fall back to the default interface if the specified one becomes unavailable. When disabled, connection attempts fail instead. ### `dns-follow-interface` (Boolean, Default: false) *iOS 5.15.2+, Mac 5.2.0+* Applies the interface parameter to DNS queries as well. ### `no-error-alert` (Boolean, Default: false) Suppresses error notifications for this policy. ### `ip-version` Controls IPv4/IPv6 behavior. Only affects connections to the proxy server itself: - dual (Default) - v4-only - v6-only - prefer-v4 - prefer-v6 ### `hybrid` (Boolean, iOS Only, Default: false) Establishes simultaneous connections via both cellular and Wi-Fi, selecting the faster path. ### `tfo` (Boolean, Default: false) Enables TCP Fast Open functionality. ### `tos` (Decimal or Hexadecimal, Default: 0) Customizes the IP TOS field value. ### `ecn` (Boolean, Default: false) *iOS 5.8.0+, Mac 5.4.0+* Enables ECN support for improved performance in high-loss scenarios, though may cause issues in unsupported networks. ### `block-quic` *iOS 5.8.0+, Mac 5.4.0+* Controls QUIC blocking since proxying QUIC may degrade performance: - auto - on - off ## Testing Parameters ### `test-url` Overrides the global testing URL for availability and latency checks. ### `test-timeout` (In seconds) Overrides the global timeout for testing operations. ### `test-udp` Example: `test-udp=google.com@1.1.1.1` Overrides global UDP testing settings using DNS lookups. ## Proxy # Proxy Policy A proxy policy directs requests to another proxy server. Surge supports HTTP/HTTPS/SOCKS5/SOCKS5-TLS and additional proxy protocols. ## Configuration Proxy policies are declared in the `[Proxy]` section: ``` [Proxy] ProxyHTTP = http, 1.2.3.4, 443, username, password ProxyHTTPS = https, 1.2.3.4, 443, username, password ProxySOCKS5 = socks5, 1.2.3.4, 443, username, password ProxySOCKS5TLS = socks5-tls, 1.2.3.4, 443, username, password, skip-common-name-verify=true ``` ## Supported Proxy Types **Standard Protocols:** - HTTP Proxy - HTTPS Proxy (HTTP via TLS) - SOCKS5 - SOCKS5 via TLS - SSH - WireGuard (L3 VPN) **Community Protocols:** - Snell - Shadowsocks - VMess - Trojan - TUIC - Hysteria 2 - AnyTLS ### UDP Relay Surge supports UDP relay of SOCKS5, Snell v4/v5, Shadowsocks, Trojan, WireGuard, Hysteria 2, and TUIC protocols. Manual enablement requires the `udp-relay=true` parameter for certain protocols. ## Common Parameters **Proxy Chain:** - `underlying-proxy`: Connect through another proxy or policy group **TLS-Based Proxies:** - `skip-cert-verify`: Disable certificate verification - `sni`: Customize Server Name Indication - `server-cert-fingerprint-sha256`: Pin server certificate **Protocol-Specific Parameters:** HTTP/HTTPS: `always-use-connect` for CONNECT method usage Shadowsocks: `obfs`, `obfs-host`, `obfs-uri`, `udp-port` VMess: `ws`, `ws-path`, `ws-headers`, `encrypt-method`, `vmess-aead` Trojan: `ws`, `ws-path`, `ws-headers` TUIC: `token` (required), `alpn`, `port-hopping`, `port-hopping-interval` ## Client Certificates TLS proxies support client certificate verification via the `[Keystore]` section. ## Shadow TLS Support Shadow TLS v2 and v3 obfuscation can wrap TCP-based proxies using `shadow-tls-password`, `shadow-tls-sni`, and `shadow-tls-version` parameters. ## Reject # REJECT Policy Surge offers multiple built-in REJECT policies to handle different rejection scenarios. In most cases, using REJECT directly is sufficient. ## Policy Types **REJECT** Returns an error page for HTTP requests. This behavior is controlled by the `show-error-page-for-reject` parameter. **REJECT-DROP** Silently discards connections without responding. Useful for applications with aggressive retry logic that could cause request storms. **REJECT-NO-DROP** Prevents automatic escalation to REJECT-DROP. When 50+ requests to a hostname trigger rejection within 30 seconds, Surge normally upgrades to REJECT-DROP to save resources. This policy bypasses that behavior. **REJECT-TINYGIF** Returns a 1-pixel transparent GIF for HTTP requests. Designed for ad-blocking purposes. ## Pre-matching Feature (iOS 5.14.0+, Mac 5.9.0+) Rules marked with `pre-matching` take effect before normal rule matching, executing during DNS resolution and TCP SYN phases with highest priority. This minimizes overhead for storm requests and ad-blocking. **Syntax:** ``` [Rule] DOMAIN,ad.com,REJECT,pre-matching ``` **Supported rule types:** DOMAIN variants, IP-CIDR variants, GEOIP, IP-ASN, logical rules (AND/OR/NOT), SUBNET, DEST-PORT, SRC-PORT, SRC-IP, and RULE-SET. Each rule appears once per 5 minutes in request logs to prevent flooding. ## Technical Implementation Details **DNS responses:** - REJECT: Returns No Record (or discards if frequency limit triggered) - REJECT-DROP: Discards without response - REJECT-NO-DROP: Returns special IP 198.18.0.244 **TCP responses:** - REJECT: Generates TCP RST (or drops packets if frequency limit triggered) - REJECT-DROP: Discards SYN packets - REJECT-NO-DROP: Generates TCP RST (with protection mechanism at 100+ packets/3 seconds) **UDP packets:** - REJECT: Sends ICMP Administratively Prohibited (or drops if frequency limit triggered) - REJECT-DROP: Discards packets - REJECT-NO-DROP: Sends ICMP Administratively Prohibited ## Ssh # SSH Proxy Policy You can configure SSH protocol as a proxy policy, functioning similarly to `ssh -D`. ## Configuration Syntax **Password Authentication:** ``` [Proxy] proxy = ssh, 1.2.3.4, 22, username=root, password=pw ``` **Public Key Authentication:** ``` [Proxy] proxy = ssh, 1.2.3.4, 22, username=root, private-key=key1 [Keystore] key1 = type=openssh-private-key, base64=[The base64 encoded content of the private key file] ``` ## Key Requirements - The private key file must be base64-encoded twice—once for the key format itself and again for the configuration - Supported key types: RSA, ECDSA, ED25519, and DSA - OpenSSH v7.3+ is required (released August 2016) - Surge supports `curve25519-sha256` for key exchange and `aes128-gcm` for encryption ## Optional Parameters **Idle Timeout:** ``` proxy = ssh, 1.2.3.4, 22, username=root, password=pw, idle-timeout=180 ``` Default value is 180 seconds. ## Server Fingerprint Verification Protect against MITM attacks by specifying the server's public key fingerprint: ``` server-fingerprint = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBk2No6KBq2m9VTCcHXXJBX4/A3RNr+L+yDBl5+TF9qz" ``` Multiple fingerprints can be specified (comma-separated) for servers with multiple keys. Obtain fingerprints from `~/.ssh/known_hosts` or using `ssh-keyscan` in a trusted network. ## Wireguard # WireGuard Surge functions as a WireGuard client, enabling L3 VPN capabilities to be utilized as an outbound proxy policy. ## Configuration Example ``` [Proxy] wireguard-home = wireguard, section-name = HomeServer [WireGuard HomeServer] private-key = sDEZLACT3zgNCS0CyClgcBC2eYROqYrwLT4wdtAJj3s= self-ip = 10.0.2.2 self-ip-v6 = fd00:1111::11 dns-server = 8.8.8.8, 2606:4700:4700::1001 prefer-ipv6 = false mtu = 1280 peer = (public-key = fWO8XS9/nwUQcqnkfBpKeqIqbzclQ6EKP20Pgvzwclg=, allowed-ips = 0.0.0.0/0, endpoint = 192.168.20.6:51820) ``` ## Configuration Notes - Keys accept base64 or hexadecimal encoding - Configure both `self-ip` and `self-ip-v6` for dual-stack or just one for single-stack - Each device requires different IP addresses to prevent conflicts - When `prefer-ipv6` is enabled, IPv6 takes precedence for domains with both A and AAAA records - Multiple peers can be configured (comma-separated with parentheses notation) - Optional peer parameters include `preshared-key` and `keepalive` - Peer endpoints support domain names, resolved via DNS settings in the General section - "0.0.0.0/0 means the policy can be used to access any address" or specific networks - Domain-based access requires DNS server configuration - Configuration sections can be split into detached profile files - Multiple instances may operate simultaneously ## Usage Considerations WireGuard's L3 VPN design creates significantly higher overhead than other general proxy protocols, making it suitable for low-bandwidth scenarios. The tunnel supports TCP and UDP, with basic ICMP/ICMPv6 responses available post-handshake. Protocol limitations mean most errors manifest as timeouts rather than explicit messages, requiring packet analysis for troubleshooting. ## Advanced Features **Reserved Bits Customization** (iOS 5.3.1+, Mac 4.10.3+): Customize WireGuard reserved bits for implementations like Cloudflare WARP. **ECN Support** (iOS 5.8.0+, Mac 5.4.0+): Preserves TOS/DSCP/ECN tags during UDP forwarding through the tunnel when `ecn=true` is configured.