Why use 'TEST-NET' IP addresses in general documentation instead of RFC 1918 ranges

June 25, 2023

Recently I saw this Fediverse post on using dedicated test IPs and domains (via), and it sparked a little dull light of realization in my mind. I've always considered it obvious why your documentation shouldn't use real IP addresses or IP address ranges. They belong to someone, they are or may become routable on the Internet, and if someone reading your documentation uses your sample IP ranges, bad things happen. However, it wasn't as obvious to me why you shouldn't use RFC 1918 private IP address ranges, which are by definition not routed on the Internet.

If the person reading your documentation is in a green-field environment, it's true that the RFC 1918 address ranges are harmless. They can freely use any of them they want, including the ones your documentation. However, if the person reading your documentation isn't in such a green-field environment, some RFC 1918 address ranges may already be in use and routed in their environment; these are, in practice, 'public' IP ranges, just public inside their networks instead of public to the entire Internet. If your documentation's RFC 1918 ranges overlap with RFC 1918 ranges already in use, they'll get more or less the same problems as if they'd used public IPs.

This problem is magnified because genuine 'green-field' network environments are increasingly hard to find even in small environments. All sorts of things are probably camping on RFC 1918 ranges these days; there's container systems, virtualization, private networks behind your home NAT router gateway, cloud environments, and so on and so forth. You can see the problems just from how these systems can clash with each other over what RFC 1918 range to use.

Using an IP address range that's specifically for use in examples and isn't supposed to ever be used otherwise sidesteps most of these problems. It can't prevent people who read your documentation from using those IP address ranges in their own live setup, but it does avoid clashing with any other IP address range they should be using, whether it's from the public Internet or internal RFC 1918 usage.

(Roughly speaking, nothing will stop some number of people from copying whatever IP address ranges and domains your documentation uses into their live setup. All we can do is reduce the potential harm of doing so. This is a cynical viewpoint but, I maintain, a realistic one.)

Written on 25 June 2023.
« Everything that uses configuration files should report where they're located
Let's Encrypt's interesting certificate issuance error »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Sun Jun 25 23:11:32 2023
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.