From 151d50f875bf9d209118acee9f03566f8d4fdc0f 2013-04-28 05:48:28
From: MinRK <benjaminrk@gmail.com>
Date: 2013-04-28 05:48:28
Subject: [PATCH] add note about `--location` around `--ip=*` in parallel docs
---

diff --git a/docs/source/parallel/parallel_intro.txt b/docs/source/parallel/parallel_intro.txt
index 86031c4..e9d3dff 100644
--- a/docs/source/parallel/parallel_intro.txt
+++ b/docs/source/parallel/parallel_intro.txt
@@ -213,7 +213,7 @@ need to use ssh tunnels to connect clients from your laptop to it.  You will als
 probably need to instruct the controller to listen for engines coming from other work nodes
 on the cluster.  An example of ipcontroller-client.json, as created by::
 
-    $> ipcontroller --ip=0.0.0.0 --ssh=login.mycluster.com
+    $> ipcontroller --ip=* --ssh=login.mycluster.com
 
 
 .. sourcecode:: python
diff --git a/docs/source/parallel/parallel_process.txt b/docs/source/parallel/parallel_process.txt
index 8e9e92c..d908459 100644
--- a/docs/source/parallel/parallel_process.txt
+++ b/docs/source/parallel/parallel_process.txt
@@ -33,15 +33,28 @@ the ``ip`` argument on the command-line, or the ``HubFactory.ip`` configurable i
 :file:`ipcontroller_config.py`.
 
 If your machines are on a trusted network, you can safely instruct the controller to listen
-on all public interfaces with::
+on all interfaces with::
 
     $> ipcontroller --ip=*
 
+
 Or you can set the same behavior as the default by adding the following line to your :file:`ipcontroller_config.py`:
 
 .. sourcecode:: python
 
     c.HubFactory.ip = '*'
+    # c.HubFactory.location = '10.0.1.1'
+
+
+.. note::
+
+    ``--ip=*`` instructs ZeroMQ to listen on all interfaces,
+    but it does not contain the IP needed for engines / clients
+    to know where the controller actually is.
+    This can be specified with ``--location=10.0.0.1``,
+    the specific IP address of the controller, as seen from engines and/or clients.
+    IPython tries to guess this value by default, but it will not always guess correctly.
+    Check the ``location`` field in your connection files if you are having connection trouble.
 
 .. note::
 
@@ -718,7 +731,11 @@ through the login node, an example :file:`ipcontroller_config.py` might contain:
     c.HubFactory.location = '10.0.1.5'
     # or to get an automatic value, try this:
     import socket
-    ex_ip = socket.gethostbyname_ex(socket.gethostname())[-1][0]
+    hostname = socket.gethostname()
+    # alternate choices for hostname include `socket.getfqdn()`
+    # or `socket.gethostname() + '.local'`
+    
+    ex_ip = socket.gethostbyname_ex(hostname)[-1][-1]
     c.HubFactory.location = ex_ip
     
     # now instruct clients to use the login node for SSH tunnels: