WordPress Network is a feature allowing you to manage multiple WordPress installations within the same code base

• all sites share PHP codebase and plug-ins
• all sites reside within the same database
• sites have different settings
• sites can have centralized admin users through the primary site
• sites can have different plug-ins enabled and different plug-in settings

This tutorial was written for Ubuntu/Debian server (not shared hosting). It was based on migrating very old WordPress installation (5+ years) to the current version and then turning on the multi-site feature.

Note: All plug-ins might not be multisite compatible. You will find it out hard way.

Note: WordPress is recommended to be installed at a virtual host root for Network feature to work well. Also it makes sense to have the WordPress running in its final domain name, as domain name will be written in all over the settings (in the case you prepare it on the test server first). Use /etc/hosts trick to spoof the domain name of the test server if needed.

These instructions are for WordPress 3.2. They are baed on the reference manul, with my own insight and troubles mixed in. This tutorial is targeted for professionals with advanced UNIX experience and lacks hand-holding.

1. Disable plug-ins

Disable all plug-ins (can be re-enabled later). Otherwise Network feature cannot be turned on.

2.  Enabling Network feature installation

Add line:

define('WP_ALLOW_MULTISITE', true);

to your wp-config.php.

3. Back-up the existing site

Copy PHP files to a back-up folder

cp -r your-site-folder your-site-folder-backup

Dump a copy of database

mysqldump -uDBUSER -p DBNAME > wordpress.sql

See that dump was succesful

ls -lh wordpress.sql
-rw-r--r-- 1 root root 7.0M Aug 22 05:34 wordpress.sql

4. Prepare file-system

You need to create blogs.dir folder which will contain content for each WordPressinstance.

# Ubuntu / Debian uses www-data user for Apache 2
cd wp-content/
mkdir blogs.dir
chown -R www-data:www-data blogs.dir/

5. Turn on Network feature

You should now see Network Tools in Tools menu in Dashboard.

It will display you a bunch of changes you need to do .htaccess and wp-config.php files which are domain name specific (ugly: I am not very keen to have something domain name specific in config files, as it makes moving the site much more difficult, but as WordPress/PHP does not do proper virtual hosting using Virtual Host Base domain name rewrite pattern)

Make sure you put wp-config.php changes in the middle of the file before  wp-settings.php line or you will be seriously screwed up.

Sanitized wp-login.php changes look somewhat like:

define('DB_COLLATE', ...)
define( 'AUTH_KEY', 'x' );
define( 'SECURE_AUTH_KEY', 'x' );
define( 'LOGGED_IN_KEY', 'x' );
define( 'NONCE_KEY', 'x' );
define( 'AUTH_SALT', 'x' );
define( 'SECURE_AUTH_SALT', 'x' );
define( 'LOGGED_IN_SALT', 'x' );
define( 'NONCE_SALT', 'x' );
...
// snip
...

define('WP_ALLOW_MULTISITE', true);

// These lines MUST come after wp-settings.php include
define( 'SUBDOMAIN_INSTALL', false );
$base = '/';
define( 'DOMAIN_CURRENT_SITE', 'site.com' );
define( 'PATH_CURRENT_SITE', '/' );
define( 'SITE_ID_CURRENT_SITE', 1 );
define( 'BLOG_ID_CURRENT_SITE', 1 );

WordPress failed to detect DOMAIN_CURRENT_SITE for me currently, so I had to fix it manually.

6. Relogin

Log-out and log in again

7. Fail #1: You do not have sufficient permissions to access this page

Well… it didn’t go well. The first login for me produced an error page:

You do not have sufficient permissions to access this page.

To honor PHP programming practices there is no log information or any hint what actually went wrong. So you can only guess.

It turns out wp-config.php edit can fail if you add change after wp-settings.php include (PHP include mechanism and define() is quite hacky and WordPress cannot warn you if you fail).

If you happened to do this then I suggest you roll back the database and files in this point and start from zero.

8. Fail #2: Error establishing database connection

After fixing wp-config.php settings order I ge the white screen of death

Error establishing database connection

This comes up when I set

define( 'MULTISITE', true );

Looks like the internet is full of posts and less and less uselful answers about what is going on. Also, WordPress Codex etc. material does not provide very helpful material what should happen when MULTISITE is turned on, when tables are migrated and so on. The only way to solve this is seems to dive head first to WordPress PHP. Argh. Well… if I cannot fix it, then who can`?

So I had to modify wp_functions.php to give me more meaningful trace back for the white screen of death:

function dead_db() {   
        global $wpdb;

        throw new Exception("PHP is pile of shit");

This way you can actually know where the error happens in the code.

Which leads to me functions.php is_blog_installed() where after adding in new die() statement I get:

Cannot find wp_users

Hmmm. I wonder why… Especially this comment is useful:

        // Loop over the WP tables.  If none exist, then scratch install is allowed.
        // If one or more exist, suggest table repair since we got here because the options
        // table could not be accessed.

So it thinks the blog is not installed, but still finds some tables and dies with useless “Error establish database connection” error.

More closely examination with print_r() shows that $alloptions variable used in is_blog_installed() is empty.

It tries to load options from a table called wp_2_options which hints that it is a multisite enabled table which has not yet been created. This is strange as we clearly say the site id is 1 in wp-config.php. So looks like WordPress think the site id is wrong.

Since there is no way to trace back where $wpdb array containing this bad is populated, the next grep goes with SITE_ID_CURRENT_SITE.

wpmu_current_site() seems to return correct id 1. False lead.

More careful examination of  print_r() $wpdb tells blog id is 2 (note: blog id differs from site id…).

Grepping again tells there exist $wpdb function called set_blog_id(). It seems to be called in a function called switch_to_blog(). However, putting exception there tells that it is never called.

Finally finally MySQL dump of wp_blogs table shows that it is damaged due to earlier run of multisite migration with bad config:

mysql> select * from wp_blogs;
+---------+---------+----------------------+--------------+---------------------+---------------------+--------+----------+--------+------+---------+---------+
| blog_id | site_id | domain               | path         | registered          | last_updated        | public | archived | mature | spam | deleted | lang_id |
+---------+---------+----------------------+--------------+---------------------+---------------------+--------+----------+--------+------+---------+---------+
|       1 |       1 | site1.fi             | /xxxx-wp/    | 2011-08-22 08:36:46 | 0000-00-00 00:00:00 |      1 | 0        |      0 |    0 |       0 |       0 |
|       2 |       1 | site2.com            | /            | 2011-08-22 10:47:51 | 0000-00-00 00:00:00 |      1 | 0        |      0 |    0 |       0 |       0 |
+---------+---------+----------------------+--------------+---------------------+---------------------+--------+----------+--------+------+---------+---------+
2 rows in set (0.00 sec)

Purge this table from bad data

delete from wp_blogs;

Also drop other multi-site config;

drop table wp_site;
drop table wp_sitemeta;

Now when you go to http://site.com/wp-admin/network.php it should be in the pristine state and you can create multi-site configuration from the scratch, in a working manner.

Make sure that Server name field show the correct value on the WordPress Network creation screen.

Press Install.

Re-enable multi-site in wp-config.php:

define( 'MULTISITE', true );

Well.. still failure. But this finally seemed to fix the site when we force the blog id (looks like it is incremental column which did not reset properly):

 update wp_blogs set blog_id=1 where blog_id=3;

Still it is looking for bad URL fix we can fix by forcing WordPress RELOCATE. RELOCATE setting in wp-config.php will update site URL in the database for the current wp-login.php page URL.

define('RELOCATE',true);

Now go to login page. I was finally able to login to migrated multisite instance.

Post-mortem: Error establishing database connection error message was misleading. The real error was along the lines “Multi-site configuration for site id X is broken.” However this is not very usual error and WordPress does not correctly check this error situation.

9. Relogin (now with success)

Now you should see Network Adminin your username name in the top right corner. Start adding those sites!

10. Fail #3: Not Found

So far so good. However, after creating a new site and trying to access the site through path (e.g. yoursite.com/subsite) it gives 404 Not Found. Lovely.

The error instantly hints that maybe something is from with Apache and .htaccess configuration.

So it seems – changes from WordPress Network installation didn’t end up correctly to .htaccess. Just to refresh the memory the correct .htaccess settings are:

# BEGIN WordPress
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]

# uploaded files
RewriteRule ^([_0-9a-zA-Z-]+/)?files/(.+) wp-includes/ms-files.php?file=$2 [L]

# add a trailing slash to /wp-admin
RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]

RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
RewriteRule  ^[_0-9a-zA-Z-]+/(wp-(content|admin|includes).*) $1 [L]
RewriteRule  ^[_0-9a-zA-Z-]+/(.*\.php)$ $1 [L]
RewriteRule . index.php [L]
# END WordPress

Even after fixing .htaccess it stills gives 404. Looks like .htaccess files were not properly enabled in the virtual host config /etc/apache2/sites-enabled directory. This fixed the problem:

<VirtualHost *>
    ServerName site.com

    <Directory /var/www/site>
    AllowOverride All
    </Directory>

</VirtualHost>

11. Fail #4: Error establishing database connection for new multi-site

Ok. This time we can already guess the problem. Blog ids and site ids don’t match somewhere.

MySQL command prompt reveals what we suspect:

mysql> select * from wp_blogs;
+---------+---------+-------------+------+---------------------+---------------------+--------+----------+--------+------+---------+---------+
| blog_id | site_id | domain      | path | registered          | last_updated        | public | archived | mature | spam | deleted | lang_id |
+---------+---------+-------------+------+---------------------+---------------------+--------+----------+--------+------+---------+---------+
|       1 |       1 | site.com    | /    | 2011-08-22 14:57:12 | 0000-00-00 00:00:00 |      1 | 0        |      0 |    0 |       0 |       0 |
|       4 |       1 | site.com    | /de/ | 2011-08-22 15:10:34 | 0000-00-00 00:00:00 |      1 | 0        |      0 |    0 |       0 |       0 |
+---------+---------+-------------+------+---------------------+---------------------+--------+----------+--------+------+---------+---------+
2 rows in set (0.00 sec)

blog_id is currently having its own life.

Delete the new site (/de/) through WordPress dashboard.

When checking wp_blogs table more closely we notice that blog_id is auto-increment column:

describe wp_blogs;
+--------------+---------------+------+-----+---------------------+----------------+
| Field        | Type          | Null | Key | Default             | Extra          |
+--------------+---------------+------+-----+---------------------+----------------+
| blog_id      | bigint(20)    | NO   | PRI | NULL                | auto_increment |
| site_id      | bigint(20)    | NO   |     | 0                   |                |
| domain       | varchar(200)  | NO   | MUL |                     |                |
| path         | varchar(100)  | NO   |     |                     |                |
| registered   | datetime      | NO   |     | 0000-00-00 00:00:00 |                |
| last_updated | datetime      | NO   |     | 0000-00-00 00:00:00 |                |
| public       | tinyint(2)    | NO   |     | 1                   |                |
| archived     | enum('0','1') | NO   |     | 0                   |                |
| mature       | tinyint(2)    | NO   |     | 0                   |                |
| spam         | tinyint(2)    | NO   |     | 0                   |                |
| deleted      | tinyint(2)    | NO   |     | 0                   |                |
| lang_id      | int(11)       | NO   | MUL | 0                   |                |
+--------------+---------------+------+-----+---------------------+----------------+
12 rows in set (0.00 sec)

We can reset the counter via MySQL command:

ALTER TABLE wp_blogs AUTO_INCREMENT=2

12. Migrating multi-sites to new domain name

As now we are familiar with wp_site and wp_blogs tables we know how to manipulate these tables if we want to migrate our test site to the production domain name:

update wp_site set domain="new.site.com";
update wp_blogs set domain="new.site.com";

Change value of DOMAIN_CURRENT_SITE in wp-config.php

define( 'DOMAIN_CURRENT_SITE', 'new.site.com' );

After this you can access the primary site at new.site.com. Then you can access each subsite settings and toggle on Update siteurl and home. Save site settings to force new site URL for the subsite.

Note: It was still hiding the old URL value for the primary site somewhere and I didn’t track down it yet.

13. More info

• The official WordPress Network tutorial
• Error establishing database connection

 Subscribe to RSS feed Follow me on Twitter Follow me on Facebook Follow me Google+