honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve network docs 

This makes some minor improvements (does not fix all problems!)

It reorders unicast disco in elasticsearch.yml to be right after the network host,
for better locality.

It removes the warning (unreleased) about publish addresses, lets try to really discourage setting
that unless you need to (behind a proxy server). Most people should be fine with `network.host`

Finally it reorganizes the network docs page a bit:

We add a table of 4 "basic" settings at the very beginning:

* network.host
* discovery.zen.ping.unicast.hosts
* http.port
* transport.tcp.port

The first two being the most important, which addresses to bind and talk to, and the other two
being the port numbers.

The rest of the stuff I tried to simplify and reorder under "advanced" headers.

This is just a quick stab, I still think we need more effort into this thing, but we gotta start somewhere.
This commit is contained in:
Robert Muir 2015-12-09 13:22:14 -05:00 committed by Clinton Gormley
parent 79cdc40afe
commit 7595c4a3c8
3 changed files with 69 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
core/src/main/java/org/elasticsearch/common/network/NetworkService.java
View File

@ -137,8 +137,7 @@ public class NetworkService extends AbstractComponent {
* Resolves {@code publishHosts} to a single publish address. The fact that it returns
* only one address is just a current limitation.
* <p>
* If {@code publishHosts} resolves to more than one address, <b>then one is selected with magic</b>,
* and the user is warned (they can always just be more specific).
* If {@code publishHosts} resolves to more than one address, <b>then one is selected with magic</b>
* @param publishHosts list of hosts to publish as. this may contain special pseudo-hostnames
* such as _local_ (see the documentation). if it is null, it will be populated
* based on global default settings.
@ -186,13 +185,12 @@ public class NetworkService extends AbstractComponent {
}
}
// 3. warn user if we end out with multiple publish addresses
// 3. if we end out with multiple publish addresses, select by preference.
// don't warn the user, or they will get confused by bind_host vs publish_host etc.
if (addresses.length > 1) {
List<InetAddress> sorted = new ArrayList<>(Arrays.asList(addresses));
NetworkUtils.sortAddresses(sorted);
addresses = new InetAddress[] { sorted.get(0) };
logger.warn("publish host: {} resolves to multiple addresses, auto-selecting {{}} as single publish address",
Arrays.toString(publishHosts), NetworkAddress.format(addresses[0]));
}
return addresses[0];
}

20
distribution/src/main/resources/config/elasticsearch.yml
View File

@ -60,19 +60,8 @@
# For more information, see the documentation at:
# <http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-network.html>
#
# ---------------------------------- Gateway -----------------------------------
#
# Block initial recovery after a full cluster restart until N nodes are started:
#
# gateway.recover_after_nodes: 3
#
# For more information, see the documentation at:
# <http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-gateway.html>
#
# --------------------------------- Discovery ----------------------------------
#
# Elasticsearch nodes will find each other via unicast, by default.
#
# Pass an initial list of hosts to perform discovery when new node is started:
# The default list of hosts is ["127.0.0.1", "[::1]"]
#
@ -85,6 +74,15 @@
# For more information, see the documentation at:
# <http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery.html>
#
# ---------------------------------- Gateway -----------------------------------
#
# Block initial recovery after a full cluster restart until N nodes are started:
#
# gateway.recover_after_nodes: 3
#
# For more information, see the documentation at:
# <http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-gateway.html>
#
# ---------------------------------- Various -----------------------------------
#
# Disable starting multiple nodes on a single system:

107
docs/reference/modules/network.asciidoc
View File

@ -1,16 +1,53 @@
[[modules-network]]
== Network Settings
== Basic Settings
There are several modules within a Node that use network based
configuration, for example, the
<<modules-transport,transport>> and
<<modules-http,http>> modules. Node level
network settings allows to set common settings that will be shared among
all network based modules (unless explicitly overridden in each module).
Commonly used network settings:
Be careful with host configuration! Never expose an unprotected instance
[cols="<,<",options="header",]
|=======================================================================
|Name |Description
|`network.host` |Host to bind and publish to other nodes. Can be set to an IP address, hostname, or special value (see table below). Defaults to `_local_`.
|`discovery.zen.ping.unicast.hosts`|Initial list other nodes. Can be set to IP addresses or hostnames. Defaults to `["127.0.0.1", "[::1]"]`.
|`http.port` |Port to bind for incoming http requests. Can be set to a single value or a range. Defaults to `9200-9300`.
|`transport.tcp.port` |Port to bind for communication between nodes. Can be set to a single value or a range. Defaults to `9300-9400`.
Be careful with network configuration! Never expose an unprotected instance
to the public internet.
[cols="<,<",options="header",]
|=======================================================================
|Special Host Value |Description
|`_[networkInterface]_` |Resolves to the addresses of the provided
network interface. For example `_en0_`.
|`_local_` |Will be resolved to loopback addresses (e.g. 127.0.0.1)
|`_site_` |Will be resolved to site-local addresses (e.g. 192.168.0.1)
|`_global_` |Will be resolved to globally-scoped addresses (e.g. 8.8.8.8)
These special values will work over both IPv4 and IPv6 by default,
but you can also limit this with the use of `:ipv4` of `:ipv6` specifiers, for
example `_en0:ipv4_` would only bind to the ipv4 addresses of interface `en0`.
|=======================================================================
When the `discovery-ec2` plugin is installed, you can use
{plugins}/discovery-ec2-discovery.html#discovery-ec2-network-host[ec2 specific host settings].
When the `discovery-gce` plugin is installed, you can use
{plugins}/discovery-gce-network-host.html[gce specific host settings].
[float]
[[advanced]]
=== Advanced network settings
`network.bind_host` and `network.publish_host` can be set instead of `network.host`
for advanced cases such as when behind a proxy server.
The `network.bind_host` setting allows to control the host different network
components will bind on. By default, the bind host will be `_local_`
(loopback addresses such as `127.0.0.1`, `::1`).
@ -21,54 +58,13 @@ Currently an elasticsearch node may be bound to multiple addresses, but only
publishes one. If not specified, this defaults to the "best" address from
`network.bind_host`, sorted by IPv4/IPv6 stack preference, then by reachability.
The `network.host` setting is a simple setting to automatically set both
`network.bind_host` and `network.publish_host` to the same host value.
Both settings allows to be configured with either explicit host address(es)
or host name(s). The settings also accept logical setting value(s) explained
in the following table:
[cols="<,<",options="header",]
|=======================================================================
|Logical Host Setting Value |Description
|`_local_` |Will be resolved to loopback addresses
|`_local:ipv4_` |Will be resolved to loopback IPv4 addresses (e.g. 127.0.0.1)
|`_local:ipv6_` |Will be resolved to loopback IPv6 addresses (e.g. ::1)
|`_site_` |Will be resolved to site-local addresses ("private network")
|`_site:ipv4_` |Will be resolved to site-local IPv4 addresses (e.g. 192.168.0.1)
|`_site:ipv6_` |Will be resolved to site-local IPv6 addresses (e.g. fec0::1)
|`_global_` |Will be resolved to globally-scoped addresses ("publicly reachable")
|`_global:ipv4_` |Will be resolved to globally-scoped IPv4 addresses (e.g. 8.8.8.8)
|`_global:ipv6_` |Will be resolved to globally-scoped IPv6 addresses (e.g. 2001:4860:4860::8888)
|`_[networkInterface]_` |Resolves to the addresses of the provided
network interface. For example `_en0_`.
|`_[networkInterface]:ipv4_` |Resolves to the ipv4 addresses of the
provided network interface. For example `_en0:ipv4_`.
|`_[networkInterface]:ipv6_` |Resolves to the ipv6 addresses of the
provided network interface. For example `_en0:ipv6_`.
|=======================================================================
When the `discovery-ec2` plugin is installed, you can use
{plugins}/discovery-ec2-discovery.html#discovery-ec2-network-host[ec2 specific host settings].
When the `discovery-gce` plugin is installed, you can use
{plugins}/discovery-gce-network-host.html[gce specific host settings].
[float]
[[tcp-settings]]
=== TCP Settings
=== Advanced TCP Settings
Any component that uses TCP (like the HTTP, Transport and Memcached)
share the following allowed settings:
@ -92,3 +88,14 @@ Defaults to `true` on non-windows machines.
size (in size setting format). By default not explicitly set.
|=======================================================================
[float]
[[module-settings]]
=== Module-specific Settings
There are several modules within a Node that use network based
configuration, for example, the
<<modules-transport,transport>> and
<<modules-http,http>> modules. Node level
network settings allows to set common settings that will be shared among
all network based modules (unless explicitly overridden in each module).