To Get Started:
Start by reading the Installing Plugins section in our comprehensive WordPress and WordPress Multisite Manual if you are new to WordPress.
Before we get started, there are 3 things we need to check first…
- WordPress Multisite: you are running your WordPress website as a multisite right? Because if not then you won’t be able to install this plugin.
- Dedicated IP: For using A Record setups, you need to ensure you have a dedicated IP. This IP would fall onto your multisite setup. i.e. when you enter the IP you see your multisite.
- FTP access: you need FTP access to your multisite to properly install and configure this plugin. Specifically, one plugin file must be relocated, and wp-config.php will need an edit.
Got all that? Great, then let’s get to it!
Getting Set Up
So first and foremost, download the plugin to your computer and then unzip it. Inside, you will see the following files:
Once unpacked, we need to upload all that to your website. Provided you have not changed your plugin directory path, it will look like this:
You will want to upload the inner domain-mapping folder there (that’s the one inside the main folder with all the numbers). So log in through FTP or, if you are on a local host, then move that folder over.
The path will then be:
You will see in the /domain-mapping/ folder there is a file called sunrise.php. We need to move that (move, not copy) to the /wp-content/ folder.
So the path to that file will be:
Thats the files sorted and uploaded. Now we just need crack open your wp-config.php file located within the root of your WordPress installation. On a cPanel server that path might be:
You will have to enter the following line:
define( 'SUNRISE', 'on' );
You can pop that right under the WP_DEBUG option, so like this:
define( 'SUNRISE', 'on' );
If for some reason you don’t have the WP_DEBUG line, then providing it is just above the following code comment it should work well:
/* That's all, stop editing! Happy blogging. */
Note: If you add this in the wrong place, you will most likely find issues when adding a domain name to be mapped from your WordPress admin area.
Now head on over to Network Admin > Plugins, and Network Activate the plugin.
We have the plugin installed now, so let’s go configure things!
Configuring Network Settings
The settings are located in the Network Admin area under Settings > Domain Mapping.
There are a few settings that need your attention under the first tab: Mapping Options. Let’s take a look at them one by one.
Enter your multisite IP address.
The Server IP Address is where you enter the IP address of your multisite. This doesn’t really affect anything; it appears in your users admin panels, and is only to inform them which IP they must use when mapping their domains.
Select the administration mapping option.
Administration mapping is where you select the domain that will be used in the admin area of sub-sites.
- domain entered by the user enables you and your users to access the admin area with either the mapped domain (userdomain.com/wp-admin/) or the original domain (usersite.yourdomain.com/wp-admin/).
- mapped domain enables you and your users to access the admin area through whichever domain is mapped. Don’t worry if you use usersite.yourdomain.com/wp-admin/, it will simply forward to userdomain.com/wp-admin/.
- original domain enables you and your users to access the admin area through the original domain only (usersite.yourdomain.com/wp-admin/).
Select the login mapping option.
Login mapping has similar options as above, but it affects login action.
- domain entered by the user enables you and your users to login with either the mapped domain (userdomain.com/wp-admin/) or the original domain (usersite.yourdomain.com/wp-admin/).
- mapped domain requires you and your users to login with whichever domain is mapped (userdomain.com/wp-login.php/).
- original domain requires you and your users to login through the original domain (usersite.yourdomain.com/wp-login.php/).
Enable/disable cross-domain login.
Enable Cross-domain autologin if you want the plugin to automatically log you into all sites you have mapped. Will also log your users into all domains they have mapped too!
Enable/disable domain verification.
If Verify domain availability is enabled, the plugin will notify your users if their selected domain cannot be mapped.
Make domain mapping a Pro Sites feature.
Select Pro Sites Levels will only appear if you have the Pro Sites plugin activated on your network. This enables you to make the domain mapping functionality available to certain Pro Site levels only, and charge your end members for the privilege of mapping their own domain via Pro Sites upgrades. (If you don’t already have Pro Sites, you can grab it here).
Now let’s take a look at the settings under the 2nd tab: Reseller Options.
1. Select the Reseller API log level.
2. Select your reseller.
1. The reseller API requests setting enables you to select how to log requests for domain names that your users purchase from you.
2. Select reseller provider allows you to select from the available domain name resellers. Currently, only eNom is available, but we plan on adding others in the future.
If you choose to enable domain purchasing for your users by checking eNom as your provider, you will need to enter your eNom account information.
1. Enter your account id and password.
2. Enable test or live environment.
3. Select your payment gateway.
1. Your account id and password are the same you use to login to your eNom account.
2. The Select environment setting enables you to specify whether to use a test account at http://resellertest.enom.com/ or your live account at http://www.enom.com/ Be sure the account ID & password you just entered are for the right account. :)
3. The Select payment gateway setting will only be visible if you have Pro Sites also active on your network. You can select between the eNom credit card processing services (requires you to have a processing agreement with eNom and a secure SSL connection), or the PayPal payment gateway in Pro Sites.
But…. But…. But…. What now!!!!
Thats your end of it done anyway. If you or your end user need to map a domain we first need a site. We won’t cover the whole creation of multisite and sub sites here. If you need help there then please pop over to our forums, we will gladly help you out there.
To add a domain name to your admin area is easy, but keep something in mind here:
If in the previous steps you chose “Mapped Domain” as the method for accessing the admin area and the domain being mapped is either not resolving to your server yet or not resolving for another reason other than DNS propagation then that admin area will not be accessible until the domain name has resolved correctly. Choose another option if this bothers you. :-)
Adding a domain name which is not resolving correctly in this instance will make that admin area inaccessible. Honest, we warned you!! ;-)
So, lets go to a sub site which has it own domain to map. In the sub site’s wp-admin, go to Tools > Domain Mapping.
Under the first tab, you can add the domain to be mapped to your sub site. Once you click add then that’s all you need to do from WordPress.
Enter the domain to be mapped to the sub site.
If you have enabled Verify domain availability in your network settings as described above, and the domain entered here is not valid for some reason, an alert like this will pop up:
Domain name verification alert.
If you have enabled domain purchasing in your network settings, clicking the second tab (Purchase domain) will enable your users to select and purchase their preferred domain name from you, right in the admin of their site. How cool is that?
Purchase a domain name right from wp-admin!
A Record & CNAME
If you or your end user wishes to map a sub domain to the blog within your multisite install then you can set up a CNAME
For the purpose of these instructions we will assume you are doing this through cPanel, however if you are using a different panel or managing the DNS with the domain name registrar then the principle is just the same, the method of adding it might be a little different.
If you cannot manage your own DNS then you would need to discuss this with whomever is currently managing it.
Even people on cPanel might not have access to the Simple and Advanced DNS options, this depends on your hosting provider. If you point your name servers to your host then it can be managed by your host or your cPanel. Again if you don’t have access, then ask your host.
CNAMEs are used for sub domain mapping. i.e. you want to map blog.userdomain.com to usersite.yourdomain.com
A Records are for mapping TLDs aka Top Level Domains. i.e. userdomain.com mapped into usersite.yourdomain.com
First we will handle a CNAME:
We will do this through Advanced DNS, so click on that.
Select Advanced DNS in cPanel
Select the domain from which you would like to enter a CNAME. Now fill in the form. :-)
Adding a CNAME in cPanel
Name: the sub domain to be mapped. So subdomain.example.com
TTL: You can set this to 14400. If you know what you are doing then please feel free to adjust this.
Type: CNAME of course ;-)
CNAME: Where it is going to, in the example above, we use usersite.yourdomain.com
Easy Peasy huh!
For A Record – Top Level Domains we go through the same process, except you will most likely already have the A record set (unless in instances where the domain is registered but not pointed anywhere).
Adding an A Record in cPanel
So If its there click on EDIT for the main A record, and change that IP address to the dedicated IP for your Multisite install.
If you are setting up A record for the first time then the type is “A” A Record. Then rather than entering a CNAME it will be the Address field, which is for the IP Address.
Yeah there are, you can also use Addon Domains and Parked Domains. They must point to the root of your multisite installation in order to function correctly.
This method also does not require a dedicated IP address.
However its not recommended you use this method for client websites as you will have to manually control their DNS. You would need to deal with MX Records if they wish to use email on that domain as well as other DNS requests.
This is a good method if you own them all though, its quick and easy!
Remember the domain root needs to be your multisite folder which is usually:
Addon Vs Parked
There really is not much difference. If you want an extra FTP account then use Addon domains. Really you shouldn’t be handing FTP accounts out due to security concerns, so there isn’t much need for this. And all FTP is usually done through your main FTP account.
Parked domains simply does as it states, it parks the domain onto a folder or redirect. Again this will vary from control control panel to control panel.
Parking a domain in cPanel
Creating an Addon Domain in cPanel
I get a 404 or some sort of server page, why?
Chances are your not using a dedicated IP or you have some issue with your htaccess file, please check those out first.
You may also wish to double check your permalinks and re-save them again.
Why do I need a dedicated IP?
You only need a dedicated IP address when using A Records to map your domain. This is because the domain being mapped needs to land on your WordPress multisite install and if it doesn’t then our plugin and WordPress won’t know when to map it.
On shared hosting platforms, usually the sites IP address will fall on a landing page which is not related to your account in anyway.
Doesn’t this need to go into the MU folder?
Nope, you no longer need to do that!
If however you are running an older version pre-3.0.7 then you must remove those older plugin files before using the new version!
When I add a domain, the page just refreshes and nothing happens?
Chances are when you edited your wp-config.php to enter the sunrise information, you put it to far down. Check through these docs again and make the appropriate adjustments.
Nope that wasn’t it, the page still refreshes and nothing happens so what now sherlock?
Another cause of this is the sunrise.php file, if you are running our Multi Domain plugin:
Then you will find in the plugin folder an alternate sunrise file dm_sunrise.php you need to use this file.
First rename it to sunrise.php and then upload it just like the original sunrise.php file in these instructions and that should fix you up! :-)
Erm… Cookie syncing does not work?
Cookie syncing is where you log into your mappeddomain.com and subsite.domain.com at the same time. Its this process that allows you to administer and view a mapped domain website whilst being logged in.
Its not a process to log you into all mapped domains on a network install.
Anything else I need to do?
If you installed your WordPress installation as a subdirectory, then nahh nothing else there.
If you installed your WordPress installation as a subdomain version, then we assume here that you’ve already set up your Wild Card? Don’t worry if not, checkout WordPress for a walk through:
After adding a domain I can not add a second domain. Is this correct?
If you haven’t added anything to your wp-config.php then it’s limited to a single domain per site. If you add the following somewhere in it then you will be able to use multiple domains per site.
Arghhhhhh, I’m still stuck, what can I do?
Open a support ticket and one of our awesome support chimps will be right along to help you.
Obviously in peak and seasonal times, responses times will vary, but don’t worry, we will help you work through the issue.
WPMU DEV Community
On behalf of the Incsub and WPMU Dev we would like to thank you for being an awesome member of our community!