Multisite Networks

A network fits sites that are run by one organization, share code, and are administered centrally, while their content stays separate. It does not make sites share content: a post on Lumen Kids is not visible to Lumen Noir unless code copies or queries it across sites.

The shared code is both the benefit and the risk. One plugin update reaches every site at once, a fatal error in a network-activated plugin takes down every site, and every site shares one PHP process pool and one database server. Many plugins are written and tested for single sites only; check each one for Multisite support before relying on it. Lumen Press accepts these trade-offs because both imprints use the same lumen-catalog plugin and the lumen theme family, and the same editors work on all three sites.

Every request goes through wp-includes/ms-settings.php, which reads the host name and path, looks them up in the wp_blogs table, and sets the current network and site before plugins load. From then on $wpdb->prefix points at that site’s tables (wp_ for the main site, wp_2_ for site 2) while users and network data stay in shared tables.

The vocabulary in the database is historical and inverted. In code and tables a site (wp_site, get_current_network_id()) is the network and a blog (wp_blogs, blog_id) is a site; the admin screens use network and site. The main site is the site with BLOG_ID_CURRENT_SITE, normally blog ID 1, which keeps the base table prefix and the base uploads folder.

Each network chooses one addressing scheme when it is created. Individual sites can still be moved to other domains later through domain mapping, described below.

Neither scheme works when the WordPress address uses a port other than 80 or 443. For local work, use a name such as lumenpress.test mapped to 127.0.0.1 in the hosts file rather than localhost:8080.

The one-month rule comes from allow_subdirectory_install(), which looks for a published post older than a month in wp_posts; the allow_subdirectory_install filter and the ALLOW_SUBDIRECTORY_INSTALL constant override it. The conversion also replaces the main site’s permalink structure: a site converted with /%postname%/ came out with /blog/%year%/%monthnum%/%day%/%postname%/, and setting /%postname%/ again stored /blog/%postname%/, so /hello-world/ answered 404 and /blog/hello-world/ 200. Plan redirects for existing post URLs before converting a site that already has traffic.

Switching an existing network between the two schemes later means changing SUBDOMAIN_INSTALL, every row of wp_blogs, the home and siteurl options of each site, URLs in content, the rewrite rules, DNS and certificates. It is possible but rarely worth it; choose carefully at the start. Lumen Press uses subdirectories for the imprints (one certificate, one DNS record) and maps Lumen Noir to its own domain.

Sites are created on Network Admin → Sites → Add Site (address, title, language, admin email) or with WP-CLI. The --slug becomes the path on a subdirectory network and the subdomain on a subdomain network:

Source: WP-CLI Commands: wp site create

The commands reported Site 2 created: https://lumenpress.test/kids/ and Site 3 created: https://lumenpress.test/noir/, and wp site list showed blog IDs 1, 2 and 3.

Every WP-CLI command that should act on one site takes --url, for example wp option get blogname --url=lumenpress.test/kids/. Without it, commands act on the main site. A reserved slug is refused with Error: The following words are reserved and cannot be used as blog names: page, comments, blog, files, feed, wp-admin, wp-content, wp-includes, wp-json, embed. The dashboard also enforces lowercase letters and digits for site names; WP-CLI accepted --slug=Noir_2, so scripts should validate slugs themselves.

A new site starts with the default theme, a "Hello world!" post, a sample page and the content defined under New Site Settings. Its uploads go to wp-content/uploads/sites/2/ (wp_upload_dir() returned that basedir for Lumen Kids).

Super admins reach Network Admin from My Sites in the toolbar (/wp-admin/network/). On 7.1.3 its menu has Dashboard (with Updates for the whole network and Upgrade Network, which runs database upgrades on every site like wp core update-db --network), Sites (All Sites, Add Site), Users, Themes and Plugins (each with its installer and file editor), and Settings (Network Settings, and Network Setup, which shows the configuration lines again).

Sites → Edit has four tabs: Info (the Site Address (URL), registration dates and the Public, Archived, Spam, Deleted and Mature flags), Users (add or remove users and set their role on that site), Themes (enable extra themes for that site only) and Settings (every option of the site, as a raw form). Archiving a site keeps it but answers visitors with HTTP 410 and This site has been archived or suspended.; WP-CLI has matching commands (wp site archive 3, wp site unarchive 3, wp site spam, wp site deactivate, wp site delete).

Settings → Network Settings holds network options stored in wp_sitemeta, readable with wp site option get:

On the test network upload_space_check_disabled was 1, so the 100 MB quota per site is not enforced until the box is ticked. fileupload_maxk limits single files on top of PHP’s upload_max_filesize.

A super admin has every capability on every site, including the network-only ones (manage_network, manage_sites, manage_network_users, manage_network_plugins, manage_network_themes, manage_network_options). The list of super admin logins is the site_admins network option, not a role:

Source: WP-CLI Commands: wp super-admin

On the test network the list held only admin, stored as ["admin"] in wp_sitemeta.

A site Administrator on a network is a smaller role than on a single site. Checked with user_can() for a user who is Administrator of Lumen Kids only:

Because a super admin can run code on every site, keep the list short, require two-factor authentication for those accounts (see Security Hardening), and give day-to-day editors per-site roles instead. Capability checks in plugin code are covered in Multisite Development.

Only super admins install, update and delete plugins and themes; the files are shared by every site. There are three ways for plugin code to run:

Lumen Press network-activates its catalogue plugin, because all three sites publish books, and lets Lumen Noir alone use an extra plugin:

Source: WP-CLI Commands: wp plugin activate

The list reported lumen-catalog as active-network and akismet as active on Lumen Noir only; the network option active_sitewide_plugins then held lumen-catalog/lumen-catalog.php with its activation timestamp.

Network activation runs the plugin’s activation hook once, in the context of the current site, not on every site. A plugin that creates tables or roles on activation must loop over sites or create them lazily; that code is shown in Multisite Development.

Themes are not activated network-wide; they are network-enabled, which only makes them available. Each site still picks one theme on its own Appearance → Themes screen, which lists only enabled themes. The default theme is enabled when the network is created; others are enabled for the whole network or for one site in Sites → Edit → Themes:

Source: WP-CLI Commands: wp theme enable

The test network printed {"twentytwentyfive":true,"twentytwentyfour":true} for allowedthemes after enabling Twenty Twenty-Four, with the default theme already present. wp theme activate does not check that list: it switched Lumen Noir to a theme that was not enabled. Editing a theme’s files changes every site using it, which is why a child theme (lumen-child) per imprint is safer than editing lumen in place.

There is one wp_users table for the network. A user who is a member of a site has a role stored in wp_usermeta under that site’s prefix (wp_capabilities for the main site, wp_2_capabilities for Lumen Kids), plus primary_blog and source_domain. Being logged in is network-wide (subject to cookie scope), but being a member is per site: a logged-in user without a role on Lumen Noir who opened its dashboard got HTTP 403 and a page saying they do not currently have privileges on that site, with links to the dashboards of the sites they do belong to.

The commands below give maria.editor (ID 2), an account created on the single site before it was converted to a network, the Editor role on Lumen Kids and then take it away again:

Source: WP-CLI Commands: wp user set-role

set-role on a site where the user has no role adds them to it (Success: Added maria.editor (2) to https://lumenpress.test/kids as editor.); remove-role removes them from the site.

Removing a user from a site keeps the account and their posts; deleting a user is a network action (Network Admin → Users), which asks who should receive their content on each site. Marking a user as spam sets the spam column that wp_users gains on Multisite and blocks their login on every site.

New user names on a network are stricter than on a single site: wpmu_validate_user_signup() allows only lowercase letters and digits, at least four characters. wp user create maria.editor ... fails with Error: Usernames can only contain lowercase letters (a-z) and numbers. Accounts created before the conversion, such as Lumen Press’s maria.editor and tom.author, keep their names and work normally. New staff on a network need names such as mariaeditor, or a login by email address.

Allow new registrations (registration) takes four values:

With all, wp-signup.php on the test network offered a Username and Email Address and the choice Gimme a site! or Just a username, please. Sign-ups wait in wp_signups until the emailed link to wp-activate.php is followed; wp_registration_log records who created which site from which IP address. Per-site Anyone can register settings do not apply on a network: Settings → General hides the Membership field when Multisite is on.

Open registration on a network attracts automated sign-ups that create spam sites as well as spam accounts. Keep it at none unless the network exists to host other people’s sites, and if it must be open:

Lumen Press keeps none: staff are added by super admins.

Since WordPress 4.5, a site can use any domain without a plugin. The site’s domain and path are the domain and path columns of its wp_blogs row, and WordPress looks requests up there. The steps are:

For Lumen Noir, saving https://lumennoir.test on that screen updated the wp_blogs row and the site’s home and siteurl options together, and the new domain served the site:

Source: Advanced Administration Handbook: WordPress Multisite Domain Mapping

WP-CLI 2.12 has no command that changes a site’s domain. Updating only the options with wp option update home and siteurl is not enough: the test site then redirected lumennoir.test to the main site (no wp_blogs row matched) and answered 404 at its old path. A script must update the row with wp_update_site() (5.1+) and the two options:

Source: Code Reference: wp_update_site(), WP-CLI Commands: wp option update

After the first command, --url uses the new domain, because WP-CLI finds the site the same way as a web request. Remove --dry-run from the last command once its report looks right; it rewrites links in that site’s content and leaves guid alone.

The old address does not redirect to the new one. On the subdomain test network, noir.lumenpress.test went to the sign-up page after mapping; on the subdirectory network, /noir/ returned 404. Add a permanent redirect in the web server for every old address that has been published.

A subdirectory network needs only the main host’s DNS record and certificate. A subdomain network needs a record for every site; a wildcard record lets new sites work without DNS changes:

Source: Advanced Administration Handbook: Before You Create A Network (domain-based networks)

A certificate for *.lumenpress.example covers one level only (kids.lumenpress.example, not www.kids.lumenpress.example) and not the bare lumenpress.example, so request both names. Let’s Encrypt issues wildcard certificates only through the DNS-01 challenge, which needs API access to the DNS provider; HTTP-01 cannot be used for them. Each mapped domain needs its own certificate (served with SNI on the same IP address). The web server must also accept the wildcard: ServerAlias *.lumenpress.example in Apache, server_name *.lumenpress.example in nginx. Lumen Press avoids all of this by using subdirectories plus one mapped domain with its own certificate.

A backup of a network is a backup of the whole database and the whole wp-content directory, including uploads/sites/. wp db export without options exports every table registered on the network; a single site’s tables can be exported for a partial restore:

Source: WP-CLI Commands: wp db export

On the test network the first file held 38 CREATE TABLE statements and the second 10. A single site’s export does not include its users (they are in the global tables) or its wp_blogs row; restore it only into the same network. Retention, off-site copies and restore drills are on Backups and Disaster Recovery.

Moving a network to a new domain (for example from staging lumenpress.test to production lumenpress.example) touches DOMAIN_CURRENT_SITE, the wp_site and wp_blogs rows, and every site’s URLs. Run a dry run first:

Source: WP-CLI Commands: wp search-replace

Source: WP-CLI Commands: wp search-replace

--network is what includes the tables of every site and the network tables. Search for the bare domain, not //lumenpress.test: the domain columns of wp_blogs and wp_site hold names without a scheme, and a pattern with slashes skips them, leaving a network that cannot find its own sites. Without --skip-columns=user_email the run also rewrites staff email addresses that use the old domain. When wp search-replace itself fails because the network cannot boot under the old URL, pass --url= with the old main address. The general migration workflow is on Importing, Exporting and Migrating.

The handbook’s network debugging guide also lists the SQL to recreate missing wp_site, wp_blogs and site_admins rows by hand.

Multisite Development (switch_to_blog(), network options, activation across sites, WP_Site_Query), Database Schema, wp-config.php Reference, Web Servers: Apache and nginx, Users, Roles and Profiles, Security Hardening, Scaling and High Availability, Debugging, Site Health and Troubleshooting and WP-CLI. Network activation and per-site uninstall of WooCommerce extensions are covered in Extension Development.