{"canonical_url":"https://engineer.company/glossary/proxy/","content_markdown":"# Proxy\n\n## What it is\n\nA proxy is a program placed between a client and the server it wants to reach.\nIt accepts the client's request, makes a request of its own to the next machine\nalong, and hands the answer back. The client talks to the proxy and the proxy\ntalks to the server, so the two ends never share a connection. Proxies come in\nseveral kinds, and the useful question to ask of each one is who put it there.\n\nHTTP's own specification, RFC 9110, names three common intermediaries. A proxy\nin the narrow sense is one the client chose, usually through local\nconfiguration such as a browser setting or an environment variable. A gateway,\nwhich the RFC also calls a reverse proxy, sits on the server's side: to whoever\nconnects it behaves as the origin server, while it forwards each request inward\nto one or more servers behind it. A tunnel relays bytes blindly between two\nconnections and stops being a party to the conversation once it is open. A\nclient asks for one with the CONNECT method, naming a host and a port, and then\nruns TLS through it end to end. The RFC adds a fourth kind that nobody chose:\nthe interception proxy, often called a transparent proxy, which redirects\noutgoing traffic on port 80 at the edge of a network, as public access points\nand corporate firewalls do.\n\nEach hop is a separate connection. The RFC's diagram puts three intermediaries\nbetween a browser and an origin server, which makes four connections, and\nsettings such as keep-alive or a timeout apply to one of those connections at a\ntime. HTTP also asks a proxy to announce itself: it must add a Via header field\nto each message it forwards, which is how a loop or an unexpected intermediary\nshows up in a trace.\n\nHTTP is only one layer. A SOCKS proxy, whose version 5 is specified in RFC 1928\nfrom March 1996, relays TCP connections and UDP datagrams without reading what\nis inside them, so any protocol can use it. Tor is a familiar example: by\ndefault it listens on port 9050 for SOCKS connections from local applications.\n\n## Why it matters\n\nWhoever runs the proxy can read the traffic. For plain HTTP that means every\nheader and every body. Through a CONNECT tunnel it sees the host name and port,\nand the rest is TLS running from the client to the server. A reverse proxy that\nterminates TLS sees everything in clear, and that is its job, because it has to\nread a request to route it. So putting another company's reverse proxy in front\nof a site, which is what a content delivery network does, hands that company\neach visitor's address and each URL before the site itself sees them. That can\nbe the right trade for a shop under attack. It is still a decision about\nprivacy, and the privacy page should say so.\n\nThe second consequence is what the server learns. RFC 7239 describes the loss\nplainly: behind a proxy, requests appear to come from the proxy's address. A\nlog, a rate limit, a ban list or an allow-list keyed on the client address then\nsees one address for everybody. The usual repair is a header that carries the\noriginal address forward: the standard Forwarded field from RFC 7239, or the\nolder X-Forwarded-For. Which copy of that header to believe is where most of\nthe trouble starts.\n\nThird, a proxy changes what an error means. A 502 Bad Gateway or a 504 Gateway\nTimeout is written by an intermediary about the server behind it: the proxy got\nan invalid response, or none in time. A 407 means the proxy itself wants\ncredentials before it forwards anything. Knowing which machine wrote the error\nis half of the diagnosis.\n\nFourth, many proxies cache. RFC 9111 calls a cache that stores responses for\nmore than one user a shared cache, usually part of an intermediary. It makes a\nsite faster and cheaper to serve, and it is also the one place where a response\nmeant for one person can reach another.\n\n## What it looks like in practice\n\nIn August 2026 the company moved its DNS zone of about twenty records into the\nrepository and reconciled it against the Cloudflare API. Sending the web\ntraffic through the provider's CDN as a reverse proxy was part of that work,\nand then\n[a working CDN proxy in front of the site was dismantled for privacy](/portfolio/reconciled-a-20-record-dns-zone-as-code/).\nThe objection was to where it sits: every reader's address and every requested\npath would reach a third party first, and for a company that tells its readers\nnobody is watching, that weighed more than the attack protection it bought.\n\nCounting readers from the access log the web server already keeps, the\nfollowing month, meant dealing with proxies the company does not run.\n[The access log discards seven headers that relay a client's address](/portfolio/measured-13-addresses-with-no-tracking/)\nbefore it writes a line. The log encoder copies headers unchanged, so without\nthat step a reader behind a company proxy would have had an unmasked address\nstored under a header name the masking rule did not cover.\n\nWhen the site gained an onion mirror on Tor that same month, the\n[Tor daemon's own proxy port for outgoing traffic was disabled in its configuration](/portfolio/published-a-readable-tor-onion-mirror/).\nThe onion service is reached through circuits the daemon establishes outward, so publishing this mirror requires no separate inbound Internet port. With its SOCKS listener disabled, this Tor daemon does not offer local applications an outbound proxy.\n\n## Where it goes wrong\n\n**Every request in the log comes from the same address.** The application sits\nbehind a reverse proxy and records the address of the connection it received,\nwhich is the proxy's. A rate limit then throttles everybody at once, and a ban\nwritten by an intrusion tool bans the proxy, which is to say the whole\naudience. Have the proxy pass the client address in a header, and configure\nthe application to read that header only on connections from the proxy's own\naddress. In nginx that is the realip module's set_real_ip_from directive; most\nweb frameworks have an equivalent trusted-proxies setting.\n\n**A client picks its own address by sending a header.** The application reads\nX-Forwarded-For on every request, including requests that reached it directly\nand requests that arrived with a forged value already in the header. RFC 7239\nis explicit that the field can be modified by any node on the way, the client\nincluded. Trust only the entries your own proxy added, counting from the right,\nand bind the application to loopback or a private network so that the proxy is\nthe only way in.\n\n**The log you meant to anonymise keeps full addresses.** The client address is\nmasked in the field somebody checked, but the same address travels in\nForwarded, X-Forwarded-For, X-Real-IP and similar headers, and a logger that\nwrites the header map as received stores them in full. List every header that\ncan carry an address, drop or mask each one at the moment the line is written,\nthen send a test request and read the line on disk.\n\n**Pages return 502 or 504 while the backend's own log stays quiet.** The error\nwas written by the proxy. A 502 means it got an invalid response: the backend\nwas down, listening on another port, or speaking plain HTTP where the proxy\nexpected TLS, or the reverse. A 504 means the backend took longer than the\nproxy's read timeout, which nginx sets to 60 seconds by default. Read the\nproxy's error log first, since it names the upstream address it tried, and\nraise a timeout only for the routes known to be slow.\n\n**One user is shown another user's page.** A shared cache in a proxy or a\ncontent network stored a response that was personal, such as an account page\nreturned alongside a session cookie, and served it to the next person who asked\nfor the same URL. Mark every per-user response with Cache-Control: private,\nwhich RFC 9111 says a shared cache must not store, or with no-store where no\ncopy should be kept anywhere, and check the headers the proxy actually returns.\n\n## Further reading\n\n- [RFC 9110, section 3.7: Intermediaries](https://www.rfc-editor.org/rfc/rfc9110#section-3.7)\n  — the definitions of proxy, gateway, tunnel and interception proxy.\n- [RFC 9110, section 9.3.6: CONNECT](https://www.rfc-editor.org/rfc/rfc9110#section-9.3.6)\n  — how a client asks a proxy to open a tunnel to a host and port.\n- [RFC 7239: Forwarded HTTP Extension](https://www.rfc-editor.org/rfc/rfc7239)\n  — the standard header for the original client address, with its caveats.\n- [RFC 9111: HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111)\n  — shared and private caches, and the directives that keep them apart.\n- [RFC 1928: SOCKS Protocol Version 5](https://www.rfc-editor.org/rfc/rfc1928)\n  — the protocol-neutral proxy that relays TCP connections and UDP.\n\n\u003chttps://engineer.company/glossary/proxy/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"What a proxy between client and server changes: which address the server sees, who can read the traffic, and what a 502 or 504 is saying.","formats":{"gemtext":"https://engineer.company/glossary/proxy/index.gmi","gopher":"https://engineer.company/glossary/proxy/gophermap","html":"https://engineer.company/glossary/proxy/","json":"https://engineer.company/glossary/proxy/index.json","markdown":"https://engineer.company/glossary/proxy/index.md","pdf":"https://engineer.company/glossary/proxy/index.pdf"},"kind":"page","language":"en","title":"What is a proxy?","url":"https://engineer.company/glossary/proxy/","version":1}