[[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.
