Creating classic plugins

Classic plugins provide Elasticsearch with mechanisms for custom authentication, authorization, scoring, and more.

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.

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.

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.

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.