About Virtual Host
Fess can serve different search results depending on the hostname (the value of the HTTP Host header) used to access it. A single Fess server can be published under multiple hostnames, providing a different set of crawl targets and page design for each hostname. The search screen can also look different for each host: a static theme whose name matches the virtual host name is used for that host.
The virtual host feature is disabled (unconfigured) by default. Configure it using the steps below.
System Configuration
In Administrator Guide > General Settings, set the mapping between the requesting hostname and the virtual host name under “Virtual Host”. Specify the virtual host name configured here in the crawl configuration.
Format
Specify one virtual host per line using the following format.
| header_name | The name of the HTTP request header used for matching. Normally specify Host. When accessing via a reverse proxy, you can also specify X-Forwarded-Host. |
| header_value | The hostname contained in the above header (in the form hostname:port if necessary). The virtual host is applied when this value exactly matches the value of the header sent by the client at access time (case-insensitive). |
| virtual_host_name | The virtual host name to specify in the crawl configuration |
Example
Note
Matching is performed by string comparison against the request header value, not by hostname resolution (DNS). The Host header sent by the browser does not include the port number when accessing via a standard port (80 for HTTP, 443 for HTTPS), but does include it in the form hostname:port when accessing via any other port. Therefore, when publishing on a non-standard port, specify the port number explicitly, for example Host:abc.example.com:8080=host1.
Note
Only alphanumeric characters and underscores ( a-z , A-Z , 0-9 , _ ) can be used in virtual host names. Other characters are automatically removed.
The following names are reserved and cannot be used as virtual host names: admin , common , error , login , profile
Page Design per Virtual Host
To give a virtual host its own search screen, install a static theme whose name in theme.yml is the virtual host name in lowercase (for example host1). A request that matches the virtual host is served with that theme; any other request is served with the default theme. The theme does not have to be set as the default. See Customizing the Bundled Theme for how to create a theme from the bundled one, and Theme for how to install it.
Note
Since Fess 15.9, saving the configuration no longer generates JSPs under WEB-INF/view/virtual_host_name. The login screen (/login/) is the same page for every virtual host (WEB-INF/view/admin/login/) and cannot be changed per virtual host. To give a virtual host its own look, use a static theme named after the virtual host, as described above.
Crawl Configuration
Specify “Virtual Host” in web crawl configuration, file crawl configuration, or data store crawl configuration. “Virtual Host” should be one of the virtual host names configured in the system settings. You can specify multiple virtual hosts for a single crawl configuration (one per line).
Searches made from a matched virtual host will only display documents belonging to crawl configurations that have that virtual host assigned. Accesses that do not match any virtual host (normal access with no virtual host configured) are not filtered, and all search results are returned as usual.
Example
| Virtual Host | host1 |