Property Substitution in Configuration 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 property 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:

<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 Solr with:

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.

Solr will also automatically map any environment variables that start with SOLR_ to system properties by lowercasing the name and replacing underscores with .. This means that starting Solr with SOLR_LOCK_TYPE=none (or setting it in solr.in.sh or solr.in.cmd) will have the same effect as the previous example.

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.

Config API to Override solrconfig.xml

The 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:

{
  "userProps":{"update.autoCreateFields":"false"},
  "requestHandler":{"/myterms":{
      "name":"/myterms",
      "class":"solr.SearchHandler",
      "defaults":{
        "terms":true,
        "distrib":false},
      "components":["terms"]}}}

For more details, see the section Config API.

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":

V1 API

http://localhost:8983/solr/admin/collections?action=CREATE&name=gettingstarted&numShards=1&property.my.custom.prop=edismax

V2 API

curl -X POST -H 'Content-type: application/json' -d '{"name": "gettingstarted", "numShards": 1, "properties": {"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):

#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:

<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:

<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 core.properties property:

  • solr.core.name

  • solr.core.config

  • solr.core.schema

  • solr.core.dataDir

  • solr.core.transient

  • solr.core.loadOnStartup