Profile manual

General

On this page

Logging
DNS
IPv6
Testing proxies
UDP and QUIC
Reading connections, and the HTTP engine
GeoIP and ASN databases
Sharing the proxy
Gateway Mode
The HTTP API
Wi-Fi and cellular
The tunnel
The system proxy
Listening on a computer
Settings Pipe reads past

[General] holds the settings that apply to the whole profile, one key = value line each.

[General]
loglevel = notify
dns-server = system, 9.9.9.9, 1.1.1.1
encrypted-dns-server = https://dns.google/dns-query
ipv6 = false
proxy-test-url = http://www.gstatic.com/generate_204
test-timeout = 3
geoip-maxmind-url = https://example.com/GeoLite2-Country.tar.gz
block-quic = per-policy

Keys are read in any case. A key given on two lines counts once: the later line.
A setting that is on or off takes true or false, or 1/0, yes/no, on/off. A value Pipe cannot read is warned about, and the setting keeps its default. Native VPN controls instead reject invalid values on the OS that uses them.
One profile serves a phone and a computer alike, so a setting of another platform's is read past without a word where it means nothing. One that changes nothing anywhere, or that Pipe does not know, is noted and read past (below).

Logging#

Key	Values	Default	What it does
`loglevel`	`verbose`, `info`, `notify`, `warning`	the normal level	`verbose` logs everything. `warning` logs problems alone. `info`, `notify` and anything else log at the normal level.

DNS#

How names are looked up. DNS describes each of these in full.

Key	Values	Default	What it does
`dns-server`	a list: `system`, addresses (`9.9.9.9`, `1.1.1.1:5353`), `tcp://` servers	`system`	Servers are raced; the first good answer wins. `system` uses the network's resolvers. With any TCP or encrypted server, those answer ordinary queries; plain servers bootstrap their names. An empty list falls back to `system`.
`encrypted-dns-server`	a list of `https://`, `h3://`, `quic://` and `tls://` servers	none	Encrypted servers. With any of them, they answer for every name, and the `dns-server` servers only look up the encrypted servers' own names.
`dns-bootstrap-server`	DNS server addresses or URLs	none	Resolvers available for proxy and DNS server names, excluded from ordinary destination queries.
`dns-final`	a `[DNS Server]` name	the ordinary server race	The resolver for queries no terminal `[DNS Rule]` handles.
`dns-strategy`	`as_is`, `prefer_ipv4`, `prefer_ipv6`, `ipv4_only`, `ipv6_only`	chosen by `ipv6`	Explicit address-family preference for DNS lookups.
`encrypted-dns-follow-outbound-mode`	`true`, `false`	`false`	DNS over TCP, TLS, HTTPS, QUIC and HTTP/3 follows the live routing mode, rules and group selection; rejected DNS routes fail. See `encrypted-dns-server`.
`encrypted-dns-skip-cert-verification`	`true`, `false`	`false`	The encrypted servers' certificates are not checked.
`always-real-ip`	a list of names: `.lan`, `-.example.com`	Pipe's own list	Names that are never given a fake IP: their lookups get real answers.
`allow-dns-svcb`	`true`, `false`	`false`	SVCB and HTTPS records are answered, instead of refused.
`use-local-host-item-for-proxy`	`true`, `false`	`false`	A TCP connection through a proxy to a name that `[Host]` gives addresses goes to one of those addresses, picked at random, instead of sending the proxy the name.

IPv6#

Key	Values	Default	What it does
`ipv6`	`true`, `false`	`false`	`false`: names are looked up for IPv4 addresses alone, and IPv6 DNS servers in `dns-server` are left out (with a note). `true`: IPv6 too, IPv4 preferred.

With either value, IPv4 addresses on a network without IPv4 — IPv6 alone, with NAT64 — are reached through the network's NAT64 (Leaving the device).

Whether the tunnel itself carries IPv6 is ipv6-vif's to say.

Testing proxies#

Groups that choose a member by testing — url-test, fallback, load-balance and smart — and the app's Test button measure each proxy with a request through it. Groups says how a test is timed.

Key	Values	Default	What it does
`proxy-test-url`	an `http://` or `https://` URL	`http://bing.com/`	What members are tested with. A proxy's own `test-url` comes first.
`test-timeout`	seconds	5	How long a test of a member may take, unless the group says otherwise with `timeout`. A member whose test takes longer counts as not answering.
`internet-test-url`	a URL	none	What `DIRECT` — and every policy that goes out directly — is tested with where it is a member of a group, given 10 seconds. Without it, `DIRECT` is tested as the group's other members are.
`proxy-test-udp`	`hostname@server`	`cloudflare.com@1.1.1.1`	The UDP test: a DNS lookup of `hostname`, sent through each proxy that carries UDP to the DNS server at `server` — an address, with `:port` when it is not 53: `apple.com@8.8.8.8`. Made when the app asks for it (Proxies, Test UDP Relay). A proxy's own `test-udp` comes first.

UDP and QUIC#

Key	Values	Default	What it does
`udp-policy-not-supported-behaviour`	`REJECT`, `DIRECT`	`REJECT`	What happens to UDP sent to a policy that cannot carry it. `REJECT`: it is refused. `DIRECT`: it goes out directly, and its record shows the policy the rules chose, then `DIRECT`.
`block-quic`	`per-policy`, `all-proxy`, `all`, `always-allow`	`per-policy`	Whether QUIC is refused. Apps that support a TCP alternative may fall back to it. See below.

block-quic:

Value	QUIC is refused
`per-policy`	As each proxy's own `block-quic` says. A policy that says nothing lets QUIC through when it carries datagrams as datagrams, and refuses it otherwise. Those that do: `DIRECT` and its kin; Hysteria 2, and TUIC in its `native` relay mode without `udp-over-stream`, when neither goes through an `underlying-proxy`; WireGuard and `tailnet` policies.
`all-proxy`	Through every proxy; never directly.
`all`	Everywhere, directly too.
`always-allow`	Nowhere.

Pipe refuses QUIC to the hosts it decrypts as well, unless auto-quic-block is off.

Reading connections, and the HTTP engine#

Pipe reads the first bytes of some connections for the name they ask for (Sniffing), and carries plain HTTP request by request (The HTTP engine).

Key	Values	Default	What it does
`always-raw-tcp-hosts`	a host list	none	Connections to these hosts are never read ahead, by the name or address the connection was made to. An item without a port means ports 80 and 443.
`always-raw-tcp-keywords`	a list of words	none	Nor are connections to hosts whose name holds one of these words.
`force-http-engine-hosts`	a host list	none	Connections to these hosts are carried as HTTP by the HTTP engine, whatever port they are on and whatever they look like. An item without a port means port 80; `host:0` and `*:0` mean every port. A connection that turns out not to be HTTP then breaks.
`show-error-page`	`true`, `false`	`true`	A request the HTTP engine cannot carry — its proxy or server cannot be reached, its server breaks off before answering — is answered `502 Bad Gateway` with a page that says why. `false`: its connection is closed, as the network would close it.
`show-error-page-for-reject`	`true`, `false`	`false`	A plain HTTP request a `REJECT` rule refuses is answered `403 Forbidden` with a page that says what refused it. `false`: a bare `403`.

GeoIP and ASN databases#

GEOIP rules place an address in a country, and IP-ASN rules in an autonomous system (Rules).

Key	Values	Default	What it does
`geoip-maxmind-url`	an `http://` or `https://` URL	none	A country database: a MaxMind `.mmdb` file, or a `.tar.gz` holding one. The engine downloads it through the rules, keeps it, and fetches it again every week. Without it, and until it has arrived, Pipe's built-in table answers, which places every country.
`disable-geoip-db-auto-update`	`true`, `false`	`false`	The country database is fetched once, and not again.
`ip-asn-maxmind-url`	an `http://` or `https://` URL	none	An ASN database, in GeoLite2-ASN's form: a `.mmdb`, or a `.tar.gz` holding one. Fetched like the country database, and again every week. Pipe has no ASN data built in: without this key, `IP-ASN` rules are left out, with a warning.

A URL that is not http:// or https:// is an error.

Without geoip-maxmind-url, GEOIP rules — for any country, UNKNOWN and REGION — go by Pipe's built-in table: every country's addresses, from DB-IP's IP to Country Lite (IP geolocation by DB-IP, CC BY 4.0), updated with Pipe.

On iPhone, the proxy Pipe runs can be shared with other devices on the same network: they set it as their HTTP or SOCKS5 proxy, and their traffic goes through Pipe's rules.

Key	Values	Default	What it does
`allow-wifi-access`	`true`, `false`	`false`	Devices on the same Wi-Fi network may use the proxy.
`allow-hotspot-access`	`true`, `false`	`false`	Devices on the iPhone's Personal Hotspot may use the proxy. Pipe does not tell the two networks apart yet: either key lets devices on both reach it, and a note says so when only one is on.
`wifi-access-http-port`	a port	6152	Where the shared proxy listens. Each port takes HTTP and SOCKS5 alike.
`wifi-access-socks5-port`	a port	6153	The second port. When both ports are the same, there is one listener.
`wifi-access-http-auth`	`username:password`	none	The credentials the shared proxy asks every client for, on both ports, since each takes either kind of client. A value without `:` is an error.
`proxy-restricted-to-lan`	`true`, `false`	`true`	The shared proxy, forwarded ports and built-in servers that listen beyond the device itself serve only devices on the local network.

A port that cannot be read is warned about, and its default is used.

Gateway Mode#

A Mac can serve as the local network's gateway.

Key	Values	Default	What it does
`gateway-restricted-to-lan`	`true`, `false`	`true`	The gateway serves only devices on the local network: a flow from any other address is dropped as it begins. On a phone it changes nothing. A module cannot change it.

gateway-restricted-to-lan = true

The HTTP API#

http-api serves an HTTP API through which other devices and tools control Pipe: its endpoints are under /v1/, the paths that dashboards, shortcuts and the scripts' $httpAPI use.

http-api = examplekey@0.0.0.0:6171
http-api-tls = true

Key	Values	Default	What it does
`http-api`	`key@address:port`	none	Serves the API at that address and port. Every request carries the key, in an `X-Key` header or as `?x-key=` in the URL. A line without a key, or without an address and port, is warned about, and the API is not served. An address on the network without `http-api-tls` is warned about: the key and the answers go unencrypted. Wrong keys are answered ever more slowly, a few a second at most.
`http-api-tls`	`true`, `false`	`false`	Serves it over HTTPS, with certificates signed by the HTTPS decryption CA: the profile's, or Pipe's own, which the app offers to install. A certificate is made for the name a client asks for, or for the address it reached: `https://192.168.1.5:6171`.
`http-api-web-dashboard`	`true`, `false`	`false`	Serves a web dashboard at `/dashboard` on the same address and port: connections, proxies and groups, the mode, DNS, traffic and logs, light and dark. The page itself holds nothing and is built into Pipe; it asks for the key, and everything it shows it asks the API for with that key.
`external-controller-access`	`password@address:port`	none	Remote control from another Pipe's app, or from `pipe --remote`: the same API at its own address and port, with this password as its key and the same limits. Over TLS when `http-api-tls` is on. An address on the network without it is warned about. It lets whoever holds the password run the engine, so a managed profile cannot give it: there it is warned about, and not served.

What the API answers comes from the engine: the outbound mode and the Global policy, groups, what they picked and their tests, requests (and ending them), rules, temporary rules, DNS, scripts (evaluating one too), events, traffic, rule sets and other downloads, the decryption certificate, GeoIP, metrics, and on a Mac the devices (/v1/devices): naming one and reserving its address too. /v1/features/ reads and switches mitm, capture, rewrite and scripting while Pipe runs; a switch lasts until Pipe stops, whatever a reload brings.

What the app keeps it answers for the API: the profile's text, the list of profiles and switching between them, checking one, modules, the system_proxy and enhanced_mode features, and POST /v1/stop. Where no app is there to ask, the answer says so. GET /v1/profiles/current gives the profile with its passwords, keys and subscription tokens taken out; ?sensitive=1 asks for them.

/traffic/stats gives what was carried per day, by app, host, device or policy, this month and the one before, where the app keeps them.

A wrong key from another machine counts against its address: after ten in a row it is refused for 15 minutes. pipe security ban shows who is refused, and changes it.

Wi-Fi and cellular#

Key	Values	Default	What it does
`wifi-assist`	`true`, `false`	`false`	When Wi-Fi has not connected within a second, or has failed, a connection is tried over cellular too.
`all-hybrid`	`true`, `false`	`false`	Every policy that does not say `hybrid=off` connects over Wi-Fi and cellular at once, the first to connect carrying the connection.

Leaving the device says how these work with each policy's own settings.

The tunnel#

What the tunnel on iOS takes in. Networks describes each of these in full.

Key	Values	Default	What it does
`ipv6-vif`	`disabled`, `auto`, `always`	`disabled`	Whether the tunnel carries IPv6.
`tun-excluded-routes`	a list of address ranges	none	Ranges that go past the tunnel, as if it were not there.
`tun-included-routes`	a list of address ranges	none	Ranges the tunnel claims besides its default route.
`include-all-networks`	`true`, `false`	`false`	iOS sends everything into the tunnel, even what an app sends out of a network of its own choosing.
`include-local-networks`	`true`, `false`	`false`	With `include-all-networks`, the local network goes into the tunnel too.
`include-apns`	`true`, `false`	`false`	With `include-all-networks`, push notifications go into the tunnel too.
`include-cellular-services`	`true`, `false`	`false`	With `include-all-networks`, the carrier's services — calls over Wi-Fi, MMS, voicemail — go into the tunnel too.
`include-device-communication`	`true`, `false`	`false`	With `include-all-networks`, talking to devices over USB and Wi-Fi — Xcode, a Mac — goes into the tunnel too.
`icmp-forwarding`	`true`, `false`	`true`	Route tunnel pings through the profile rules. A direct selection forwards the echo and its reply; rejected requests and proxy selections without ICMP support are dropped.
`udp-priority`	`true`, `false`	`false`	When packets wait to be written back into the tunnel, UDP, DNS answers and pings go before TCP.

ICMP rules see restored fake-IP names and source/inbound metadata. PROTOCOL,ICMP,REJECT blocks echoes. A selected direct policy uses its protected interface/network configuration. WireGuard, tailnet and other proxy echo paths are not implemented and never fall back to the public network. At most 32 echoes run concurrently, with budgeted packet storage.

The five include-* controls belong to the iOS VPN configuration.

The system proxy#

What a Mac's System Proxy does when it is on, which points the system's proxy settings at http-listen and socks5-listen.

Key	Values	Default	What it does
`skip-proxy`	a list of hosts and ranges: `192.168.0.0/16`, `*.local`, `localhost`	none	What the system proxy leaves alone: apps connect to these themselves. At most 1,024, of up to 255 bytes each; one that would read as something else is left out, with a warning.
`exclude-simple-hostnames`	`true`, `false`	`false`	Names without a dot are left alone too.
`set-system-socks-proxy`	`true`, `false`	`false`	The system's SOCKS proxy is set as well as its HTTP and HTTPS ones.

Off a Mac they are read past without a word. A module cannot set set-system-socks-proxy.

Listening on a computer#

Key	Values	Default	What it does
`http-listen`	a list of `[username:password@]address[:port]`, or `address` alone	`127.0.0.1:6152` in the Mac app, none in the CLI	Where Pipe for Mac, and `pipe run` on its Mac or Linux host, listen. An address alone listens on port 6152. Each listener takes HTTP and SOCKS5 alike, and asks every client for the username and password when they are given — one without the other is an error, never a listener without them. Written empty, the app does not listen.
`socks5-listen`	the same	`127.0.0.1:6153` in the Mac app, none in the CLI	The same; an address alone listens on port 6153. Each listener still accepts HTTP and SOCKS5.

On iOS the tunnel takes all traffic, and these are read past without a word.

Settings Pipe reads past#

Another platform's settings are read past without a word, where they mean nothing:

Key	Read on	Elsewhere
`skip-proxy`, `exclude-simple-hostnames`, `set-system-socks-proxy`, `read-etc-hosts`, `subnet-exp-wifi-always-match`	a Mac	Pipe takes traffic through the tunnel alone.
`http-listen`, `socks5-listen`	a computer	On iOS the tunnel takes all traffic.
`allow-wifi-access` and the other sharing keys, `wifi-assist`, `all-hybrid`, the five `include-*` keys	an iPhone	On a computer `http-listen` and `socks5-listen` say where the proxy listens.
`ipv6-vif`, `tun-excluded-routes`, `tun-included-routes`, `icmp-forwarding`, `udp-priority`	an iPhone, and a Mac in Enhanced Mode	Pipe sets up no tunnel on Linux.

What no platform reads, or Pipe does not do yet, is said:

Key	Said as	Why
`external-controller-access`, in a profile kept current from a link	warning	Not served: the provider chose its password, and would hold the key to Pipe. In a profile of your own, Pipe serves remote control there, as `http-api` does.
`auto-suspend`	warning	Suspending while another device serves the network as its gateway is not supported yet.
`debug-cpu-usage`, `debug-memory-usage`	nothing	Read without a word: they change nothing.
Any other key	note	It is not a setting Pipe knows.

A profile converted from Surge's has none of these: the conversion leaves them out, and says so once, when the profile is added.