diff options
Diffstat (limited to 'develop/modules/index.html')
| -rw-r--r-- | develop/modules/index.html | 30 |
1 files changed, 23 insertions, 7 deletions
diff --git a/develop/modules/index.html b/develop/modules/index.html index 956e84dab8..a512784333 100644 --- a/develop/modules/index.html +++ b/develop/modules/index.html @@ -184,6 +184,10 @@ <h1 id="modules"><a class="header" href="#modules">Modules</a></h1> <p>Synapse supports extending its functionality by configuring external modules.</p> +<p><strong>Note</strong>: When using third-party modules, you effectively allow someone else to run +custom code on your Synapse homeserver. Server admins are encouraged to verify the +provenance of the modules they use on their homeserver and make sure the modules aren't +running malicious code on their instance.</p> <h2 id="using-modules"><a class="header" href="#using-modules">Using modules</a></h2> <p>To use a module on Synapse, add it to the <code>modules</code> section of the configuration file:</p> <pre><code class="language-yaml">modules: @@ -195,18 +199,30 @@ </code></pre> <p>Each module is defined by a path to a Python class as well as a configuration. This information for a given module should be available in the module's own documentation.</p> -<p><strong>Note</strong>: When using third-party modules, you effectively allow someone else to run -custom code on your Synapse homeserver. Server admins are encouraged to verify the -provenance of the modules they use on their homeserver and make sure the modules aren't -running malicious code on their instance.</p> -<p>Also note that we are currently in the process of migrating module interfaces to this -system. While some interfaces might be compatible with it, others still require -configuring modules in another part of Synapse's configuration file.</p> +<h2 id="using-multiple-modules"><a class="header" href="#using-multiple-modules">Using multiple modules</a></h2> +<p>The order in which modules are listed in this section is important. When processing an +action that can be handled by several modules, Synapse will always prioritise the module +that appears first (i.e. is the highest in the list). This means:</p> +<ul> +<li>If several modules register the same callback, the callback registered by the module +that appears first is used.</li> +<li>If several modules try to register a handler for the same HTTP path, only the handler +registered by the module that appears first is used. Handlers registered by the other +module(s) are ignored and Synapse will log a warning message about them.</li> +</ul> +<p>Note that Synapse doesn't allow multiple modules implementing authentication checkers via +the password auth provider feature for the same login type with different fields. If this +happens, Synapse will refuse to start.</p> +<h2 id="current-status"><a class="header" href="#current-status">Current status</a></h2> +<p>We are currently in the process of migrating module interfaces to this system. While some +interfaces might be compatible with it, others still require configuring modules in +another part of Synapse's configuration file.</p> <p>Currently, only the following pre-existing interfaces are compatible with this new system:</p> <ul> <li>spam checker</li> <li>third-party rules</li> <li>presence router</li> +<li>password auth providers</li> </ul> </main> |