OpenSearch/docs/plugins/discovery-file.asciidoc

[[discovery-file]]
=== File-Based Discovery Plugin

The file-based discovery plugin uses a list of hosts/ports in a `unicast_hosts.txt` file 
in the `config/discovery-file` directory for unicast discovery.

[[discovery-file-install]]
[float]
==== Installation

This plugin can be installed using the plugin manager:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin install discovery-file
----------------------------------------------------------------

The plugin must be installed on every node in the cluster, and each node must
be restarted after installation. Note that installing the plugin will add a
`discovery-file` directory to the `config` folder, and a default `unicast_hosts.txt`
file that must be edited with the correct unicast hosts list before starting the node.

[[discovery-file-remove]]
[float]
==== Removal

The plugin can be removed with the following command:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin remove discovery-file
----------------------------------------------------------------

The node must be stopped before removing the plugin.

[[discovery-file-usage]]
[float]
==== Using the file-based discovery plugin

The file-based discovery plugin provides the ability to specify the 
unicast hosts list through a simple `unicast_hosts.txt` file that can
be dynamically updated at any time. To enable, add the following in `elasticsearch.yml`:

[source,yaml]
----
discovery.zen.hosts_provider: file
----

This plugin simply provides a facility to supply the unicast hosts list for
zen discovery through an external file that can be updated at any time by a side process.  

For example, this gives a convenient mechanism for an Elasticsearch instance 
that is  run in docker containers to be dynamically supplied a list of IP 
addresses to connect to for zen discovery when those IP addresses may not be 
known at node startup.  

Note that the file-based discovery plugin is meant to augment the unicast
hosts list in `elasticsearch.yml` (if specified), not replace it.  Therefore,
if there are valid unicast host entries in `discovery.zen.ping.unicast.hosts`,
they will be used in addition to those supplied in `unicast_hosts.txt`.

Anytime a change is made to the `unicast_hosts.txt` file, even as Elasticsearch
continues to run, the new changes will be picked up by the plugin and the
new hosts list will be used for the next pinging round for master election.

Upon installation of the plugin, a default `unicast_hosts.txt` file will
be found in the `$CONFIG_DIR/discovery-file` directory.  This default file
will contain some comments about what the file should contain.  All comments
for this file must appear on their lines starting with `#` (i.e. comments
cannot start in the middle of a line).

[[discovery-file-format]]
[float]
==== unicast_hosts.txt file format

The format of the file is to specify one unicast host entry per line.  
Each unicast host entry consists of the host (host name or IP address) and
an optional transport port number.  If the port number is specified, is must 
come immediately after the host (on the same line) separated by a `:`. 
If the port number is not specified, a default value of 9300 is used.  

For example, this is an example of `unicast_hosts.txt` for a cluster with
four nodes that participate in unicast discovery, some of which are not
running on the default port:

[source,txt]
----------------------------------------------------------------
10.10.10.5
10.10.10.6:9305
10.10.10.5:10005
# an IPv6 address
[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:9301
----------------------------------------------------------------

Host names are allowed instead of IP addresses (similar to 
`discovery.zen.ping.unicast.hosts`), and IPv6 addresses must be
specified in brackets with the port coming after the brackets.