OpenSearch/docs/plugins/store-smb.asciidoc

[[store-smb]]
=== Store SMB Plugin

The Store SMB plugin works around for a bug in Windows SMB and Java on windows.

[[store-smb-install]]
[float]
==== Installation

This plugin can be installed using the plugin manager:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin install store-smb
----------------------------------------------------------------

The plugin must be installed on every node in the cluster, and each node must
be restarted after installation.

This plugin can be downloaded for <<plugin-management-custom-url,offline install>> from
{plugin_url}/store-smb/store-smb-{version}.zip.

[[store-smb-remove]]
[float]
==== Removal

The plugin can be removed with the following command:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin remove store-smb
----------------------------------------------------------------

The node must be stopped before removing the plugin.

[[store-smb-usage]]
==== Working around a bug in Windows SMB and Java on windows

When using a shared file system based on the SMB protocol (like Azure File Service) to store indices, the way Lucene
open index segment files is with a write only flag. This is the _correct_ way to open the files, as they will only be
used for writes and allows different FS implementations to optimize for it. Sadly, in windows with SMB, this disables
the cache manager, causing writes to be slow. This has been described in
https://issues.apache.org/jira/browse/LUCENE-6176[LUCENE-6176], but it affects each and every Java program out there!.
This need and must be fixed outside of ES and/or Lucene, either in windows or OpenJDK. For now, we are providing an
experimental support to open the files with read flag, but this should be considered experimental and the correct way
to fix it is in OpenJDK or Windows.

The Store SMB plugin provides two storage types optimized for SMB:

`smb_mmap_fs`::

    a SMB specific implementation of the default
    {ref}/index-modules-store.html#mmapfs[mmap fs]

`smb_simple_fs`::

    a SMB specific implementation of the default
    {ref}/index-modules-store.html#simplefs[simple fs]

To use one of these specific storage types, you need to install the Store SMB plugin and restart the node.
Then configure Elasticsearch to set the storage type you want.

This can be configured for all indices by adding this to the `elasticsearch.yml` file:

[source,yaml]
----
index.store.type: smb_simple_fs
----

Note that setting will be applied for newly created indices.

It can also be set on a per-index basis at index creation time:

[source,js]
----
PUT my_index
{
   "settings": {
       "index.store.type": "smb_mmap_fs"
   }
}
----
// CONSOLE