Added documentation page about running Locust distributed

docs/index.rst

@@ -29,6 +29,7 @@ Locust Documentation
 .. toctree ::
     :maxdepth: 1
     
+    running-locust-distributed
     testing-other-systems
     api
     extending-locust

docs/running-locust-distributed.rst

@@ -0,0 +1,73 @@
+===========================
+Running Locust distributed
+===========================
+
+Once a single machine isn't enough to simulate the number of users that you need, Locust supports 
+running load tests distributed across multiple machines. 
+
+To do this, you start one instance of Locust in master mode using the ``--master`` flag. This is 
+the instance that will be running Locust's web interface where you start the test and see live 
+statistics. The master node doesn't simulate any users itself. Instead you have to start one or 
+- most likely - multiple slave Locust nodes using the ``--slave`` flag, together with the 
+``--master-host`` (to specify the IP/hostname of the master node).
+
+A common set up is to run a single master on one machine, and then run one slave instance per 
+processor core, on the slave machines.
+
+.. note::
+    Both the master and each slave machine, must have a copy of the locust test scripts 
+    when running Locust distributed.
+
+
+Example
+=======
+
+To start locust in master mode::
+
+    locust -f my_locustfile.py --master
+
+And then on each slave (replace ``192.168.0.14`` with IP of the master machine)::
+
+    locust -f my_locustfile.py --slave --master-host=192.168.0.14
+
+
+Options
+=======
+
+``--master``
+------------
+
+Sets locust in master mode. The web interface will run on this node.
+
+
+``--slave``
+-----------
+
+Sets locust in slave mode.
+
+
+``--master-host=X.X.X.X``
+-------------------------
+
+Optionally used together with ``--slave`` to set the hostname/IP of the master node (defaults 
+to 127.0.0.1)
+
+``--master-port=5557``
+----------------------
+
+Optionally used together with ``--slave`` to set the port number of the master node (defaults to 5557). 
+Note that locust will use the port specified, as well as the port number +1. So if 5557 is used, locust 
+will use both port 5557 and 5558.
+
+``--master-bind-host=X.X.X.X``
+------------------------------
+
+Optionally used together with ``--master``. Determines what network interface that the master node 
+will bind to. Defaults to * (all available inrefaces).
+
+``--master-bind-port=5557``
+------------------------------
+
+Optionally used together with ``--master``. Determines what network ports that the master node will
+listen to. Defaults to 5557. Note that locust will use the port specified, as well as the port 
+number +1. So if 5557 is used, locust will use both port 5557 and 5558.