> ## Documentation Index > Fetch the complete documentation index at: https://docs.safesquid.com/llms.txt > Use this file to discover all available pages before exploring further. # Forward proxy CLI man page: `safesquid-forward(5)` Forward peer selection ## Overview The `Forward` section (`safesquid-forward(5)`) configures upstream proxy routing, enabling SafeSquid to chain requests to parents, siblings, or Cache Array Routing Protocol (CARP) clusters. ## Core Mechanics (C++ Source Validation) CARP hash, blank Proxy stop, ICP peer selection. * **CARP Hashing**: When routing requests through an array of proxies, the routing engine performs a deterministic 32-bit bitwise rotation hash combining the requested URL and the peer’s hostname. The peer generating the highest hash score receives the request. * **Self-Resolution (Loop Prevention)**: If SafeSquid calculates that its *own* hostname generates the highest CARP hash (`op >= hp`), it drops the forwarding requirement and resolves the request directly. * **Cache Coordination**: When a request is forwarded to another CARP array member, SafeSquid sets `CONNECTION_NOCACHE`. This ensures the object is only cached on the designated CARP owner, creating a single, distributed logical cache without duplication. ## Schema Fields ### Global Fields * **Enabled (enabled)**: Toggles proxy forwarding globally. * **Enable CARP (carp)**: Enables Cache Array Routing Protocol for load balancing across peers. * **CARP hash size (carphashsize)**: Determines the hash bucket size for CARP distribution. ### Rule-Based Fields (Per Connection Tuning) * **Enabled (enabled)**: Toggles the rule. * **Comment (comment)**: User description. * **Profiles (profiles)**: The trigger condition. Limit this entry to connections that already carry these Access Profile tags. * **Proxy (proxy)**: The IP address or hostname of the upstream proxy server. * **User name (username)**: The username to authenticate with the upstream proxy. * **Password (password)**: The password to authenticate with the upstream proxy. * **Domain (domain)**: PCRE regex matching the request URL domain. Blank matches all domains. * **Port (port)**: The TCP port of the upstream proxy server. * **ICP peer type (icptype)**: Defines the relationship with the peer (e.g., Parent, Sibling). * **ICP port (icpport)**: The UDP port used for ICP queries. * **Type (type)**: The protocol type of the upstream proxy (e.g., HTTP, HTTPS). * **Applies to (which)**: Specifies whether the forwarding rule applies to the client request URL or the response Location header. ## Important entry fields * **Profiles** — Limit the row with Access Profile tags. Blank matches all profiles. * **Proxy** — Upstream hostname or IP. Blank on a matching row **stops candidate collection** without forwarding. Rows whose Proxy equals this instance hostname or System configuration **Proxy hostname** are skipped (shared-config safety). * **Type** — **HTTP** (standard proxy), **SOCKS4** / **SOCKS5**, or **CONNECT** tunnel. Port defaults to `3128` for HTTP/SOCKS and `443` for CONNECT when Port is 0. * **Applies to** — Protocol flags: HTTP, FTP, CONNECT. Row is skipped when the connection protocol does not match any selected flag. * **ICP peer type / ICP port** — When global CARP is off: **NONE** gives fixed priority 1; **PARENT** forwards on ICP miss; **SIBLING** forwards only on ICP HIT. UDP ICP uses the ICP port on this row; global ICP listen port and timeout come from [Caching](/admin_guide/performance/caching). * **User name / Password / Domain** — Upstream proxy authentication when the selected peer requires it. **Blank Proxy stops collection.** A matching row with empty Proxy ends the scan — lower rows are not added as candidates. Place intentional “direct” stop rows carefully. ## Processing order 1. If forwarding is disabled, or Access **Bypass → Forward** is set, skip. 2. Walk Forwarding proxies top to bottom; add each enabled matching row with a non-self Proxy to the candidate list. 3. Blank Proxy on a matching row stops collection immediately. 4. CONNECT requests skip ICP/CARP selection logic used for plain HTTP. 5. Select one peer: CARP hash among candidates, or ICP priorities, or random tie-break. 6. Send the request through the selected peer, or direct if no candidate remains. `startup.ini` may append implicit upstream rows from the proxy’s IP detection / port when set — not shown in the Web UI but affects runtime. ## Examples ### 1 — All HTTP through one upstream * Enabled: on * Row: Proxy `upstream.example.com`, Port `3128`, Type HTTP, Applies to HTTP + CONNECT **Result:** matching HTTP and CONNECT traffic uses that upstream. Access Bypass Forward sends affected users direct instead. ### 2 — Profile-specific upstream with direct stop * Row 1: Profiles `USE PARENT PROXY`, Proxy `parent.internal:8080` * Row 2: Profiles blank, Proxy blank **Result:** connections with the profile match row 1 and forward to the parent. Others match row 2, collection stops at blank Proxy, and traffic goes direct. ### 3 — CARP among two peers * Enable CARP on; two rows with different Proxy hosts, both match profiles/protocols **Result:** for each URL, CARP picks one peer (or local handling if this proxy wins the hash). Non-selected paths do not forward that request. ## How to verify 1. Enable FORWARD in `LOG_LEVEL`; look for native `forwarding:` lines. 2. From a test client, confirm upstream sees traffic from SafeSquid (or from your upstream auth logs). 3. Enable **Trace Entry** on one Forwarding proxies row to see candidate collection. 4. Detailed logs may show forward-related status when policies apply. ## Related topics - [Forward Proxy](/use_cases/scaling_and_high_availability/forward_proxy.md) - [Proxy Chain](/use_cases/scaling_and_high_availability/proxy_chain.md) - [TCP Proxy](/use_cases/scaling_and_high_availability/tcp_proxy.md) - [Reverse Proxy](/use_cases/scaling_and_high_availability/reverse_proxy.md) - [Choose an Architecture](/deployment/choose_an_architecture.md)