Documentation

Cloudflare in front of Velotrak

Updated 17 Nov 2026

When Cloudflare connects straight to Velotrak, the click stores the visitor from CF-Connecting-IP, not the edge address. Use SSL mode Full (strict) with a certificate file. The built-in ACME client cannot issue or renew while that proxy terminates TLS.

Visitor IP

Clicks, GeoIP, the bot check, flow rules on the ip field, the LP Protect entry token, admin login limits, and the audit log all use one client-IP function.

The TCP peer is the client whenever that peer is not a trusted proxy. Forwarding headers on a direct public connection are ignored, so a visitor cannot pick their own address by sending them.

A trusted proxy is a Cloudflare edge address from the list compiled into the binary, a loopback or private address, or a CIDR you set in VELOTRAK_TRUSTED_PROXIES. From a trusted peer, X-Forwarded-For is read from the right, across every header line. Trusted hops are skipped. The first hop that is not a trusted proxy is the visitor. The left end is whatever the client wrote, so it is never taken by itself.

CF-Connecting-IP is used when the peer, or one of those hops, is a Cloudflare address. It is also used when the peer is loopback and the request has no X-Forwarded-For at all. That is a cloudflared tunnel on this machine; the public demo is published that way. True-Client-IP and X-Real-IP are not read. Standard orange cloud sends CF-Connecting-IP, which is the header that counts.

Orange cloud straight to the Velotrak process is the direct Cloudflare case. Leave VELOTRAK_TRUSTED_PROXIES empty for Cloudflare. That variable is for a different CDN in front of the server.

The Cloudflare list is fixed in the binary. It is not downloaded on startup. On 17 November 2026 it matched the published lists at cloudflare.com/ips-v4 and cloudflare.com/ips-v6. An edge address that a later Cloudflare change adds, and that this binary does not contain, is an ordinary public client: the headers are ignored and the stored IP is that edge.

A proxy you run between Cloudflare and Velotrak has to append X-Forwarded-For. For nginx that is proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;. The walk then meets the Cloudflare hop and uses CF-Connecting-IP. A proxy on 127.0.0.1 that sends only CF-Connecting-IP is accepted. A Docker bridge or LAN address that forwards headers without appending X-Forwarded-For is stored as itself, and a CF-Connecting-IP the visitor supplied is ignored. The installer runs Velotrak on the host, with no extra proxy, so orange cloud to that host is the direct case.

The same address is what the rest of the tracker uses:

  • GeoIP looks up country, region, city, and ISP. An empty country after install is a missing database at /var/lib/velotrak/geoip/dbip-city.mmdb. A proxy address comes back as that proxy’s location, which is a filled-in country, not an empty one.
  • The bot check matches user-agent patterns and a built-in datacenter list (ranges such as AWS, GCP, and Azure). Cloudflare’s ranges are not on that list, so an edge address is not marked dc_ip on its own. A custom IP rule you saved matches whatever address was stored.
  • A flow rule on ip compares that address.
  • LP Protect signs the vt_lp entry token, valid for 5 minutes, with that IP and the user agent. The session cookie after a valid entry lasts 2 hours and is not tied to the IP. A click and a lander request that resolve to different addresses produce the empty 403.
  • Meta CAPI sends the click row’s IP as client_ip_address. TikTok sends it as ip. Both are copied from ClickHouse when the event is delivered. Google Measurement Protocol sends no IP field.

vt_vid and vt_cid are Secure when the origin connection is TLS, or when X-Forwarded-Proto is exactly https. Keep that header. The cookies stay readable by the pixel; they are not HttpOnly.

The compiled range list does not refuse other clients. A request that reaches the port directly is stored as the peer address. Blocking the origin IP so that only Cloudflare can connect is a firewall rule on the server.

Certificates and SSL mode

VELOTRAK_TLS_DOMAIN turns on the built-in ACME client and listens on VELOTRAK_TLS_PORT (default 443). VELOTRAK_TLS_CERT_FILE and VELOTRAK_TLS_KEY_FILE load a certificate you already have. The installer’s env comments name a Cloudflare Origin CA certificate or the files from a DNS-01 issuance. This program does not talk to a DNS provider, so it cannot do DNS-01 itself. When VELOTRAK_TLS_DOMAIN is set, the certificate files are not loaded.

The ACME client tries tls-alpn-01 first: the certificate authority must finish a TLS handshake with this process on 443. It then tries http-01: GET /.well-known/acme-challenge/… on port 80. The plain HTTP listener is VELOTRAK_HTTP_PORT. The installer sets that to 8080. The HTTP handler serves the challenge and then the normal application. It does not redirect other HTTP requests to HTTPS.

Orange cloud terminates TLS at Cloudflare, so the tls-alpn-01 handshake stops there. http-01 is fetched on port 80 of the public name. The default process is on 8080, and Cloudflare’s “Always Use HTTPS” answers port 80 at the edge, so the challenge never reaches the process. Issuance fails. Renewal fails the same way for as long as the name stays proxied. Issuing while the record is DNS-only, then turning the proxy on, leaves the next renewal broken.

For an orange-cloud hostname, leave VELOTRAK_TLS_DOMAIN unset and install a certificate file. A Cloudflare Origin CA certificate is trusted by Cloudflare’s Full (strict) check. A browser that opens the origin directly does not trust that certificate, so visitors should reach the hostname through Cloudflare. A certificate you renew with DNS-01 outside this program works too. Restart the service after the env change.

Set the zone’s SSL mode to Full (strict). Cloudflare then opens TLS to port 443 and checks the certificate name. Flexible opens plain HTTP to the origin. This server answers that HTTP request in place, so Flexible does not loop against Velotrak by itself. Flexible never uses the certificate on 443, and the hop from Cloudflare to the server is unencrypted. Use Full (strict). A redirect you add on port 80 to https:// the same host will loop in Flexible mode, because Cloudflare keeps fetching the origin over HTTP.

The domain Check requests https://<host>/healthz, does not follow redirects, and expects the response header X-Probe-Ack. active means this instance answered. issuing means plain HTTP reached this instance and HTTPS did not. pending_dns with the detail “a proxy is in between” means the host answered without that header. A challenge page or an interstitial is that case. Pass Host through unchanged, and pass X-Probe and X-Probe-Ack. A hostname that is not on the Domains page is not a tracking host: its landers are sandboxed, and a pixel there cannot read the tracking cookies. See installation.

Paths the proxy must not change

These responses are per visitor. The origin sends Cache-Control: no-store on each of them:

Path What it is
GET /click/{campaign-id} The campaign redirect. The default type is HTTP 302. meta, double_meta, and js are HTTP 200 HTML pages, also no-store.
GET /dm The second hop of a double-meta redirect.
GET /go Lander to the offer chosen for that click.
GET or POST /postback/{network-key} The affiliate network’s server-to-server postback.
GET or POST /track The browser pixel.
GET /lp/… when LP Protect is on, or when the HTML URL contains click_id The protected or macro-substituted lander.

Leave those as the origin sent them. A cache rule that stores them, or that ignores the query string, replays one visitor’s redirect, cookie, or lander HTML for the next visitor. Hosted HTML without click_id, and other lander files, are public, max-age=60. /velotrak.js is public, max-age=300. Caching those for that long matches the origin.

The js redirect is an inline script, and an injected pixel is <script src="/velotrak.js" async></script>. Neither carries a Cloudflare skip attribute. Turn Rocket Loader off for the tracking hostname, and turn off Auto Minify for HTML and JavaScript there. Those features rewrite the response body this server generated.

Bot Fight Mode, Super Bot Fight Mode, Browser Integrity Check, and “I’m Under Attack” serve a JavaScript challenge or a block page. This server has no bypass for that. A network postback is a plain GET or POST from the network’s servers. The challenge never completes, and the conversion is never booked. The same challenge drops /click, /go, /dm, /track, and /velotrak.js. POST /mcp is also a non-browser client; a zone-wide fight mode blocks it on any hostname that reaches this process. Turn those features off for the tracking hostname, or skip them for /click, /go, /dm, /postback, /track, /lp, /velotrak.js, and /mcp.

Campaign redirects are HTTP 302, or an HTTP 200 HTML page for the meta and script types. Leave the status code as the origin sent it. There is no WebSocket endpoint in the tracker or the admin, so the zone does not need WebSockets enabled.

Cloudflare closes a proxied request at about 100 seconds and returns error 524. This server does not. Backup and restore run inside the admin HTTP request, and a large one can outlast that limit. The admin shell is Cache-Control: no-cache.

Which hostname to proxy

Hosted landers, the click link, the postback, and the pixel are paths on a hostname you register. There is no separate lander product-mode.

Hostname Orange cloud
Tracking domain (campaign link, /postback, /lp, /go, /track) Works for visitor IP when Cloudflare connects straight to Velotrak. Full (strict), a certificate file, no cache on the paths above, bot features off, Rocket Loader and HTML/JS minify off.
Admin domain (VELOTRAK_ADMIN_HOST) Optional. Same TLS mode, and do not cache it. A restore that runs past the proxy’s timeout fails in the browser while the server may still be working. DNS-only avoids that. Give the admin its own hostname when an operator can upload landers.
A network postback URL Not its own DNS name. It is https://<tracking-host>/postback/<network-key> on the tracking domain. The network’s servers must be able to complete that request with no challenge page.
An external lander on your own site Outside this process. Velotrak only redirects to that URL.

More on the objects those paths belong to: flows, landers, conversions, and CAPI.

Questions

Q1Does Flexible SSL loop against Velotrak?
No. Ordinary HTTP is answered as HTTP. Flexible still leaves the hop from Cloudflare to your server unencrypted, and it never uses the certificate on port 443. Use Full (strict).
Q2Will the built-in certificate renew behind orange cloud?
No. Issuance tries a TLS handshake on port 443 first, which Cloudflare answers itself, then an HTTP check on port 80. The installer listens on 8080. Bring a certificate file instead.