Loon Documentation

Loon is an iOS network proxy tool that supports ss and ssr proxy protocols.

IMPORTANT: Loon is a client tool and does not provide proxy server addresses. You must build your own server or purchase one from a provider.

Loon is a powerful networking tool for iOS that supports traffic splitting (rule-based routing) and traffic manipulation.

Key features include:

• Traffic Splitting: Supports rules based on Domain, IP, URL, and SSID.
• Policy Groups: Advanced policy group combinations to meet complex network routing requirements.
• Traffic Interception: Capability to capture, save, and modify HTTP/HTTPS traffic.
• Scripting: Supports JavaScript to handle complex traffic processing requirements.

Subscription nodes are collections of proxy servers provided by a service provider. Loon downloads and parses these nodes, but they cannot be modified directly within the Loon app; modifications must be requested from the provider.

Loon reads traffic usage information from the Subscription-Userinfo header in the subscription response. This allows the app to display data usage details.

Header Format: Subscription-Userinfo:upload=1111;download=111;total=123456;expire=1614527045

The Node Filter feature supports three distinct methods for selecting nodes:

1. NodeSelect: Manually select specific nodes to combine into a group.
2. NameKeyword: Filter nodes based on whether their names contain specific keywords.
3. NameRegex: Filter nodes using Regular Expressions (Regex) against their names.

Starting from version 3.1.7+, you can use port rules to match network requests based on either the source port (SRC-PORT) or the destination port (DEST-PORT).

Rules follow the format: [TYPE],[PORT_RANGE],[ACTION].

Supported port range syntaxes:

• Specific Port: A single integer (e.g., 443).
• Closed Interval: A range using a hyphen (e.g., 80-443).
• Infinite Interval: Using comparison operators like >, <, <=, or >= (e.g., >=443).

Loon follows a specific sequence to determine how traffic is handled:

1. Request received from device
2. Rule matching: The request is checked against defined rules.
3. Policy lookup: The rule points to a specific Policy.
4. Node selection: The policy determines which Node is used to forward the traffic.

In short: Rules $\rightarrow$ Policies $\rightarrow$ Nodes.

The fallback policy group type automatically selects the first available node. It periodically tests nodes using a provided URL and uses the first one that responds successfully.

Configurable Parameters:

• url: The URL used for testing (Loon sends a HEAD request to this URL).
• interval: The time interval between tests, in seconds.
• max-timeout: The maximum timeout in milliseconds. If a node's test exceeds this value, it is considered unavailable and excluded from the ranking.

The load-balance policy group type distributes traffic among sub-strategies based on a selected load-balancing algorithm.

Configurable Parameters:

• url: The URL used for testing (Loon sends a HEAD request to this URL).
• interval: The time interval between tests, in seconds.
• max-timeout: The maximum timeout in milliseconds. If a node's test exceeds this value, it is considered unavailable.
• algorithm: The load-balancing algorithm to use:
  • Random: Randomly selects a sub-strategy.
  • PCC: Based on Random, but ensures that requests with the same hostname are locked to the same node.
  • Round-Robin: Cycles through sub-strategies in order.

Loon uses an LRU (Least Recently Used) algorithm for memory caching.

• Capacity: 100 entries (increased to 200 on iOS 15+).
• Lifecycle: The cache is valid during the Loon session and is cleared when the app is closed.

Lookup Workflow:

1. Cache Check: Loon first checks the memory cache. If a hit occurs, it uses the cached result. If the IP's TTL (Time To Live) has expired, it performs a new query and updates the cache.
2. Network Query: If there is no cache hit, Loon performs concurrent queries to the configured DNS servers and uses the first response received to update the cache.

Loon supports a wide range of proxy protocols for network transmission. If the client and server use the same protocol, data can be exchanged normally.

Supported Protocols:

• ShadowSocks
• ShadowSocksR
• VMESS (including TLS, WebSocket, WebSocket + TLS, HTTP, and HTTP + TLS variants)
• VLESS (including WebSocket, HTTP, WebSocket + TLS, HTTP + TLS variants)
• Trojan (including WebSocket and HTTP variants)
• HTTP
• HTTPS
• Wireguard
• Hysteria2
• Custom via JavaScript: Allows defining custom protocols using JS scripts.