Configsets API

The Configsets API enables you to upload new configsets to ZooKeeper, create, and delete configsets when Solr is running SolrCloud mode.

Configsets are a collection of configuration files such as solrconfig.xml, synonyms.txt, the schema, language-specific files, and other collection-level configuration files (everything that normally lives in the conf directory). Solr ships with two example configsets (_default and sample_techproducts_configs) which can be used when creating collections. Using the same concept, you can create your own configsets and make them available when creating collections.

This API provides a way to upload configuration files to ZooKeeper and share the same set of configuration files between two or more collections.

Once a configset has been uploaded to ZooKeeper, use the configset name when creating the collection with the Collections API and the collection will use your configuration files.

Configsets do not have to be shared between collections if they are uploaded with this API, but this API makes it easier to do so if you wish. An alternative to uploading your configsets in advance would be to put the configuration files into a directory under server/solr/configsets and using the directory name as the -d parameter when using bin/solr create to create a collection.

This API can only be used with Solr running in SolrCloud mode. If you are not running Solr in SolrCloud mode but would still like to use shared configurations, please see the section Configsets.

The API works by passing commands to the configs endpoint. The path to the endpoint varies depending on the API being used: the v1 API uses /solr/admin/configs, while the v2 API uses /api/configsets. Examples of both types are provided below.

List Configsets

The list command fetches the names of the configsets that are available for use during collection creation.

  • V1 API

  • V2 API

With the v1 API, the list command must be capitalized as LIST:

http://localhost:8983/solr/admin/configs?action=LIST&omitHeader=true

With the v2 API, the list command is implied when there is no data sent with the request.

http://localhost:8983/api/configsets?omitHeader=true

The output will look like:

{
  "configSets": [
    "_default",
    "techproducts",
    "gettingstarted"
  ]
}

Download a Configset

The v2 API allows configsets to be downloaded as a single zipped file. This is useful for backing up configsets, sharing them between environments, or examining their contents.

The download command takes the following parameters:

name

Required

Default: none

The name of the configset to download.

The response will be a ZIP file containing all files from the configset.

To download a configset named "myConfigSet":

  • V1 API

  • V2 API

The v1 API does not currently support downloading configsets. Use the v2 API instead.

With the v2 API, use a GET request to /configsets/config_name/files:

curl -X GET -o myConfigSet.zip "http://localhost:8983/api/configsets/myConfigSet/files"

The configset will be downloaded as a ZIP file that can be extracted and used locally, or re-uploaded to another Solr instance.

Upload a Configset

You can upload an entire configset as a ZIP archive, which is useful for creating new configsets or replacing all files in an existing configset.

This functionality is enabled by default, but can be disabled via a runtime parameter -Dsolr.configset.upload.enabled=false. Disabling this feature is advisable if you want to expose Solr installation to untrusted users (even though you should never do that!).

Not all file types are supported for use in configsets. Please see forbidden file types for more information.

The following parameters are supported when uploading a configset:

name

Required

Default: none

The configset to be created when the upload is complete.

overwrite

Optional

Default: see description

If set to true, Solr will overwrite an existing configset with the same name (if false, the request will fail).

cleanup

Optional

Default: false

When overwriting an existing configset (overwrite=true), this parameter tells Solr to delete the files in ZooKeeper that existed in the old configset but not in the one being uploaded.

When uploading an entire configset, the body of the request should be a zip file that contains the configset. The zip file must be created from within the conf directory (i.e., solrconfig.xml must be the top level entry in the zip file).

Here is an example on how to create the zip file named "myconfig.zip" and upload it as a configset named "myConfigSet":

  • V1 API

  • V2 API

With the v1 API, the upload command must be capitalized as UPLOAD:

$ (cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip

$ curl -X POST --header "Content-Type:application/octet-stream" --data-binary @myconfigset.zip "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet"

The same can be achieved using a Unix pipe with a single request as follows:

$ (cd server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) | curl -X POST --header "Content-Type:application/octet-stream" --data-binary @- "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet"

With the v2 API, the name of the configset to upload is provided as a path parameter:

$ (cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip

$ curl -X PUT --header "Content-Type:application/octet-stream" --data-binary @myconfigset.zip
    "http://localhost:8983/api/configsets/myConfigSet"

With this API, the default behavior is to overwrite the configset if it already exists. This behavior can be disabled with the parameter overwrite=false, in which case the request will fail if the configset already exists.

Update a Single File in a Configset

This API lets you modify a specific file in an existing configset. This is useful for making targeted changes without re-uploading the entire configset.

URL Path Parameters:

configSetName

Required

Default: none

The name of the configset containing the file.

filePath

Required

Default: none

The path to the file within the configset, specified as part of the URL path (e.g., solrconfig.xml or lang/stopwords_en.txt). For nested paths, use slashes as shown in the examples below.

Here is an example on how to upload a single file to a configset named "myConfigSet":

  • V1 API

  • V2 API

With the v1 API, the upload command must be capitalized as UPLOAD. The filename to upload is provided via the filePath parameter:

curl -X POST --header "Content-Type:application/octet-stream"
    --data-binary @solr/server/solr/configsets/sample_techproducts_configs/conf/solrconfig.xml
    "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet&filePath=solrconfig.xml"

With the v2 API, the file path is part of the URL path. Use a PUT request to /api/configsets/{configSetName}/files/{filePath}:

curl -X PUT --header "Content-Type:application/octet-stream"
    --data-binary @solr/server/solr/configsets/sample_techproducts_configs/conf/solrconfig.xml
    "http://localhost:8983/api/configsets/myConfigSet/files/solrconfig.xml"

For nested files within the configset:

curl -X PUT --header "Content-Type:application/octet-stream"
    --data-binary @solr/server/solr/configsets/sample_techproducts_configs/conf/lang/stopwords_en.txt
    "http://localhost:8983/api/configsets/myConfigSet/files/lang/stopwords_en.txt"

Get a Single File from a Configset

This API retrieves the raw contents of a single file from an existing configset. This is useful for inspecting individual configuration files without downloading the entire configset.

This endpoint mirrors the upload API structure, with the file path specified as part of the URL path. The response contains the raw bytes of the file, supporting both text and binary files.

URL Path Parameters:

configSetName

Required

Default: none

The name of the configset containing the file.

filePath

Required

Default: none

The path to the file within the configset, specified as part of the URL path (e.g., solrconfig.xml or lang/stopwords_en.txt). For nested paths, use slashes as shown in the examples below.

The response is the raw file content as application/octet-stream. This format supports both text files (XML, properties, etc.) and binary files (images, class files, etc.).

To retrieve the solrconfig.xml file from a configset named "myConfigSet":

  • V1 API

  • V2 API

The v1 API does not currently support retrieving individual configset files. Use the v2 API instead.

With the v2 API, the file path is part of the URL path. Use a GET request to /api/configsets/{configSetName}/files/{filePath}:

curl -X GET "http://localhost:8983/api/configsets/myConfigSet/files/solrconfig.xml"

For nested files within the configset:

curl -X GET "http://localhost:8983/api/configsets/myConfigSet/files/lang/stopwords_en.txt"

Example Output

The response is the raw file content. For a text file like solrconfig.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<config>
  ...
</config>

For binary files, the raw bytes are returned directly, preserving the binary content.

Create a Configset

The create command creates a new configset based on a configset that has been previously been created.

If you have not yet created any configsets, see the Upload a Configset command above.

The following parameters are supported when creating a configset.

name

Required

Default: none

The configset to be created.

baseConfigSet

Optional

Default: _default

The name of the configset to copy as a base.

configSetProp.property=value

Optional

Default: none

A configset property from the base configset to override in the copied configset.

For example, to create a configset named "myConfigset" based on a previously defined "predefinedTemplate" configset, overriding the immutable property to false.

  • V1 API

  • V2 API

With the v1 API, the create command must be capitalized as CREATE:

http://localhost:8983/solr/admin/configs?action=CREATE&name=myConfigSet&baseConfigSet=predefinedTemplate&configSetProp.immutable=false&wt=xml&omitHeader=true

With the v2 API, the create command is implicit and parameters are specified in a POST request body.

curl -X POST -H 'Content-type: application/json' -d '{
  "name": "myConfigSet",
  "baseConfigSet": "predefinedTemplate",
  "properties": {
    "immutable": "false"
  }
}'
  http://localhost:8983/api/configsets?omitHeader=true

Output

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">323</int>
  </lst>
</response>

Delete a Configset

The delete command removes a configset. It does not remove any collections that were created with the configset.

name

Required

Default: none

The configset to be deleted.

To delete a configset named "myConfigSet":

  • V1 API

  • V2 API

With the v1 API, the delete command must be capitalized as DELETE. The name of the configset to delete is provided with the name parameter:

http://localhost:8983/solr/admin/configs?action=DELETE&name=myConfigSet&omitHeader=true

With the v2 API, the delete command is provided as the request method, as in -X DELETE. The name of the configset to delete is provided as a path parameter:

curl -X DELETE http://localhost:8983/api/configsets/myConfigSet

Output

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">170</int>
  </lst>
</response>