Apache Solr Documentation

6.5 Ref Guide (PDF Download)
Solr Tutorial
Solr Community Wiki

Older Versions of this Guide (PDF)

Ref Guide Topics


*** As of June 2017, the latest Solr Ref Guide is located at https://lucene.apache.org/solr/guide ***

Please note comments on these pages have now been disabled for all users.

Skip to end of metadata
Go to start of metadata

This section will describe the default solr.xml file included with Solr and how to modify it for your needs. For details on how to configure core.properties, see the section Defining core.properties.

Defining solr.xml

You can find solr.xml in your Solr Home directory or in Zookeeper. The default solr.xml file looks like this:

#666666html/xmlsolid ${host:} ${jetty.port:8983} ${hostContext:solr} ${zkClientTimeout:15000} ${genericCoreNodeNames:true} ${socketTimeout:0} ${connTimeout:0} ]]>

As you can see, the discovery Solr configuration is "SolrCloud friendly". However, the presence of the <solrcloud> element does not mean that the Solr instance is running in SolrCloud mode. Unless the -DzkHost or -DzkRun are specified at startup time, this section is ignored.

Solr.xml Parameters

The <solr> Element

There are no attributes that you can specify in the <solr> tag, which is the root element of solr.xml. The tables below list the child nodes of each XML element in solr.xml.




If used, this attribute should be set to the FQN (Fully qualified name) of a class that inherits from CoreAdminHandler. For example, <str name="adminHandler">com.myorg.MyAdminHandler</str> would configure the custom admin handler (MyAdminHandler) to handle admin requests. If this attribute isn't set, Solr uses the default admin handler, org.apache.solr.handler.admin.CoreAdminHandler. For more information on this parameter, see the Solr Wiki at http://wiki.apache.org/solr/CoreAdmin#cores.

As above, for custom CollectionsHandler implementations.
As above, for custom InfoHandler implementations.


Specifies the number of threads that will be assigned to load cores in parallel.


The root of the core discovery tree, defaults to SOLR_HOME.


Currently non-operational.


Specifies the path to a common library directory that will be shared across all cores. Any JAR files in this directory will be added to the search path for Solr plugins. This path is relative to the top-level container's Solr Home. Custom handlers may be placed in this directory


This attribute, when set to true, ensures that the multiple cores pointing to the same Schema resource file will be referring to the same IndexSchema Object. Sharing the IndexSchema Object makes loading the core faster. If you use this feature, make sure that no core-specific property is used in your Schema file.


Defines how many cores with transient=true that can be loaded before swapping the least recently used core for a new core.

The directory under which configsets for solr cores can be found. Defaults to SOLR_HOME/configsets

The <solrcloud> element

This element defines several parameters that relate so SolrCloud. This section is ignored unless the solr instance is started with either -DzkRun or -DzkHost




Used to set the underlying "connTimeout" for intra-cluster updates.


Used to set the underlying "socketTimeout" for intra-cluster updates.


The hostname Solr uses to access cores.


The url context path.


The port Solr uses to access cores. In the default solr.xml file, this is set to ${jetty.port:8983}, which will use the Solr port defined in Jetty, and otherwise fall back to 8983.


When SolrCloud is starting up, how long each Solr node will wait for all known replicas for that shard to be found before assuming that any nodes that haven't reported are down.


When trying to elect a leader for a shard, this property sets the maximum time a replica will wait to see conflicting state information to be resolved; temporary conflicts in state information can occur when doing rolling restarts, especially when the node hosting the Overseer is restarted. Typically, the default value of 180000 (ms) is sufficient for conflicts to be resolved; you may need to increase this value if you have hundreds or thousands of small collections in SolrCloud.


A timeout for connection to a ZooKeeper server. It is used with SolrCloud.


In SolrCloud mode, the URL of the ZooKeeper host that Solr should use for cluster state information.


If TRUE, node names are not based on the address of the node, but on a generic name that identifies the core. When a different machine takes over serving that core things will be much easier to understand.

zkCredentialsProvider zkACLProvider

Optional parameters that can be specified if you are using ZooKeeper Access Control.

The <logging> element




The class to use for logging. The corresponding JAR file must be available to solr, perhaps through a <lib> directive in solrconfig.xml.


true/false - whether to enable logging or not.

The <logging><watcher> element




The number of log events that are buffered.


The logging level above which your particular logging implementation will record. For example when using log4j one might specify DEBUG, WARN, INFO, etc.

The <shardHandlerFactory> element

Custom shard handlers can be defined in solr.xml if you wish to create a custom shard handler.


Since this is a custom shard handler, sub-elements are specific to the implementation. The default and only shard handler provided by Solr is the HttpShardHandlerFactory in which case, the following sub-elements can be specified:

socketTimeoutThe read timeout for intra-cluster query and administrative requests. The default is the same as the distribUpdateSoTimeout specified in the solrcloud section.
connTimeoutThe connection timeout for intra-cluster query and administrative requests. Defaults to the distribUpdateConnTimeout specified in the solrcloud section
urlSchemeURL scheme to be used in distributed search
maxConnectionsPerHostMaximum connections allowed per host. Defaults to 20
maxConnectionsMaximum total connections allowed. Defaults to 10000
corePoolSizeThe initial core size of the threadpool servicing requests. Default is 0.
maximumPoolSizeThe maximum size of the threadpool servicing requests. Default is unlimited.
maxThreadIdleTimeThe amount of time in seconds that idle threads persist for in the queue, before being killed. Default is 5 seconds.
sizeOfQueueIf the threadpool uses a backing queue, what is its maximum size to use direct handoff. Default is to use a SynchronousQueue.
fairnessPolicyA boolean to configure if the threadpool favours fairness over throughput. Default is false to favor throughput.


Substituting JVM System Properties in solr.xml

Solr supports variable substitution of JVM system property values in solr.xml, which allows runtime specification of various configuration options. The syntax is ${propertyname[:option default value]}. This allows defining a default that can be overridden when Solr is launched. If a default value is not specified, then the property must be specified at runtime or the solr.xml file will generate an error when parsed.

Any JVM system properties usually specified using the -D flag when starting the JVM, can be used as variables in the solr.xml file.

For example, in the solr.xml file shown below, the socketTimeout and connTimeout values are each set to "0". However, if you start Solr using 'bin/solr -DsocketTimeout=1000', the socketTimeout option of the HttpShardHandlerFactory to be overridden using a value of 1000ms, while the connTimeout option will continue to use the default property value of "0".

#666666html/xmlsolid ${socketTimeout:0} ${connTimeout:0} ]]>

  • No labels


  1. A few suggestions:

    • Instead of using the blue info box for your path examples (under Multiple Solr Cores) a code box might be better - it has a white background. In Wiki Markup, you can replace {info} with {code}. There is a further convention throughout the rest of the Ref Guide for code boxes that they should have a solid black border. To define that, use {code:borderStyle=solid|borderColor=#666666}, so the first box would be changed:

      And would look like:
    • A relatively minor nit, but important in the broader sense for consistency, is to use monospace text for command-line commands, API calls, field names, program names, and other technical-level information. You specify that with double curly-brackets around the text (such as {{ and }}). Anyone who doesn't (or can't) copy the text directly from the screen (or the PDF) will be at a lower risk for transcription errors.
    • In the section "Solr.xml Parameters", the first sentence says, "There are no attributes that you can specify on <solr>, which is the root element of solr.xml. Here is a full example of all the possibilities in a solr.xml file with comments." But there is no example there and a full list of attributes before the SolrCloud parameters start. Is that a hold-over from a previous page?
    • At the bottom of the content, add the {scrollbar} macro for consistency with other pages - it adds page navigation (prev, next, etc.).
    1. I did a bunch ofthese changes, with one notable exception...

      Instead of using the blue info box for your path examples (under Multiple Solr Cores) a code box might be better...

      ...i went with "noformat" instead for these directory listing things to help distinguish them from actual xml code boxes.

  2. I have a gut feeling that the dataDir description under the section "Individual core.properties Files" is wrong, particularly since dataDir is mentioned again under the Implicit Properties section. However, the Solr Wiki doesn't give me any clues about what it should be (I'm guessing either 'solr.home' or 'instanceDir'). Anyone know for a fact that is correct as it is today?

    1. i fixed the description of dataDir in the "Individual core.properties Files" – but i think a bigger remaining problem is clarifying what we're talking about in the "Implicit Properties section." ... ther'es nothing her that conveys the diff between these two sections, or why seemingly identical properties have diff names.

      the gist of which being: the first section (individual...) is property names that can be defined in core.properties to drive behavior of core functionality in solr. the second section (implicit...) is properties that solr generates for you to use as variable substitutes when parsing your config files in addition to user defined properties. ie: even if you don't have "dataDir" in your core.properties, a "solr.core.dataDir" property with a real path will be available when your solrconfig.xml file is parsed.

      we need to better explain his – and we probably need to add to that list of implicit properties – i'm pretty sure there is an implicit property for everything in the "individual..." section.

      1. we need to better explain his – and we probably need to add to that list of implicit properties – i'm pretty sure there is an implicit property for everything in the "individual..." section.

        I moved most discussion of hte implicit properties over to the solrconfig.xml page...


        ..and cleaned up this page (and the legacy solr.xml page) a bit to better clarify the distinction between JVM sys props that can be substituted in solr.xml, from the plethora of props that can be substituted in solrconfig.xml and schema.xml (either from sys props, or core specific props, and the diff places core specific props can come from, etc....)

  3. "Custom share handlers" -> "Custom shard handlers"?


  4. I think we should add a section here to show how to load up solr.xml from ZooKeeper.

    One can do that by adding the following sysprop while starting up solr nodes -Dsolr.solrxml.location=zookeeper 


  5. 创建collection时候,修改默认的schema与solrconfig配置文件名字,如何写参数指令,我写的不起作用。

  6. This page should mention solr.properties substitution as well as the fact that solr.xml can be loaded from zookeeper (SOLR-4718, SOLR-7735)

  7. This page must mention the two new <solrcloud> params for ZK ACL: zkCredentialsProvider and zkACLProvider

  8. In the current format for defining adminHandler, how to pass initArgs?