Creating classic plugins
editCreating classic plugins
editClassic plugins provide Elasticsearch with mechanisms for custom authentication, authorization, scoring, and more.
Plugin release lifecycle
Classic plugins require you to build a new version for each new Elasticsearch release.
This version is checked when the plugin is installed and when it is loaded. Elasticsearch
will refuse to start in the presence of plugins with the incorrect
elasticsearch.version
.
Classic plugin file structure
editClassic plugins are ZIP files composed of JAR files and
a metadata file called
plugin-descriptor.properties
, a Java properties file that describes the
plugin.
Note that only JAR files at the root of the plugin are added to the classpath for the plugin. If you need other resources, package them into a resources JAR.
Example plugins
editThe Elasticsearch repository contains examples of plugins. Some of these include:
- a plugin with custom settings
- adding custom rest endpoints
- adding a custom rescorer
- a script implemented in Java
These examples provide the bare bones needed to get started. For more information about how to write a plugin, we recommend looking at the source code of existing plugins for inspiration.
Testing your plugin
editUse bin/elasticsearch-plugin install file:///path/to/your/plugin
to install your plugin for testing. The Java plugin is auto-loaded only if it’s in the
plugins/
directory.
Java Security permissions
editSome plugins may need additional security permissions. A plugin can include
the optional plugin-security.policy
file containing grant
statements for
additional permissions. Any additional permissions will be displayed to the user
with a large warning, and they will have to confirm them when installing the
plugin interactively. So if possible, it is best to avoid requesting any
spurious permissions!
If you are using the Elasticsearch Gradle build system, place this file in
src/main/plugin-metadata
and it will be applied during unit tests as well.
The Java security model is stack-based, and additional permissions are granted to the jars in your plugin, so you have to write proper security code around operations requiring elevated privileges. You might add a check to prevent unprivileged code (such as scripts) from gaining escalated permissions. For example:
// ES permission you should check before doPrivileged() blocks import org.elasticsearch.SpecialPermission; SecurityManager sm = System.getSecurityManager(); if (sm != null) { // unprivileged code such as scripts do not have SpecialPermission sm.checkPermission(new SpecialPermission()); } AccessController.doPrivileged( // sensitive operation );
Check Secure Coding Guidelines for Java SE for more information.