1. Getting Started

The WPMU DEV migration tool is a server-to-server via FTP process that is much more robust than any PHP-driven, i.e., plugin migration.

For starters, the migration tool is far less susceptible to timeout issues than PHP. Additionally, it handles all file transfers and redefines URLs in one smooth process that doesn’t involve programs or utilities that many users seldom use. As long as the source server isn’t afflicted with FTP issues, it would take the Mario Andretti of web admins to perform a faster, safer migration.

Prepare to Migrate

First, as always, backup your site. Do this at your original host. It’s unlikely that the migration process will harm your site, especially when using the migration tool, but backing up is always step one when making major changes to your site.

You will need your current FTP username and password. The migration tool connects WPMU DEV servers to your host’s servers using the same FTP credentials you would use to connect via FTP. If you don’t know them, they should be displayed on a screen you can access from your dashboard or control panel at your original host. If you cannot locate them, contact the host’s support team for assistance.

Commence Migration

From the Hub 2.0 site overview screen, click the Add a website (+) icon.

From the Let’s get started! screen, click Migrate Existing Site.

The dropdown menu on the next screen will reveal a list of all the sites currently connected to The Hub. If the site you wish to migrate does not appear in the list, then it is not connected, and you should click the Please add it to your Hub first link, and follow the instructions provided. Once the site is connected, select it from the dropdown menu and click the arrow to proceed.

Your site’s files will reside on a temporary domain until you make DNS record changes. Learn more about pointing your site to a custom domain name in our DNS documentation. Enter your preferred temporary domain name in the field provided, and click the arrow to proceed.

Select the geographic area where you wish your site to be hosted.

WPMU DEV servers need to log in to your site using the same FTP username and password you use when you manage files with an FTP client. If you don’t know the credentials, you should find them in your site’s dashboard or control panel at your current host. If they do not exist, create them, paste them into the fields provided, and click Start Migration.

Required FTP/SFTP credentials:

• Host name
• Port
• Username
• Password

Once they access your site, WMPU DEV servers will attempt to locate your site’s files, and most of the time, they have no problem doing so. Occasionally, however, the path to those files contains an unknown directory that our servers cannot resolve, and the migration will fail. If you know the FTP path to your site files, you can insert it in the WordPress install path field highlighted below if the automated system cannot locate the files.

If you don’t know your FTP path, the simplest thing to do is ask your current host to provide it.

You can find it on your own by logging in to your site via FTP. Regardless of the FTP client you use, your path will be displayed on the screen similarly to how they appear in the image below.

Simply cut and paste the path–in this case /site/public_html/–into the WordPress install path field.

Do not include the domain name in the path but just the words and slashes as they appear in the placeholder text in the image above.

When ready, click Start Migration.

This screen allows users to monitor migration’s progress, although you can safely close the window and move on to other things without jeopardizing the migration. You will receive an email notification when the migration is complete or if it fails.

Following a successful migration, the temporary domain used in this migration is set as the primary domain for the migrated content and is viewable. Unless the original site has been disabled in some way, your content is viewable at both the original URL and the temporary one. In a moment, you will be instructed to update your DNS records and set your original domain as the primary domain, at which point your permanent domain is the only one visitors can access.

Before making those updates, however, we encourage you to visit the temporary domain to verify that the migration was successful. You can do so by clicking WP Admin option next to the temporary domain in The Hub site manager.

If you discover a problem with the site following migration, contact support, and our team will help you determine how best to proceed. If you are satisfied with the migration, then it’s time to edit your DNS records. See our WPMU DEV DNS Records documentation for guidance.

Manual migration occurs in two phases. The first phase involves exporting the database and files that make up your site into files that can be used in phase two, which involves importing those files to your new WPMU DEV Hosting environment.

Export the Database (.sql)

We’ll be using phpMyAdmin in this guide, but if your current host provides another database manager, don’t worry. Most database managers have similar interfaces, and you should have little trouble following the steps below.

Likewise, if your host provides a tool or other simple method to export your database to a .sql file, by all means, use that tool. Otherwise, follow the steps below.

First, create a folder on your local system into which you will export your site’s database and files. We’re calling ours “Migration.”

Navigate to phpMyAdmin and click on your database name from the left side of the screen.

When you see the database tables in the main screen click Export in the menu near the top.

On the next screen, leave everything as is (Quick and SQL) and click Go.

You should be prompted to save a .sql file. Name the file “my_database.sql” and save it to the local migration folder you created.

Naturally, you can name the file whatever you wish as long as it’s a .sql file, but to avoid confusion, it might be helpful if your file names matched the ones we’ll be referencing in this guide.

That takes care of creating a backup of the database. Now, we must conduct a similar but more lengthy operation for the site files.

Exporting Files

Again, if your current host provides a tool to archive your site, use it. If not, you’ll need to download and install one, such as Filezilla, WinSCP, Cyberduck, or anyone of the many available FTP clients. For this example, we are using the WPMU DEV File Manager tool located in the Hub.

Be aware that, depending on the tool being used, some effort may be required to ensure that all the necessary files are included. If you have any doubt, contact your host’s support team or our 24/7 live support to ensure all required files are included in the archive file.

If there are old files you’ve meant to delete—leftover plugin files, unused images, etc.—now would be a good time to make that happen by simply not including those files in the archive.

When you’re ready, navigate to your WordPress root directory, select all the files that appear in the window, right-click to select Create archive, and then ZIP archive.

Name the file “my_site.zip” or according to your own labeling preference, to avoid confusion.

Once the archive completes, the new .zip file will appear in your root directory. Right-click the file name, select Download and save the file to the same migration folder in which the database is saved.

A complete copy, aka a full backup, of your site is now saved on your local system.

The Import

You will need sFTP and/or SSH credentials to import your site. If you haven’t already created those credentials, follow the steps below. If you have, skip down to the Copy wp-config.php section.

Keep in mind that sFTP/SSH credentials provide access to the inner-workings of your site. Never share these credentials with anyone who doesn’t require that access.

Create sFTP and SSH Credentials

In the Hub, select the temporary domain you created for this migration to access the dashboard for that domain. Create an SFTP and SSH user, and keep the credentials handy because you will need them in a moment. If you are unsure about how to create these users, visit Creating SFTP/SSH Users for a comprehensive guide.

For the purposes of this migration, leave the Path Restriction field set to None.  Leave the Environment field set to Production.(Keep in mind that staging sites require their own credentials, which you don’t need for migration but will need later if you need to access the staging environment.)

Copy the old wp-config.php

Open your FTP client and, using the sFTP user you just created, connect to your WPMU DEV temporary domain. As shown in the image below, your temporary domain name is the Host, the protocol is sFTP (not FTP or SSH, yet), and the Port is 22.

Once connected, navigate to the directory site/public.html and locate, then download the wp-config.php file to your migration folder.

Once that is accomplished, minimize but don’t disconnect the FTP client, and open a command prompt or terminal (Mac).

Prepping the hosting environment

At the command/terminal prompt, log in to your WPMU DEV server by entering, ssh @.wpmudev.host, and when prompted, enter your SSH password, as shown below.

Navigate to your new WordPress file system by entering, cd site/public_html/.

The public_html folder contains files that are created whenever a new instance of WordPress is installed. Deleting those files will ensure that your existing file structure remains the same, for the time being.

Type the command rm-rf * to delete all the files in public_html.

Minimize the command/terminal prompt if you wish, but don’t close it. Move back to your FTP client, and you will see that your site/public_html folder is empty and ready to receive the database and files saved in your migration folder.

Importing the Database

The import process is largely the same for a single site and Multisite installation unless the site’s domain has changed, in which case we’ve outlined both methods below.

First, return to the wp cli command/terminal prompt and enter the command wp db reset --yes to reset and empty the existing WordPress database.

Next, import the database with the wp db import my_database.sql command.

When the import is complete, clear the site’s object cache by entering the command wp cache flush.

Changing domain names

If the site’s domain name is changing as part of this migration, the names of the database tables associated with the old domain name must be updated. There are several, so you are going to need to use the wp search-replace command and the syntax of that command is different for single and Multisite installations:

New single site domain

First, replace all the instances of the old URL with the new temporary one you created with the command: wp search-replace oldurl.com newurl.wpmudev.host --skip-themes --skip-plugins

Next, change the email addresses associated with a site with the command: wp search-replace @newurl.wpmudev.host @oldurl.com --skip themes --skip-plugins

New Multisite domain

First, replace all the instances of the old URL with the new temporary one you created with the command: wp search-replace oldurl.com newurl.wpmudev.host --url=oldurl.com --network --skip-themes --skip-plugins

Next, change the email addresses associated with a site with the command: wp search-replace @newurl.wpmudev.host @oldurl.com --url=newurl.wpmudev.host --network --skip-themes --skip-plugins

Upload the my_database.sql and my_site.zip to your environment.

Extracting the .zip

Return to the command/terminal prompt, which should still be logged in to the site/public_html folder, and enter the command unzip my_site.zip. Don’t forget the period at the end of the command.

Your files will scroll down the screen as they inflate (extract) in your hosting environment.

Locate and Add Database Credentials

The final step is to update the credentials your sites need to access their respective databases. To do that, simply reset the wp-config file, which renews the correct database credentials or creates a new config and credentials if none exists. This can be done quickly using the WP-Config tool in the Hub. For more information on resetting the wp-config file, refer to the Reset wp-config document.

As a WPMU DEV member, you can also request that we manually migrate your site in case the above options don’t work for you. We can migrate either directly from the server where your existing site is currently hosted, or by using a full and complete backup of your existing site that you provide.

To get your migration done by our staff, you’d need to provide the following required information for either method to our live chat support superheroes.

They will then create the needed support ticket for you, and our hosting support techs will get the migration done. You’ll be notified in your support ticket once the migration is finished.

Info required for manual migration

From server

1. Admin login credentials to your existing WordPress site (if Multisite please provide Super Admin details):
   • Admin Username
   • Admin Password
   • Login URL
2. FTP credentials to your existing WordPress site:
   • Hostname
   • Username
   • Password
   • Port
   • Key-File (and password) if needed
3. Server admin credentials to your existing WordPress site (cPanel, Plesk or equivalent at your current host):
   • Username
   • Password
   • Login URL
4. Destination Environment
   • WPMU DEV Hosting temporary *.wpmudev.host URL (can be an existing WPMU DEV hosted site you wish to overwrite, or a brand new one you create before requesting the migration)

From backup

1. A full backup of your existing WordPress site (.zip, .tar.gz etc)
   • Must include all site files and export of your database (.sql file)
2. Destination Environment
   • WPMU DEV Hosting temporary *.wpmudev.host URL (can be an existing WPMU DEV hosted site you wish to overwrite, or a brand new one you create before requesting the migration)

Supported Migrations & Conversions

It’s important to note that some types of migrations are out-of-scope and cannot be handled by our support or hosting staff. Following are the types of manual migrations/conversions that we can and cannot do for you.

1. Supported migrations
   • Yes – If Single site -> Single site
   • Yes – If Multisite -> Multisite
2. Supported conversions
   • Yes – If Single site -> Multisite
   • Yes – If Subsite -> Single site (you should expect to need to perform some cleanup in the converted site, and there may be configuration issues for some plugins due to conversion)
   • Depends – If Multisite -> Single site (supported only if there’s just a main site, without subsites)
   • Depends – If Subdomain -> Subdirectory (supported only if there’s just a main site, without subsites)
   • Depends – If Subdirectory -> Subdomain (supported only if there’s just a main site, without subsites)
3. Not supported – Out of scope
   • No – If Single -> Subsite (3rd party developer required for this type of migration)
   • No – If Subsite -> Subsite (3rd party developer required for this type of migration)

Are there discount rates available for bulk hosting with WPMU DEV dedicated managed WordPress hosting? Yes, WPMU DEV has discount rates available for agencies or users with 20+ websites.

To learn more about bulk pricing, contact support, or start a live chat to discuss discount options.

Hosting Discounts Rates:

• Are for users with more than 20 sites
• Are based on volume (the more sites you have on your account, the better the rate we can offer.)

Multisite admins can adjust both the file size and file type limits in their Network Settings, located here: Dashboard > Network Admin > Settings > Network Settings.

Scroll down to the Upload Settings section, where you will find the Upload file type and Max Upload File Size fields.

Adding/Removing File Types in Multisite

In the Upload file types field, enter the file extensions of the file types you want to add, separating the extensions with a single space. Delete the extensions of file types you do not want to be uploaded.

Modifying the File Size Upload Limit in Multisite

In the Max Upload File Size field, enter a size, in kilobytes, up to 12800kb (128mb) to set the max size for files uploaded to this network.

Click Save Changes, and that’s all there is to it. The new file size limit will apply to every site within this network.

If you’ve seen the “Sorry, this file type is not permitted for security reasons” error message; you’ve tried to upload a file type that is not on your site’s upload allowed list or has failed a WordPress security validation test.

Adding/Removing File Types in Standard Installations

We’re going to show you how the plugin WP Extra File Types can resolve either issue. The first thing to do is install and activate the plugin.

While we’re at it, we will show you how to use this plugin to identify why a file might trigger a security validation error, information that will be helpful if a particular file type or a particular user experiences ongoing upload issues.

Get WP Extra File Types

Once you’ve installed the plugin, you’ll find a new option, Extra File Types, in your site’s Settings tab, located here: Dashboard > Settings > Extra File Types.

Click Extra File Types UI, and you will see a list of hundreds of file types from which to choose.

You will also see two checkbox options, shown below. Do not select either of these boxes yet. Selective use of these options can help identify why a file triggered the upload error.

Select the file type(s) you wish to add to the allowed list and then scroll to the bottom of the UI to click Save Changes.

Try to upload the problem file again, and if the upload succeeds, great! This means the file was simply not on the allowed list, and now it is. You and your users can now upload that file type as needed.

If the file triggers a validation error again, return to the WP Extra File Types UI, and select the Check only file extensions option shown below. Leave Skip WordPress checks unchecked, and click Save Changes. If the file is failing WordPress’s MIME type validation, this option will bypass that check without disabling other security measures.

Try to upload the problem file again, and if the upload succeeds, great! This means there was an issue with the file’s MIME type. Otherwise, the file was deemed safe to upload.

If the file triggers a validation error with Check only file extensions enabled, it’s time to consider whether you are certain the file is valid and not harmful. If you are uncertain, we recommend not uploading the file.

If you are certain the file is valid and not harmful, return to the WP Extra File Types UI. Uncheck the Check only file extensions option, and check the Skip WordPress checks option. Save your changes.

WARNING: Selecting this option will disable all WordPress upload security measures, and should only be used to upload files you are certain are not harmful. Leaving this option enabled allows users to upload any file type to your site, including potentially harmful files. You should disable this option when you are not actively troubleshooting an upload issue.

Try to upload the problem file again. If the upload fails with WordPress checks disabled, it is likely that the issue has nothing to do with the file type, and you should contact support for help troubleshooting the problem.

Adding Custom File Types in Standard Installations

You also can use WP Extra File Types to add file types not included with the plugin’s preset list. To do this, scroll to the bottom of the UI where you will find the Add your custom file types panel. Click the plus sign (+) to open the interface.

This will open up a table of fields where you must specify a file format by completing the Description, File Extension, and MIME Type fields. The Internet Assigned Numbers Authority (IANA) is responsible for all official MIME types, and you can find the information required for these fields at their Media Types page. Click Save Changes before returning to the media uploader.

Install the Increase Maximum Upload File Size plugin to make this task as easy as it can be.

Once the plugin is activated, Increase Maximum Upload File Size will appear as a new option near the bottom of your Admin Menu. Click the link to open the plugin.

The plugin contains a single dropdown menu. When you open the UI for the first time, it will display your current max upload file size.

Click the dropdown menu to view the menu of various upload size limits. Setting a file size larger than 128mb will not override the 128mb max upload limit. Select the desired upload limit and click Save Changes.

Once a limit has been set, the plugin displays both the WPMU DEV Managed Hosting default limit of 128mb and the lower limit established by the plugin.

Here are the error pages that can be customized to suit your needs:

Client error pages

401.html – Displays if the site has password protection enabled and the HTTP Auth form is dismissed by the user.

402.html – Displays if the site is suspended due to required payment on your account.

404.html – Displays when the URL or page requested by the user cannot be found.

410.html – Displays if the requested page has been deleted permanently.

Note that the 403 error page that displays if a connection is forbidden, possibly via a WAF rule, cannot be customized as it is built into nginx.

Server error pages

500.html – Displays if there is an internal server error.

502.html – Displays if your server gets an invalid response from another web server.

503.html – Displays if the server is currently unable to handle your request due to scheduled maintenance or a temporary overload.

504.html – Displays if the server timed-out handling your request due to a temporary overload or a long-running script.

To create a custom page for any of the above errors, create a .html file with the error number as the filename, with any content you wish inside. Then upload it to the root of your WordPress install.

For example, to create a custom error page in the unlikely case something goes wrong on your server and you get the dreaded “500 internal server error”, you’d create a file called 500.html

Add any custom HTML content you like to your file, and upload. You can use the Manage Files utility from your Hub > Tools screen to create and add content to the file, or edit on your computer and upload via the File Manager or FTP.

Here’s an example of the basic HTML you’d want to have in any custom error page:

Your custom pages can be as simple or as creative as you like, and branded however you need. If you need some inspiration, have a look at these pages for some great examples:
https://uicookies.com/500-error-page-templates/
https://freefrontend.com/html-css-404-page-templates/

Our White Label services allow you to remove all WPMU DEV branding so that you can use your own branding or even your client’s branding. This is largely offered as a tool through our WPMU DEV Dashboard Plugin. For a guide to rebranding with the WPMU DEV Dashboard Plugin, read our White Label Plugins document.

The process of white labeling your site is also closely linked to our Branda plugin. Branda simplifies white label branding, maintenance and much more. Read our WPMU DEV documents on Branda to learn more about the plugin’s capabilities.

And if you’re using our Hub Client plugin to offer all the amazing site management tools of our Hub to your clients, you’ll want to review the Hub Client documentation as well.