cloudflare-realip-nginx is a single bash script, with a systemd timer and an installer, for operators who run nginx behind Cloudflare. It keeps the real-IP trust list current so that nginx, your logs and your rate limits see the visitor’s address, not a Cloudflare edge address. The code is at https://github.com/IndianOpinion/cloudflare-realip-nginx, under the MIT licence. Version v0.1.0 was released on 12 November 2026.
Behind Cloudflare, every request reaches nginx from an edge address. Unless nginx is told which addresses to trust and which header carries the visitor’s address, it treats the edge as the client. Rate limits keyed on the client address then put many readers into a few buckets, and one abuser throttles everyone on the same edge. Blocklists and logs see Cloudflare, not the attacker.
Cloudflare publishes its ranges as two plain text lists and says they need regular updates. When the local copy goes stale the failure is quiet: a new range is not trusted, and visitors through it show up as the edge again. Nothing errors.
The usual fix is a ten-line cron script. The usual version writes over the live file before testing it, reloads nginx on every run, checks only the IPv4 count, and accepts any line containing a slash as a range. Each of those became a test case here.
set_real_ip_from snippet.--dry-run, --diff, --status, --verify, --rollback and --release.The tool is one bash file, bin/cloudflare-realip-nginx, run under set -euo pipefail. It has no Python and no jq. Address validation is done in pure bash parsers for IPv4 and IPv6 CIDRs, so there is no dependency whose output differs between distributions.
Each run takes an exclusive flock in the state directory, then does these steps and stops at the first failure:
unchanged and stop without a reload.nginx -t against a throwaway configuration.nginx -t. On failure, restore the backup and exit 4.The staging directory sits outside the include directory so no include glob can see a half-written file. Requiring the same filesystem keeps the rename atomic and keeps the SELinux label.
The snippet is plain nginx configuration:
# Generated by cloudflare-realip-nginx. Do not edit: changes are overwritten.
# Cloudflare IPv4 ranges
set_real_ip_from ...;
# Cloudflare IPv6 ranges
set_real_ip_from ...;
real_ip_header CF-Connecting-IP;
Typical use:
cloudflare-realip-nginx --dry-run --test
sudo cloudflare-realip-nginx
sudo cloudflare-realip-nginx --verify
--force. If either family fails, nothing is written.--force takes over a hand-written file after backing it up.eval.--release, so the next timer run does not undo it.The tool never touches a firewall. The README opens with a section on locking the origin to Cloudflare’s ranges, because real-IP only changes what nginx believes about connections from those ranges, and a direct visitor still skips the WAF and rate limits. It warns that closing port 80 silently breaks HTTP-01 certificate renewal, and that closing IPv4 but not IPv6 leaves the origin exposed. It also notes that the ranges are shared by all Cloudflare customers, so an allowlist alone does not stop traffic sent through another account.
--extra-trusted accepted an IPv4 or IPv6 default route (a prefix of zero), which would let any client set its own address. Both are now refused with exit 1.install.sh --purge ran rm -rf on the state directory named in the config, so a bad value such as /var/lib would have wiped it. It now removes only the files the tool writes, and the directory only if empty.install.sh run said “already installed” and never enabled the timer. In cron mode the cron file was written even when the dry run failed. Both are fixed.nginx.conf, a server block or a log format. Refreshing a firewall allowlist is a separate job. The repo ships a script that prints the commands for ufw or nftables without running them.Test status: this is v0.1.0. The bats suite had 169 passing tests and one skipped out of 170 in review, using stand-in commands plus integration tests against a local nginx. The parsers were compared with Python’s ipaddress module on 3,037 generated and edge-case CIDRs with no mismatches. shellcheck could not be run locally, and the CI workflows (shellcheck, a container matrix) are parked in a pending folder, so CI has not run on GitHub. It has not run on a live site.
It needs bash 4.2 or later, coreutils, curl 7.52 or later, flock, logger, diff, and nginx 1.18 or later with the realip module.
git clone https://github.com/IndianOpinion/cloudflare-realip-nginx.git
cd cloudflare-realip-nginx
sudo ./install.sh
The installer runs a dry run with the nginx test first and enables the timer only if that passes. --cron installs a cron file instead of the timer.