WordPress Multi-Site Domain Mapping

Important: This was written in 2012, when you needed to use a plugin for domain mapping. With version 5.something of WordPress, and with version 6+, domain mapping is built into the WordPress core.

If you were using the obsolete plugin for domain mapping, you should document the exact domain names you were mapping to, for each site. Then, network disable it and then delete it.

In new versions of WordPress, you simply put the domain name you want into My Sites, Network Admin, Sites, then hover over the site you want, click Edit, in the Info tab edit the “Site Address (URL)” field. Use the full URL, including https://

You still have to set the DNS so the domain name points to your WordPress Multi-Site installation.

With WordPress version 3+ or 4+ in Multi-Site Mode, and the Domain Mapping Plugin, you can map domain names to any of your blogs. I’ll walk you through the steps to install the plugin (you have to move a few files and edit some configuration settings). Then I’ll show how to specify the mappings you want. (There are several blogs with partial instructions, that didn’t explain the configuration settings and didn’t give examples of how to specify the mappings — but you won’t have to figure it out because I did!)

Domain Mapping Plug-in Installation

Before doing anything else:

Backup your database and files, and save them to another location, with a name including “before Multi-Site” and the date;
Upgrade WordPress to the latest version; and
Install your security and anti-hacker plugins. I cover what you can do (vs. what your hosting company should do) in WordPress Security for People Without Technical Knowledge since for WordPress Multi-Site you have even more reasons for needing top-quality security.

Before Installing Domain Mapping

Follow my instructions in WordPress Multi-Site Installation to configure WordPress for multi-site. Even if you already have Multi-Site working, there are some things you should check before domain mapping.

Before doing anything with the Domain Mapping plugin, you must configure “wildcard DNS” and you have to test it works. Again, see my WordPress Multi-Site Installation to get wildcard DNS working. WordPress Multi-Site uses what you could call “virtual domain names”, converting calls to all the domains into WordPress pages. If wildcard DNS isn’t working, the domain names can’t get to WordPress, and you will think there is a problem with the Domain Mapping plugin, and you’ll waste time, and you’ll be frustrated, because the problem was actually wildcard DNS.

Go check you have WordPress installed right for the domain mapping plugin, first!

Gotchas

You must have WordPress installed in the root of your hosting account (/public_html/) or in the root of a subdomain (for example, /public_html/yoursubdomain/), or domain mapping will not work. You can Not install WordPress in a Folder, as distinct from a subdomain, and have multi-site domain mapping work. Follow my Multi-Site Installation (above link) if you need to move an existing site and/or move WordPress.

Don’t put the domain that WordPress itself is in, into a mapping — WordPress needs an actual domain name, not a virtual one; it needs a “stable place” to work from. If you map the WordPress domain, you will get an error “The domain mapping plugin only works if the site is installed in /. This is a limitation of how virtual servers work and is very difficult to work around”. Worse, you then can’t access WordPress at all. If you do put the domain in a mapping, you will have to delete the record using phpMyAdmin, in the domain_mapping table. [If that doesn’t make sense to you, have a database person do that for you; don’t fumble around in phpMyAdmin.]

Note: I am giving instructions for Apache web servers. If you must use a Microsoft IIS 7 server, it definitely can work with multi-site and domain mapping, I have a client doing that, and you will need to be able to do things like set up wildcard DNS and edit the extremely picky web.config file — I feel for your suffering.

Plugin Installation

The Domain Mapping plugin needs special installation instructions. (Do not just use the WordPress plugin install, there are files you must move to special locations, and you must edit some configuration files. And there are conflicting instructions for the plug-in at different web sites. The Ottopress site mentioned in the plugin readme.txt is so outdated and incomplete it is useless, except the section on DNS.)

Download the current version from the Developers page (there are some improvements over the “published” version 0.5.4, including minor fixes that remove minor warnings from your PHP error log) and click the Current Version link, which as of August 2015 is 0.5.5.1.

Install the plugin via My Sites, Network Admin, Dashboard, then Plugins, Add New. Upload the .zip file you just downloaded.

Move sunrise.php from /public_html/wp-content/plugins/wordpress-mu-domain-mapping to /public_html/wp-content/ . (If there is a sunrise.php there already, from another plugin, you’ll just have to merge them as best you can.)

Edit /public_html/wp-config.php and uncomment or add the SUNRISE definition line. If it does not exist please ensure it’s on the line above the last “require_once” command.
define( 'SUNRISE', 'on' );

Move domain_mapping.php from /public_html/wp-content/plugins/wordpress-mu-domain-mapping/ to /public_html/wp-content/mu-plugins/ (create that folder if needed). [Note: The plugin’s readme.txt says to ignore this instruction in the Domain Mapping Tutorial written by a user, but this works.]

Note: Moving domain_mapping.php means that in Plugins, Installed Plugins, you will not find the domain mapping plugin in the main plugins list, which is good; you don’t want to ever disable it. Click “Must-Use” at the top of the Installed Plugins screen to see it.

Note: The plugin readme.txt talks about setting ANAME and CNAME records.
If you are installing on your own server, having to configure your own DNS, follow these instructions (or the more detailed instructions in the OttoPress link).
If you are installing on a shared hosting account, most shared hosting providers don’t give you access to setting ANAME or CNAME records; your hosting provider will do it for you, or you do the equivalent by going into CPanel and Add-On Domains.

Configuration

In Network Settings

Network Settings (/wp-admin/network/settings.php):
Set “Network Name” as you want (e.g. “Lerner Consulting Network”). This will show on the “Add your New Blog” screen, “Get another {YOUR NETWORK NAME} site in seconds”.

Set “Network Admin Email” to one of your valid email accounts, where you want to be notified of new registrations and comments.

Set “Allow new registrations” how you want. I have mine set to “Registration is disabled”, since I can create new blogs from the Network Admin, Sites menu. Warning: If you select “Both sites and user accounts can be registered.” then you will get spammers creating blogs on your network, so you’d better have every other security measure in place.

You probably want to have “Allow site administrators to add new users to their site via the “Users → Add New” page” checked. They can not add Super-Administrators (able to install plugins or change things across all sites), they can add Administrators (able to change settings for their site, delete posts written by others on their site, etc.)

In “Banned Names” I put the folder names used by my non-WordPress web sites. (If you’re the only one permitted to create blogs, you can leave this field empty, and just remember.)

Here’s some of my banned names: admin administrator articlesite audio blog calendar cgi-bin fonts images lists main root shared web www. Since it’s so popular, block hackers trying to use “blog” by having it in the banned list, if you aren’t using it.

If you have a SubDomain setup of WordPress Multi-Site, you Can Not use for blogs (e.g. include in “Banned Names”) the names of folders created when you make parked domains, add-on domains, or subdomains — I created a SubDomain “test” in CPanel, and made a blog of the same name. Trying to access the blog gave me my main WordPress blog (https://glerner.com/) instead; trying to access the Dashboard (http://test.lernerconsulting.info/wp-admin/) gave me an Internal Server Error.

Note: If you are setting up a new WordPress Multi-Site, you could switch between subfolder and subdomain setup, simply by changing the variable in wp-config.php. Once you have sites indexed by search engines (which could be in minutes), leave the setting alone. If you do switch, you must update your .htaccess and wp-config.php with the code WordPress says in Network Admin, Settings, Network Setup /wp-admin/network/setup.php; and any links and images and Media Library items will need to be fixed. It is easier to not change to/from subfolder or subdomain installation.

In Settings, Network Setup

Nothing to do, informational only. (Fill this in to help your site owners mapping their domain names, if you won’t be doing it for them.)

In the My Sites menu, select Network Admin, Sites

At the top of the screen click the Screen Options button
Change the Show on Screen to 999 sites. (Otherwise, it only shows a few, very awkward.)

In Settings, Domain Mapping

/wp-admin/network/settings.php?page=dm_admin_page

(These settings work while setting things up, and when using the blogs. I’m not sure what other combinations work; you can experiment with them.)

Domain Options (x means checked, _ means unchecked)
_ Remote Login
x Permanent redirect (better for your blogger’s pagerank)
x User domain mapping page
_ Redirect administration pages to site’s original domain
_ Disable primary domain check.

Note: After changing the Domain Mapping Configuration, you should run Update Network – /wp-admin/network/upgrade.php

Easy Way: User Domain Mapping page

If this doesn’t work, something isn’t configured right; follow the rest of the instructions to get everything configured right.

For this to work, it has to be enabled in Network Settings, Domain Mapping (checkmark for the User Domain Mapping page, see above).

In the My Sites menu, select Network Admin, Sites
/wp-admin/network/sites.php

Hover over the blog name (or the Edit link) for the site you want to map to a domain.

Click the Dashboard link.

In the Tools menu, select Domain Mapping
/wp-admin/tools.php?page=domainmapping

In the “Add new domain” section, type the subdomain you want, without leading “http://” or trailing slash. For example, if you own yummyfish.com and you want to access your blog with http://salmon.yummyfish.com then you type salmon.yummyfish.com .

Check the “Primary domain for this blog” box.

When you click “Add”, you will see the mapping in “Active domains on this blog”

[I recommend have Primary checked on the mapped domain. If you have the WordPress domain set as Primary, visitors will see that domain for logging in and making comments. Having the mapped domain set as primary may be better for search engines. With Primary checked for the mapped domain, you access /wp-admin/ via the mapped domain; if you try accessing it through your WordPress domain (the unmapped Dashboard URL for this blog), you will get automatically redirected.]

Effect of Primary setting

I have WordPress installed in http://lernerconsulting.info and I have mapped a blog to http://liquidfluoridethoriumreactor.glerner.com/
If I have the default location for the blog (http://liquidfluoridethoriumreactor.lernerconsulting.info) as Primary, when visitors log in (or post comments, or many other actions) at http://liquidfluoridethoriumreactor.glerner.com they get brought to http://liquidfluoridethoriumreactor.lernerconsulting.info, not what I want.

I prefer keeping everything visitors see at the domain they started in, less confusing for people; so, set the mapped location as Primary, instead of the default location.

(My /wp-admin/ will be on different domains for different blogs, but if I type the default location for /wp-admin/ I get automatically redirected to the mapped location).

Notice the server name shown, so you can add a DNS “CNAME” record pointing to it. If you are on a shared hosting account, you would do this by adding an add-on domain, or have your hosting provider set it up for you.

Note: In the Sites page /wp-admin/network/sites.php the Dashboard and Visit links will remain showing the WordPress domain. You will see the mapping you entered, in the Mapping column. The Dashboard and Visit links will redirect to the mapping you set.

Test if you can access the blog via the mapping you set. Test you can access the Dashboard via the mapping you just set followed by /wp-admin/ and if both work, you’re done.

If the mapping did not work, you will have to follow the full instructions, below.

Detailed Configuration

In Sites

In the My Sites menu, select Network Admin, Sites
/wp-admin/network/sites.php

If you were trying to get domain mapping to work, you may well have tried changing these settings. Nope, you need to set them back to the default (the settings that would be there when you create a new blog and haven’t modified anything).

Hover over the blog name so a menu appears, hover over the Dashboard link, right click, copy the link location.

Still hovering over this blog’s menu, Click Edit

In the Domain field, paste the link location (the Dashboard location).

Delete the http:// from the beginning, and delete the /wp-admin/ from the end.

Example: If the Dashboard location is http://opera.lernerconsulting.info/wp-admin/, then you would have opera.lernerconsulting.info . Note: no trailing slash.

In the Path field, type a slash / . [Note: I’m giving instructions for a SubDomain setup. For a SubFolder setup, use: Domain like lernerconsulting.info (no trailing slash) and Path like /opera/ (with leading and trailing slash).]

Put a checkmark by “Update siteurl and home as well”.

When you click “Save Changes” you will get a message near the top of the screen, “Site info updated.” and the “Edit Site” location at the top of the screen will show the new location. If you have it correct, clicking this “Edit Site” link will display your blog.

Repeat this for each site (blog) in your network. All sites, mapped or not, should be set this way.

In Settings, Domains

/wp-admin/network/settings.php?page=dm_domains_admin

This is where the magic happens. You will need to know your site IDs before you can use this page.

Getting Site IDs

From My Sites, Network Admin, Sites
/wp-admin/network/settings.php

Hover over the blog name (or the Edit link) for the site you want to map to a domain. You will see a link like “http://…/wp-admin/network/site-info.php?id=15“
The Site ID is at the end (e.g. 15). You will need this number.

Make a list of all of the Site IDs you will be mapping.

Mapping, Via Network Settings Domains

If this works on one mapping (i.e. everything is configured properly now), the User Domain Mapping (see above) will also work, if you enabled it. This is easier for mapping several domains at once (less browsing to different domains); User Domain Mapping is easier for an occasional mapping.

From My Sites, Network Admin, Sites, in the Settings menu, Domains

/wp-admin/network/settings.php?page=dm_domains_admin

Delete any incorrectly entered domains (e.g. the site ID isn’t correct)

Note: do Not enter your WordPress domain to be mapped.

In the “New Domain” section,

Enter the Site ID from the step above (Network, Sites)
Enter the sub-domain you want mapped for that site (without leading “http://” or trailing slash)
example domain: homesforsale.glerner.com
example domain: liquidfluoridethoriumreactor.glerner.com

Check “Primary” if you want http://blogsubdomain.domain.com to be what visitors see when making comments, when logging in, etc. (I recommend this, easier for your visitors, and perhaps better for search engines.)

If you want multiple blogs for a domain name, make a separate record for each, with the correct Site ID in each. The most common example of this is somedomain.com and www.somedomain.com, with only one set as Primary.

You should now see the mapping listed in the Mapping column of the Network Sites page. You should be able to access the blog from the domain you mapped (or get redirected there from the un-mapped address). The Dashboard for the blog should work from both domains.

Any problems or questions? Please leave me comments!