mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 13:08:29 +00:00
5d001d1578
* Add ability for plugins to declare additional permissions with a custom plugin-security.policy file and corresponding AccessController logic. See the plugin author's guide for more information. * Add warning messages to users for extra plugin permissions in bin/plugin. * When bin/plugin is run interactively (stdin is a controlling terminal and -b/--batch not supplied), require user confirmation. * Improve unit test and IDE support for plugins with additional permissions by exposing plugin's metadata as a maven test resource. Closes #14108 Squashed commit of the following: commit cf8ace65a7397aaccd356bf55f95d6fbb8bb571c Author: Robert Muir <rmuir@apache.org> Date: Wed Oct 14 13:36:05 2015 -0400 fix new unit test from master merge commit 9be3c5aa38f2d9ae50f3d54924a30ad9cddeeb65 Merge: 2f168b8 7368231 Author: Robert Muir <rmuir@apache.org> Date: Wed Oct 14 12:58:31 2015 -0400 Merge branch 'master' into off_my_back commit 2f168b8038e32672f01ad0279fb5db77ba902ae8 Author: Robert Muir <rmuir@apache.org> Date: Wed Oct 14 12:56:04 2015 -0400 improve plugin author documentation commit 6e6c2bfda68a418d92733ac22a58eec35508b2d0 Author: Robert Muir <rmuir@apache.org> Date: Wed Oct 14 12:52:14 2015 -0400 move security confirmation after 'plugin already installed' check, to prevent user from answering unnecessary questions. commit 08233a2972554afef2a6a7521990283102e20d92 Author: Robert Muir <rmuir@apache.org> Date: Wed Oct 14 05:36:42 2015 -0400 Add documentation and pluginmanager support commit 05dad86c51488ba43ccbd749f0164f3fbd3aee62 Author: Robert Muir <rmuir@apache.org> Date: Wed Oct 14 02:22:24 2015 -0400 Decentralize plugin permissions (modulo docs and pluginmanager work)
159 lines
5.9 KiB
Plaintext
159 lines
5.9 KiB
Plaintext
[[plugin-authors]]
|
|
== Help for plugin authors
|
|
|
|
The Elasticsearch repository contains examples of:
|
|
|
|
* a https://github.com/elastic/elasticsearch/tree/master/plugins/site-example[site plugin]
|
|
for serving static HTML, JavaScript, and CSS.
|
|
* a https://github.com/elastic/elasticsearch/tree/master/plugins/jvm-example[Java plugin]
|
|
which contains Java code.
|
|
|
|
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.
|
|
|
|
[NOTE]
|
|
.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
|
|
|
|
====================================
|
|
|
|
[float]
|
|
=== Plugin descriptor file
|
|
|
|
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:
|
|
|
|
https://github.com/elastic/elasticsearch/blob/master/dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties[`dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties`].
|
|
|
|
Either fill in this template yourself (see
|
|
https://github.com/lmenezes/elasticsearch-kopf/blob/master/plugin-descriptor.properties[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
|
|
https://github.com/elastic/elasticsearch/blob/master/plugins/site-example/pom.xml[`plugins/site-example/pom.xml`].
|
|
|
|
[float]
|
|
==== Mandatory elements for all plugins
|
|
|
|
|
|
[cols="<,<,<",options="header",]
|
|
|=======================================================================
|
|
|Element | Type | Description
|
|
|
|
|`description` |String | simple summary of the plugin
|
|
|
|
|`version` |String | plugin's version
|
|
|
|
|`name` |String | the plugin name
|
|
|
|
|=======================================================================
|
|
|
|
|
|
|
|
[float]
|
|
==== Mandatory elements for Java plugins
|
|
|
|
|
|
[cols="<,<,<",options="header",]
|
|
|=======================================================================
|
|
|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.
|
|
|
|
|=======================================================================
|
|
|
|
[IMPORTANT]
|
|
.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`.
|
|
|
|
==============================================
|
|
|
|
|
|
[float]
|
|
==== Mandatory elements for Site plugins
|
|
|
|
|
|
[cols="<,<,<",options="header",]
|
|
|=======================================================================
|
|
|Element | Type | Description
|
|
|
|
|`site` |Boolean | true to indicate contents of the `_site/`
|
|
directory in the root of the plugin should be served.
|
|
|
|
|=======================================================================
|
|
|
|
|
|
[float]
|
|
=== Testing your plugin
|
|
|
|
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 {ref}/integration-tests.html#changing-node-configuration[Changing Node Configuration].
|
|
|
|
|
|
[float]
|
|
=== Java Security permissions
|
|
|
|
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:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
// 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 http://www.oracle.com/technetwork/java/seccodeguide-139067.html[Secure Coding Guidelines for Java SE]
|
|
for more information.
|
|
|