Creating classic plugins

edit

Classic 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

edit

Classis 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

edit

The Elasticsearch repository contains examples of plugins. Some of these include:

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

edit

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

You may also load your plugin within the test framework for integration tests. Check Changing Node Configuration for more information.

Java Security permissions

edit

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