mirror of
https://github.com/elastic/logstash.git
synced 2025-04-24 22:57:16 -04:00
136 lines
4.7 KiB
Text
136 lines
4.7 KiB
Text
[[working-with-plugins]]
|
||
== Working with plugins
|
||
|
||
Logstash has a rich collection of input, filter, codec and output plugins. Plugins are available as self-contained
|
||
packages called gems and hosted on RubyGems.org. The plugin manager accessed via `bin/logstash-plugin` script is used to manage the
|
||
lifecycle of plugins in your Logstash deployment. You can install, remove and upgrade plugins using the Command Line
|
||
Interface (CLI) invocations described below.
|
||
|
||
[float]
|
||
[[http-proxy]]
|
||
=== Proxy configuration
|
||
|
||
The majority of the plugin manager commands require access to the internet to reach https://rubygems.org[RubyGems.org].
|
||
If your organization is behind a firewall you can set these environments variables to configure Logstash to use your proxy.
|
||
|
||
[source, shell]
|
||
----------------------------------
|
||
export http_proxy=http://localhost:3128
|
||
export https_proxy=http://localhost:3128
|
||
----------------------------------
|
||
|
||
[float]
|
||
[[listing-plugins]]
|
||
=== Listing plugins
|
||
|
||
Logstash release packages bundle common plugins so you can use them out of the box. To list the plugins currently
|
||
available in your deployment:
|
||
|
||
[source,shell]
|
||
----------------------------------
|
||
bin/logstash-plugin list <1>
|
||
bin/logstash-plugin list --verbose <2>
|
||
bin/logstash-plugin list '*namefragment*' <3>
|
||
bin/logstash-plugin list --group output <4>
|
||
----------------------------------
|
||
<1> Will list all installed plugins
|
||
|
||
<2> Will list installed plugins with version information
|
||
|
||
<3> Will list all installed plugins containing a namefragment
|
||
|
||
<4> Will list all installed plugins for a particular group (input, filter, codec, output)
|
||
|
||
[float]
|
||
[[installing-plugins]]
|
||
=== Adding plugins to your deployment
|
||
|
||
The most common situation when dealing with plugin installation is when you have access to internet. Using this method,
|
||
you will be able to retrieve plugins hosted on the public repository (RubyGems.org) and install on top of your Logstash
|
||
installation.
|
||
|
||
[source,shell]
|
||
----------------------------------
|
||
bin/logstash-plugin install logstash-output-kafka
|
||
----------------------------------
|
||
|
||
Once the plugin is successfully installed, you can start using it in your configuration file.
|
||
|
||
[[installing-local-plugins]]
|
||
[float]
|
||
==== Advanced: Adding a locally built plugin
|
||
|
||
In some cases, you want to install plugins which have not yet been released and not hosted on RubyGems.org. Logstash
|
||
provides you the option to install a locally built plugin which is packaged as a ruby gem. Using a file location:
|
||
|
||
[source,shell]
|
||
----------------------------------
|
||
bin/logstash-plugin install /path/to/logstash-output-kafka-1.0.0.gem
|
||
----------------------------------
|
||
|
||
[[installing-local-plugins-path]]
|
||
[float]
|
||
==== Advanced: Using `--path.plugins`
|
||
|
||
Using the Logstash `--path.plugins` flag, you can load a plugin source code located on your file system. Typically this is used by
|
||
developers who are iterating on a custom plugin and want to test it before creating a ruby gem.
|
||
|
||
The path needs to be in a specific directory hierarchy: `PATH/logstash/TYPE/NAME.rb`, where TYPE is 'inputs' 'filters', 'outputs' or 'codecs' and NAME is the name of the plugin.
|
||
|
||
[source,shell]
|
||
----------------------------------
|
||
# supposing the code is in /opt/shared/lib/logstash/inputs/my-custom-plugin-code.rb
|
||
bin/logstash --path.plugins /opt/shared/lib
|
||
----------------------------------
|
||
|
||
[[updating-plugins]]
|
||
[float]
|
||
=== Updating plugins
|
||
|
||
Plugins have their own release cycle and are often released independent of Logstash’s core release cycle. Using the update
|
||
subcommand you can get the latest version of the plugin.
|
||
|
||
[source,shell]
|
||
----------------------------------
|
||
bin/logstash-plugin update <1>
|
||
bin/logstash-plugin update logstash-output-kafka <2>
|
||
----------------------------------
|
||
<1> will update all installed plugins
|
||
|
||
<2> will update only this plugin
|
||
|
||
[[removing-plugins]]
|
||
[float]
|
||
=== Removing plugins
|
||
|
||
If you need to remove plugins from your Logstash installation:
|
||
|
||
[source,shell]
|
||
----------------------------------
|
||
bin/logstash-plugin remove logstash-output-kafka
|
||
----------------------------------
|
||
|
||
[[proxy-plugins]]
|
||
[float]
|
||
=== Proxy Support
|
||
|
||
The previous sections relied on Logstash being able to communicate with RubyGems.org. In certain environments, Forwarding
|
||
Proxy is used to handle HTTP requests. Logstash Plugins can be installed and updated through a Proxy by setting the
|
||
`HTTP_PROXY` environment variable:
|
||
|
||
[source,shell]
|
||
----------------------------------
|
||
export HTTP_PROXY=http://127.0.0.1:3128
|
||
|
||
bin/logstash-plugin install logstash-output-kafka
|
||
----------------------------------
|
||
|
||
Once set, plugin commands install, update can be used through this proxy.
|
||
|
||
include::plugin-generator.asciidoc[]
|
||
|
||
include::offline-plugins.asciidoc[]
|
||
|
||
include::private-gem-repo.asciidoc[]
|
||
|
||
include::event-api.asciidoc[]
|