Easier Site Migrations: Avoiding DNS Problems with the hosts File
Over this past month, I’ve needed to migrate quite a few WordPress sites from one host to another. I can say with confidence: it’s still not my favorite process. There’s nothing that should be complex about it, but somehow there are enough moving parts that it’s never simple, and you feel on edge throughout. If you’ve ever put together a chair from Ikea, you’ll know what I’m talking about.
Today, we’ll be looking at a specific source of complications in a WordPress site migration: Domain Name System (DNS) records. We’ll talk in depth about potential DNS pitfalls in a WordPress site migration, and introduce a very helpful way to step around many of them: the
DNS: A Quick Rundown
DNS is a massive set of recorded associations between domain names and IP addresses.
To understand DNS, it’s helpful to reflect on a couple of things:
- Every location on the internet is specified by a numeric IP address that looks something like this:
18.104.22.168. Your web browser, FTP client, etc., all ultimately rely on IP addresses to know which server to request information from.
- But humans aren’t so good at remembering 12-digit numeric strings. They’re a lot better at remembering names, like wpshout.com, which is why domain names exist.
So we have two sets of address information on the internet: a big list of human-readable domain names, and a big list of computer-readable IP addresses.
So what is DNS? DNS is a massive set of recorded associations between domain names and IP addresses. “wpshout.com is at 22.214.171.124” is a single DNS record—domain-name/IP address associations—of which there are millions and millions.
When you enter a domain name into your browser, your request is sent to a nameserver: a computer whose job is to store DNS records. When it gets your request, the nameserver looks up its record for the domain you’ve given it, finds the IP address it has on file for that domain, and sends you there. That’s how you get to the actual web server that’s storing the resources you’ve requested.
How DNS Can Get Tricky During a WordPress Site Migration
You can’t point your domain to the target site because you’re not sure it works properly; and you can’t test whether it works properly because it has no domain name.
If you’re migrating a WordPress site from one host to another, DNS generally presents the following conundrum: You want to view, work with, and make changes to the new site on the new hosting (the “target site”), but that site doesn’t have a domain name associated with it. In other words, you can only view the target site at
mysite.com still points to your old site on your old hosting.
When you access the target site by IP, it’s probably mostly broken: depending on how you’ve done the migration, your links across the site will probably look like
mysite.com/link points, of course, back to the old site on the old hosting. The target site’s resources are actually at links looking like
126.96.36.199/link, since the target site has no domain name pointing to it.
You can use a tool like searchreplacedb2 to go into the database on the target site and rewrite every instance of
188.8.131.52, which should give you a working target site. From experience, though, this is the kind of change that can be a big headache to undo later. If you write your find-replace rules wrong, you can, for example, miss instances of
184.108.40.206 in the database—which, for one site, caused me to rewrite all of the site’s email addresses from
[email protected] to the very broken
To summarize, you’ve got a Catch-22: You don’t want to point your domain to the target site because you’re not sure it works properly; and you can’t test whether the target site works properly because it has no domain name.
It Gets Worse: DNS Propagation and Caching
DNS records have to propagate: all nameservers throughout the world have to be told that a particular domain now points to a new IP address.
Okay, we’ve got a problem. But can’t we just point our domain to the new site really quickly to see if everything’s okay, and then point it back if it’s not?
Here’s where I tell you that DNS records aren’t stored on one single computer. That would be a very big computer, and if someone ever unplugged it the whole internet would break. On the contrary, they’re stored on an immense hierarchy of nameservers that looks something like this:
- “Authoritative” nameservers that answer occasional questions from other nameservers
- Intermediate nameservers scattered into zones throughout the world that take their cues from nameservers higher up the chain
- Nameservers kept by your internet service provider (ISP) that take their cues from intermediate nameservers, and that actually direct your requests
Each of these nameservers caches its information: rather than trying to constantly update every single record, it assumes that the records it has are good until someone tells it otherwise. It’ll also dump any record that’s older than a certain age; this maximum age is given by a setting called time-to-live (TTL) that varies server-to-server, but is a few hours or less for most nameservers.
This is why DNS records have to propagate: all nameservers throughout the world have to be told that a particular domain now points to a new IP address. Until that happens, some nameservers will know about the new IP address, and some won’t, and people will be seeing different versions of the site. And in particular, if your nameserver hasn’t updated its record, you can’t see the new site.
Because of relatively short TTLs on most nameservers, DNS propagation usually takes a few hours or less—which is already a significant headache, since “Show the world a perhaps-broken site, that you can’t see is broken, for half a day” isn’t the greatest proposition for a site someone actually cares about.
Now here’s where your ISP (Comcast, Time Warner, or whomever provides your internet connection) comes into play. ISPs may not have the most thoughtfully configured nameservers, and in my experience the time-to-live on an ISP’s nameservers can be way too long: 24 or 48 hours or more. This means you’ll be seeing the old site basically forever, as long as you still use the same internet connection—even once your phone (with its different ISP) is properly showing you the new site.
You can switch things up by moving to a coffee shop or connecting through your phone’s hotspot capability, but those are sketchy solutions, and ones you shouldn’t have to count on.
Okay, We’re Done with the Bad News
That’s a lot about how DNS can mess you up, but I wanted to paint a picture so you know where DNS issues can lead, and so that if you do get turned around by DNS you at least know how you’re turned around. Hopefully these confusions are feeling familiar if you’ve migrated a site before.
With all the bad news out of the way, let’s talk about a better solution for testing a new site prior to redirecting a domain name: your computer’s
hosts to Test Sites with No Domains
It turns out your computer can act as its own nameserver.
It turns out your computer can act as its own nameserver: you can manually map IP addresses to domain names, just for your own computer, using your computer’s
This file is mercifully similar across Windows machines and Macs. The only key difference is its location on your computer: on Windows machines, it’s at
C:\Windows\System32\drivers\etc\hosts, and on Macs it’s at
/etc/hosts. In either case, the file has no file extension—it’s not
hosts.txt, for example, but just
Once you’ve found the file, you need to open it with a text editor, which could be something simple and preinstalled like Windows’s Notepad, or, preferably, an actual code editor like Sublime Text.
Once you’ve got it open it looks like this:
How you use it is mercifully simple: you just enter the IP address of the target site—the IP associated with your new hosting account—and the domain you want it to point to on your computer. In the image above you can see the example for
nickkranz.com: its hosting account’s IP is
220.127.116.11, and I wanted to browse
nickkranz.com at that address prior to actually making any DNS changes to the domain. (Note that all the lines that begin with
# are commented-out: the first line that does something is line 19.)
The syntax looks like:
18.104.22.168 mysite.com 22.214.171.124 secondsite.com
with each record on a new line. Once you’ve edited the file as needed, simply save it in your text editor and close the file.
What this Gets You
You can browse and edit the new site at its target domain, while the rest of the world still sees the old site.
hosts record changes, you can browse and edit the target site—the site on the new hosting—at its normal domain (mysite.com), while the rest of the world still sees the old site you’re about to switch from when it visits that domain.
This means no database rewrites: any
mysite.com/link-looking links on the new site will work properly. You can edit the site just as you would if it were already live. Then, when you do redirect the domain to the new hosting account’s DNS records, and those changes propagate, the rest of the world will see what you already see on your computer.
Checking if the Site Propagated
Of course, with
hosts, there’s always the danger that you’re the only one seeing the new site. You can check the progress of DNS propagation by browsing the domain on your phone. It’s also quite easy to remove the
hosts record you created and then test whether you see the new site or the old site. This is the best long-term, since in general you want to see what the rest of the world sees for debugging purposes.
hosts is Awesome!
I hope we’ve shown how big a headache DNS stuff can be in a WordPress site migration—and how you can route around a lot of that unwanted complexity with the
hosts file. Got any questions or thoughts about
hosts or DNS? Let’s hear ’em in the comments below!