solr/solr-ref-guide/src/configsets-api.adoc

= Configsets API
:toclevels: 1
// 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 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, DIH-related configuration, 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.adoc#,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.

NOTE: 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 <<config-sets.adoc#,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/cluster/configs`. Examples of both types are provided below.

[[configsets-list]]
== List Configsets

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

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

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

[source,bash]
----
http://localhost:8983/solr/admin/configs?action=LIST&omitHeader=true

----
====

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

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

[source,bash]
----
http://localhost:8983/api/cluster/configs?omitHeader=true
----
====
--

The output will look like:

[source,json]
----
{
  "configSets": [
    "_default",
    "techproducts",
    "gettingstarted"
  ]
}
----

[[configsets-upload]]
== Upload a Configset

Upload a configset, which is sent as a zipped file.
A single, non-zipped file can also be uploaded with the `filePath` parameter.

This functionality is enabled by default, but can be disabled via a runtime parameter `-Dconfigset.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!).

A configset is uploaded in a "trusted" mode if authentication is enabled and the upload operation is performed as an authenticated request. Without authentication, a configset is uploaded in an "untrusted" mode. Upon creation of a collection using an "untrusted" configset, the following functionality will not work:

* If specified in the configset, the DataImportHandler's ScriptTransformer will not initialize.
* The XSLT transformer (`tr` parameter) cannot be used at request processing time.
* If specified in the configset, the StatelessScriptUpdateProcessor will not initialize.
* Collections won't initialize if <lib> directives are used in the configset. (Note: Libraries added to Solr's classpath don't need the <lib> directive)

If you use any of these parameters or features, you must have enabled security features in your Solr installation and you must upload the configset as an authenticated user.

The `upload` command takes the following parameters:

`name`::
The configset to be created when the upload is complete. This parameter is required.

`overwrite`::
If set to `true`, Solr will overwrite an existing configset with the same name (if false, the request will fail).
If `filePath` is provided, then this option specifies whether the specified file within the configset should be overwritten if it already exists.
Default is `false` when using the v1 API, but `true` when using the v2 API.

`cleanup`::
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. Default is `false`.
This parameter cannot be set to true when `filePath` is used.

`filePath`::
This parameter allows the uploading of a single, non-zipped file to the given path under the configset in ZooKeeper.
This functionality respects the `overwrite` parameter, so a request will fail if the given file path already exists in the configset and overwrite is set to `false`.
The `cleanup` parameter cannot be set to true when `filePath` is used.

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

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

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

[source,bash]
----
$ (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:

[source,bash]
----
$ (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"
----
====

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

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

[source,bash]
----
$ (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/cluster/configs/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.
====
--

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

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

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

[source,bash]
----
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&overwrite=true"
----
====

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

With the v2 API, the name of the configset and file are both provided in the URL.
They can be substituted in `/cluster/configs/__config_name__/__file_name__`.
The filename may be nested and include `/` characters.

[source,bash]
----
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/cluster/configs/myConfigSet/solrconfig.xml"
----

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

[[configsets-create]]
== Create a Configset

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

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

The following parameters are supported when creating a configset.

`name`::
The configset to be created. This parameter is required.

`baseConfigSet`::
The name of the configset to copy as a base. This defaults to `_default`

`configSetProp._property_=_value_`::
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.

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

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

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

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

With the v2 API, the `create` command is provided as part of the JSON data that contains the required parameters:

[source,bash]
----
curl -X POST -H 'Content-type: application/json' -d '{
  "create":{
    "name": "myConfigSet",
    "baseConfigSet": "predefinedTemplate",
    "configSetProp.immutable": "false"}}'
    http://localhost:8983/api/cluster/configs?omitHeader=true
----

With the v2 API, configset properties can also be provided via the `properties` map:

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

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">323</int>
  </lst>
</response>
----

[[configsets-delete]]
== Delete a Configset

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

`name`::
The configset to be deleted. This parameter is required.

To delete a configset named "myConfigSet":

[.dynamic-tabs]
--
[example.tab-pane#v1deleteconfigset]
====
[.tab-label]*V1 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:

[source,bash]
----
http://localhost:8983/solr/admin/configs?action=DELETE&name=myConfigSet&omitHeader=true
----
====

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

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:

[source,bash]
----
curl -X DELETE http://localhost:8983/api/cluster/configs/myConfigSet?omitHeader=true
----
====
--

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">170</int>
  </lst>
</response>
----