Help for plugin authors

edit

The Elasticsearch repository contains examples of:

These examples provide the bare bones needed to get started. For more information about how to write a plugin, we recommend looking at the plugins listed in this documentation for inspiration.

Site plugins

The example site plugin mentioned above contains all of the scaffolding needed for integrating with Maven builds. If you don’t plan on using Maven, then all you really need in your plugin is:

  • The plugin-descriptor.properties file
  • The _site/ directory
  • The _site/index.html file

Plugin descriptor file

edit

All plugins, be they site or Java plugins, must contain a file called plugin-descriptor.properties in the root directory. The format for this file is described in detail here:

dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties.

Either fill in this template yourself (see elasticsearch-kopf as an example) or, if you are using Elasticsearch’s Maven build system, you can fill in the necessary values in the pom.xml for your plugin. For instance, see plugins/site-example/pom.xml.

Mandatory elements for all plugins

edit
Element Type Description

description

String

simple summary of the plugin

version

String

plugin’s version

name

String

the plugin name

Mandatory elements for Java plugins

edit
Element Type Description

jvm

Boolean

true if the classname class should be loaded from jar files in the root directory of the plugin. Note that only jar files in the root directory are added to the classpath for the plugin! If you need other resources, package them into a resources jar.

classname

String

the name of the class to load, fully-qualified.

java.version

String

version of java the code is built against. Use the system property java.specification.version. Version string must be a sequence of nonnegative decimal integers separated by "."'s and may have leading zeros.

elasticsearch.version

String

version of elasticsearch compiled against.

Plugin release lifecycle

You will have to release a new version of the plugin for each new elasticsearch release. This version is checked when the plugin is loaded so Elasticsearch will refuse to start in the presence of plugins with the incorrect elasticsearch.version.

Mandatory elements for Site plugins

edit
Element Type Description

site

Boolean

true to indicate contents of the _site/ directory in the root of the plugin should be served.

Testing your plugin

edit

When testing a Java plugin, it will only be auto-loaded if it is in the plugins/ directory. Use bin/plugin install file:///path/to/your/plugin to install your plugin for testing.

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

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 Maven build system, place this file in src/main/plugin-metadata and it will be applied during unit tests as well.

Keep in mind that the Java security model is stack-based, and the additional permissions will only be granted to the jars in your plugin, so you will have write proper security code around operations requiring elevated privileges. It is recommended to 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
);

See Secure Coding Guidelines for Java SE for more information.