blog single gear

Domains and IP Addresses Reserved for Documentation – and Why You Should Use Them

Earlier in my programming days, my go-to example would have been Well, not always. If we had any inside jokes on the team, I might put something clever in there for fun. On the Cloud Foundry backend team, one of our current inside jokes includes a picture of Bob Ross in the free space on one of our CI boards, so maybe in that case I would have gone with or, just for fun, if I needed a fake URL for a test.

Bob Ross

I think it was Ken Mayer who taught me that is actually meant to be used in documentation and tests. isn’t just some domain that some private party is using for the greater good; The Internet Engineering Task Force published RFC2606 which specifically says that example.{com,net,org} are reserved exclusively for that purpose.

Why would you care about that? Why shouldn’t you go ahead and use in the tests you write while rocking out to Tubthumping? RFC2606 explains:

Test and experimental software can escape and end up being run against the global operational DNS. Even examples used “only” in documentation can end up being coded and released or cause conflicts due to later real use and the possible acquisition of intellectual property rights in such “example” names.

Besides that, carries no connotations. It is effectively a metasyntactic variable like foo and bar. tells the reader that it’s a domain just for the sake of a domain. There is nothing special about it.

Not only do we have for example domains, we also have RFC5737 which describes the IP addresses to use in documentation.

The blocks (TEST-NET-1), (TEST-NET-2), and (TEST-NET-3) are provided for use in documentation.

I know I’ve been very guilty of using IP addresses like or when I write example IP addresses; but I had never considered that I might inadvertently write an example that does Something Bad™ when copied and pasted because I picked an IP address that maps to a real, live network. If someone blindly copies and pastes echo "Hi!" | nc 8000 that’s one thing that probably won’t do any damage. But on the wrong network, nmap might actually get its operator in trouble and so we should write nmap as an example that’s guaranteed to be harmless. And savvy readers will understand that it’s an IP or domain just for the sake of example, no strings attached.

For me, it’s an easy choice now. Use for example domain names — if I need multiple domain names, is perfectly acceptable. And start with for example IP addresses (192 is easy to remember from being in rote memory, and then I just have to remember 0.2 after that).

I’ll be careful about example domains and IPs in the future, but I’m not sure that I’ll spend the time to change existing Cloud Foundry test code that uses nonstandard examples. If you’ve wanted to contribute to an open source project but you’ve never known where to start, I would welcome you to make a pull request fixing nonstandard examples in any of our repositories on GitHub or to any other open source project. I can tell you from firsthand experience that it feels great to say you’ve contributed to an open source project — so what are you waiting for?