Use reserved domains and IPs in examples
A while back I posted in frustration on various social media platforms — I was reading software documentation and it used some made up domain as example text. This is bad! But in the replies to my post, some people weren’t aware of reserved domains and IP addresses, so this seems like a good opportunity to share what I know.
Why reserve domains and IPs?
The most important answer is to protect the users. Imagine I was writing documentation or building an example configuration file for some software. I might think “duckalignment.academy” is a fun domain name to use as a placeholder. It’s unregistered, so there’s no harm.
Until someone registers it. Then it could be whatever the registrant wants, including a malicious service. If someone forgets to update the example configuration before launching the software, they’re at the mercy of the domain owner.
The other reason to use reserved domains and IPs is that it makes placeholders more obvious. If a configuration file or documentation contains “duckalignment.academy”, it’s less obvious that you need to replace it than using “example.com.” Example values that are unambiguously examples are much friendlier to your users.
Which domains and IPs are reserved?
Several standards define reserved domains and IPs. RFC 2606 defines several reserved top-level domains, including .example for use in examples and documentation. It also reserves example.com, example.net, and example.org. RFC 6761 gives instructions on how those domains should be treated.
RFC 5737 reserves three IP address blocks for documentation: 192.0.2.0/24, 198.51.100.0/24, and 203.0.113.0/24. Using IPv6? RFC 3849 reserves 2001:DB8::/32. RFC 9637 added a reservation for 3fff::/20 last year in order to preserve a range big enough to encompass modern real-world networks.
Using example domains and IPs
Please don’t use domains like “foo” or “bar” in your documentation and sample configuration files. They’re not helpful and can actually prove harmful to your users. The reserved domains and IP blocks are almost always what you need. If they aren’t for whatever reason, ensure that you own the domain you’re using and commit to owning it for at least the life of your project (and ideally far beyond that).
