mirror of
https://github.com/elastic/logstash.git
synced 2025-04-24 22:57:16 -04:00
2e05338554
This PR changes the behavior of the command when you were specify a directory instead of a filename, if the directory exists it would have deleted the directory and the files in it. The new flow and validation is now safer, if you specify a directory Logstash will tell you to specify a complete filename. If the ZIP extension is missing, the command line will ask you to make sure you target a right filename. If the output file already exist it will *not* delete it but instead will return a warning message, you can force a delete by using the `--overwrite` option. Fixes: #6862 Fixes #6861
142 lines
6.3 KiB
Text
142 lines
6.3 KiB
Text
[[offline-plugins]]
|
|
=== Offline Plugin Management
|
|
|
|
The Logstash <<working-with-plugins,plugin manager>> provides support for preparing offline plugin packs that you can
|
|
use to install Logstash plugins on systems that don't have Internet access.
|
|
|
|
This procedure requires a staging machine running Logstash that has access to a public or
|
|
<<private-rubygem,private Rubygems>> server. The staging machine downloads and packages all the files and dependencies
|
|
required for offline installation.
|
|
|
|
NOTE: If you used offline plugin management prior to Logstash 5.2, you used the `pack` and `unpack` subcommands. Those
|
|
subcommands are now deprecated, but the procedure for using them is still available in the documentation
|
|
<<building-offline-packages-deprecated,here>>.
|
|
|
|
[[building-offline-packs]]
|
|
[float]
|
|
=== Building Offline Plugin Packs
|
|
|
|
An _offline plugin pack_ is a compressed file that contains all the plugins your offline Logstash installation requires,
|
|
along with the dependencies for those plugins.
|
|
|
|
To build an offline plugin pack:
|
|
|
|
. Make sure all the plugins that you want to package are installed on the staging server and that the staging server can
|
|
access the Internet.
|
|
|
|
. Run the `bin/logstash-plugin prepare-offline-pack` subcommand to package the plugins and dependencies:
|
|
+
|
|
[source, shell]
|
|
-------------------------------------------------------------------------------
|
|
bin/logstash-plugin prepare-offline-pack --output OUTPUT [PLUGINS] --overwrite
|
|
-------------------------------------------------------------------------------
|
|
+
|
|
where:
|
|
+
|
|
* `OUTPUT` specifies the zip file where the compressed plugin pack will be written. The default file is
|
|
+/LOGSTASH_HOME/logstash-offline-plugins-{logstash_version}.zip+. If you are using 5.2.x and 5.3.0, this location should be a zip file whose contents will be overwritten.
|
|
* `[PLUGINS]` specifies one or more plugins that you want to include in the pack.
|
|
* `--overwrite` specifies if you want to override an existing file at the location
|
|
|
|
Examples:
|
|
|
|
["source","sh",subs="attributes"]
|
|
-------------------------------------------------------------------------------
|
|
bin/logstash-plugin prepare-offline-pack logstash-input-beats <1>
|
|
bin/logstash-plugin prepare-offline-pack logstash-filter-* <2>
|
|
bin/logstash-plugin prepare-offline-pack logstash-filter-* logstash-input-beats <3>
|
|
-------------------------------------------------------------------------------
|
|
<1> Packages the Beats input plugin and any dependencies.
|
|
<2> Uses a wildcard to package all filter plugins and any dependencies.
|
|
<3> Packages all filter plugins, the Beats input plugin, and any dependencies.
|
|
|
|
NOTE: Downloading all dependencies for the specified plugins may take some time, depending on the plugins listed.
|
|
|
|
[[installing-offline-packs]]
|
|
[float]
|
|
=== Installing Offline Plugin Packs
|
|
|
|
To install an offline plugin pack:
|
|
|
|
. Move the compressed bundle to the machine where you want to install the plugins.
|
|
|
|
. Run the `bin/logstash-plugin install` subcommand to install the packaged plugins:
|
|
+
|
|
["source","sh",subs="attributes"]
|
|
-------------------------------------------------------------------------------
|
|
bin/logstash-plugin install file:///path/to/logstash-offline-plugins-{logstash_version}.zip
|
|
-------------------------------------------------------------------------------
|
|
+
|
|
Where +path/to/logstash-offline-plugins-{logstash_version}.zip+ is the path to the offline plugin pack.
|
|
|
|
[float]
|
|
=== Updating Offline Plugins
|
|
|
|
To update offline plugins, you update the plugins on the staging server and then use the same process that you followed to
|
|
build and install the plugin pack:
|
|
|
|
. On the staging server, run the `bin/logstash-plugin update` subcommand to update the plugins. See <<updating-plugins>>.
|
|
|
|
. Create a new version of the plugin pack. See <<building-offline-packs>>.
|
|
|
|
. Install the new version of the plugin pack. See <<installing-offline-packs>>.
|
|
|
|
|
|
[[building-offline-packages-deprecated]]
|
|
[float]
|
|
=== Building the Offline Package (Deprecated Procedure)
|
|
|
|
deprecated[5.2, Starting with Logstash 5.2, the `pack` and `unpack` commands are deprecated and replaced by the `prepare-offline-pack` and `install` commands]
|
|
|
|
Working with offline plugins requires you to create an _offline package_, which is a compressed file that contains all of
|
|
the plugins your offline Logstash installation requires, along with the dependencies for those plugins.
|
|
|
|
. Create the offline package with the `bin/logstash-plugin pack` subcommand.
|
|
+
|
|
When you run the `bin/logstash-plugin pack` subcommand, Logstash creates a compressed bundle that contains all of the currently
|
|
installed plugins and the dependencies for those plugins. By default, the compressed bundle is a GZipped TAR file when you
|
|
run the `bin/logstash-plugin pack` subcommand on a UNIX machine. By default, when you run the `bin/logstash-plugin pack` subcommand on a
|
|
Windows machine, the compressed bundle is a ZIP file. See <<managing-packs,Managing Plugin Packs>> for details on changing
|
|
these default behaviors.
|
|
+
|
|
NOTE: Downloading all dependencies for the specified plugins may take some time, depending on the plugins listed.
|
|
|
|
. Move the compressed bundle to the offline machines that are the source for offline plugin installation, then use the
|
|
`bin/logstash-plugin unpack` subcommand to make the packaged plugins available.
|
|
|
|
[float]
|
|
=== Install or Update a local plugin (Deprecated Procedure)
|
|
|
|
deprecated[5.2]
|
|
|
|
To install or update a local plugin, use the `--local` option with the install and update commands, as in the following
|
|
examples:
|
|
|
|
.Installing a local plugin
|
|
============
|
|
`bin/logstash-plugin install --local logstash-input-jdbc`
|
|
============
|
|
|
|
.Updating a local plugin
|
|
============
|
|
`bin/logstash-plugin update --local logstash-input-jdbc`
|
|
============
|
|
|
|
.Updating all local plugins in one command
|
|
============
|
|
`bin/logstash-plugin update --local`
|
|
============
|
|
|
|
[float]
|
|
[[managing-packs]]
|
|
=== Managing Plugin Packs
|
|
|
|
deprecated[5.2]
|
|
|
|
The `pack` and `unpack` subcommands for `bin/logstash-plugin` take the following options:
|
|
|
|
[horizontal]
|
|
`--tgz`:: Generate the offline package as a GZipped TAR file. The default behavior on UNIX systems.
|
|
`--zip`:: Generate the offline package as a ZIP file. The default behavior on Windows systems.
|
|
`[packname] --override`:: Generates a new offline package that overwrites an existing offline with the specified name.
|
|
`[packname] --[no-]clean`: Deletes offline packages matching the specified name.
|