Configuring Virtual Hosts Site URLs

A virtual host connects a domain name (e.g., www.helloworld.com) to a site. This can be a full domain or a subdomain (e.g., developers.helloworld.com). You can use this to host many websites as separate sites on one Liferay DXP server.

With your provider, set the DNS name to point to your Liferay DXP instance’s IP address. You can refer to a guide from a common provider on how to assign a domain as an example.
Inside Liferay DXP, open the Site Menu (), expand Configuration, and go to Site Settings → Site Configuration → Site URL.
Enter the desired domain or subdomain in the Virtual Host field (e.g., www.helloworld.com, developers.helloworld.com).

Important

A domain can only be applied to a single site. You can’t map a single domain to multiple sites.
Click Save.

Your site is now accessible using the configured domain. By default, it also remains reachable through the instance’s other domains, including other sites’ virtual hosts. To restrict every site to its own domain, see Configuring Virtual Host Restrictions.

Assigning Languages to Virtual Hosts

If your site is available in multiple languages and each language has its own domain, you can map each domain to a specific language. Liferay uses these mappings when generating alternate URLs for multilingual SEO (see Alternate URLs and Localized Virtual Hosts).

Open the Site Menu (), expand Configuration, and go to Site Settings → Site Configuration → Site URL.
Click Add () to add a new virtual host row.
Enter the domain for the language in the Virtual Host field (for example, www.holamundo.com).

Note

The Language drop-down shows only languages configured for the site. If no language is specified, the site’s default language is used.
Select the language from the Language drop-down (for example, Spanish (Spain)).
Repeat for each additional language.
Click Save.

After saving, the virtual host rows remain visible under Site URL, showing each domain and its assigned language.

Alternate URLs and Localized Virtual Hosts

When you assign a language to a virtual host, Liferay uses those localized virtual hosts when generating alternate URLs for multilingual SEO. Alternate URLs are the language-specific links (hreflang tags) that tell search engines which domain hosts each language variant of your site, helping them show the right language to the right audience.

For each locale (a language and regional variant, for example, Spanish (Spain)), Liferay resolves the alternate URL in this order:

If the page has a custom canonical URL (a page-specific preferred address for SEO) configured for that locale, it is used.
If a virtual host is configured for that locale, Liferay uses its domain.
If no localized virtual host exists for the locale, Liferay uses the site’s default virtual host.

For example, if your site’s default virtual host is www.example.com and you’ve mapped de.example.com to German, alternate URLs for German pages use de.example.com. Locales without a dedicated virtual host fall back to www.example.com.

Configuring Virtual Host Restrictions

Liferay DXP 2026.Q3+

Mapping a domain to a site doesn’t stop other domains from reaching it. By default, every site is also reachable through every other domain in the instance. Adding the site’s friendly URL path (for example, /web/hello-world) to any of those domains loads the site. Strict Virtual Host Mode restricts a site with a virtual host to that virtual host alone, and requests for that site through any other domain return a Not Found (404) error.

Three rules determine which sites are restricted:

A site without a virtual host of its own is never restricted: it remains reachable through every domain in the instance, including the instance’s own domain and other sites’ virtual hosts. This keeps a shared intranet site or the default site available everywhere.
Site hierarchy isn’t a factor. A child site is treated like any other site: it’s restricted when it has its own virtual host and unrestricted when it doesn’t, whatever its parent has.
Only a virtual host set on a site’s public pages restricts it, and setting one on private pages alone has no effect. See Site Settings UI Reference for both fields. Once a site is restricted, other domains reach neither its public nor its private pages.

For example, consider an instance whose own domain is www.example.com, holding two sites: Hello World, mapped to the virtual host www.helloworld.com, and Intranet, with no virtual host. With Strict Virtual Host Mode enabled, Hello World is reachable only at www.helloworld.com, and a request for www.example.com/web/hello-world returns 404. Intranet, having no virtual host of its own, remains reachable at both www.example.com/web/intranet and www.helloworld.com/web/intranet.

Liferay DXP doesn’t redirect a blocked request to the site’s own domain. The 404 page renders using the site that belongs to the requested domain, matching the domain the visitor typed. To customize it, see Using Utility Pages.

Enabling Strict Virtual Host Mode

Changing Virtual Host Restrictions requires instance administrator permissions. The settings apply to every site in a virtual instance. You configure them once per instance, leaving other instances unchanged. They also appear in System Settings as defaults for every virtual instance, and saving them in Instance Settings overrides those defaults for that instance alone. See Understanding Configuration Scope.

Important

Strict Virtual Host Mode takes effect as soon as you save it: any link or bookmark that reaches a restricted site through another domain returns a Not Found error. Review your existing links before enabling it. To keep the instance’s own domain working for every site, also check Allow Default Instance URL Bypass before saving.

Open the Global Menu () and navigate to Control Panel → Configuration → Instance Settings.
Select SEO under Platform and click Virtual Host Restrictions.
Check Strict Virtual Host Mode Enabled.
Click Save.

Each site with a virtual host on its public pages is now reachable only through that virtual host. To confirm, open one of those sites through its own virtual host. Then request the same site through the instance’s domain and the site’s friendly URL path. The first loads, and the second returns 404.

Allowing Default Instance URL Bypass

Configure Allow Default Instance URL Bypass to keep every site reachable through the default instance URL, the domain set for the whole instance in Instance Configuration. You can then reach every site through that domain for maintenance.

This setting has an effect only when Strict Virtual Host Mode is enabled. It reopens the instance’s own domain alone, not one site’s content through another site’s virtual host. The request’s domain must match the instance’s configured domain exactly. Reaching the server by IP address or by localhost returns 404.

Both checkboxes appear on the same Virtual Host Restrictions screen. You can check them together before saving.

Capability: