=rem #15007 add ability to bind to a different address than the remoting waits messages from

This can be used to traverse NATs with the following configuration:

akka.remote.netty.tcp {
  ...
  hostname = my-external-address.lt
  bind-hostname = 192.168.1.100
}

Use Akka BoundAddressesExtension to get bound addresses

akka-docs/rst/additional/faq.rst

@@ -111,7 +111,7 @@ Observe all the parts you need here:
 * ``system`` is the remote system’s name (must match exactly, case-sensitive!)
 
 * ``host`` is the remote system’s IP address or DNS name, and it must match that
-  system’s configuration (i.e. `akka.remote.netty.hostname`)
+  system’s configuration (i.e. `akka.remote.netty.tcp.hostname`)
 
 * ``1234`` is the port number on which the remote system is listening for
   connections and receiving messages
@@ -131,6 +131,14 @@ The most common reason is that the local system’s name (i.e. the
 system’s network location, e.g. because ``host`` was configured to be ``0.0.0.0``,
 ``localhost`` or a NAT’ed IP address.
 
+If you are running an ActorSystem under a NAT or inside a docker container, make sure to
+set `akka.remote.netty.tcp.hostname` and `akka.remote.netty.tcp.port` to the address
+it is reachable at from other ActorSystems. If you need to bind your network interface
+to a different address - use `akka.remote.netty.tcp.bind-hostname` and
+`akka.remote.netty.tcp.bind-port` settings. Also make sure your network is configured
+to translate from the address your ActorSystem is reachable at to the address your
+ActorSystem network interface is bound to.
+
 How reliable is the message delivery?
 -------------------------------------
 

akka-docs/rst/general/remoting.rst

@@ -52,6 +52,8 @@ be set to a specific :class:`Deploy` instance; this has the same effect as
 putting an equivalent deployment into the configuration file (if both are
 given, configuration file wins).
 
+.. _symmetric-communication:
+
 Peer-to-Peer vs. Client-Server
 ------------------------------
 
@@ -65,12 +67,27 @@ design decisions:
    is no system that only accepts connections, and there is no system that only initiates connections.
    
 The consequence of these decisions is that it is not possible to safely create
-pure client-server setups with predefined roles (violates assumption 2) and
-using setups involving Network Address Translation or Load Balancers (violates
-assumption 1).
-
+pure client-server setups with predefined roles (violates assumption 2).
 For client-server setups it is better to use HTTP or Akka I/O.
 
+Using setups involving Network Address Translation, Load Balancers or Docker
+containers violates assumption 1, unless additional steps are taken in the
+network configuration to allow symmetric communication between involved systems.
+In such situations Akka can be configured to bind to a different network
+address than the one used for establishing connections between Akka nodes::
+
+  akka {
+    remote {
+      netty.tcp {
+        hostname = my.domain.com      # external (logical) hostname
+        port = 8000                   # external (logical) port
+
+        bind-hostname = local.address # internal (bind) hostname
+        bind-port = 2552              # internal (bind) port
+      }
+   }
+  }
+
 Marking Points for Scaling Up with Routers
 ------------------------------------------
 

akka-docs/rst/java/remoting.rst

@@ -10,8 +10,10 @@ For an introduction of remoting capabilities of Akka please see :ref:`remoting`.
 
   As explained in that chapter Akka remoting is designed for communication in a
   peer-to-peer fashion and it has limitations for client-server setups. In
-  particular Akka Remoting does not work with Network Address Translation and
-  Load Balancers, among others.
+  particular Akka Remoting does not work transparently with Network Address Translation,
+  Load Balancers, or in Docker containers. For symmetric communication in these situations
+  network and/or Akka configuration will have to be changed as described in
+  :ref:`symmetric-communication`.
 
 Preparing your ActorSystem for Remoting
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

akka-docs/rst/scala/remoting.rst

@@ -4,16 +4,16 @@
  Remoting
 ##########
 
-
 For an introduction of remoting capabilities of Akka please see :ref:`remoting`.
 
 .. note::
 
   As explained in that chapter Akka remoting is designed for communication in a
   peer-to-peer fashion and it has limitations for client-server setups. In
-  particular Akka Remoting does not work with Network Address Translation and
-  Load Balancers, among others.
-
+  particular Akka Remoting does not work transparently with Network Address Translation,
+  Load Balancers, or in Docker containers. For symmetric communication in these situations
+  network and/or Akka configuration will have to be changed as described in
+  :ref:`symmetric-communication`.
 
 Preparing your ActorSystem for Remoting
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^