Improvements to network docs

docs/reference/index.asciidoc

@@ -7,6 +7,7 @@
 :jdk:           1.8.0_25
 :defguide:      https://www.elastic.co/guide/en/elasticsearch/guide/current
 :plugins:       https://www.elastic.co/guide/en/elasticsearch/plugins/master
+:javaclient:    https://www.elastic.co/guide/en/elasticsearch/client/java-api/master/
 :issue:         https://github.com/elastic/elasticsearch/issues/
 :pull:          https://github.com/elastic/elasticsearch/pull/
 

docs/reference/modules/network.asciidoc

@@ -1,102 +1,175 @@
 [[modules-network]]
-== Basic Settings
+== Network Settings
 
-Commonly used network settings:
+Elasticsearch binds to localhost only by default.  This is sufficient for you
+to run a local development server (or even a development cluster, if you start
+multiple nodes on the same machine), but you will need to configure some
+<<common-network-settings,basic network settings>> in order to run a real
+production cluster across multiple servers.
 
-[cols="<,<",options="header",]
-|=======================================================================
-|Name |Description
-|`network.host` |Host to bind and publish to other nodes. Accepts an IP address, hostname, or special value (see table below). Defaults to `_local_`.
+[WARNING]
+.Be careful with the network configuration!
+=============================
+Never expose an unprotected node to the public internet.
+=============================
 
-|`discovery.zen.ping.unicast.hosts`|Initial list of other nodes. Accepts IP addresses or hostnames. Defaults to `["127.0.0.1", "[::1]"]`.
+[float]
+[[common-network-settings]]
+=== Commonly Used Network Settings
+
+`network.host`::
+
+The node will bind to this hostname or IP address and _publish_ (advertise)
+this host to other nodes in the cluster. Accepts an IP address, hostname, or a
+<<network-interface-values,special value>>.
++
+Defaults to `_local_`.
+
+`discovery.zen.ping.unicast.hosts`::
 
-|`http.port` |Port to bind for incoming http requests. Accepts a single value or a range. Defaults to `9200-9300`.
+In order to join a cluster, a node needs to know the hostname or IP address of
+at least some of the other nodes in the cluster.  This settting provides the
+initial list of other nodes that this node will try to contact. Accepts IP
+addresses or hostnames.
++
+Defaults to `["127.0.0.1", "[::1]"]`.
 
-|`transport.tcp.port` |Port to bind for communication between nodes. Accepts a single value or a range. Defaults to `9300-9400`.
-|=======================================================================
+`http.port`::
 
-Be careful with network configuration! Never expose an unprotected instance
-to the public internet.
+Port to bind to for incoming HTTP requests. Accepts a single value or a range.
+If a range is specified, the node will bind to the first available port in the
+range.
++
+Defaults to `9200-9300`.
+
+`transport.tcp.port`::
+
+Port to bind for communication between nodes. Accepts a single value or a
+range. If a range is specified, the node will bind to the first available port
+in the range.
++
+Defaults to `9300-9400`.
 
 [float]
-[[special-values]]
+[[network-interface-values]]
 === Special values for `network.host`
 
-[cols="<,<",options="header",]
-|=======================================================================
-|Special Host Value |Description
-|`_[networkInterface]_` |Addresses of a network interface, for example `_en0_`.
+The following special values may be passed to `network.host`:
+
+[horizontal]
+`_[networkInterface]_`::
 
-|`_local_` |Any loopback addresses on the system, for example `127.0.0.1`.
+  Addresses of a network interface, for example `_en0_`.
 
-|`_site_` |Any site-local addresses on the system, for example `192.168.0.1`.
+`_local_`::
 
-|`_global_` |Any globally-scoped addresses on the system, for example `8.8.8.8`.
-|=======================================================================
+  Any loopback addresses on the system, for example `127.0.0.1`.
 
-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`.
+`_site_`::
 
-When the `discovery-ec2` plugin is installed, you can use
-{plugins}/discovery-ec2-discovery.html#discovery-ec2-network-host[ec2 specific host settings].
+  Any site-local addresses on the system, for example `192.168.0.1`.
+
+`_global_`::
+
+  Any globally-scoped addresses on the system, for example `8.8.8.8`.
 
-When the `discovery-gce` plugin is installed, you can use
-{plugins}/discovery-gce-network-host.html[gce specific host settings].
 
 [float]
-[[advanced]]
+==== IPv4 vs IPv6
+
+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`.
+
+[TIP]
+.Discovery in the cloud
+================================
+
+More special settings are available when running in the cloud with either the
+{plugins}/discovery-ec2-discovery.html#discovery-ec2-network-host[EC2 discovery plugin] or the
+{plugins}/discovery-gce-network-host.html#discovery-gce-network-host[Google Compute Engine discovery plugin]
+installed.
+
+================================
+
+[float]
+[[advanced-network-settings]]
 === 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.host` setting explained in <<common-network-settings,Commonly used network settings>>
+is a shortcut which sets the _bind host_ and the _publish host_ at the same
+time. In advanced used cases, such as when running behind a proxy server, you
+may need to set these settings to different values:
+
+`network.bind_host`::
 
-`network.bind_host` sets the host different network
-components will bind on.
+This specifies which network interface(s) a node should bind to in order to
+listen for incoming requests.  A node can bind to multiple interfaces, e.g.
+two network cards, or a site-local address and a local address. Defaults to
+`network.host`.
 
-`network.publish_host` sets 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.
+`network.publish_host`::
 
-Both settings can be configured just like `network.host`: they accept ip
-addresses, host names, and special values.
+The publish host is the single interface that the node advertises to other
+nodes in the cluster, so that those nodes can 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 of the above settings can be configured just like `network.host` -- they
+accept IP addresses, host names, and
+<<network-interface-values,special values>>.
 
 [float]
 [[tcp-settings]]
 === Advanced TCP Settings
 
-Any component that uses TCP (like the HTTP, Transport and Memcached)
-share the following allowed settings:
+Any component that uses TCP (like the <<modules-http,HTTP>> and
+<<modules-transport,Transport>> modules) share the following settings:
+
+[horizontal]
+`network.tcp.no_delay`::
 
-[cols="<,<",options="header",]
-|=======================================================================
-|Setting |Description
-|`network.tcp.no_delay` |Enable or disable tcp no delay setting.
+Enable or disable the https://en.wikipedia.org/wiki/Nagle%27s_algorithm[TCP no delay]
+setting. Defaults to `true`.
+
+`network.tcp.keep_alive`::
+
+Enable or disable https://en.wikipedia.org/wiki/Keepalive[TCP keep alive].
 Defaults to `true`.
 
-|`network.tcp.keep_alive` |Enable or disable tcp keep alive. Defaults
-to `true`.
+`network.tcp.reuse_address`::
+
+Should an address be reused or not. Defaults to `true` on non-windows
+machines.
 
-|`network.tcp.reuse_address` |Should an address be reused or not.
-Defaults to `true` on non-windows machines.
+`network.tcp.send_buffer_size`::
 
-|`network.tcp.send_buffer_size` |The size of the tcp send buffer size
-(in size setting format). By default not explicitly set.
+The size of the TCP send buffer (specified with <<size-units,size units>>).
+By default not explicitly set.
 
-|`network.tcp.receive_buffer_size` |The size of the tcp receive buffer
-size (in size setting format). By default not explicitly set.
-|=======================================================================
+`network.tcp.receive_buffer_size`::
+
+The size of the TCP receive buffer (specified with <<size-units,size units>>).
+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).
+=== Transport and HTTP protocols
+
+An Elasticsearch node exposes two network protocols which inherit the above
+settings, but may be further configured independently:
+
+TCP Transport::
+
+Used for communication between nodes in the cluster and by the Java
+{javaclient}/node-client.html[Node client],
+{javaclient}/transport-client.html[Transport client], and by the
+<<modules-tribe,Tribe node>>.  See the <<modules-transport,Transport module>>
+for more information.
+
+HTTP::
+
+Exposes the JSON-over-HTTP interface used by all clients other than the Java
+clients. See the <<modules-http,HTTP module>> for more information.