The Cloud Foundry Blog

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 foo.com. 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 bobross.com or paintingclouds.com, just for fun, if I needed a fake URL for a test.

Bob Ross

I think it was Ken Mayer who taught me that example.com is actually meant to be used in documentation and tests. example.com 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 chumbawamba.com 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, example.com carries no connotations. It is effectively a metasyntactic variable like foo and bar. example.com 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 example.com for example domains, we also have RFC5737 which describes the IP addresses to use in documentation.

The blocks 192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2), and 203.0.113.0/24 (TEST-NET-3) are provided for use in documentation.

I know I’ve been very guilty of using IP addresses like 1.2.3.4 or 192.168.1.1 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 192.168.0.1 8000 that’s one thing that probably won’t do any damage. But on the wrong network, nmap 192.168.0.0/16 might actually get its operator in trouble and so we should write nmap 192.0.2.0/24 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 example.com for example domain names — if I need multiple domain names, bobross.example.com is perfectly acceptable. And start with 192.0.2.1 for example IP addresses (192 is easy to remember from 192.168.0.0/24 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?

This entry was posted in Engineering. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>