Skip to content
OpenCms documentation
OpenCms documentation

Solr handler

When Solr runs stand-alone, you typically communicate with the Solr server via request handlers. OpenCms makes the select (for normal search queries) and the spellcheck handler of the embedded Solr server available. Hence you can query Solr as if it would by a stand-alone server.

But, the special OpenCms Solr handler does more than just querying Solr. It also checks permissions for the search results that correspond to VFS resources where the current user has no read permission on.

Since OpenCms 11, the extend to which you expose the Solr handler is very configurable.

If you get along without a client-side search feature that directly contacts the Solr handler, you should disable it or use it for debugging only. This way you prevent that someone accesses information in an unintended way.

OpenCms provides access to Solr's select and spell handler. For your local installation you can query the handlers via:

// The select handler
http://localhost:8080/opencms/handleSolrSelect?q=opencms

// the spellcheck handler
http://localhost:8080/opencms/handleSolrSpell?q=opencns

The handler can be enabled/disabled completely. If enabled, the behavior of the handler can be configured for each single Solr index.

The handler is implement by the class org.opencms.main.OpenCmsSolrHandler. In the OpenCms default system configuration (opencms-system.xml) the Solr request handler is configured by default:

<requesthandlers>
	<requesthandler class="org.opencms.main.OpenCmsSolrHandler" />
</requesthandlers>

Alternatively the request handler class can be used as a servlet. Therefore add the handler class to the WEB-INF/web.xml of your OpenCms application:

<servlet>
	<description>
		The OpenCms Solr servlet.
	</description>
	<servlet-name>OpenCmsSolrServlet</servlet-name>
	<servlet-class>org.opencms.main.OpenCmsSolrHandler</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>
[...]
<servlet-mapping>
	<servlet-name>OpenCmsSolrServlet</servlet-name>
	<url-pattern>/solr/*</url-pattern>
</servlet-mapping>

To disable the handler completely, remove the <requesthandler ... /> node in the opencms-system.xml.

Since OpenCms 11 you can configure for which indexes the handler can be queried and which fields can be returned. When you enable the handler since you have client-side code querying it, we strongly recommend to adjust the configuration such that only the really necessary information is retrievable by the handler.

The confguration is done in the opencms-search.xml file in the index node for the specific index.

Here's an exerpt from the default opencms-search.xml that contains explanations for the various configuration options:

<index class="org.opencms.search.solr.CmsSolrIndex">
   <name>Solr Online</name>

   <!-- ... some more nodes not of interest here -->

   <!-- The following parameters secure the Solr Handlers by disallowing certain requests. 
        All the restrictions are only applied if the request is not a valid debug request,
        i.e., if the param "_debug" does not hold the debug secret, as specified in a file configured via the
        configuration parameter "handle.solr.debugSecretFile" listed below. -->

   <!-- Specify if querying the index via handleSolrSelect should be disabled (in non-debug-mode). -->
   <param name="handle.solr.disableSelectHandler">true</param>

   <!-- Specify if querying the index via handleSolrSpell should be disabled (in non-debug-mode). -->
   <param name="handle.solr.disableSpellHandler">true</param>

   <!-- VFS path to the file that holds the debug secret.
        To disable debug mode remove the file or leave it empty. -->
   <param name="handle.solr.debugSecretFile">/system/config/solr-handler/debug-secret.txt</param>
   
   <!-- The following restrictions can be apllied to the handleSolrSelect enabled in non-debug-mode. -->

   <!-- Specify a comma-separated list of fields, only these will be allowed
        in the "fl"-parameter of the Solr Query -->
   <param name="handle.solr.allowedFields">path,id,solr_id,lastmodified,created</param>

   <!-- Specify the number of results maximally allowed per page, i.e., the maximal value of the "rows" parameter. -->
   <param name="handle.solr.maxAllowedResultsPerPage">20</param> -->

   <!-- Specify the number of results maximally allowed to be returned,
        i.e., the maximal sum of the values of the "rows" and the "start" parameter. -->
   <param name="handle.solr.maxAllowedResultsAtAll"></param>
</index>