1 files changed, 93 insertions, 0 deletions
diff --git a/erts/doc/src/alt_disco.xml b/erts/doc/src/alt_disco.xml
new file mode 100644
index 0000000000..d04221b9b3
--- /dev/null
+++ b/erts/doc/src/alt_disco.xml
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2018</year><year>2018</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+
+    </legalnotice>
+
+    <title>How to Implement an Alternative Service Discovery for Erlang Distribution
+    </title>
+    <prepared>Timmo Verlaan</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>2018-04-25</date>
+    <rev>PA1</rev>
+    <file>alt_disco.xml</file>
+  </header>
+  <p>
+    This section describes how to implement an alternative discovery mechanism
+    for Erlang distribution. Discovery is normally done using DNS and the
+    Erlang Port Mapper Daemon (EPMD) for port discovery.
+  </p>
+
+  <note><p>
+    Support for alternative service discovery mechanisms was added in Erlang/OTP
+    21.
+  </p></note>
+
+
+  <section>
+    <title>Introduction</title>
+    <p>To implement your own service discovery module you have to write your own
+    EPMD module. The <seealso marker="kernel:erl_epmd">EPMD module</seealso> is
+    responsible for providing the location of another node. The distribution
+    modules (<c>inet_tcp_dist</c>/<c>inet_tls_dist</c>) call the EPMD module to
+    get the IP address and port of the other node. The EPMD module that is part
+    of Erlang/OTP will resolve the hostname using DNS and uses the EPMD unix
+    process to get the port of another node. The EPMD unix process does this by
+    connecting to the other node on a well-known port, port 4369.</p>
+  </section>
+
+  <section>
+    <title>Discovery module</title>
+    <p>The discovery module needs to implement the same API as the regular
+    <seealso marker="kernel:erl_epmd">EPMD module</seealso>. However, instead of
+    communicating with EPMD you can connect to any service to find out
+    connection details of other nodes. A discovery module is enabled
+    by setting <seealso marker="erts:erl#epmd_module">-epmd_module</seealso>
+    when starting erlang. The discovery module must implement the following
+    callbacks:</p>
+
+    <taglist>
+      <tag><seealso marker="kernel:erl_epmd#start_link/0">start_link/0</seealso></tag>
+      <item>Start any processes needed by the discovery module.</item>
+      <tag><seealso marker="kernel:erl_epmd#names/1">names/1</seealso></tag>
+      <item>Return node names held by the registrar for the given host.</item>
+      <tag><seealso marker="kernel:erl_epmd#register_node/2">register_node/2</seealso></tag>
+      <item>Register the given node name with the registrar.</item>
+      <tag><seealso marker="kernel:erl_epmd#port_please/3">port_please/3</seealso></tag>
+      <item>Return the distribution port used by the given node.</item>
+    </taglist>
+
+    <p>The discovery module may implement the following callback:</p>
+
+    <taglist>
+      <tag><seealso marker="kernel:erl_epmd#address_please/3">address_please/3</seealso></tag>
+      <item><p>Return the address of the given node.
+        If not implemented, <seealso marker="kernel:inet#gethostbyname/1">
+        inet:gethostbyname/1</seealso> will be used instead</p>
+        <p>This callback may also return the port of the given node. In that case
+        <seealso marker="kernel:erl_epmd#port_please/3">port_please/3</seealso>
+        may be omitted.</p></item>
+    </taglist>
+  </section>
+</chapter>