solr/solr-ref-guide/src/libs.adoc

= Lib Directories and Directives

// 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.

Here we describe two simple and effective methods to make the `.jar` files for Solr plugins visible to Solr.

Such files are sometimes called "libraries" or "libs" for short.
Essentially you can put them in some special places or explicitly tell Solr about them from your config.

If there is overlap or inter-dependencies between libraries, then pay attention to the order.  You can think of it like a stack that is searched top-down.  At the top are the lib directives in reverse order, then Solr core's lib, then Solr home's lib, then Solr itself.

== Lib Directories

There are several special places you can place Solr plugin `.jar` files:

* `<solr_home>/lib/`: The `.jar` files placed here are available to all Solr cores running on the node, and to node level plugins referenced in `solr.xml` -- so basically everything.
This directory is not present by default so create it.
See <<taking-solr-to-production.adoc#solr-home-directory,Solr home directory>>.

* `<core_instance>/lib/`: In standalone Solr, you may want to add plugins just for a specific Solr core.
Create this adjacent to the `conf/` directory; it's not present by default.

* `<solr_install>/server/solr-webapp/webapp/WEB-INF/lib/`: The `.jar` files for Solr itself and it's dependencies live here.
Certain plugins or add-ons to plugins require placement here.
They will document themselves to say so.

Solr incorporates Jetty for providing HTTP server functionality.
Jetty has some directories that contain `.jar` files for itself and its own plugins / modules or JVM level plugins (e.g., loggers).
Solr plugins won't work in these locations.

== Lib Directives in SolrConfig

_Both_ plugin and <<resource-loading.adoc#,resource>> file paths are configurable via `<lib/>` directives in `solrconfig.xml`.
When a directive matches a directory, then resources can be resolved from it.
When a directive matches a `.jar` file, Solr plugins and their dependencies are resolved from it.
Resources can be placed in a `.jar` too but that's unusual.
It's erroneous to refer to any other type of file.

A `<lib/>` directive must have one (not both) of these two attributes:

* `path`: used to refer to a single directory (for resources) or file (for a plugin `.jar`)

* `dir`: used to refer to _all_ direct descendants of the specified directory.  Optionally supply a `regex` attribute to filter these to those matching the regular expression.

All directories are resolved as relative to the Solr core's `instanceDir`.

These examples show how to load contrib modules into Solr:

[source,xml]
----
  <lib dir="${solr.install.dir:../../../..}/contrib/extraction/lib" regex=".*\.jar" />
  <lib dir="${solr.install.dir:../../../..}/dist/" regex="solr-cell-\d.*\.jar" />

  <lib dir="${solr.install.dir:../../../..}/contrib/clustering/lib/" regex=".*\.jar" />
  <lib dir="${solr.install.dir:../../../..}/dist/" regex="solr-clustering-\d.*\.jar" />

  <lib dir="${solr.install.dir:../../../..}/contrib/langid/lib/" regex=".*\.jar" />
  <lib dir="${solr.install.dir:../../../..}/dist/" regex="solr-langid-\d.*\.jar" />

  <lib dir="${solr.install.dir:../../../..}/contrib/velocity/lib" regex=".*\.jar" />
  <lib dir="${solr.install.dir:../../../..}/dist/" regex="solr-velocity-\d.*\.jar" />
  <lib dir="${solr.install.dir:../../../..}/dist/" regex="solr-ltr-\d.*\.jar" />
----