Installing plugins
You can install individual plugins for Lucenia based on your needs. For information about available plugins, see Available plugins.
For plugins to work properly with Lucenia, all plugins must have the ability to access the data in the cluster, including metadata about cluster operations. Therefore, to protect your cluster’s data and preserve its integrity, first be sure you understand the function of a plugin before installing it on your Lucenia cluster. Second, when selecting a custom plugin, make sure the plugin’s source is a reliable one.
Managing plugins
Lucenia uses a command line tool called lucenia-plugin for managing plugins. This tool allows you to:
Print help text by passing -h or --help. Depending on your host configuration, you might also need to run the command with sudo privileges.
If you are running Lucenia in a Docker container, plugins must be installed, removed, and configured by modifying the Docker image. For information, see Working with plugins
List
Use list to see a list of plugins that have already been installed.
Usage
bin/lucenia-plugin list
Example
$ ./lucenia-plugin list
lucenia-security
You can also list installed plugins by using the CAT API.
Path and HTTP method
GET _cat/plugins
Example response
lucenia-node1 lucenia-security 0.1.0.0
Install
There are three ways to install plugins using the lucenia-plugin:
- Install a plugin by name.
- Install a plugin from a ZIP file.
- Install a plugin using Maven coordinates.
Install a plugin by name:
For a list of plugins that can be installed by name, see Additional plugins.
Usage
bin/lucenia-plugin install <plugin-name>
Example
$ sudo ./lucenia-plugin install repository-gcs
-> Installing repository-gcs
-> Downloading repository-gcs from lucenia
[=================================================] 100%
-> Installed repository-gcs with folder name repository-gcs
Install a plugin from a zip file
Remote zip files can be installed by replacing <zip-file> with the URL of the hosted file. The tool only supports downloading over HTTP/HTTPS protocols. For local zip files, replace <zip-file> with file: followed by the absolute or relative path to the plugin zip file as in the second example below.
Usage
bin/lucenia-plugin install <zip-file>
Example
# Zip file is hosted on a remote server - in this case, Maven central repository.
$ sudo ./lucenia-plugin install https://repo1.maven.org/maven2/org/lucenia/plugin/lucenia-store-smb/0.1.0/lucenia-store-smb-0.1.0.zip
-> Installing https://repo1.maven.org/maven2/org/lucenia/plugin/lucenia-store-smb/0.1.0/lucenia-store-smb-0.1.0.zip
-> Downloading https://repo1.maven.org/maven2/org/lucenia/plugin/lucenia-store-smb/0.1.0/lucenia-store-smb-0.1.0.zip
[=================================================] 100%
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: plugin requires additional permissions @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
* java.lang.RuntimePermission accessClassInPackage.sun.misc
* java.lang.RuntimePermission accessDeclaredMembers
* java.lang.RuntimePermission getClassLoader
* java.lang.RuntimePermission setContextClassLoader
* java.lang.reflect.ReflectPermission suppressAccessChecks
* java.net.SocketPermission * connect,resolve
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
* javax.management.MBeanServerPermission createMBeanServer
* javax.management.MBeanTrustPermission register
See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
for descriptions of what these permissions allow and the associated risks.
Continue with installation? [y/N]y
-> Installed lucenia-store-smb with folder name lucenia-store-smb
# Zip file in a local directory.
$ sudo ./lucenia-plugin install file:/home/user/lucenia-store-smb-0.1.0.zip
-> Installing file:/home/user/lucenia-store-smb-0.1.0.zip
-> Downloading file:/home/user/lucenia-store-smb-2.2.0.0.zip
[=================================================] 100%
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: plugin requires additional permissions @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
* java.lang.RuntimePermission accessClassInPackage.sun.misc
* java.lang.RuntimePermission accessDeclaredMembers
* java.lang.RuntimePermission getClassLoader
* java.lang.RuntimePermission setContextClassLoader
* java.lang.reflect.ReflectPermission suppressAccessChecks
* java.net.SocketPermission * connect,resolve
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
* javax.management.MBeanServerPermission createMBeanServer
* javax.management.MBeanTrustPermission register
See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
for descriptions of what these permissions allow and the associated risks.
Continue with installation? [y/N]y
-> Installed lucenia-store-smb with folder name lucenia-store-smb
Install a plugin using Maven coordinates
The lucenia-plugin install tool also accepts Maven coordinates for available artifacts and versions hosted on Maven Central. lucenia-plugin will parse the Maven coordinates you provide and construct a URL. As a result, the host must be able to connect directly to Maven Central. The plugin installation will fail if you pass coordinates to a proxy or local repository.
Usage
bin/lucenia-plugin install <groupId>:<artifactId>:<version>
Example
$ sudo ./lucenia-plugin install io.lucenia.plugin:lucenia-store-smb:0.1.0
-> Installing io.lucenia.plugin:lucenia-store-smb:0.1.0
-> Downloading io.lucenia.plugin:lucenia-store-smb:0.1.0 from maven central
[=================================================] 100%
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: plugin requires additional permissions @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
* java.lang.RuntimePermission accessClassInPackage.sun.misc
* java.lang.RuntimePermission accessDeclaredMembers
* java.lang.RuntimePermission getClassLoader
* java.lang.RuntimePermission setContextClassLoader
* java.lang.reflect.ReflectPermission suppressAccessChecks
* java.net.SocketPermission * connect,resolve
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
* javax.management.MBeanServerPermission createMBeanServer
* javax.management.MBeanTrustPermission register
See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
for descriptions of what these permissions allow and the associated risks.
Continue with installation? [y/N]y
-> Installed lucenia-store-smb with folder name lucenia-store-smb
Restart your Lucenia node after installing a plugin.
Installing multiple plugins
Multiple plugins can be installed in a single invocation.
Usage
bin/lucenia-plugin install <plugin-name> <plugin-name> ... <plugin-name>
Example
$ sudo $ ./lucenia-plugin install analysis-nori repository-s3
Remove
You can remove a plugin that has already been installed with the remove option.
Usage
bin/lucenia-plugin remove <plugin-name>
Example
$ sudo $ ./lucenia-plugin remove lucenia-store-smb
-> removing [lucenia-store-smb]...
Restart your Lucenia node after removing a plugin.
Batch mode
When installing plugins that require additional privileges not included by default, the plugins will prompt the user for confirmation of the required privileges. To grant all requested privileges, use batch mode to skip the confirmation prompt.
To force batch mode when installing plugins, add the -b or --batch option:
bin/lucenia-plugin install --batch <plugin-name>
Available plugins
Lucenia provides several plugins provided by Lucenia, Inc. and several written by the community. Source code is available under The Apache Software License v2.0 by visiting the Lucenia Plugin Repo.
Plugin compatibility
A plugin can explicitly specify compatibility with a specific Lucenia version by listing that version in its plugin-descriptor.properties file. For example, a plugin with the following property is compatible only with Lucenia 0.1.0:
lucenia.version=0.1.0
Alternatively, a plugin can specify a range of compatible Lucenia versions by setting the dependencies property in its plugin-descriptor.properties file using one of the following notations:
dependencies={ lucenia: "0.1.0" }: The plugin is compatible only with Lucenia version 0.1.0.dependencies={ lucenia: "=0.1.0" }: The plugin is compatible only with Lucenia version 0.1.0.dependencies={ lucenia: "~0.1.0" }: The plugin is compatible with all versions starting from 0.1.0 up to the next minor version, in this example, 2.4.0 (exclusive).dependencies={ lucenia: "^0.1.0" }: The plugin is compatible with all versions starting from 0.1.0 up to the next major version, in this example, 1.0.0 (exclusive).
You can specify only one of the lucenia.version or dependencies properties.
Bundled plugins
The following plugins are bundled with all Lucenia distributions except for minimum distribution packages.
| Plugin name | Repository | Earliest available version |
|---|---|---|
| Vector | lucenia-vector | 0.2.0 |
| Security | lucenia-security | 0.1.0 |
Additional plugins
Members of the Lucenia community are building countless plugins for the service. Although it isn’t possible to build an exhaustive list of every plugin, since many plugins are not maintained within the Lucenia GitHub repositories, the following list of plugins are available to be installed by name using bin/lucenia-plugin install <plugin-name>.
| Plugin name | Earliest available version |
|---|---|
| analysis-icu | 0.1.0 |
| analysis-kuromoji | 0.1.0 |
| analysis-nori | 0.1.0 |
| analysis-phonetic | 0.1.0 |
| analysis-smartcn | 0.1.0 |
| analysis-stempel | 0.1.0 |
| analysis-ukrainian | 0.1.0 |
| discovery-azure-classic | 0.1.0 |
| discovery-ec2 | 0.1.0 |
| discovery-gce | 0.1.0 |
| ingest-attachment | 0.1.0 |
| mapper-annotated-text | 0.1.0 |
| mapper-murmur3 | 0.1.0 |
| mapper-size | 0.1.0 |
| query-insights | 0.2.0 |
| repository-azure | 0.1.0 |
| repository-gcs | 0.1.0 |
| repository-hdfs | 0.1.0 |
| repository-s3 | 0.1.0 |
| store-smb | 0.1.0 |
| transport-nio | 0.1.0 |