solr/solr-ref-guide/src/configuring-solrconfig-xml.adoc

= Configuring solrconfig.xml
:page-children: datadir-and-directoryfactory-in-solrconfig, \
    schema-factory-definition-in-solrconfig, \
    indexconfig-in-solrconfig, \
    requesthandlers-and-searchcomponents-in-solrconfig, \
    initparams-in-solrconfig, \
    updatehandlers-in-solrconfig, \
    query-settings-in-solrconfig, \
    requestdispatcher-in-solrconfig, \
    update-request-processors, \
    codec-factory

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

The `solrconfig.xml` file is the configuration file with the most parameters affecting Solr itself.

While configuring Solr, you'll work with `solrconfig.xml` often, either directly or via the <<config-api.adoc#,Config API>> to create "configuration overlays" (`configoverlay.json`) to override the values in `solrconfig.xml`.

In `solrconfig.xml`, you configure important features such as:

* request handlers, which process the requests to Solr, such as requests to add documents to the index or requests to return results for a query

* listeners, processes that "listen" for particular query-related events; listeners can be used to trigger the execution of special code, such as invoking some common queries to warm-up caches

* the Request Dispatcher for managing HTTP communications

* the Admin Web interface

* parameters related to replication and duplication (these parameters are covered in detail in <<legacy-scaling-and-distribution.adoc#,Legacy Scaling and Distribution>>)

The `solrconfig.xml` file is located in the `conf/` directory for each collection. Several well-commented example files can be found in the `server/solr/configsets/` directories demonstrating best practices for many different types of installations.

We've covered the options in the following sections:

* <<datadir-and-directoryfactory-in-solrconfig.adoc#,DataDir and DirectoryFactory in SolrConfig>>
* <<schema-factory-definition-in-solrconfig.adoc#,Schema Factory Definition in SolrConfig>>
* <<indexconfig-in-solrconfig.adoc#,IndexConfig in SolrConfig>>
* <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#,RequestHandlers and SearchComponents in SolrConfig>>
* <<initparams-in-solrconfig.adoc#,InitParams in SolrConfig>>
* <<updatehandlers-in-solrconfig.adoc#,UpdateHandlers in SolrConfig>>
* <<query-settings-in-solrconfig.adoc#,Query Settings in SolrConfig>>
* <<requestdispatcher-in-solrconfig.adoc#,RequestDispatcher in SolrConfig>>
* <<update-request-processors.adoc#,Update Request Processors>>
* <<codec-factory.adoc#,Codec Factory>>

Some SolrConfig aspects are covered in other sections.
See <<libs.adoc#lib-directives-in-solrconfig,lib directives in SolrConfig>>, which can be used for both Plugins and Resources.

== Substituting Properties in Solr Config Files

Solr supports variable substitution of property values in configuration files, which allows runtime specification of various configuration options in `solrconfig.xml`. 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 configuration file will generate an error when parsed.

There are multiple methods for specifying properties that can be used in configuration files. Of those below, strongly consider "config overlay" as the preferred approach, as it stays local to the configset and is easy to modify.

=== JVM System Properties

Any JVM System properties, usually specified using the `-D` flag when starting the JVM, can be used as variables in any XML configuration file in Solr.

For example, in the sample `solrconfig.xml` files, you will see this value which defines the locking type to use:

[source,xml]
----
<lockType>${solr.lock.type:native}</lockType>
----

Which means the lock type defaults to "native" but when starting Solr, you could override this using a JVM system property by launching the Solr it with:

[source,bash]
----
bin/solr start -Dsolr.lock.type=none
----

In general, any Java system property that you want to set can be passed through the `bin/solr` script using the standard `-Dproperty=value` syntax. Alternatively, you can add common system properties to the `SOLR_OPTS` environment variable defined in the Solr include file (`bin/solr.in.sh` or `bin/solr.in.cmd`). For more information about how the Solr include file works, refer to: <<taking-solr-to-production.adoc#,Taking Solr to Production>>.

=== Config API to Override solrconfig.xml

The <<config-api.adoc#,Config API>> allows you to use an API to modify Solr's configuration, specifically user defined properties. Changes made with this API are stored in a file named `configoverlay.json`. This file should only be edited with the API, but will look like this example:

[source,json]
----
{"userProps": {
    "dih.db.url": "jdbc:oracle:thin:@localhost:1521",
    "dih.db.user": "username",
    "dih.db.pass": "password"}}
----

For more details, see the section <<config-api.adoc#,Config API>>.

=== solrcore.properties

If the configuration directory for a Solr core contains a file named `solrcore.properties` that file can contain any arbitrary user-defined property names and values using the Java https://en.wikipedia.org/wiki/.properties[properties file format]. Those properties can then be used as variables in other configuration files for that Solr core.

For example, the following `solrcore.properties` file could be created in the `conf/` directory of a collection using one of the example configurations, to override the lockType used.

[source,properties]
----
#conf/solrcore.properties
solr.lock.type=none
----

.Deprecation
[WARNING]
====
`solrcore.properties` won't work in SolrCloud mode (it is not read from ZooKeeper). This feature is likely to be removed in the future. Instead, use another mechanism like a config overlay.
====

[IMPORTANT]
====

The path and name of the `solrcore.properties` file can be overridden using the `properties` property in <<defining-core-properties.adoc#,`core.properties`>>.

====

=== User-Defined Properties in core.properties

Every Solr core has a `core.properties` file, automatically created when using the APIs. When you create a SolrCloud collection, you can pass through custom parameters by prefixing the parameter name with `_property.name_` as a parameter.

For example, to add a property named "my.custom.prop":

[.dynamic-tabs]
--
[example.tab-pane#v1customprop]
====
[.tab-label]*V1 API*

[source,bash]
----
http://localhost:8983/solr/admin/collections?action=CREATE&name=gettingstarted&numShards=1&property.my.custom.prop=edismax
----
====

[example.tab-pane#v2]
====
[.tab-label]*V2 API*

[source,bash]
----
curl -X POST -H 'Content-type: application/json' -d '{"create": {"name": "gettingstarted", "numShards": "1", "property.my.custom.prop": "edismax"}}' http://localhost:8983/api/collections
----
====
--

This will create a `core.properties` file that has at least the following properties (others omitted for brevity):

[source,properties]
----
#core.properties
name=gettingstarted
my.custom.prop=edismax
----

The `my.custom.prop` property can then be used as a variable, such as in `solrconfig.xml`:

[source,xml]
----
<requestHandler name="/select">
  <lst name="defaults">
    <str name="defType">${my.custom.prop}</str>
  </lst>
</requestHandler>
----

=== Implicit Core Properties

Several attributes of a Solr core are available as "implicit" properties that can be used in variable substitution, independent of where or how the underlying value is initialized.

For example, regardless of whether the name for a particular Solr core is explicitly configured in `core.properties` or inferred from the name of the instance directory, the implicit property `solr.core.name` is available for use as a variable in that core's configuration file:

[source,xml]
----
<requestHandler name="/select">
  <lst name="defaults">
    <str name="collection_name">${solr.core.name}</str>
  </lst>
</requestHandler>
----

All implicit properties use the `solr.core.` name prefix, and reflect the runtime value of the equivalent <<defining-core-properties.adoc#,`core.properties` property>>:

* `solr.core.name`
* `solr.core.config`
* `solr.core.schema`
* `solr.core.dataDir`
* `solr.core.transient`
* `solr.core.loadOnStartup`