Document remote server config

docs/Core.rst

@@ -442,6 +442,8 @@ Other init files
   directory, will be run when any world or that save is loaded.
 
 
+.. _env-vars:
+
 Environment variables
 =====================
 
@@ -453,6 +455,7 @@ on UNIX-like systems::
 - ``DFHACK_PORT``: the port to use for the RPC server (used by ``dfhack-run``
   and `remotefortressreader` among others) instead of the default ``5000``. As
   with the default, if this port cannot be used, the server is not started.
+  See `remote` for more details.
 
 - ``DFHACK_DISABLE_CONSOLE``: if set, the DFHack console is not set up. This is
   the default behavior if ``PRINT_MODE:TEXT`` is set in ``data/init/init.txt``.

docs/Remote.rst

@@ -6,9 +6,8 @@ DFHack Remote Interface
 
 DFHack provides a remote access interface that external tools can connect to and
 use to interact with DF. This is implemented with `Google protobuf`_ messages
-exchanged over a TCP socket (which only accepts connections from the local
-machine by default). Both the core and plugins can define remotely-accessible
-methods (often referred to as **RPC methods**). The RPC methods currently
+exchanged over a TCP socket. Both the core and plugins can define
+remotely-accessible methods, or **RPC methods**. The RPC methods currently
 available are not comprehensive, but can be extended with plugins.
 
 .. _Google protobuf: https://developers.google.com/protocol-buffers
@@ -16,6 +15,26 @@ available are not comprehensive, but can be extended with plugins.
 .. contents::
     :local:
 
+
+Server configuration
+====================
+
+DFHack attempts to start a TCP server to listen for remote connections on
+startup. If this fails (due to the port being in use, for example), an error
+message will be logged to stderr.log.
+
+The server can be configured by setting options in ``dfhack-config/remote-server.json``:
+
+- ``allow_remote`` (default: ``false``): if true, allows connections from hosts
+  other than the local machine. This is insecure and may allow arbitrary code
+  execution on your machine, so it is disabled by default.
+- ``port`` (default: ``5000``): the port that the remote server listens on.
+  Overriding this will allow the server to work if you have multiple instances
+  of DF running, or if you have something else running on port 5000. Note that
+  the ``DFHACK_PORT`` `environment variable <env-vars>` takes precedence over
+  this setting and may be more useful for overriding the port temporarily.
+
+
 Examples
 ========