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.

core/src/main/java/org/elasticsearch/common/network/NetworkService.java

@@ -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];
     }

distribution/src/main/resources/config/elasticsearch.yml

@@ -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:

docs/reference/modules/network.asciidoc

@@ -1,62 +1,38 @@
 [[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).
-
-Be careful with host configuration! Never expose an unprotected instance
-to the public internet.
-
-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`).
-
-The `network.publish_host` setting allows to control the host the node will
-publish itself within the cluster so other nodes will be able to connect to it.
-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:
+Commonly used network settings:
 
 [cols="<,<",options="header",]
 |=======================================================================
-|Logical Host Setting Value |Description
-|`_local_` |Will be resolved to loopback addresses
+|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_`.
 
-|`_local:ipv4_` |Will be resolved to loopback IPv4 addresses (e.g. 127.0.0.1)
+|`discovery.zen.ping.unicast.hosts`|Initial list other nodes. Can be set to IP addresses or hostnames. Defaults to `["127.0.0.1", "[::1]"]`.
 
-|`_local:ipv6_` |Will be resolved to loopback IPv6 addresses (e.g. ::1)
+|`http.port` |Port to bind for incoming http requests. Can be set to a single value or a range. Defaults to `9200-9300`.
 
-|`_site_` |Will be resolved to site-local addresses ("private network")
+|`transport.tcp.port` |Port to bind for communication between nodes. Can be set to a single value or a range. Defaults to `9300-9400`.
 
-|`_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)
+Be careful with network configuration! Never expose an unprotected instance
+to the public internet.
 
-|`_global_` |Will be resolved to globally-scoped addresses ("publicly reachable")
+[cols="<,<",options="header",]
+|=======================================================================
+|Special Host Value |Description
+|`_[networkInterface]_` |Resolves to the addresses of the provided
+network interface. For example `_en0_`.
 
-|`_global:ipv4_` |Will be resolved to globally-scoped IPv4 addresses (e.g. 8.8.8.8)
+|`_local_` |Will be resolved to loopback addresses (e.g. 127.0.0.1)
 
-|`_global:ipv6_` |Will be resolved to globally-scoped IPv6 addresses (e.g. 2001:4860:4860::8888)
+|`_site_` |Will be resolved to site-local addresses (e.g. 192.168.0.1)
 
-|`_[networkInterface]_` |Resolves to the addresses of the provided
-network interface. For example `_en0_`.
+|`_global_` |Will be resolved to globally-scoped addresses (e.g. 8.8.8.8)
 
-|`_[networkInterface]:ipv4_` |Resolves to the ipv4 addresses of the
-provided network interface. For example `_en0:ipv4_`.
+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`.
 
-|`_[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
@@ -65,10 +41,30 @@ When the `discovery-ec2` plugin is installed, you can use
 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`).
+
+The `network.publish_host` setting allows to control the host the node will
+publish itself within the cluster so other nodes will be able to connect to it.
+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.
+
+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:
 
 [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).
+