diff options
| author | Badlop <badlop@process-one.net> | 2009-08-12 14:15:59 +0000 |
|---|---|---|
| committer | Badlop <badlop@process-one.net> | 2009-08-12 14:15:59 +0000 |
| commit | 695ff58c55c0080062622e84f022f0849916d635 (patch) | |
| tree | d29ac8c064f00762e924d232ff55675a2acfd440 /doc | |
| parent | Update French translation (thanks to Nicolas Vérité) (diff) | |
Describe the options syntax, not only the name (EJAB-998)
SVN Revision: 2472
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/dev.html | 2 | ||||
| -rw-r--r-- | doc/features.html | 2 | ||||
| -rw-r--r-- | doc/guide.html | 569 | ||||
| -rw-r--r-- | doc/guide.tex | 589 |
4 files changed, 553 insertions, 609 deletions
diff --git a/doc/dev.html b/doc/dev.html index ff3b7e2e..a5cb0c2c 100644 --- a/doc/dev.html +++ b/doc/dev.html @@ -84,7 +84,7 @@ Kevin Smith, Current maintainer of the Psi project</I></BLOCKQUOTE><!--TOC secti </LI><LI CLASS="li-toc"><A HREF="#htoc15">8.2  Services</A> </LI></UL> </LI></UL><P>Introduction -<A NAME="intro"></A></P><P><TT>ejabberd</TT> is a free and open source instant messaging server written in <A HREF="http://www.erlang.org/">Erlang</A>.</P><P><TT>ejabberd</TT> is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.</P><P><TT>ejabberd</TT> is designed to be a rock-solid and feature rich XMPP server.</P><P><TT>ejabberd</TT> is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.</P><!--TOC section Key Features--> +<A NAME="intro"></A></P><P><TT>ejabberd</TT> is a free and open source instant messaging server written in <A HREF="http://www.erlang.org/">Erlang/OTP</A>.</P><P><TT>ejabberd</TT> is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.</P><P><TT>ejabberd</TT> is designed to be a rock-solid and feature rich XMPP server.</P><P><TT>ejabberd</TT> is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.</P><!--TOC section Key Features--> <H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc1">1</A>  Key Features</H2><!--SEC END --><P> <A NAME="keyfeatures"></A> </P><P><TT>ejabberd</TT> is: diff --git a/doc/features.html b/doc/features.html index a02460be..d8f14d14 100644 --- a/doc/features.html +++ b/doc/features.html @@ -61,7 +61,7 @@ SPAN{width:20%; float:right; text-align:left; margin-left:auto;} </DIV><BLOCKQUOTE CLASS="quotation"><FONT COLOR="#921700"><I>I can thoroughly recommend ejabberd for ease of setup – Kevin Smith, Current maintainer of the Psi project</I></FONT></BLOCKQUOTE><P>Introduction <A NAME="intro"></A></P><BLOCKQUOTE CLASS="quotation"><FONT COLOR="#921700"><I>I just tried out ejabberd and was impressed both by ejabberd itself and the language it is written in, Erlang. — -Joeri</I></FONT></BLOCKQUOTE><P><TT>ejabberd</TT> is a <B><FONT SIZE=4><FONT COLOR="#001376">free and open source</FONT></FONT></B> instant messaging server written in <A HREF="http://www.erlang.org/">Erlang</A>.</P><P><TT>ejabberd</TT> is <B><FONT SIZE=4><FONT COLOR="#001376">cross-platform</FONT></FONT></B>, distributed, fault-tolerant, and based on open standards to achieve real-time communication.</P><P><TT>ejabberd</TT> is designed to be a <B><FONT SIZE=4><FONT COLOR="#001376">rock-solid and feature rich</FONT></FONT></B> XMPP server.</P><P><TT>ejabberd</TT> is suitable for small deployments, whether they need to be <B><FONT SIZE=4><FONT COLOR="#001376">scalable</FONT></FONT></B> or not, as well as extremely big deployments.</P><!--TOC section Key Features--> +Joeri</I></FONT></BLOCKQUOTE><P><TT>ejabberd</TT> is a <B><FONT SIZE=4><FONT COLOR="#001376">free and open source</FONT></FONT></B> instant messaging server written in <A HREF="http://www.erlang.org/">Erlang/OTP</A>.</P><P><TT>ejabberd</TT> is <B><FONT SIZE=4><FONT COLOR="#001376">cross-platform</FONT></FONT></B>, distributed, fault-tolerant, and based on open standards to achieve real-time communication.</P><P><TT>ejabberd</TT> is designed to be a <B><FONT SIZE=4><FONT COLOR="#001376">rock-solid and feature rich</FONT></FONT></B> XMPP server.</P><P><TT>ejabberd</TT> is suitable for small deployments, whether they need to be <B><FONT SIZE=4><FONT COLOR="#001376">scalable</FONT></FONT></B> or not, as well as extremely big deployments.</P><!--TOC section Key Features--> <H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc1"></A>Key Features</H2><!--SEC END --><P> <A NAME="keyfeatures"></A> </P><BLOCKQUOTE CLASS="quotation"><FONT COLOR="#921700"><I>Erlang seems to be tailor-made for writing stable, robust servers. — diff --git a/doc/guide.html b/doc/guide.html index e8cc5922..6d4d81a0 100644 --- a/doc/guide.html +++ b/doc/guide.html @@ -219,7 +219,7 @@ BLOCKQUOTE.figure DIV.center DIV.center HR{display:none;} </LI><LI CLASS="li-toc"><A HREF="#htoc99">Appendix D  Copyright Information</A> </LI></UL><!--TOC chapter Introduction--> <H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc1">Chapter 1</A>  Introduction</H1><!--SEC END --><P> -<A NAME="intro"></A></P><P><TT>ejabberd</TT> is a free and open source instant messaging server written in <A HREF="http://www.erlang.org/">Erlang</A>.</P><P><TT>ejabberd</TT> is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.</P><P><TT>ejabberd</TT> is designed to be a rock-solid and feature rich XMPP server.</P><P><TT>ejabberd</TT> is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.</P><!--TOC section Key Features--> +<A NAME="intro"></A></P><P><TT>ejabberd</TT> is a free and open source instant messaging server written in <A HREF="http://www.erlang.org/">Erlang/OTP</A>.</P><P><TT>ejabberd</TT> is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.</P><P><TT>ejabberd</TT> is designed to be a rock-solid and feature rich XMPP server.</P><P><TT>ejabberd</TT> is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.</P><!--TOC section Key Features--> <H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc2">1.1</A>  Key Features</H2><!--SEC END --><P> <A NAME="keyfeatures"></A> </P><P><TT>ejabberd</TT> is: @@ -538,7 +538,7 @@ edit the configuration file, or remove all its content.</P><P>The configuration the name of an option, and any further elements are that option’s values. If the configuration file do not contain for instance the ‘hosts’ option, the old host name(s) stored in the database will be used.</P><P>You can override the old values stored in the database by adding next lines to -the configuration file: +the beginning of the configuration file: </P><PRE CLASS="verbatim">override_global. override_local. override_acls. @@ -547,22 +547,18 @@ cluster), local options (which are specific for this particular <TT>ejabberd</TT and ACLs will be removed before new ones are added.</P><P> <A NAME="hostnames"></A> </P><!--TOC subsection Host Names--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc21">3.1.1</A>  <A HREF="#hostnames">Host Names</A></H3><!--SEC END --><P> <A NAME="hostnames"></A> </P><P>The option <TT>hosts</TT> defines a list containing one or more domains that -<TT>ejabberd</TT> will serve.</P><P>Examples: +<TT>ejabberd</TT> will serve.</P><P>The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{hosts, [HostName, ...]}.</TT></B></DT></DL><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> Serving one domain: <PRE CLASS="verbatim">{hosts, ["example.org"]}. -</PRE></LI><LI CLASS="li-itemize">Serving one domain, and backwards compatible with older <TT>ejabberd</TT> -versions: -<PRE CLASS="verbatim">{host, "example.org"}. -</PRE></LI><LI CLASS="li-itemize">Serving two domains: -<PRE CLASS="verbatim">{hosts, ["example.net", "example.com"]}. +</PRE></LI><LI CLASS="li-itemize">Serving three domains: +<PRE CLASS="verbatim">{hosts, ["example.net", "example.com", "jabber.somesite.org"]}. </PRE></LI></UL><P> <A NAME="virtualhost"></A> </P><!--TOC subsection Virtual Hosting--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc22">3.1.2</A>  <A HREF="#virtualhost">Virtual Hosting</A></H3><!--SEC END --><P> <A NAME="virtualhost"></A> </P><P>Options can be defined separately for every virtual host using the -<TT>host_config</TT> option. It has the following -syntax: -</P><PRE CLASS="verbatim">{host_config, <hostname>, [<option>, <option>, ...]}. -</PRE><P>Examples: +<TT>host_config</TT> option.</P><P>The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{host_config, HostName, [Option, ...]}</TT></B></DT></DL><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> Domain <TT>example.net</TT> is using the internal authentication method while domain <TT>example.com</TT> is using the LDAP server running on the @@ -590,11 +586,10 @@ while domain <TT>example.com</TT> is using the LDAP servers running on the domai </PRE></LI></UL><P>To define specific ejabberd modules in a virtual host, you can define the global <TT>modules</TT> option with the common modules, and later add specific modules to certain virtual hosts. -To accomplish that, instead of defining each option in <TT>host_config</TT> with the syntax -</P><PRE CLASS="verbatim">{<option-name>, <option-value>} -</PRE><P>use this syntax: -</P><PRE CLASS="verbatim">{{add, <option-name>}, <option-value>} -</PRE><P>In this example three virtual hosts have some similar modules, but there are also +To accomplish that, instead of defining each option in <TT>host_config</TT> with the general syntax +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{OptionName, OptionValue}</TT></B></DT></DL><P> +use this syntax: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{{add, OptionName}, OptionValue}</TT></B></DT></DL><P>In this example three virtual hosts have some similar modules, but there are also other different modules for some specific virtual hosts: </P><PRE CLASS="verbatim">%% This ejabberd server has three vhosts: {hosts, ["one.example.org", "two.example.org", "three.example.org"]}. @@ -637,18 +632,9 @@ tuple with the following elements: Port number. Optionally also the IP address and/or a transport protocol. </LI><LI CLASS="li-itemize">Listening module that serves this port. </LI><LI CLASS="li-itemize">Options for the TCP socket and for the listening module. -</LI></UL><P>With the basic syntax the ports will listen on all IPv4 network addresses: -</P><PRE CLASS="verbatim">{listen, [ - {<port-number>, <module>, [<options>]}, - {<port-number>, <module>, [<options>]}, - ... - {<port-number>, <module>, [<options>]} - ]}. -</PRE><P>It is possible to specify the IP address for a port using the full syntax: -</P><PRE CLASS="verbatim"> {{<port-number>, <ip-address>}, <module>, [<options>]} - {{<port-number>, <transport-protocol>}, <module>, [<options>]} - {{<port-number>, <ip-address>, <transport-protocol>}, <module>, [<options>]} -</PRE><P> <A NAME="listened-port"></A> </P><!--TOC subsubsection Port Number, IP Address and Transport Protocol--> +</LI></UL><P>The option syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{listen, [Listener, ...]}.</TT></B></DT></DL><P>To define a listener there are several syntax. +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{PortNumber, Module, [Option, ...]}</TT></B></DT></DL><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{{PortNumber, IPaddress}, Module, [Option, ...]}</TT></B></DT></DL><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{{PortNumber, TransportProtocol}, Module, [Option, ...]}</TT></B></DT></DL><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{{PortNumber, IPaddress, TransportProtocol}, Module, [Option, ...]}</TT></B></DT></DL><P> <A NAME="listened-port"></A> </P><!--TOC subsubsection Port Number, IP Address and Transport Protocol--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#listened-port">Port Number, IP Address and Transport Protocol</A></H4><!--SEC END --><P> <A NAME="listened-port"></A> </P><P>The port number defines which port to listen for incoming connections. It can be a Jabber/XMPP standard port (see section <A HREF="#firewall">5.1</A>) or any other valid port number.</P><P>The IP address can be represented with a string @@ -656,7 +642,8 @@ or an Erlang tuple with decimal or hexadecimal numbers. The socket will listen only in that network interface. It is possible to specify a generic address, so <TT>ejabberd</TT> will listen in all addresses. -Depending in the type of the IP address, IPv4 or IPv6 will be used.</P><P>Some example values for IP address: +Depending in the type of the IP address, IPv4 or IPv6 will be used. +When not specified the IP address, it will listen on all IPv4 network addresses.</P><P>Some example values for IP address: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> <CODE>"0.0.0.0"</CODE> to listen in all IPv4 network interfaces. This is the default value when no IP is specified. </LI><LI CLASS="li-itemize"><CODE>"::"</CODE> to listen in all IPv6 network interfaces @@ -695,19 +682,19 @@ Handles incoming HTTP connections.<BR> </DD></DL><P> <A NAME="listened-options"></A> </P><!--TOC subsubsection Options--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#listened-options">Options</A></H4><!--SEC END --><P> <A NAME="listened-options"></A> </P><P>This is a detailed description of each option allowed by the listening modules: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>{access, <access rule>}</TT></B></DT><DD CLASS="dd-description"> This option defines +<B><TT>{access, AccessName}</TT></B></DT><DD CLASS="dd-description"> This option defines access to the port. The default value is <TT>all</TT>. </DD><DT CLASS="dt-description"><B><TT>{certfile, Path}</TT></B></DT><DD CLASS="dd-description"> Full path to a file containing the default SSL certificate. To define a certificate file specific for a given domain, use the global option <TT>domain_certfile</TT>. -</DD><DT CLASS="dt-description"><B><TT>service_check_from</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{service_check_from, true|false}</TT></B></DT><DD CLASS="dd-description"> This option can be used with <TT>ejabberd_service</TT> only. It is used to disable control on the from field on packets send by an external components. The option can be either <TT>true</TT> or <TT>false</TT>. The default value is <TT>true</TT> which conforms to <A HREF="http://xmpp.org/extensions/xep-0114.html">XEP-0114</A>. -</DD><DT CLASS="dt-description"><B><TT>{hosts, [Hostnames], [HostOptions]}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{hosts, [Hostname, ...], [HostOption, ...]}</TT></B></DT><DD CLASS="dd-description"> The external Jabber component that connects to this <TT>ejabberd_service</TT> can serve one or more hostnames. -In <TT>HostOptions</TT> you can define options for the component; +As <TT>HostOption</TT> you can define options for the component; currently the only allowed option is the password required to the component when attempt to connect to ejabberd: <TT>{password, Secret}</TT>. Note that you cannot define in a single <TT>ejabberd_service</TT> components of @@ -746,7 +733,7 @@ value is <TT>infinity</TT>. Recommended values are 65536 for c2s connections and 131072 for s2s connections. s2s max stanza size must always much higher than c2s limit. Change this value with extreme care as it can cause unwanted disconnect if set too low. -</DD><DT CLASS="dt-description"><B><TT>{request_handlers, [{Path, Module}]}</TT></B></DT><DD CLASS="dd-description"> To define one or several handlers that will serve HTTP requests. +</DD><DT CLASS="dt-description"><B><TT>{request_handlers, [ {Path, Module}, ...]}</TT></B></DT><DD CLASS="dd-description"> To define one or several handlers that will serve HTTP requests. The Path is a list of strings; so the URIs that start with that Path will be served by Module. For example, if you want <TT>mod_foo</TT> to serve the URIs that start with <TT>/a/b/</TT>, and you also want <TT>mod_http_bind</TT> to serve the URIs <TT>/http-bind/</TT>, @@ -756,7 +743,7 @@ By enabling this option, <TT>ejabberd</TT> allows the component to send packets Note that <A HREF="http://xmpp.org/extensions/xep-0114.html">XEP-0114</A> requires that the domain must match the hostname of the component. Only enable this option if you are completely sure you need to enable it. Default value: false. -</DD><DT CLASS="dt-description"><B><TT>{shaper, <access rule>}</TT></B></DT><DD CLASS="dd-description"> This option defines a +</DD><DT CLASS="dt-description"><B><TT>{shaper, none|ShaperName}</TT></B></DT><DD CLASS="dd-description"> This option defines a shaper for the port (see section <A HREF="#shapers">3.1.6</A>). The default value is <TT>none</TT>. </DD><DT CLASS="dt-description"><B><TT>starttls</TT></B></DT><DD CLASS="dd-description"> This option @@ -801,7 +788,7 @@ Full path to the file containing the SSL certificate for a specific domain. Specify which address families to try, in what order, and connect timeout in milliseconds. By default it first tries connecting with IPv4, if that fails it tries using IPv6, with a timeout of 10000 milliseconds. -</DD><DT CLASS="dt-description"><B><TT>{s2s_dns_options, [{Property, Value}]}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{s2s_dns_options, [ {Property, Value}, ...]}</TT></B></DT><DD CLASS="dd-description"> Define properties to use for DNS resolving. Allowed Properties are: <TT>timeout</TT> in seconds which default value is <TT>10</TT> and <TT>retries</TT> which default value is <TT>2</TT>. @@ -982,10 +969,9 @@ you have to make the transports log and do XDB by themselves: </xdb> </PRE><P> <A NAME="auth"></A> </P><!--TOC subsection Authentication--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc24">3.1.4</A>  <A HREF="#auth">Authentication</A></H3><!--SEC END --><P> <A NAME="auth"></A> -</P><P>The option <TT>auth_method</TT> defines the authentication method that is used -for user authentication: -</P><PRE CLASS="verbatim">{auth_method, [<method>]}. -</PRE><P>The following authentication methods are supported by <TT>ejabberd</TT>: +</P><P>The option <TT>auth_method</TT> defines the authentication methods that are used +for user authentication. The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{auth_method, [Method, ...]}.</TT></B></DT></DL><P>The following authentication methods are supported by <TT>ejabberd</TT>: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> internal (default) — See section <A HREF="#internalauth">3.1.4</A>. </LI><LI CLASS="li-itemize">external — There are <A HREF="http://www.ejabberd.im/extauth">some @@ -997,10 +983,8 @@ example authentication scripts</A>. </LI><LI CLASS="li-itemize">pam — See section <A HREF="#pam">3.1.4</A>. </LI></UL><P>Account creation is only supported by internal and odbc methods.</P><P> <A NAME="internalauth"></A> </P><!--TOC subsubsection Internal--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#internalauth">Internal</A></H4><!--SEC END --><P> <A NAME="internalauth"></A> -</P><P><TT>ejabberd</TT> uses its internal Mnesia database as the default authentication method.</P><UL CLASS="itemize"><LI CLASS="li-itemize"> -<TT>auth_method</TT>: The value <TT>internal</TT> will enable the internal -authentication method. -</LI></UL><P>Examples: +</P><P><TT>ejabberd</TT> uses its internal Mnesia database as the default authentication method. +The value <TT>internal</TT> will enable the internal authentication method.</P><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> To use internal authentication on <TT>example.org</TT> and LDAP authentication on <TT>example.net</TT>: @@ -1010,25 +994,23 @@ authentication on <TT>example.net</TT>: <PRE CLASS="verbatim">{auth_method, internal}. </PRE></LI></UL><P> <A NAME="saslanonymous"></A> </P><!--TOC subsubsection SASL Anonymous and Anonymous Login--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#saslanonymous">SASL Anonymous and Anonymous Login</A></H4><!--SEC END --><P> <A NAME="saslanonymous"></A> -</P><P>The anonymous authentication method can be configured with the following +</P><P>The value <TT>anonymous</TT> will enable the internal authentication method.</P><P>The anonymous authentication method can be configured with the following options. Remember that you can use the <TT>host_config</TT> option to set virtual host specific options (see section <A HREF="#virtualhost">3.1.2</A>). Note that there also is a detailed tutorial regarding <A HREF="http://support.process-one.net/doc/display/MESSENGER/Anonymous+users+support">SASL -Anonymous and anonymous login configuration</A>.</P><UL CLASS="itemize"><LI CLASS="li-itemize"> -<TT>auth_method</TT>: The value <TT>anonymous</TT> will enable the anonymous -authentication method. -</LI><LI CLASS="li-itemize"><TT>allow_multiple_connections</TT>: This value for this option can be -either <TT>true</TT> or <TT>false</TT> and is only used when the anonymous mode is +Anonymous and anonymous login configuration</A>.</P><DL CLASS="description"><DT CLASS="dt-description"> +<B><TT>{allow_multiple_connections, false|true}</TT></B></DT><DD CLASS="dd-description"> This option is only used +when the anonymous mode is enabled. Setting it to <TT>true</TT> means that the same username can be taken multiple times in anonymous login mode if different resource are used to connect. This option is only useful in very special occasions. The default value is <TT>false</TT>. -</LI><LI CLASS="li-itemize"><TT>anonymous_protocol</TT>: This option can take three values: -<TT>sasl_anon</TT>, <TT>login_anon</TT> or <TT>both</TT>. <TT>sasl_anon</TT> means +</DD><DT CLASS="dt-description"><B><TT>{anonymous_protocol, sasl_anon | login_anon | both}</TT></B></DT><DD CLASS="dd-description"> +<TT>sasl_anon</TT> means that the SASL Anonymous method will be used. <TT>login_anon</TT> means that the anonymous login method will be used. <TT>both</TT> means that SASL Anonymous and login anonymous are both enabled. -</LI></UL><P>Those options are defined for each virtual host with the <TT>host_config</TT> +</DD></DL><P>Those options are defined for each virtual host with the <TT>host_config</TT> parameter (see section <A HREF="#virtualhost">3.1.2</A>).</P><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> To enable anonymous login on all virtual hosts: @@ -1059,7 +1041,7 @@ PAM authentication is disabled by default, so you have to configure and compile </P><PRE CLASS="verbatim">./configure --enable-pam && make install </PRE><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>pam_service</TT></B></DT><DD CLASS="dd-description">This option defines the PAM service name. +<B><TT>{pam_service, Name}</TT></B></DT><DD CLASS="dd-description">This option defines the PAM service name. Default is <TT>"ejabberd"</TT>. Refer to the PAM documentation of your operation system for more information. </DD></DL><P>Example: @@ -1101,48 +1083,47 @@ then <TT>/etc/nssswitch.conf</TT> must be configured to use <TT>winbind</TT> as <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#ACLDefinition">ACL Definition</A></H4><!--SEC END --><P> <A NAME="ACLDefinition"></A> </P><P>Access control in <TT>ejabberd</TT> is performed via Access Control Lists (ACLs). The declarations of ACLs in the configuration file have the following syntax: -</P><PRE CLASS="verbatim">{acl, <aclname>, {<acltype>, ...}}. -</PRE><P><TT><acltype></TT> can be one of the following: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{acl, ACLName, ACLValue}.</TT></B></DT></DL><P><TT>ACLValue</TT> can be one of the following: </P><DL CLASS="description"><DT CLASS="dt-description"> <B><TT>all</TT></B></DT><DD CLASS="dd-description"> Matches all JIDs. Example: <PRE CLASS="verbatim">{acl, all, all}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{user, <username>}</TT></B></DT><DD CLASS="dd-description"> Matches the user with the name -<TT><username></TT> at the first virtual host. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{user, Username}</TT></B></DT><DD CLASS="dd-description"> Matches the user with the name +<TT>Username</TT> at the first virtual host. Example: <PRE CLASS="verbatim">{acl, admin, {user, "yozhik"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{user, <username>, <server>}</TT></B></DT><DD CLASS="dd-description"> Matches the user with the JID -<TT><username>@<server></TT> and any resource. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{user, Username, Server}</TT></B></DT><DD CLASS="dd-description"> Matches the user with the JID +<TT>Username@Server</TT> and any resource. Example: <PRE CLASS="verbatim">{acl, admin, {user, "yozhik", "example.org"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{server, <server>}</TT></B></DT><DD CLASS="dd-description"> Matches any JID from server -<TT><server></TT>. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{server, Server}</TT></B></DT><DD CLASS="dd-description"> Matches any JID from server +<TT>Server</TT>. Example: <PRE CLASS="verbatim">{acl, exampleorg, {server, "example.org"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{resource, <resource>}</TT></B></DT><DD CLASS="dd-description"> Matches any JID with a resource -<TT><resource></TT>. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{resource, Resource}</TT></B></DT><DD CLASS="dd-description"> Matches any JID with a resource +<TT>Resource</TT>. Example: <PRE CLASS="verbatim">{acl, mucklres, {resource, "muckl"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{shared_group, <groupname>}</TT></B></DT><DD CLASS="dd-description"> Matches any member of a Shared Roster Group with name <TT><groupname></TT> in the virtual host. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{shared_group, Groupname}</TT></B></DT><DD CLASS="dd-description"> Matches any member of a Shared Roster Group with name <TT>Groupname</TT> in the virtual host. Example: <PRE CLASS="verbatim">{acl, techgroupmembers, {shared_group, "techteam"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{shared_group, <groupname>, <server>}</TT></B></DT><DD CLASS="dd-description"> Matches any member of a Shared Roster Group with name <TT><groupname></TT> in the virtual host <TT><server></TT>. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{shared_group, Groupname, Server}</TT></B></DT><DD CLASS="dd-description"> Matches any member of a Shared Roster Group with name <TT>Groupname</TT> in the virtual host <TT>Server</TT>. Example: <PRE CLASS="verbatim">{acl, techgroupmembers, {shared_group, "techteam", "example.org"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{user_regexp, <regexp>}</TT></B></DT><DD CLASS="dd-description"> Matches any local user with a name that -matches <TT><regexp></TT> on local virtual hosts. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{user_regexp, Regexp}</TT></B></DT><DD CLASS="dd-description"> Matches any local user with a name that +matches <TT>Regexp</TT> on local virtual hosts. Example: <PRE CLASS="verbatim">{acl, tests, {user_regexp, "^test[0-9]*$"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{user_regexp, <regexp>, <server>}</TT></B></DT><DD CLASS="dd-description"> Matches any user with a name -that matches <TT><regexp></TT> at server <TT><server></TT>. Example: -<PRE CLASS="verbatim">{acl, tests, {user_regexp, "^test", "example.org"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{server_regexp, <regexp>}</TT></B></DT><DD CLASS="dd-description"> Matches any JID from the server that -matches <TT><regexp></TT>. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{user_regexp, UserRegexp, Server}</TT></B></DT><DD CLASS="dd-description"> Matches any user with a name +that matches <TT>Regexp</TT> at server <TT>Server</TT>. Example: +<PRE CLASS="verbatim">{acl, tests, {user_Userregexp, "^test", "example.org"}}. +</PRE></DD><DT CLASS="dt-description"><B><TT>{server_regexp, Regexp}</TT></B></DT><DD CLASS="dd-description"> Matches any JID from the server that +matches <TT>Regexp</TT>. Example: <PRE CLASS="verbatim">{acl, icq, {server_regexp, "^icq\\."}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{resource_regexp, <regexp>}</TT></B></DT><DD CLASS="dd-description"> Matches any JID with a resource that -matches <TT><regexp></TT>. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{resource_regexp, Regexp}</TT></B></DT><DD CLASS="dd-description"> Matches any JID with a resource that +matches <TT>Regexp</TT>. Example: <PRE CLASS="verbatim">{acl, icq, {resource_regexp, "^laptop\\."}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{node_regexp, <user_regexp>, <server_regexp>}</TT></B></DT><DD CLASS="dd-description"> Matches any user -with a name that matches <TT><user_regexp></TT> at any server that matches -<TT><server_regexp></TT>. Example: +</PRE></DD><DT CLASS="dt-description"><B><TT>{node_regexp, UserRegexp, ServerRegexp}</TT></B></DT><DD CLASS="dd-description"> Matches any user +with a name that matches <TT>UserRegexp</TT> at any server that matches +<TT>ServerRegexp</TT>. Example: <PRE CLASS="verbatim">{acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}. -</PRE></DD><DT CLASS="dt-description"><B><TT>{user_glob, <glob>}</TT></B></DT><DD CLASS="dd-description"> -</DD><DT CLASS="dt-description"><B><TT>{user_glob, <glob>, <server>}</TT></B></DT><DD CLASS="dd-description"> -</DD><DT CLASS="dt-description"><B><TT>{server_glob, <glob>}</TT></B></DT><DD CLASS="dd-description"> -</DD><DT CLASS="dt-description"><B><TT>{resource_glob, <glob>}</TT></B></DT><DD CLASS="dd-description"> -</DD><DT CLASS="dt-description"><B><TT>{node_glob, <user_glob>, <server_glob>}</TT></B></DT><DD CLASS="dd-description"> This is the same as +</PRE></DD><DT CLASS="dt-description"><B><TT>{user_glob, Glob}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{user_glob, Glob, Server}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{server_glob, Glob}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{resource_glob, Glob}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{node_glob, UserGlob, ServerGlob}</TT></B></DT><DD CLASS="dd-description"> This is the same as above. However, it uses shell glob patterns instead of regexp. These patterns can have the following special characters: <DL CLASS="description"><DT CLASS="dt-description"> @@ -1153,19 +1134,15 @@ ranges are specified by a pair of characters separated by a <TT>‘-’ If the first character after <TT>‘[’</TT> is a <TT>‘!’</TT>, any character not enclosed is matched. </DD></DL> -</DD></DL><P>The following ACLs are pre-defined: +</DD></DL><P>The following <TT>ACLName</TT> are pre-defined: </P><DL CLASS="description"><DT CLASS="dt-description"> <B><TT>all</TT></B></DT><DD CLASS="dd-description"> Matches any JID. </DD><DT CLASS="dt-description"><B><TT>none</TT></B></DT><DD CLASS="dd-description"> Matches no JID. </DD></DL><P> <A NAME="AccessRights"></A> </P><!--TOC subsubsection Access Rights--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#AccessRights">Access Rights</A></H4><!--SEC END --><P> <A NAME="AccessRights"></A> -</P><P>An entry allowing or denying access to different services looks similar to -this: -</P><PRE CLASS="verbatim">{access, <accessname>, [{allow, <aclname>}, - {deny, <aclname>}, - ... - ]}. -</PRE><P>When a JID is checked to have access to <TT><accessname></TT>, the server +</P><P>An entry allowing or denying access to different services. +The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{access, AccessName, [ {allow|deny, ACLName}, ...]}.</TT></B></DT></DL><P>When a JID is checked to have access to <TT>Accessname</TT>, the server sequentially checks if that JID matches any of the ACLs that are named in the second elements of the tuples in the list. If it matches, the first element of the first matched tuple is returned, otherwise the value ‘<TT>deny</TT>’ is @@ -1173,7 +1150,7 @@ returned.</P><P>Example: </P><PRE CLASS="verbatim">{access, configure, [{allow, admin}]}. {access, something, [{deny, badmans}, {allow, all}]}. -</PRE><P>The following access rules are pre-defined: +</PRE><P>The following <TT>AccessName</TT> are pre-defined: </P><DL CLASS="description"><DT CLASS="dt-description"> <B><TT>all</TT></B></DT><DD CLASS="dd-description"> Always returns the value ‘<TT>allow</TT>’. </DD><DT CLASS="dt-description"><B><TT>none</TT></B></DT><DD CLASS="dd-description"> Always returns the value ‘<TT>deny</TT>’. @@ -1186,35 +1163,27 @@ opened session will be disconnected. The error <TT>session replaced</TT> will be sent to the disconnected session. The value for this option can be either a number, or <TT>infinity</TT>. The default value is <TT>infinity</TT>.</P><P>The syntax is: -</P><PRE CLASS="verbatim">{access, max_user_sessions, [{<maxnumber>, <aclname>}, - ... - ]}. -</PRE><P>Examples: -</P><UL CLASS="itemize"><LI CLASS="li-itemize"> -To limit the number of sessions per user to 10 for all users: -<PRE CLASS="verbatim">{access, max_user_sessions, [{10, all}]}. -</PRE></LI></UL><P> <A NAME="configmaxs2sconns"></A> </P><!--TOC subsubsection Several connections to a remote Jabber server with ACL--> +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{access, max_user_sessions, [ {MaxNumber, ACLName}, ...]}.</TT></B></DT></DL><P>This example limits the number of sessions per user to 5 for all users, and to 10 for admins: +</P><PRE CLASS="verbatim">{access, max_user_sessions, [{10, admin}, {5, all}]}. +</PRE><P> <A NAME="configmaxs2sconns"></A> </P><!--TOC subsubsection Several connections to a remote Jabber server with ACL--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#configmaxs2sconns">Several connections to a remote Jabber server with ACL</A></H4><!--SEC END --><P> <A NAME="configmaxs2sconns"></A> </P><P>The special access <TT>max_s2s_connections</TT> specifies how many simultaneus S2S connections can be established to a specific remote Jabber server. The default value is <TT>1</TT>. There’s also available the access <TT>max_s2s_connections_per_node</TT>.</P><P>The syntax is: -</P><PRE CLASS="verbatim">{access, max_s2s_connections, [{<maxnumber>, <aclname>}, - ... - ]}. -</PRE><P>Examples: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{access, max_s2s_connections, [ {MaxNumber, ACLName}, ...]}.</TT></B></DT></DL><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> Allow up to 3 connections with each remote server: <PRE CLASS="verbatim">{access, max_s2s_connections, [{3, all}]}. </PRE></LI></UL><P> <A NAME="shapers"></A> </P><!--TOC subsection Shapers--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc26">3.1.6</A>  <A HREF="#shapers">Shapers</A></H3><!--SEC END --><P> <A NAME="shapers"></A> -</P><P>Shapers enable you to limit connection traffic. The syntax of -shapers is like this: -</P><PRE CLASS="verbatim">{shaper, <shapername>, <kind>}. -</PRE><P>Currently only one kind of shaper called <TT>maxrate</TT> is available. It has the +</P><P>Shapers enable you to limit connection traffic. +The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{shaper, ShaperName, Kind}.</TT></B></DT></DL><P> +Currently only one kind of shaper called <TT>maxrate</TT> is available. It has the following syntax: -</P><PRE CLASS="verbatim">{maxrate, <rate>} -</PRE><P>where <TT><rate></TT> stands for the maximum allowed incoming rate in bytes per +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{maxrate, Rate}</TT></B></DT></DL><P> +where <TT>Rate</TT> stands for the maximum allowed incoming rate in bytes per second. When a connection exceeds this limit, <TT>ejabberd</TT> stops reading from the socket until the average rate is again below the allowed maximum.</P><P>Examples: @@ -1229,9 +1198,10 @@ To define a shaper named ‘<TT>normal</TT>’ with traffic speed limi <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc27">3.1.7</A>  <A HREF="#language">Default Language</A></H3><!--SEC END --><P> <A NAME="language"></A> </P><P>The option <TT>language</TT> defines the default language of server strings that can be seen by Jabber clients. If a Jabber client does not support -<TT>xml:lang</TT>, the specified language is used. The default value is -<TT>en</TT>. In order to take effect there must be a translation file -<TT><language>.msg</TT> in <TT>ejabberd</TT>’s <TT>msgs</TT> directory.</P><P>For example, to set Russian as default language: +<TT>xml:lang</TT>, the specified language is used.</P><P>The option syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{language, Language}.</TT></B></DT></DL><P>The default value is <TT>en</TT>. +In order to take effect there must be a translation file +<TT>Language.msg</TT> in <TT>ejabberd</TT>’s <TT>msgs</TT> directory.</P><P>For example, to set Russian as default language: </P><PRE CLASS="verbatim">{language, "ru"}. </PRE><P>Appendix <A HREF="#i18ni10n">A</A> provides more details about internationalization and localization.</P><P> <A NAME="captcha"></A> </P><!--TOC subsection CAPTCHA--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc28">3.1.8</A>  <A HREF="#captcha">CAPTCHA</A></H3><!--SEC END --><P> <A NAME="captcha"></A> @@ -1294,19 +1264,18 @@ _stun._tcp IN SRV 0 0 3478 stun.example.com. _stuns._tcp IN SRV 0 0 5349 stun.example.com. </PRE><P> <A NAME="includeconfigfile"></A> </P><!--TOC subsection Include Additional Configuration Files--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc30">3.1.10</A>  <A HREF="#includeconfigfile">Include Additional Configuration Files</A></H3><!--SEC END --><P> <A NAME="includeconfigfile"></A> -</P><P>The option <TT>include_config_file</TT> in a configuration file instructs <TT>ejabberd</TT> to include other configuration files immediately.</P><P>The basic usage is: -</P><PRE CLASS="verbatim">{include_config_file, <filename>}. -</PRE><P>It is also possible to specify suboptions: -</P><PRE CLASS="verbatim">{include_config_file, <filename>, [<suboption>, <suboption>, ...]}. -</PRE><P>The filename can be indicated either as an absolute path, +</P><P>The option <TT>include_config_file</TT> in a configuration file instructs <TT>ejabberd</TT> to include other configuration files immediately.</P><P>The basic syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{include_config_file, Filename}.</TT></B></DT></DL><P> +It is possible to specify suboptions using the full syntax: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{include_config_file, Filename, [Suboption, ...]}.</TT></B></DT></DL><P>The filename can be indicated either as an absolute path, or relative to the main <TT>ejabberd</TT> configuration file. It isn’t possible to use wildcards. The file must exist and be readable.</P><P>The allowed suboptions are: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>{disallow, [<option>, <option>, ...]}</TT></B></DT><DD CLASS="dd-description"> Disallows the usage of those options in the included configuration file. +<B><TT>{disallow, [Optionname, ...]}</TT></B></DT><DD CLASS="dd-description"> Disallows the usage of those options in the included configuration file. The options that match this criteria are not accepted. The default value is an empty list: <TT>[]</TT> -</DD><DT CLASS="dt-description"><B><TT>{allow_only, [<option>, <option>, ...]}</TT></B></DT><DD CLASS="dd-description"> Allows only the usage of those options in the included configuration file. +</DD><DT CLASS="dt-description"><B><TT>{allow_only, [Optionname, ...]}</TT></B></DT><DD CLASS="dd-description"> Allows only the usage of those options in the included configuration file. The options that do not match this criteria are not accepted. The default value is: <TT>all</TT> </DD></DL><P>This is a basic example: @@ -1328,8 +1297,8 @@ and later includes another file with additional rules: </P><P>In the <TT>ejabberd</TT> configuration file, it is possible to define a macro for a value and later use this macro when defining an option.</P><P>A macro is defined with this syntax: -</P><PRE CLASS="verbatim">{define_macro, '<MACRO>', <value>}. -</PRE><P>The <TT>MACRO</TT> must be surrounded by single quotation marks, +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{define_macro, ’MACRO’, Value}.</TT></B></DT></DL><P> +The <TT>MACRO</TT> must be surrounded by single quotation marks, and all letters in uppercase; check the examples bellow. The <TT>value</TT> can be any valid arbitrary Erlang term.</P><P>The first definition of a macro is preserved, and additional definitions of the same macro are forgotten.</P><P>Macros are processed after @@ -1337,17 +1306,17 @@ additional configuration files have been included, so it is possible to use macros that are defined in configuration files included before the usage.</P><P>It isn’t possible to use a macro in the definition of another macro.</P><P>There are two ways to use a macro: -</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>’<MACRO>’</TT></B></DT><DD CLASS="dd-description"> +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>’MACRO’</TT></B></DT><DD CLASS="dd-description"> You can put this instead of a value in an <TT>ejabberd</TT> option, and will be replaced with the <TT>value</TT> previously defined. If the macro is not defined previously, -the program will crash and report an error.</DD><DT CLASS="dt-description"><B><TT>{use_macro, ’<MACRO>’, <defaultvalue>}</TT></B></DT><DD CLASS="dd-description"> +the program will crash and report an error.</DD><DT CLASS="dt-description"><B><TT>{use_macro, ’MACRO’, Defaultvalue}</TT></B></DT><DD CLASS="dd-description"> Use a macro even if it may not be defined. If the macro is not defined previously, the provided <TT>defaultvalue</TT> is used. This usage behaves as if it were defined and used this way: -<PRE CLASS="verbatim">{define_macro, '<MACRO>', <defaultvalue>}. -'<MACRO>' +<PRE CLASS="verbatim">{define_macro, 'MACRO', Defaultvalue}. +'MACRO' </PRE></DD></DL><P>This example shows the basic usage of a macro: </P><PRE CLASS="verbatim">{define_macro, 'LOG_LEVEL_NUMBER', 5}. {loglevel, 'LOG_LEVEL_NUMBER'}. @@ -1430,17 +1399,13 @@ commands: value is used to define if we want to use ODBC, or one of the two native interface available, PostgreSQL or MySQL.</P><P>To use the native MySQL interface, you can pass a tuple of the following form as parameter: -</P><PRE CLASS="verbatim">{mysql, "Server", "Database", "Username", "Password"} -</PRE><P><TT>mysql</TT> is a keyword that should be kept as is. For example: -</P><PRE CLASS="verbatim">{odbc_server, {mysql, "localhost", "test", "root", "password"}}. -</PRE><P>Optionally, it is possible to define the MySQL port to use. This +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{mysql, "Server", "Database", "Username", "Password"}</TT></B></DT></DL><P><TT>mysql</TT> is a keyword that should be kept as is. For example: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{odbc_server, {mysql, "localhost", "test", "root", "password"}}.</TT></B></DT></DL><P>Optionally, it is possible to define the MySQL port to use. This option is only useful, in very rare cases, when you are not running MySQL with the default port setting. The <TT>mysql</TT> parameter can thus take the following form: -</P><PRE CLASS="verbatim">{mysql, "Server", Port, "Database", "Username", "Password"} -</PRE><P>The <TT>Port</TT> value should be an integer, without quotes. For example: -</P><PRE CLASS="verbatim">{odbc_server, {mysql, "localhost", Port, "test", "root", "password"}}. -</PRE><P>By default <TT>ejabberd</TT> opens 10 connections to the database for each virtual host. +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{mysql, "Server", Port, "Database", "Username", "Password"}</TT></B></DT></DL><P>The <TT>Port</TT> value should be an integer, without quotes. For example: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{odbc_server, {mysql, "localhost", Port, "test", "root", "password"}}.</TT></B></DT></DL><P>By default <TT>ejabberd</TT> opens 10 connections to the database for each virtual host. Use this option to modify the value: </P><PRE CLASS="verbatim">{odbc_pool_size, 10}. </PRE><P>You can configure an interval to make a dummy SQL request @@ -1532,17 +1497,13 @@ using next commands: value is used to define if we want to use ODBC, or one of the two native interface available, PostgreSQL or MySQL.</P><P>To use the native PostgreSQL interface, you can pass a tuple of the following form as parameter: -</P><PRE CLASS="verbatim">{pgsql, "Server", "Database", "Username", "Password"} -</PRE><P><TT>pgsql</TT> is a keyword that should be kept as is. For example: -</P><PRE CLASS="verbatim">{odbc_server, {pgsql, "localhost", "database", "ejabberd", "password"}}. -</PRE><P>Optionally, it is possible to define the PostgreSQL port to use. This +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{pgsql, "Server", "Database", "Username", "Password"}</TT></B></DT></DL><P><TT>pgsql</TT> is a keyword that should be kept as is. For example: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{odbc_server, {pgsql, "localhost", "database", "ejabberd", "password"}}.</TT></B></DT></DL><P>Optionally, it is possible to define the PostgreSQL port to use. This option is only useful, in very rare cases, when you are not running PostgreSQL with the default port setting. The <TT>pgsql</TT> parameter can thus take the following form: -</P><PRE CLASS="verbatim">{pgsql, "Server", Port, "Database", "Username", "Password"} -</PRE><P>The <TT>Port</TT> value should be an integer, without quotes. For example: -</P><PRE CLASS="verbatim">{odbc_server, {pgsql, "localhost", 5432, "database", "ejabberd", "password"}}. -</PRE><P>By default <TT>ejabberd</TT> opens 10 connections to the database for each virtual host. +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{pgsql, "Server", Port, "Database", "Username", "Password"}</TT></B></DT></DL><P>The <TT>Port</TT> value should be an integer, without quotes. For example: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{odbc_server, {pgsql, "localhost", 5432, "database", "ejabberd", "password"}}.</TT></B></DT></DL><P>By default <TT>ejabberd</TT> opens 10 connections to the database for each virtual host. Use this option to modify the value: </P><PRE CLASS="verbatim">{odbc_pool_size, 10}. </PRE><P>You can configure an interval to make a dummy SQL request @@ -1619,20 +1580,20 @@ it is possible to consult data, but not possible to create accounts, change password or edit vCard that is stored in LDAP.</P><P> <A NAME="ldapconnection"></A> </P><!--TOC subsubsection Connection--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#ldapconnection">Connection</A></H4><!--SEC END --><P> <A NAME="ldapconnection"></A> </P><P>Parameters: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>ldap_servers</TT></B></DT><DD CLASS="dd-description"> List of IP addresses or DNS names of your +<B><TT>{ldap_servers, [Servers, ...]}</TT></B></DT><DD CLASS="dd-description"> List of IP addresses or DNS names of your LDAP servers. This option is required. -</DD><DT CLASS="dt-description"><B><TT>ldap_encrypt</TT></B></DT><DD CLASS="dd-description"> Type of connection encryption to the LDAP server. +</DD><DT CLASS="dt-description"><B><TT>{ldap_encrypt, none|tls}</TT></B></DT><DD CLASS="dd-description"> Type of connection encryption to the LDAP server. Allowed values are: <TT>none</TT>, <TT>tls</TT>. Note that STARTTLS is not supported. The default value is: <TT>none</TT>. -</DD><DT CLASS="dt-description"><B><TT>ldap_port</TT></B></DT><DD CLASS="dd-description"> Port to connect to your LDAP server. +</DD><DT CLASS="dt-description"><B><TT>{ldap_port, Number}</TT></B></DT><DD CLASS="dd-description"> Port to connect to your LDAP server. The default port is 389 if encryption is disabled; and 636 if encryption is enabled. If you configure a value, it is stored in <TT>ejabberd</TT>’s database. Then, if you remove that value from the configuration file, the value previously stored in the database will be used instead of the default port. -</DD><DT CLASS="dt-description"><B><TT>ldap_rootdn</TT></B></DT><DD CLASS="dd-description"> Bind DN. The default value +</DD><DT CLASS="dt-description"><B><TT>{ldap_rootdn, RootDN}</TT></B></DT><DD CLASS="dd-description"> Bind DN. The default value is <TT>""</TT> which means ‘anonymous connection’. -</DD><DT CLASS="dt-description"><B><TT>ldap_password</TT></B></DT><DD CLASS="dd-description"> Bind password. The default +</DD><DT CLASS="dt-description"><B><TT>{ldap_password, Password}</TT></B></DT><DD CLASS="dd-description"> Bind password. The default value is <TT>""</TT>. </DD></DL><P>Example: </P><PRE CLASS="verbatim">{auth_method, ldap}. @@ -1643,15 +1604,15 @@ value is <TT>""</TT>. </PRE><P>Note that current LDAP implementation does not support SSL secured communication and SASL authentication.</P><P> <A NAME="ldapauth"></A> </P><!--TOC subsubsection Authentication--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#ldapauth">Authentication</A></H4><!--SEC END --><P> <A NAME="ldapauth"></A> </P><P>You can authenticate users against an LDAP directory. Available options are:</P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>ldap_base</TT></B></DT><DD CLASS="dd-description">LDAP base directory which stores +<B><TT>{ldap_base, Base}</TT></B></DT><DD CLASS="dd-description">LDAP base directory which stores users accounts. This option is required. -</DD><DT CLASS="dt-description"><B><TT>ldap_uids</TT></B></DT><DD CLASS="dd-description">LDAP attribute which holds a list -of attributes to use as alternatives for getting the JID. The value is of -the form: <TT>[{ldap_uidattr}]</TT> or <TT>[{ldap_uidattr, -ldap_uidattr_format}]</TT>. You can use as many comma separated tuples -<TT>{ldap_uidattr, ldap_uidattr_format}</TT> that is needed. The default -value is <TT>[{"uid", "%u"}]</TT>. The defaut <TT>ldap_uidattr_format</TT> -is <TT>"%u"</TT>. The values for <TT>ldap_uidattr</TT> and +</DD><DT CLASS="dt-description"><B><TT>{ldap_uids, [ {ldap_uidattr} | {ldap_uidattr, ldap_uidattr_format}, ...]}</TT></B></DT><DD CLASS="dd-description"> +LDAP attribute which holds a list of attributes to use as alternatives for getting the JID. +The default attributes are <TT>[{"uid", "%u"}]</TT>. +The attributes are of the form: +<TT>[{ldap_uidattr}]</TT> or <TT>[{ldap_uidattr, ldap_uidattr_format}]</TT>. +You can use as many comma separated attributes as needed. +The values for <TT>ldap_uidattr</TT> and <TT>ldap_uidattr_format</TT> are described as follow: <DL CLASS="description"><DT CLASS="dt-description"> <B><TT>ldap_uidattr</TT></B></DT><DD CLASS="dd-description">LDAP attribute which holds @@ -1662,13 +1623,13 @@ only one pattern variable <TT>"%u"</TT> which will be replaced by the user’s part of a JID. For example, <TT>"%u@example.org"</TT>. The default value is <TT>"%u"</TT>. </DD></DL> -</DD><DT CLASS="dt-description"><B><TT>ldap_filter</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{ldap_filter, Filter}</TT></B></DT><DD CLASS="dd-description"> <A HREF="http://tools.ietf.org/html/rfc4515">RFC 4515</A> LDAP filter. The default is <TT>none</TT>. Example: <TT>"(&(objectClass=shadowAccount)(memberOf=Jabber Users))"</TT>. Please, do not forget to close brackets and do not use superfluous whitespaces. Also you <EM>must not</EM> use <TT>ldap_uidattr</TT> attribute in filter because this -attribute will be substituted in LDAP filter automatically.</DD><DT CLASS="dt-description"><B><TT>ldap_local_filter</TT></B></DT><DD CLASS="dd-description"> +attribute will be substituted in LDAP filter automatically.</DD><DT CLASS="dt-description"><B><TT>{ldap_local_filter, Filter}</TT></B></DT><DD CLASS="dd-description"> If you can’t use <TT>ldap_filter</TT> due to performance reasons (the LDAP server has many users registered), you can use this local filter. @@ -1801,7 +1762,8 @@ configuration is shown below:</P><PRE CLASS="verbatim">{auth_method, ldap}. </P><P>The option <TT>modules</TT> defines the list of modules that will be loaded after <TT>ejabberd</TT>’s startup. Each entry in the list is a tuple in which the first element is the name of a module and the second is a list of options for that -module.</P><P>Examples: +module.</P><P>The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{modules, [ {ModuleName, ModuleOptions}, ...]}.</TT></B></DT></DL><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> In this example only the module <TT>mod_echo</TT> is loaded and no module options are specified between the square brackets: @@ -1888,7 +1850,8 @@ this separate section.</P><P> <A NAME="modiqdiscoption"></A> </P><!--TOC subsubs </P><P>Many modules define handlers for processing IQ queries of different namespaces to this server or to a user (e. g. to <TT>example.org</TT> or to <TT>user@example.org</TT>). This option defines processing discipline for -these queries. Possible values are: +these queries.</P><P>The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{iqdisc, Value}</TT></B></DT></DL><P>Possible <TT>Value</TT> are: </P><DL CLASS="description"><DT CLASS="dt-description"> <B><TT>no_queue</TT></B></DT><DD CLASS="dd-description"> All queries of a namespace with this processing discipline are processed immediately. This also means that no other packets can be processed @@ -1915,8 +1878,9 @@ number of processes (32000 by default). ]}. </PRE><P> <A NAME="modhostoption"></A> </P><!--TOC subsubsection <TT>host</TT>--> <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#modhostoption"><TT>host</TT></A></H4><!--SEC END --><P> <A NAME="modhostoption"></A> -</P><P>This option defines the Jabber ID of a service provided by an <TT>ejabberd</TT> module. -The keyword "@HOST@" is replaced at start time with the real virtual host string.</P><P>This example configures +</P><P>This option defines the Jabber ID of a service provided by an <TT>ejabberd</TT> module.</P><P>The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{host, HostName}</TT></B></DT></DL><P>If you include the keyword "@HOST@" in the HostName, +it is replaced at start time with the real virtual host string.</P><P>This example configures the echo module to provide its echoing service in the Jabber ID <TT>mirror.example.org</TT>: </P><PRE CLASS="verbatim">{modules, @@ -1965,7 +1929,7 @@ login. The message is <EM>not sent</EM> to any currently connected user. Any message sent to this JID removes the existing message of the day (MOTD). </DD></DL><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>access</TT></B></DT><DD CLASS="dd-description"> This option specifies who is allowed to +<B><TT>{access, AccessName}</TT></B></DT><DD CLASS="dd-description"> This option specifies who is allowed to send announcements and to set the message of the day (by default, nobody is able to send such messages). </DD></DL><P>Examples: @@ -2011,12 +1975,12 @@ for the superseded Jabber Browsing (<A HREF="http://xmpp.org/extensions/xep-0011 the newer Service Discovery protocol if you want them be able to discover the services you offer.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +<B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for Service Discovery (<TT>http://jabber.org/protocol/disco#items</TT> and <TT>http://jabber.org/protocol/disco#info</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). -</DD><DT CLASS="dt-description"><B><TT>{extra_domains, [ Domain ]}</TT></B></DT><DD CLASS="dd-description"> With this option, +</DD><DT CLASS="dt-description"><B><TT>{extra_domains, [Domain, ...]}</TT></B></DT><DD CLASS="dd-description"> With this option, you can specify a list of extra domains that are added to the Service Discovery item list. -</DD><DT CLASS="dt-description"><B><TT>{server_info, [ {Modules, Field, [Value]} ]}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{server_info, [ {Modules, Field, [Value, ...]}, ... ]}</TT></B></DT><DD CLASS="dd-description"> Specify additional information about the server, as described in Contact Addresses for XMPP Services (<A HREF="http://xmpp.org/extensions/xep-0157.html">XEP-0157</A>). <TT>Modules</TT> can be the keyword ‘all’, @@ -2078,7 +2042,7 @@ packet back to the sender. This mirror can be of interest for <TT>ejabberd</TT> and Jabber client debugging.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>host</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the +<B><TT>{host, HostName}</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the service. If the <TT>host</TT> option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix ‘<TT>echo.</TT>’. The keyword "@HOST@" is replaced at start time with the real virtual host name. @@ -2132,35 +2096,37 @@ For example: }, ... ]}. -</PRE><P>The maximum inactivity period is by default 30 seconds. -This can be configured with the module option <TT>max_inactivity</TT>. +</PRE><P>Options: +</P><DL CLASS="description"><DT CLASS="dt-description"> +<B><TT>{max_inactivity, Seconds}</TT></B></DT><DD CLASS="dd-description"> +Define the maximum inactivity period in seconds. +Default value is 30 seconds. For example, to set 50 seconds: -</P><PRE CLASS="verbatim">{modules, +<PRE CLASS="verbatim">{modules, [ ... {mod_http_bind, [ {max_inactivity, 50} ]}, ... ]}. -</PRE><P> <A NAME="modhttpfileserver"></A> </P><!--TOC subsection <TT>mod_http_fileserver</TT>--> +</PRE></DD></DL><P> <A NAME="modhttpfileserver"></A> </P><!--TOC subsection <TT>mod_http_fileserver</TT>--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc45">3.3.7</A>  <A HREF="#modhttpfileserver"><TT>mod_http_fileserver</TT></A></H3><!--SEC END --><P> <A NAME="modhttpfileserver"></A> </P><P>This simple module serves files from the local disk over HTTP.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>docroot</TT></B></DT><DD CLASS="dd-description"> +<B><TT>{docroot, Path}</TT></B></DT><DD CLASS="dd-description"> Directory to serve the files. -</DD><DT CLASS="dt-description"><B><TT>accesslog</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{accesslog, Path}</TT></B></DT><DD CLASS="dd-description"> File to log accesses using an Apache-like format. No log will be recorded if this option is not specified. -</DD><DT CLASS="dt-description"><B><TT>directory_indices</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{directory_indices, [Index, ...]}</TT></B></DT><DD CLASS="dd-description"> Indicate one or more directory index files, similarly to Apache’s DirectoryIndex variable. When a web request hits a directory instead of a regular file, those directory indices are looked in order, and the first one found is returned. -</DD><DT CLASS="dt-description"><B><TT>content_types</TT></B></DT><DD CLASS="dd-description"> Specify a mapping of extensions to content types. There are several content types already defined, with this option you can add new definitions, modify or delete existing ones. To delete an existing definition, simply define it with a value: ‘undefined’. -</DD><DT CLASS="dt-description"><B><TT>default_content_type</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{default_content_type, Type}</TT></B></DT><DD CLASS="dd-description"> Specify the content type to use for unknown extensions. Default value is ‘application/octet-stream’. </DD></DL><P>This example configuration will serve the files from @@ -2227,14 +2193,15 @@ number of conections from one IP. </LI></UL><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>host</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the +<B><TT>{host, HostName}</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the service. If the <TT>host</TT> option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix ‘<TT>irc.</TT>’. The keyword "@HOST@" is replaced at start time with the real virtual host name. -</DD><DT CLASS="dt-description"><B><TT>access</TT></B></DT><DD CLASS="dd-description"> This option can be used to specify who +</DD><DT CLASS="dt-description"><B><TT>{access, AccessName}</TT></B></DT><DD CLASS="dd-description"> This option can be used to specify who may use the IRC transport (default value: <TT>all</TT>). -</DD><DT CLASS="dt-description"><B><TT>default_encoding</TT></B></DT><DD CLASS="dd-description"> Set the default IRC encoding (default value: <TT>"koi8-r"</TT>). +</DD><DT CLASS="dt-description"><B><TT>{default_encoding, Encoding}</TT></B></DT><DD CLASS="dd-description"> Set the default IRC encoding. +Default value: <TT>"koi8-r"</TT> </DD></DL><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> In the first example, the IRC transport is available on (all) your @@ -2269,7 +2236,7 @@ discover when a disconnected user last accessed the server, to know when a connected user was last active on the server, or to query the uptime of the <TT>ejabberd</TT> server.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +<B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for Last activity (<TT>jabber:iq:last</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). </DD></DL><P> <A NAME="modmuc"></A> </P><!--TOC subsection <TT>mod_muc</TT>--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc48">3.3.10</A>  <A HREF="#modmuc"><TT>mod_muc</TT></A></H3><!--SEC END --><P> <A NAME="modmuc"></A> @@ -2294,20 +2261,20 @@ set of rooms goes down, the rooms disappear and they will be recreated on an available node on first connection attempt.</P><P>Module options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>host</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the +<B><TT>{host, HostName}</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the service. If the <TT>host</TT> option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix ‘<TT>conference.</TT>’. The keyword "@HOST@" is replaced at start time with the real virtual host name. -</DD><DT CLASS="dt-description"><B><TT>access</TT></B></DT><DD CLASS="dd-description"> You can specify who is allowed to use +</DD><DT CLASS="dt-description"><B><TT>{access, AccessName}</TT></B></DT><DD CLASS="dd-description"> You can specify who is allowed to use the Multi-User Chat service. By default everyone is allowed to use it. -</DD><DT CLASS="dt-description"><B><TT>access_create</TT></B></DT><DD CLASS="dd-description"> To configure who is +</DD><DT CLASS="dt-description"><B><TT>{access_create, AccessName}</TT></B></DT><DD CLASS="dd-description"> To configure who is allowed to create new rooms at the Multi-User Chat service, this option can be used. By default everybody is allowed to create rooms. -</DD><DT CLASS="dt-description"><B><TT>access_persistent</TT></B></DT><DD CLASS="dd-description"> To configure who is +</DD><DT CLASS="dt-description"><B><TT>{access_persistent, AccessName}</TT></B></DT><DD CLASS="dd-description"> To configure who is allowed to modify the ’persistent’ room option. By default everybody is allowed to modify that option. -</DD><DT CLASS="dt-description"><B><TT>access_admin</TT></B></DT><DD CLASS="dd-description"> This option specifies +</DD><DT CLASS="dt-description"><B><TT>{access_admin, AccessName}</TT></B></DT><DD CLASS="dd-description"> This option specifies who is allowed to administrate the Multi-User Chat service. The default value is <TT>none</TT>, which means that only the room creator can administer his room. @@ -2315,7 +2282,7 @@ The administrators can send a normal message to the service JID, and it will be shown in all active rooms as a service message. The administrators can send a groupchat message to the JID of an active room, and the message will be shown in the room as a service message. -</DD><DT CLASS="dt-description"><B><TT>history_size</TT></B></DT><DD CLASS="dd-description"> A small history of +</DD><DT CLASS="dt-description"><B><TT>{history_size, Size}</TT></B></DT><DD CLASS="dd-description"> A small history of the current discussion is sent to users when they enter the room. With this option you can define the number of history messages to keep and send to users joining the room. The value is an @@ -2323,35 +2290,35 @@ integer. Setting the value to <TT>0</TT> disables the history feature and, as a result, nothing is kept in memory. The default value is <TT>20</TT>. This value is global and thus affects all rooms on the service. -</DD><DT CLASS="dt-description"><B><TT>max_users</TT></B></DT><DD CLASS="dd-description"> This option defines at +</DD><DT CLASS="dt-description"><B><TT>{max_users, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines at the service level, the maximum number of users allowed per room. It can be lowered in each room configuration but cannot be increased in individual room configuration. The default value is 200. -</DD><DT CLASS="dt-description"><B><TT>max_users_admin_threshold</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{max_users_admin_threshold, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines the number of service admins or room owners allowed to enter the room when the maximum number of allowed occupants was reached. The default limit is 5. -</DD><DT CLASS="dt-description"><B><TT>max_user_conferences</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{max_user_conferences, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines the maximum number of rooms that any given user can join. The default value is 10. This option is used to prevent possible abuses. Note that this is a soft limit: some users can sometimes join more conferences in cluster configurations. -</DD><DT CLASS="dt-description"><B><TT>max_room_id</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{max_room_id, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines the maximum number of characters that Room ID can have when creating a new room. The default value is to not limit: infinite. -</DD><DT CLASS="dt-description"><B><TT>max_room_name</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{max_room_name, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines the maximum number of characters that Room Name can have when configuring the room. The default value is to not limit: infinite. -</DD><DT CLASS="dt-description"><B><TT>max_room_desc</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{max_room_desc, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines the maximum number of characters that Room Description can have when configuring the room. The default value is to not limit: infinite. -</DD><DT CLASS="dt-description"><B><TT>min_message_interval</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{min_message_interval, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines the minimum interval between two messages send by an occupant in seconds. This option is global and valid for all rooms. A decimal value can be used. When this option is not defined, @@ -2361,7 +2328,7 @@ be broadcasted by the service. A good value for this minimum message interval is 0.4 second. If an occupant tries to send messages faster, an error is send back explaining that the message has been discarded and describing the reason why the message is not acceptable. -</DD><DT CLASS="dt-description"><B><TT>min_presence_interval</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{min_presence_interval, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines the minimum of time between presence changes coming from a given occupant in seconds. This option is global and valid for all rooms. A @@ -2373,36 +2340,36 @@ presence is cached by <TT>ejabberd</TT> and only the last presence is broadcasted to all occupants in the room after expiration of the interval delay. Intermediate presence packets are silently discarded. A good value for this option is 4 seconds. -</DD><DT CLASS="dt-description"><B><TT>default_room_options</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{default_room_options, [ {OptionName, OptionValue}, ...]}</TT></B></DT><DD CLASS="dd-description"> This module option allows to define the desired default room options. Note that the creator of a room can modify the options of his room at any time using a Jabber client with MUC capability. The available room options and the default values are: <DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>{allow_change_subj, true}</TT></B></DT><DD CLASS="dd-description"> Allow occupants to change the subject. -</DD><DT CLASS="dt-description"><B><TT>{allow_private_messages, true}</TT></B></DT><DD CLASS="dd-description"> Occupants can send private messages to other occupants. -</DD><DT CLASS="dt-description"><B><TT>{allow_query_users, true}</TT></B></DT><DD CLASS="dd-description"> Occupants can send IQ queries to other occupants. -</DD><DT CLASS="dt-description"><B><TT>{allow_user_invites, false}</TT></B></DT><DD CLASS="dd-description"> Allow occupants to send invitations. -</DD><DT CLASS="dt-description"><B><TT>{allow_visitor_nickchange, true}</TT></B></DT><DD CLASS="dd-description"> Allow visitors to +<B><TT>{allow_change_subj, true|false}</TT></B></DT><DD CLASS="dd-description"> Allow occupants to change the subject. +</DD><DT CLASS="dt-description"><B><TT>{allow_private_messages, true|false}</TT></B></DT><DD CLASS="dd-description"> Occupants can send private messages to other occupants. +</DD><DT CLASS="dt-description"><B><TT>{allow_query_users, true|false}</TT></B></DT><DD CLASS="dd-description"> Occupants can send IQ queries to other occupants. +</DD><DT CLASS="dt-description"><B><TT>{allow_user_invites, false|true}</TT></B></DT><DD CLASS="dd-description"> Allow occupants to send invitations. +</DD><DT CLASS="dt-description"><B><TT>{allow_visitor_nickchange, true|false}</TT></B></DT><DD CLASS="dd-description"> Allow visitors to change nickname. -</DD><DT CLASS="dt-description"><B><TT>{allow_visitor_status, true}</TT></B></DT><DD CLASS="dd-description"> Allow visitors to send +</DD><DT CLASS="dt-description"><B><TT>{allow_visitor_status, true|false}</TT></B></DT><DD CLASS="dd-description"> Allow visitors to send status text in presence updates. If disallowed, the <TT>status</TT> text is stripped before broadcasting the presence update to all the room occupants. -</DD><DT CLASS="dt-description"><B><TT>{anonymous, true}</TT></B></DT><DD CLASS="dd-description"> The room is anonymous: +</DD><DT CLASS="dt-description"><B><TT>{anonymous, true|false}</TT></B></DT><DD CLASS="dd-description"> The room is anonymous: occupants don’t see the real JIDs of other occupants. Note that the room moderators can always see the real JIDs of the occupants. -</DD><DT CLASS="dt-description"><B><TT>{logging, false}</TT></B></DT><DD CLASS="dd-description"> The public messages are logged using <TT>mod_muc_log</TT>. +</DD><DT CLASS="dt-description"><B><TT>{logging, false|true}</TT></B></DT><DD CLASS="dd-description"> The public messages are logged using <TT>mod_muc_log</TT>. </DD><DT CLASS="dt-description"><B><TT>{max_users, 200}</TT></B></DT><DD CLASS="dd-description"> Maximum number of occupants in the room. -</DD><DT CLASS="dt-description"><B><TT>{members_by_default, true}</TT></B></DT><DD CLASS="dd-description"> The occupants that enter the room are participants by default, so they have ’voice’. -</DD><DT CLASS="dt-description"><B><TT>{members_only, false}</TT></B></DT><DD CLASS="dd-description"> Only members of the room can enter. -</DD><DT CLASS="dt-description"><B><TT>{moderated, true}</TT></B></DT><DD CLASS="dd-description"> Only occupants with ’voice’ can send public messages. -</DD><DT CLASS="dt-description"><B><TT>{password, ""}</TT></B></DT><DD CLASS="dd-description"> Password of the room. You may want to enable the next option too. -</DD><DT CLASS="dt-description"><B><TT>{password_protected, false}</TT></B></DT><DD CLASS="dd-description"> The password is required to enter the room. -</DD><DT CLASS="dt-description"><B><TT>{persistent, false}</TT></B></DT><DD CLASS="dd-description"> The room persists even if the last participant leaves. -</DD><DT CLASS="dt-description"><B><TT>{public, true}</TT></B></DT><DD CLASS="dd-description"> The room is public in the list of the MUC service, so it can be discovered. -</DD><DT CLASS="dt-description"><B><TT>{public_list, true}</TT></B></DT><DD CLASS="dd-description"> The list of participants is public, without requiring to enter the room. -</DD><DT CLASS="dt-description"><B><TT>{title, ""}</TT></B></DT><DD CLASS="dd-description"> A human-readable title of the room. +</DD><DT CLASS="dt-description"><B><TT>{members_by_default, true|false}</TT></B></DT><DD CLASS="dd-description"> The occupants that enter the room are participants by default, so they have ’voice’. +</DD><DT CLASS="dt-description"><B><TT>{members_only, false|true}</TT></B></DT><DD CLASS="dd-description"> Only members of the room can enter. +</DD><DT CLASS="dt-description"><B><TT>{moderated, true|false}</TT></B></DT><DD CLASS="dd-description"> Only occupants with ’voice’ can send public messages. +</DD><DT CLASS="dt-description"><B><TT>{password, "roompass123"}</TT></B></DT><DD CLASS="dd-description"> Password of the room. You may want to enable the next option too. +</DD><DT CLASS="dt-description"><B><TT>{password_protected, false|true}</TT></B></DT><DD CLASS="dd-description"> The password is required to enter the room. +</DD><DT CLASS="dt-description"><B><TT>{persistent, false|true}</TT></B></DT><DD CLASS="dd-description"> The room persists even if the last participant leaves. +</DD><DT CLASS="dt-description"><B><TT>{public, true|false}</TT></B></DT><DD CLASS="dd-description"> The room is public in the list of the MUC service, so it can be discovered. +</DD><DT CLASS="dt-description"><B><TT>{public_list, true|false}</TT></B></DT><DD CLASS="dd-description"> The list of participants is public, without requiring to enter the room. +</DD><DT CLASS="dt-description"><B><TT>{title, "Room Title"}</TT></B></DT><DD CLASS="dd-description"> A human-readable title of the room. </DD></DL> All of those room options can be set to <TT>true</TT> or <TT>false</TT>, except <TT>password</TT> and <TT>title</TT> which are strings, @@ -2518,53 +2485,52 @@ displayed, including the reason if available. </LI><LI CLASS="li-itemize">A custom link can be added on top of each page. </LI></UL><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>access_log</TT></B></DT><DD CLASS="dd-description"> +<B><TT>{access_log, AccessName}</TT></B></DT><DD CLASS="dd-description"> This option restricts which occupants are allowed to enable or disable room logging. The default value is <TT>muc_admin</TT>. Note for this default setting you need to have an access rule for <TT>muc_admin</TT> in order to take effect. -</DD><DT CLASS="dt-description"><B><TT>cssfile</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{cssfile, false|URL}</TT></B></DT><DD CLASS="dd-description"> With this option you can set whether the HTML files should have a custom CSS file or if they need to use the embedded CSS file. Allowed values are <TT>false</TT> and an URL to a CSS file. With the first value, HTML files will include the embedded CSS code. With the latter, you can specify the URL of the -custom CSS file (for example: ‘http://example.com/my.css’). The default value +custom CSS file (for example: <TT>"http://example.com/my.css"</TT>). The default value is <TT>false</TT>. -</DD><DT CLASS="dt-description"><B><TT>dirname</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{dirname, room_jid|room_name}</TT></B></DT><DD CLASS="dd-description"> Allows to configure the name of the room directory. Allowed values are <TT>room_jid</TT> and <TT>room_name</TT>. With the first value, the room directory name will be the full room JID. With the latter, the room directory name will be only the room name, not including the MUC service name. The default value is <TT>room_jid</TT>. -</DD><DT CLASS="dt-description"><B><TT>dirtype</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{dirtype, subdirs|plain}</TT></B></DT><DD CLASS="dd-description"> The type of the created directories can be specified with this option. Allowed values are <TT>subdirs</TT> and <TT>plain</TT>. With the first value, subdirectories are created for each year and month. With the latter, the names of the log files contain the full date, and there are no subdirectories. The default value is <TT>subdirs</TT>. -</DD><DT CLASS="dt-description"><B><TT>file_format</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{file_format, html|plaintext}</TT></B></DT><DD CLASS="dd-description"> Define the format of the log files: <TT>html</TT> stores in HTML format, <TT>plaintext</TT> stores in plain text. The default value is <TT>html</TT>. -</DD><DT CLASS="dt-description"><B><TT>outdir</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{outdir, Path}</TT></B></DT><DD CLASS="dd-description"> This option sets the full path to the directory in which the HTML files should be stored. Make sure the <TT>ejabberd</TT> daemon user has write access on that directory. The default value is <TT>"www/muc"</TT>. -</DD><DT CLASS="dt-description"><B><TT>spam_prevention</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{spam_prevention true|false}</TT></B></DT><DD CLASS="dd-description"> To prevent spam, the <TT>spam_prevention</TT> option adds a special attribute to links that prevent their indexation by search engines. The default value is <TT>true</TT>, which mean that nofollow attributes will be added to user submitted links. -</DD><DT CLASS="dt-description"><B><TT>timezone</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{timezone, local|universal}</TT></B></DT><DD CLASS="dd-description"> The time zone for the logs is configurable with this option. Allowed values are <TT>local</TT> and <TT>universal</TT>. With the first value, the local time, as reported to Erlang by the operating system, will be used. With the latter, GMT/UTC time will be used. The default value is <TT>local</TT>. -</DD><DT CLASS="dt-description"><B><TT>top_link</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{top_link, {URL, Text}}</TT></B></DT><DD CLASS="dd-description"> With this option you can customize the link on the top right corner of each -log file. The syntax of this option is <TT>{"URL", "Text"}</TT>. The default -value is <TT>{"/", "Home"}</TT>. +log file. The default value is <TT>{"/", "Home"}</TT>. </DD></DL><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> In the first example any room owner can enable logging, and a @@ -2622,7 +2588,7 @@ sent to an offline user will be stored on the server until that user comes online again. Thus it is very similar to how email works. Note that <TT>ejabberdctl</TT> has a command to delete expired messages (see section <A HREF="#ejabberdctl">4.1</A>).</P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>access_max_user_messages</TT></B></DT><DD CLASS="dd-description"> +<B><TT>{access_max_user_messages, Number}</TT></B></DT><DD CLASS="dd-description"> This option defines which access rule will be enforced to limit the maximum number of offline messages that a user can have (quota). When a user has too many offline messages, any new messages that he receive are discarded, @@ -2652,7 +2618,7 @@ and all the other users up to 100. When this module is enabled ejabberd responds correctly to ping requests, as defined in the protocol.</P><P>Configuration options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>{send_pings, true | false}</TT></B></DT><DD CLASS="dd-description"> +<B><TT>{send_pings, true|false}</TT></B></DT><DD CLASS="dd-description"> If this option is set to <TT>true</TT>, the server sends pings to connected clients that are not active in a given interval <TT>ping_interval</TT>. This is useful to keep client connections alive or checking availability. @@ -2662,7 +2628,7 @@ How often to send pings to connected clients, if the previous option is enabled. If a client connection does not send or receive any stanza in this interval, a ping request is sent to the client. The default value is 60 seconds. -</DD><DT CLASS="dt-description"><B><TT>{timeout_action, none | kill}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{timeout_action, none|kill}</TT></B></DT><DD CLASS="dd-description"> What to do when a client does not answer to a server ping request in less than 32 seconds. The default is to do nothing. </DD></DL><P>This example enables Ping responses, configures the module to send pings @@ -2700,7 +2666,7 @@ subscription type (or globally). (from <A HREF="http://xmpp.org/specs/rfc3921.html#privacy"><TT>http://xmpp.org/specs/rfc3921.html#privacy</TT></A>) </BLOCKQUOTE><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +<B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for Blocking Communication (<TT>jabber:iq:privacy</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). </DD></DL><P> <A NAME="modprivate"></A> </P><!--TOC subsection <TT>mod_private</TT>--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc53">3.3.15</A>  <A HREF="#modprivate"><TT>mod_private</TT></A></H3><!--SEC END --><P> <A NAME="modprivate"></A> @@ -2712,7 +2678,7 @@ it is valid XML. One typical usage for this namespace is the server-side storage of client-specific preferences; another is Bookmark Storage (<A HREF="http://xmpp.org/extensions/xep-0048.html">XEP-0048</A>). </BLOCKQUOTE><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +<B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for Private XML Storage (<TT>jabber:iq:private</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). </DD></DL><P> <A NAME="modproxy"></A> </P><!--TOC subsection <TT>mod_proxy65</TT>--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc54">3.3.16</A>  <A HREF="#modproxy"><TT>mod_proxy65</TT></A></H3><!--SEC END --><P> <A NAME="modproxy"></A> @@ -2720,24 +2686,27 @@ the processing discipline for Private XML Storage (<TT>jabber:iq:private</TT>) I It allows <TT>ejabberd</TT> to act as a file transfer proxy between two XMPP clients.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>host</TT></B></DT><DD CLASS="dd-description">This option defines the hostname of the service. -If this option is not set, the prefix ‘<TT>proxy.</TT>’ is added to <TT>ejabberd</TT> -hostname. -</DD><DT CLASS="dt-description"><B><TT>name</TT></B></DT><DD CLASS="dd-description">Defines Service Discovery name of the service. + +<B><TT>{host, HostName}</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the +service. If the <TT>host</TT> option is not specified, the Jabber ID will be the +hostname of the virtual host with the prefix ‘<TT>proxy.</TT>’. The keyword "@HOST@" +is replaced at start time with the real virtual host name. + +</DD><DT CLASS="dt-description"><B><TT>{name, Text}</TT></B></DT><DD CLASS="dd-description">Defines Service Discovery name of the service. Default is <TT>"SOCKS5 Bytestreams"</TT>. -</DD><DT CLASS="dt-description"><B><TT>ip</TT></B></DT><DD CLASS="dd-description">This option specifies which network interface +</DD><DT CLASS="dt-description"><B><TT>{ip, IPTuple}</TT></B></DT><DD CLASS="dd-description">This option specifies which network interface to listen for. Default is an IP address of the service’s DNS name, or, if fails, <CODE>{127,0,0,1}</CODE>. -</DD><DT CLASS="dt-description"><B><TT>port</TT></B></DT><DD CLASS="dd-description">This option defines port to listen for +</DD><DT CLASS="dt-description"><B><TT>{port, Number}</TT></B></DT><DD CLASS="dd-description">This option defines port to listen for incoming connections. Default is 7777. -</DD><DT CLASS="dt-description"><B><TT>auth_type</TT></B></DT><DD CLASS="dd-description">SOCKS5 authentication type. +</DD><DT CLASS="dt-description"><B><TT>{auth_type, anonymous|plain}</TT></B></DT><DD CLASS="dd-description">SOCKS5 authentication type. Possible values are <TT>anonymous</TT> and <TT>plain</TT>. Default is <TT>anonymous</TT>. -</DD><DT CLASS="dt-description"><B><TT>access</TT></B></DT><DD CLASS="dd-description">Defines ACL for file transfer initiators. +</DD><DT CLASS="dt-description"><B><TT>{access, AccessName}</TT></B></DT><DD CLASS="dd-description">Defines ACL for file transfer initiators. Default is <TT>all</TT>. -</DD><DT CLASS="dt-description"><B><TT>max_connections</TT></B></DT><DD CLASS="dd-description">Maximum number of +</DD><DT CLASS="dt-description"><B><TT>{max_connections, Number}</TT></B></DT><DD CLASS="dd-description">Maximum number of active connections per file transfer initiator. No limit by default. -</DD><DT CLASS="dt-description"><B><TT>shaper</TT></B></DT><DD CLASS="dd-description">This option defines shaper for +</DD><DT CLASS="dt-description"><B><TT>{shaper, none|ShaperName}</TT></B></DT><DD CLASS="dd-description">This option defines shaper for the file transfer peers. Shaper with the maximum bandwidth will be selected. Default is <TT>none</TT>. </DD></DL><P>Examples: @@ -2778,30 +2747,30 @@ is enabled in the default ejabberd configuration file, and it requires <TT>mod_caps</TT>.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>host</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the +<B><TT>{host, HostName}</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the service. If the <TT>host</TT> option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix ‘<TT>pubsub.</TT>’. The keyword "@HOST@" is replaced at start time with the real virtual host name. -</DD><DT CLASS="dt-description"><B><TT>access_createnode</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{access_createnode, AccessName}</TT></B></DT><DD CLASS="dd-description"> This option restricts which users are allowed to create pubsub nodes using -ACL and ACCESS. The default value is <TT>pubsub_createnode</TT>. </DD><DT CLASS="dt-description"><B><TT>plugins</TT></B></DT><DD CLASS="dd-description"> +ACL and ACCESS. The default value is <TT>pubsub_createnode</TT>. </DD><DT CLASS="dt-description"><B><TT>{plugins, [ Plugin, ...]}</TT></B></DT><DD CLASS="dd-description"> To specify which pubsub node plugins to use. If not defined, the default pubsub plugin is always used. -</DD><DT CLASS="dt-description"><B><TT>nodetree</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{nodetree, Name}</TT></B></DT><DD CLASS="dd-description"> To specify which nodetree to use. If not defined, the default pubsub nodetree is used. Only one nodetree can be used per host, and is shared by all node plugins. -</DD><DT CLASS="dt-description"><B><TT>pep_sendlast_offline</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{pep_sendlast_offline, false|true}</TT></B></DT><DD CLASS="dd-description"> To specify whether or not we should get last published PEP items from users in our roster which are offline when we connect. Value is true or false. If not defined, pubsub assumes false so we only get last items of online contacts. -</DD><DT CLASS="dt-description"><B><TT>last_item_cache</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{last_item_cache, false|true}</TT></B></DT><DD CLASS="dd-description"> To specify whether or not pubsub should cache last items. Value is true or false. If not defined, pubsub do not cache last items. On systems with not so many nodes, caching last items speeds up pubsub and allows to raise user connection rate. The cost is memory usage, as every item is stored in memory. -</DD><DT CLASS="dt-description"><B><TT>pep_mapping</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{pep_mapping, [ {Key, Value}, ...]}</TT></B></DT><DD CLASS="dd-description"> This allow to define a Key-Value list to choose defined node plugins on given PEP namespace. The following example will use node_tune instead of node_pep for every PEP node with tune namespace: <PRE CLASS="verbatim"> {mod_pubsub, [{pep_mapping, [{"http://jabber.org/protocol/tune", "tune"}]}]} @@ -2825,17 +2794,17 @@ Register a new account on the server. </LI><LI CLASS="li-itemize">Delete an existing account on the server. </LI></UL><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>access</TT></B></DT><DD CLASS="dd-description"> This option can be configured to specify +<B><TT>{access, AccessName}</TT></B></DT><DD CLASS="dd-description"> This option can be configured to specify rules to restrict registration. If a rule returns ‘deny’ on the requested user name, registration for that user name is denied. (there are no restrictions by default). -</DD><DT CLASS="dt-description"><B><TT>welcome_message</TT></B></DT><DD CLASS="dd-description"> Set a welcome message that +</DD><DT CLASS="dt-description"><B><TT>{welcome_message, Message}</TT></B></DT><DD CLASS="dd-description"> Set a welcome message that is sent to each newly registered account. The first string is the subject, and the second string is the message body. In the body you can set a newline with the characters: <CODE>\n</CODE> -</DD><DT CLASS="dt-description"><B><TT>registration_watchers</TT></B></DT><DD CLASS="dd-description"> This option defines a +</DD><DT CLASS="dt-description"><B><TT>{registration_watchers, [ JID, ...]}</TT></B></DT><DD CLASS="dd-description"> This option defines a list of JIDs which will be notified each time a new account is registered. -</DD><DT CLASS="dt-description"><B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +</DD><DT CLASS="dt-description"><B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for In-Band Registration (<TT>jabber:iq:register</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). </DD></DL><P>This module reads also another option defined globally for the server: <TT>{registration_timeout, Timeout}</TT>. @@ -2894,12 +2863,12 @@ Also define a registration timeout of one hour: <A HREF="http://xmpp.org/specs/rfc3921.html#roster">RFC 3921: XMPP IM</A>. It also supports Roster Versioning (<A HREF="http://xmpp.org/extensions/xep-0237.html">XEP-0237</A>).</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +<B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for Roster Management (<TT>jabber:iq:roster</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). -</DD><DT CLASS="dt-description"><B><TT>{versioning, false | true}</TT></B></DT><DD CLASS="dd-description"> Enables +</DD><DT CLASS="dt-description"><B><TT>{versioning, false|true}</TT></B></DT><DD CLASS="dd-description"> Enables Roster Versioning. This option is disabled by default. -</DD><DT CLASS="dt-description"><B><TT>{store_current_id, false | true}</TT></B></DT><DD CLASS="dd-description"> +</DD><DT CLASS="dt-description"><B><TT>{store_current_id, false|true}</TT></B></DT><DD CLASS="dd-description"> If this option is enabled, the current version number is stored on the database. If disabled, the version number is calculated on the fly each time. Enabling this option reduces the load for both ejabberd and the database. @@ -2922,7 +2891,7 @@ auditing service such as packets are encapsulated in a <CODE><route/></CODE> element and sent to the specified service(s).</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>loggers</TT></B></DT><DD CLASS="dd-description"> With this option a (list of) service(s) +<B><TT>{loggers, [Names, ...]}</TT></B></DT><DD CLASS="dd-description"> With this option a (list of) service(s) that will receive the packets can be specified. </DD></DL><P>Examples: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> @@ -3030,7 +2999,7 @@ Total number of registered users on the current virtual host (users/total). </LI><LI CLASS="li-itemize">Total number of online users on all virtual hosts (users/all-hosts/online). </LI></UL><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +<B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for Statistics Gathering (<TT>http://jabber.org/protocol/stats</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). </DD></DL><P>As there are only a small amount of clients (for example <A HREF="http://tkabber.jabber.ru/">Tkabber</A>) and software libraries with @@ -3056,7 +3025,7 @@ by sending: </P><P>This module features support for Entity Time (<A HREF="http://xmpp.org/extensions/xep-0202.html">XEP-0202</A>). By using this XEP, you are able to discover the time at another entity’s location.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +<B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for Entity Time (<TT>jabber:iq:time</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). </DD></DL><P> <A NAME="modvcard"></A> </P><!--TOC subsection <TT>mod_vcard</TT>--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc62">3.3.24</A>  <A HREF="#modvcard"><TT>mod_vcard</TT></A></H3><!--SEC END --><P> <A NAME="modvcard"></A> @@ -3066,26 +3035,26 @@ implements an uncomplicated Jabber User Directory based on the vCards of these users. Moreover, it enables the server to send its vCard when queried.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>host</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the +<B><TT>{host, HostName}</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the service. If the <TT>host</TT> option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix ‘<TT>vjud.</TT>’. The keyword "@HOST@" is replaced at start time with the real virtual host name. -</DD><DT CLASS="dt-description"><B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +</DD><DT CLASS="dt-description"><B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for <TT>vcard-temp</TT> IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). -</DD><DT CLASS="dt-description"><B><TT>search</TT></B></DT><DD CLASS="dd-description">This option specifies whether the search -functionality is enabled (value: <TT>true</TT>) or disabled (value: -<TT>false</TT>). If disabled, the option <TT>host</TT> will be ignored and the +</DD><DT CLASS="dt-description"><B><TT>{search, true|false}</TT></B></DT><DD CLASS="dd-description">This option specifies whether the search +functionality is enabled or not +If disabled, the option <TT>host</TT> will be ignored and the Jabber User Directory service will not appear in the Service Discovery item list. The default value is <TT>true</TT>. -</DD><DT CLASS="dt-description"><B><TT>matches</TT></B></DT><DD CLASS="dd-description">With this option, the number of reported +</DD><DT CLASS="dt-description"><B><TT>{matches, infinity|Number}</TT></B></DT><DD CLASS="dd-description">With this option, the number of reported search results can be limited. If the option’s value is set to <TT>infinity</TT>, all search results are reported. The default value is <TT>30</TT>. -</DD><DT CLASS="dt-description"><B><TT>allow_return_all</TT></B></DT><DD CLASS="dd-description">This option enables +</DD><DT CLASS="dt-description"><B><TT>{allow_return_all, false|true}</TT></B></DT><DD CLASS="dd-description">This option enables you to specify if search operations with empty input fields should return all users who added some information to their vCard. The default value is <TT>false</TT>. -</DD><DT CLASS="dt-description"><B><TT>search_all_hosts</TT></B></DT><DD CLASS="dd-description">If this option is set +</DD><DT CLASS="dt-description"><B><TT>{search_all_hosts, true|false}</TT></B></DT><DD CLASS="dd-description">If this option is set to <TT>true</TT>, search operations will apply to all virtual hosts. Otherwise only the current host will be searched. The default value is <TT>true</TT>. This option is available in <TT>mod_vcard</TT>, but not available in <TT>mod_vcard_odbc</TT>. @@ -3129,32 +3098,35 @@ about these options. If one of these options is not set, <TT>ejabberd</TT> will for the top-level option with the same name.</P><P>The second group of parameters consists of the following <TT>mod_vcard_ldap</TT>-specific options:</P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>host</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the +<B><TT>{host, HostName}</TT></B></DT><DD CLASS="dd-description"> This option defines the Jabber ID of the service. If the <TT>host</TT> option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix ‘<TT>vjud.</TT>’. The keyword "@HOST@" is replaced at start time with the real virtual host name. -</DD><DT CLASS="dt-description"><B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +</DD><DT CLASS="dt-description"><B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for <TT>vcard-temp</TT> IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). -</DD><DT CLASS="dt-description"><B><TT>search</TT></B></DT><DD CLASS="dd-description">This option specifies whether the search +</DD><DT CLASS="dt-description"><B><TT>{search, true|false}</TT></B></DT><DD CLASS="dd-description">This option specifies whether the search functionality is enabled (value: <TT>true</TT>) or disabled (value: <TT>false</TT>). If disabled, the option <TT>host</TT> will be ignored and the Jabber User Directory service will not appear in the Service Discovery item list. The default value is <TT>true</TT>. -</DD><DT CLASS="dt-description"><B><TT>matches</TT></B></DT><DD CLASS="dd-description">With this option, the number of reported +</DD><DT CLASS="dt-description"><B><TT>{matches, infinity|Number}</TT></B></DT><DD CLASS="dd-description">With this option, the number of reported search results can be limited. If the option’s value is set to <TT>infinity</TT>, all search results are reported. The default value is <TT>30</TT>. -</DD><DT CLASS="dt-description"><B><TT>ldap_vcard_map</TT></B></DT><DD CLASS="dd-description">With this option you can -set the table that maps LDAP attributes to vCard fields. The format is: -<TT>[</TT><TT>Name_of_vCard_field, Pattern, List_of_LDAP_attributes</TT><TT>, ...]</TT>. -<TT>Name_of_vcard_field</TT> is the type name of the vCard as defined in -<A HREF="http://tools.ietf.org/html/rfc2426">RFC 2426</A>. <TT>Pattern</TT> is a -string which contains pattern variables <TT>"%u"</TT>, <TT>"%d"</TT> or -<TT>"%s"</TT>. <TT>List_of_LDAP_attributes</TT> is the list containing LDAP -attributes. The pattern variables <TT>"%s"</TT> will be sequentially replaced +</DD><DT CLASS="dt-description"><B><TT>{ldap_vcard_map, [ {Name, Pattern, LDAPattributes}, ...]}</TT></B></DT><DD CLASS="dd-description"> +With this option you can set the table that maps LDAP attributes to vCard fields. + +<TT>Name</TT> is the type name of the vCard as defined in +<A HREF="http://tools.ietf.org/html/rfc2426">RFC 2426</A>. +<TT>Pattern</TT> is a string which contains pattern variables +<TT>"%u"</TT>, <TT>"%d"</TT> or <TT>"%s"</TT>. +<TT>LDAPattributes</TT> is the list containing LDAP attributes. +The pattern variables +<TT>"%s"</TT> will be sequentially replaced with the values of LDAP attributes from <TT>List_of_LDAP_attributes</TT>, -<TT>"%u"</TT> will be replaced with the user part of a JID, and <TT>"%d"</TT> -will be replaced with the domain part of a JID. The default is: +<TT>"%u"</TT> will be replaced with the user part of a JID, +and <TT>"%d"</TT> will be replaced with the domain part of a JID. +The default is: <PRE CLASS="verbatim">[{"NICKNAME", "%u", []}, {"FN", "%s", ["displayName"]}, {"LAST", "%s", ["sn"]}, @@ -3175,9 +3147,9 @@ will be replaced with the domain part of a JID. The default is: {"BDAY", "%s", ["birthDay"]}, {"ROLE", "%s", ["employeeType"]}, {"PHOTO", "%s", ["jpegPhoto"]}] -</PRE></DD><DT CLASS="dt-description"><B><TT>ldap_search_fields</TT></B></DT><DD CLASS="dd-description">This option -defines the search form and the LDAP attributes to search within. The format -is: <TT>[</TT><TT>Name, Attribute</TT><TT>, ...]</TT>. <TT>Name</TT> is the name of a search form +</PRE></DD><DT CLASS="dt-description"><B><TT>{ldap_search_fields, [ {Name, Attribute}, ...]}</TT></B></DT><DD CLASS="dd-description">This option +defines the search form and the LDAP attributes to search within. +<TT>Name</TT> is the name of a search form field which will be automatically translated by using the translation files (see <TT>msgs/*.msg</TT> for available words). <TT>Attribute</TT> is the LDAP attribute or the pattern <TT>"%u"</TT>. The default is: @@ -3193,11 +3165,11 @@ LDAP attribute or the pattern <TT>"%u"</TT>. The default is: {"Email", "mail"}, {"Organization Name", "o"}, {"Organization Unit", "ou"}] -</PRE></DD><DT CLASS="dt-description"><B><TT>ldap_search_reported</TT></B></DT><DD CLASS="dd-description">This option -defines which search fields should be reported. The format is: -<TT>[</TT><TT>Name, vCard_Name</TT><TT>, ...]</TT>. <TT>Name</TT> is the name of a search form +</PRE></DD><DT CLASS="dt-description"><B><TT>{ldap_search_reported, [ {SearchField, VcardField}, ...]}</TT></B></DT><DD CLASS="dd-description">This option +defines which search fields should be reported. +<TT>SearchField</TT> is the name of a search form field which will be automatically translated by using the translation -files (see <TT>msgs/*.msg</TT> for available words). <TT>vCard_Name</TT> is the +files (see <TT>msgs/*.msg</TT> for available words). <TT>VcardField</TT> is the vCard field name defined in the <TT>ldap_vcard_map</TT> option. The default is: <PRE CLASS="verbatim">[{"Full Name", "FN"}, @@ -3294,9 +3266,9 @@ searching his info in LDAP.</P></LI><LI CLASS="li-itemize"><TT>ldap_vcard_map</T </P><P>This module implements Software Version (<A HREF="http://xmpp.org/extensions/xep-0092.html">XEP-0092</A>). Consequently, it answers <TT>ejabberd</TT>’s version when queried.</P><P>Options: </P><DL CLASS="description"><DT CLASS="dt-description"> -<B><TT>show_os</TT></B></DT><DD CLASS="dd-description">Should the operating system be revealed or not. +<B><TT>{show_os, true|false}</TT></B></DT><DD CLASS="dd-description">Should the operating system be revealed or not. The default value is <TT>true</TT>. -</DD><DT CLASS="dt-description"><B><TT>iqdisc</TT></B></DT><DD CLASS="dd-description"> This specifies +</DD><DT CLASS="dt-description"><B><TT>{iqdisc, Discipline}</TT></B></DT><DD CLASS="dd-description"> This specifies the processing discipline for Software Version (<TT>jabber:iq:version</TT>) IQ queries (see section <A HREF="#modiqdiscoption">3.3.2</A>). </DD></DL><P> <A NAME="manage"></A> </P><!--TOC chapter Managing an <TT>ejabberd</TT> Server--> <H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc65">Chapter 4</A>  <A HREF="#manage">Managing an <TT>ejabberd</TT> Server</A></H1><!--SEC END --><P> <A NAME="manage"></A> </P><P> <A NAME="ejabberdctl"></A> </P><!--TOC section <TT>ejabberdctl</TT>--> @@ -3483,11 +3455,11 @@ is very high. In that case, authentication information must be provided. In each frontend the <TT>AccessCommands</TT> option is defined in a different place. But in all cases the option syntax is the same: -</P><PRE CLASS="verbatim">AccessCommands = [ {Access, CommandNames, Arguments} ] +</P><PRE CLASS="verbatim">AccessCommands = [ {Access, CommandNames, Arguments}, ...] Access = atom() CommandNames = all | [CommandName] CommandName = atom() -Arguments = [{ArgumentName, ArgumentValue}] +Arguments = [ {ArgumentName, ArgumentValue}, ...] ArgumentName = atom() ArgumentValue = any() </PRE><P>The default value is to not define any restriction: <TT>[]</TT>. @@ -3800,8 +3772,8 @@ domain.</P><P> <A NAME="servicelb"></A> </P><!--TOC section Service Load-Balanci </P><P> <A NAME="componentlb"></A> </P><!--TOC subsection Components Load-Balancing--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc89">6.3.1</A>  <A HREF="#componentlb">Components Load-Balancing</A></H3><!--SEC END --><P> <A NAME="componentlb"></A> </P><P> <A NAME="domainlb"></A> </P><!--TOC subsection Domain Load-Balancing Algorithm--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc90">6.3.2</A>  <A HREF="#domainlb">Domain Load-Balancing Algorithm</A></H3><!--SEC END --><P> <A NAME="domainlb"></A> -</P><P><TT>ejabberd</TT> includes an algorithm to load balance the components that are plugged on an <TT>ejabberd</TT> cluster. It means that you can plug one or several instances of the same component on each <TT>ejabberd</TT> cluster and that the traffic will be automatically distributed.</P><P>The default distribution algorithm try to deliver to a local instance of a component. If several local instances are available, one instance is chosen randomly. If no instance is available locally, one instance is chosen randomly among the remote component instances.</P><P>If you need a different behaviour, you can change the load balancing behaviour with the option <TT>domain_balancing</TT>. The syntax of the option is the following:</P><PRE CLASS="verbatim">{domain_balancing, "component.example.com", <balancing_criterium>}. -</PRE><P>Several balancing criteria are available: +</P><P><TT>ejabberd</TT> includes an algorithm to load balance the components that are plugged on an <TT>ejabberd</TT> cluster. It means that you can plug one or several instances of the same component on each <TT>ejabberd</TT> cluster and that the traffic will be automatically distributed.</P><P>The default distribution algorithm try to deliver to a local instance of a component. If several local instances are available, one instance is chosen randomly. If no instance is available locally, one instance is chosen randomly among the remote component instances.</P><P>If you need a different behaviour, you can change the load balancing behaviour with the option <TT>domain_balancing</TT>. The syntax of the option is the following: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{domain_balancing, "component.example.com", BalancingCriteria}.</TT></B></DT></DL><P>Several balancing criteria are available: </P><UL CLASS="itemize"><LI CLASS="li-itemize"> <TT>destination</TT>: the full JID of the packet <TT>to</TT> attribute is used. </LI><LI CLASS="li-itemize"><TT>source</TT>: the full JID of the packet <TT>from</TT> attribute is used. @@ -3809,17 +3781,16 @@ domain.</P><P> <A NAME="servicelb"></A> </P><!--TOC section Service Load-Balanci </LI><LI CLASS="li-itemize"><TT>bare_source</TT>: the bare JID (without resource) of the packet <TT>from</TT> attribute is used. </LI></UL><P>If the value corresponding to the criteria is the same, the same component instance in the cluster will be used.</P><P> <A NAME="lbbuckets"></A> </P><!--TOC subsection Load-Balancing Buckets--> <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc91">6.3.3</A>  <A HREF="#lbbuckets">Load-Balancing Buckets</A></H3><!--SEC END --><P> <A NAME="lbbuckets"></A> -</P><P>When there is a risk of failure for a given component, domain balancing can cause service trouble. If one component is failing the service will not work correctly unless the sessions are rebalanced.</P><P>In this case, it is best to limit the problem to the sessions handled by the failing component. This is what the <TT>domain_balancing_component_number</TT> option does, making the load balancing algorithm not dynamic, but sticky on a fix number of component instances.</P><P>The syntax is the following: -</P><PRE CLASS="verbatim">{domain_balancing_component_number, "component.example.com", N} -</PRE><P> <A NAME="debugging"></A> </P><!--TOC chapter Debugging--> +</P><P>When there is a risk of failure for a given component, domain balancing can cause service trouble. If one component is failing the service will not work correctly unless the sessions are rebalanced.</P><P>In this case, it is best to limit the problem to the sessions handled by the failing component. This is what the <TT>domain_balancing_component_number</TT> option does, making the load balancing algorithm not dynamic, but sticky on a fix number of component instances.</P><P>The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{domain_balancing_component_number, "component.example.com", Number}.</TT></B></DT></DL><P> <A NAME="debugging"></A> </P><!--TOC chapter Debugging--> <H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc92">Chapter 7</A>  <A HREF="#debugging">Debugging</A></H1><!--SEC END --><P> <A NAME="debugging"></A> </P><P> <A NAME="logfiles"></A> </P><!--TOC section Log Files--> <H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc93">7.1</A>  <A HREF="#logfiles">Log Files</A></H2><!--SEC END --><P> <A NAME="logfiles"></A> </P><P>An <TT>ejabberd</TT> node writes two log files: </P><DL CLASS="description"><DT CLASS="dt-description"> <B><TT>ejabberd.log</TT></B></DT><DD CLASS="dd-description"> is the ejabberd service log, with the messages reported by <TT>ejabberd</TT> code </DD><DT CLASS="dt-description"><B><TT>sasl.log</TT></B></DT><DD CLASS="dd-description"> is the Erlang/OTP system log, with the messages reported by Erlang/OTP using SASL (System Architecture Support Libraries) -</DD></DL><P>The option <TT>loglevel</TT> modifies the verbosity of the file ejabberd.log. -The possible levels are: +</DD></DL><P>The option <TT>loglevel</TT> modifies the verbosity of the file ejabberd.log. The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{loglevel, Level}.</TT></B></DT></DL><P>The possible <TT>Level</TT> are: </P><DL CLASS="description"><DT CLASS="dt-description"> <B><TT>0</TT></B></DT><DD CLASS="dd-description"> No ejabberd log at all (not recommended) </DD><DT CLASS="dt-description"><B><TT>1</TT></B></DT><DD CLASS="dd-description"> Critical @@ -3847,12 +3818,14 @@ when troubleshooting a problem related to memory usage. If a process in the <TT>ejabberd</TT> server consumes more memory than the configured threshold, a message is sent to the Jabber accounts defined with the option <TT>watchdog_admins</TT> - in the <TT>ejabberd</TT> configuration file.</P><P>The memory consumed is measured in <TT>words</TT>: + in the <TT>ejabberd</TT> configuration file.</P><P>The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{watchdog_admins, [JID, ...]}.</TT></B></DT></DL><P>The memory consumed is measured in <TT>words</TT>: a word on 32-bit architecture is 4 bytes, and a word on 64-bit architecture is 8 bytes. The threshold by default is 1000000 words. This value can be configured with the option <TT>watchdog_large_heap</TT>, -or in a conversation with the watchdog alert bot.</P><P>Example configuration: +or in a conversation with the watchdog alert bot.</P><P>The syntax is: +</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>{watchdog_large_heap, Number}.</TT></B></DT></DL><P>Example configuration: </P><PRE CLASS="verbatim">{watchdog_admins, ["admin2@localhost", "admin2@example.org"]}. {watchdog_large_heap, 30000000}. </PRE><P>To remove watchdog admins, remove them in the option. diff --git a/doc/guide.tex b/doc/guide.tex index aba77c4a..b869e860 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -59,6 +59,7 @@ \newcommand{\shell}[1]{\texttt{#1}} \newcommand{\ejabberd}{\texttt{ejabberd}} \newcommand{\Jabber}{Jabber} +\newcommand{\esyntax}[1]{\begin{description}\titem{#1}\end{description}} %% Modules \newcommand{\module}[1]{\texttt{#1}} @@ -106,10 +107,10 @@ %\ifthenelse{\boolean{modhttpbind}}{\input{mod_http_bind.tex}}{} %% Common options -\newcommand{\iqdiscitem}[1]{\titem{iqdisc} \ind{options!iqdisc}This specifies +\newcommand{\iqdiscitem}[1]{\titem{\{iqdisc, Discipline\}} \ind{options!iqdisc}This specifies the processing discipline for #1 IQ queries (see section~\ref{modiqdiscoption}).} \newcommand{\hostitem}[1]{ - \titem{host} \ind{options!host} This option defines the Jabber ID of the + \titem{\{host, HostName\}} \ind{options!host} This option defines the Jabber ID of the service. If the \texttt{host} option is not specified, the Jabber ID will be the hostname of the virtual host with the prefix `\jid{#1.}'. The keyword "@HOST@" is replaced at start time with the real virtual host name. @@ -608,7 +609,7 @@ host name(s) stored in the database will be used. You can override the old values stored in the database by adding next lines to -the configuration file: +the beginning of the configuration file: \begin{verbatim} override_global. override_local. @@ -624,20 +625,18 @@ and ACLs will be removed before new ones are added. The option \option{hosts} defines a list containing one or more domains that \ejabberd{} will serve. +The syntax is: +\esyntax{\{hosts, [HostName, ...]\}.} + Examples: \begin{itemize} \item Serving one domain: \begin{verbatim} {hosts, ["example.org"]}. \end{verbatim} -\item Serving one domain, and backwards compatible with older \ejabberd{} - versions: -\begin{verbatim} -{host, "example.org"}. -\end{verbatim} -\item Serving two domains: +\item Serving three domains: \begin{verbatim} -{hosts, ["example.net", "example.com"]}. +{hosts, ["example.net", "example.com", "jabber.somesite.org"]}. \end{verbatim} \end{itemize} @@ -645,11 +644,10 @@ Examples: \ind{virtual hosting}\ind{virtual hosts}\ind{virtual domains} Options can be defined separately for every virtual host using the -\term{host\_config} option.\ind{options!host\_config} It has the following -syntax: -\begin{verbatim} -{host_config, <hostname>, [<option>, <option>, ...]}. -\end{verbatim} +\term{host\_config} option. + +The syntax is: \ind{options!host\_config} +\esyntax{\{host\_config, HostName, [Option, ...]\}} Examples: \begin{itemize} @@ -685,14 +683,10 @@ Examples: To define specific ejabberd modules in a virtual host, you can define the global \term{modules} option with the common modules, and later add specific modules to certain virtual hosts. -To accomplish that, instead of defining each option in \term{host\_config} with the syntax -\begin{verbatim} -{<option-name>, <option-value>} -\end{verbatim} +To accomplish that, instead of defining each option in \term{host\_config} with the general syntax +\esyntax{\{OptionName, OptionValue\}} use this syntax: -\begin{verbatim} -{{add, <option-name>}, <option-value>} -\end{verbatim} +\esyntax{\{\{add, OptionName\}, OptionValue\}} In this example three virtual hosts have some similar modules, but there are also other different modules for some specific virtual hosts: @@ -743,22 +737,14 @@ tuple with the following elements: \item Options for the TCP socket and for the listening module. \end{itemize} -With the basic syntax the ports will listen on all IPv4 network addresses: -\begin{verbatim} -{listen, [ - {<port-number>, <module>, [<options>]}, - {<port-number>, <module>, [<options>]}, - ... - {<port-number>, <module>, [<options>]} - ]}. -\end{verbatim} +The option syntax is: +\esyntax{\{listen, [Listener, ...]\}.} -It is possible to specify the IP address for a port using the full syntax: -\begin{verbatim} - {{<port-number>, <ip-address>}, <module>, [<options>]} - {{<port-number>, <transport-protocol>}, <module>, [<options>]} - {{<port-number>, <ip-address>, <transport-protocol>}, <module>, [<options>]} -\end{verbatim} +To define a listener there are several syntax. +\esyntax{\{PortNumber, Module, [Option, ...]\}} +\esyntax{\{\{PortNumber, IPaddress\}, Module, [Option, ...]\}} +\esyntax{\{\{PortNumber, TransportProtocol\}, Module, [Option, ...]\}} +\esyntax{\{\{PortNumber, IPaddress, TransportProtocol\}, Module, [Option, ...]\}} \makesubsubsection{listened-port}{Port Number, IP Address and Transport Protocol} @@ -773,6 +759,7 @@ The socket will listen only in that network interface. It is possible to specify a generic address, so \ejabberd{} will listen in all addresses. Depending in the type of the IP address, IPv4 or IPv6 will be used. +When not specified the IP address, it will listen on all IPv4 network addresses. Some example values for IP address: \begin{itemize} @@ -823,19 +810,19 @@ The available modules, their purpose and the options allowed by each one are: This is a detailed description of each option allowed by the listening modules: \begin{description} - \titem{\{access, <access rule>\}} \ind{options!access}This option defines + \titem{\{access, AccessName\}} \ind{options!access}This option defines access to the port. The default value is \term{all}. \titem{\{certfile, Path\}} Full path to a file containing the default SSL certificate. To define a certificate file specific for a given domain, use the global option \term{domain\_certfile}. - \titem{service\_check\_from} \ind{options!service\_check\_from} + \titem{\{service\_check\_from, true|false\}} \ind{options!service\_check\_from} This option can be used with \term{ejabberd\_service} only. It is used to disable control on the from field on packets send by an external components. The option can be either \term{true} or \term{false}. The default value is \term{true} which conforms to \xepref{0114}. - \titem{\{hosts, [Hostnames], [HostOptions]\}} \ind{options!hosts} + \titem{\{hosts, [Hostname, ...], [HostOption, ...]\}} \ind{options!hosts} The external Jabber component that connects to this \term{ejabberd\_service} can serve one or more hostnames. - In \term{HostOptions} you can define options for the component; + As \term{HostOption} you can define options for the component; currently the only allowed option is the password required to the component when attempt to connect to ejabberd: \poption{\{password, Secret\}}. Note that you cannot define in a single \term{ejabberd\_service} components of @@ -884,7 +871,7 @@ This is a detailed description of each option allowed by the listening modules: connections and 131072 for s2s connections. s2s max stanza size must always much higher than c2s limit. Change this value with extreme care as it can cause unwanted disconnect if set too low. - \titem{\{request\_handlers, [\{Path, Module\}]\}} To define one or several handlers that will serve HTTP requests. + \titem{\{request\_handlers, [ \{Path, Module\}, ...]\}} To define one or several handlers that will serve HTTP requests. The Path is a list of strings; so the URIs that start with that Path will be served by Module. For example, if you want \term{mod\_foo} to serve the URIs that start with \term{/a/b/}, and you also want \term{mod\_http\_bind} to serve the URIs \term{/http-bind/}, @@ -894,7 +881,7 @@ This is a detailed description of each option allowed by the listening modules: Note that \xepref{0114} requires that the domain must match the hostname of the component. Only enable this option if you are completely sure you need to enable it. Default value: false. - \titem{\{shaper, <access rule>\}} \ind{options!shaper}This option defines a + \titem{\{shaper, none|ShaperName\}} \ind{options!shaper}This option defines a shaper for the port (see section~\ref{shapers}). The default value is \term{none}. \titem{starttls} \ind{options!starttls}\ind{STARTTLS}This option @@ -941,7 +928,7 @@ There are some additional global options that can be specified in the ejabberd c Specify which address families to try, in what order, and connect timeout in milliseconds. By default it first tries connecting with IPv4, if that fails it tries using IPv6, with a timeout of 10000 milliseconds. - \titem{\{s2s\_dns\_options, [\{Property, Value\}]\}} + \titem{\{s2s\_dns\_options, [ \{Property, Value\}, ...]\}} \ind{options!s2s\_dns\_options}Define properties to use for DNS resolving. Allowed Properties are: \term{timeout} in seconds which default value is \term{10} and \term{retries} which default value is \term{2}. @@ -1136,11 +1123,9 @@ you have to make the transports log and do \ind{XDB}XDB by themselves: \makesubsection{auth}{Authentication} \ind{authentication}\ind{options!auth\_method} -The option \option{auth\_method} defines the authentication method that is used -for user authentication: -\begin{verbatim} -{auth_method, [<method>]}. -\end{verbatim} +The option \option{auth\_method} defines the authentication methods that are used +for user authentication. The syntax is: +\esyntax{\{auth\_method, [Method, ...]\}.} The following authentication methods are supported by \ejabberd{}: \begin{itemize} @@ -1160,11 +1145,7 @@ Account creation is only supported by internal and odbc methods. \ind{internal authentication}\ind{Mnesia} \ejabberd{} uses its internal Mnesia database as the default authentication method. - -\begin{itemize} -\item \term{auth\_method}: The value \term{internal} will enable the internal - authentication method. -\end{itemize} +The value \term{internal} will enable the internal authentication method. Examples: \begin{itemize} @@ -1183,6 +1164,8 @@ Examples: \makesubsubsection{saslanonymous}{SASL Anonymous and Anonymous Login} \ind{sasl anonymous}\ind{anonymous login} +The value \term{anonymous} will enable the internal authentication method. + %TODO: introduction; tell what people can do with this The anonymous authentication method can be configured with the following options. Remember that you can use the \term{host\_config} option to set virtual @@ -1190,21 +1173,19 @@ host specific options (see section~\ref{virtualhost}). Note that there also is a detailed tutorial regarding \footahref{http://support.process-one.net/doc/display/MESSENGER/Anonymous+users+support}{SASL Anonymous and anonymous login configuration}. -\begin{itemize} -\item \term{auth\_method}: The value \term{anonymous} will enable the anonymous - authentication method. -\item \term{allow\_multiple\_connections}: This value for this option can be - either \term{true} or \term{false} and is only used when the anonymous mode is +\begin{description} +\titem{\{allow\_multiple\_connections, false|true\}} This option is only used + when the anonymous mode is enabled. Setting it to \term{true} means that the same username can be taken multiple times in anonymous login mode if different resource are used to connect. This option is only useful in very special occasions. The default value is \term{false}. -\item \term{anonymous\_protocol}: This option can take three values: - \term{sasl\_anon}, \term{login\_anon} or \term{both}. \term{sasl\_anon} means +\titem{\{anonymous\_protocol, sasl\_anon | login\_anon | both\}} + \term{sasl\_anon} means that the SASL Anonymous method will be used. \term{login\_anon} means that the anonymous login method will be used. \term{both} means that SASL Anonymous and login anonymous are both enabled. -\end{itemize} +\end{description} Those options are defined for each virtual host with the \term{host\_config} parameter (see section~\ref{virtualhost}). @@ -1257,7 +1238,7 @@ PAM authentication is disabled by default, so you have to configure and compile Options: \begin{description} -\titem{pam\_service}\ind{options!pam\_service}This option defines the PAM service name. +\titem{\{pam\_service, Name\}}\ind{options!pam\_service}This option defines the PAM service name. Default is \term{"ejabberd"}. Refer to the PAM documentation of your operation system for more information. \end{description} @@ -1314,75 +1295,74 @@ then \term{/etc/nssswitch.conf} must be configured to use \term{winbind} as well Access control in \ejabberd{} is performed via Access Control Lists (ACLs). The declarations of ACLs in the configuration file have the following syntax: -\begin{verbatim} -{acl, <aclname>, {<acltype>, ...}}. -\end{verbatim} -\term{<acltype>} can be one of the following: +\esyntax{\{acl, ACLName, ACLValue\}.} + +\term{ACLValue} can be one of the following: \begin{description} \titem{all} Matches all JIDs. Example: \begin{verbatim} {acl, all, all}. \end{verbatim} -\titem{\{user, <username>\}} Matches the user with the name - \term{<username>} at the first virtual host. Example: +\titem{\{user, Username\}} Matches the user with the name + \term{Username} at the first virtual host. Example: \begin{verbatim} {acl, admin, {user, "yozhik"}}. \end{verbatim} -\titem{\{user, <username>, <server>\}} Matches the user with the JID - \term{<username>@<server>} and any resource. Example: +\titem{\{user, Username, Server\}} Matches the user with the JID + \term{Username@Server} and any resource. Example: \begin{verbatim} {acl, admin, {user, "yozhik", "example.org"}}. \end{verbatim} -\titem{\{server, <server>\}} Matches any JID from server - \term{<server>}. Example: +\titem{\{server, Server\}} Matches any JID from server + \term{Server}. Example: \begin{verbatim} {acl, exampleorg, {server, "example.org"}}. \end{verbatim} -\titem{\{resource, <resource>\}} Matches any JID with a resource - \term{<resource>}. Example: +\titem{\{resource, Resource\}} Matches any JID with a resource + \term{Resource}. Example: \begin{verbatim} {acl, mucklres, {resource, "muckl"}}. \end{verbatim} -\titem{\{shared\_group, <groupname>\}} Matches any member of a Shared Roster Group with name \term{<groupname>} in the virtual host. Example: +\titem{\{shared\_group, Groupname\}} Matches any member of a Shared Roster Group with name \term{Groupname} in the virtual host. Example: \begin{verbatim} {acl, techgroupmembers, {shared_group, "techteam"}}. \end{verbatim} -\titem{\{shared\_group, <groupname>, <server>\}} Matches any member of a Shared Roster Group with name \term{<groupname>} in the virtual host \term{<server>}. Example: +\titem{\{shared\_group, Groupname, Server\}} Matches any member of a Shared Roster Group with name \term{Groupname} in the virtual host \term{Server}. Example: \begin{verbatim} {acl, techgroupmembers, {shared_group, "techteam", "example.org"}}. \end{verbatim} -\titem{\{user\_regexp, <regexp>\}} Matches any local user with a name that - matches \term{<regexp>} on local virtual hosts. Example: +\titem{\{user\_regexp, Regexp\}} Matches any local user with a name that + matches \term{Regexp} on local virtual hosts. Example: \begin{verbatim} {acl, tests, {user_regexp, "^test[0-9]*$"}}. \end{verbatim} %$ -\titem{\{user\_regexp, <regexp>, <server>\}} Matches any user with a name - that matches \term{<regexp>} at server \term{<server>}. Example: +\titem{\{user\_regexp, UserRegexp, Server\}} Matches any user with a name + that matches \term{Regexp} at server \term{Server}. Example: \begin{verbatim} -{acl, tests, {user_regexp, "^test", "example.org"}}. +{acl, tests, {user_Userregexp, "^test", "example.org"}}. \end{verbatim} -\titem{\{server\_regexp, <regexp>\}} Matches any JID from the server that - matches \term{<regexp>}. Example: +\titem{\{server\_regexp, Regexp\}} Matches any JID from the server that + matches \term{Regexp}. Example: \begin{verbatim} {acl, icq, {server_regexp, "^icq\\."}}. \end{verbatim} -\titem{\{resource\_regexp, <regexp>\}} Matches any JID with a resource that - matches \term{<regexp>}. Example: +\titem{\{resource\_regexp, Regexp\}} Matches any JID with a resource that + matches \term{Regexp}. Example: \begin{verbatim} {acl, icq, {resource_regexp, "^laptop\\."}}. \end{verbatim} -\titem{\{node\_regexp, <user\_regexp>, <server\_regexp>\}} Matches any user - with a name that matches \term{<user\_regexp>} at any server that matches - \term{<server\_regexp>}. Example: +\titem{\{node\_regexp, UserRegexp, ServerRegexp\}} Matches any user + with a name that matches \term{UserRegexp} at any server that matches + \term{ServerRegexp}. Example: \begin{verbatim} {acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}. \end{verbatim} -\titem{\{user\_glob, <glob>\}} -\titem{\{user\_glob, <glob>, <server>\}} -\titem{\{server\_glob, <glob>\}} -\titem{\{resource\_glob, <glob>\}} -\titem{\{node\_glob, <user\_glob>, <server\_glob>\}} This is the same as +\titem{\{user\_glob, Glob\}} +\titem{\{user\_glob, Glob, Server\}} +\titem{\{server\_glob, Glob\}} +\titem{\{resource\_glob, Glob\}} +\titem{\{node\_glob, UserGlob, ServerGlob\}} This is the same as above. However, it uses shell glob patterns instead of regexp. These patterns can have the following special characters: \begin{description} @@ -1395,7 +1375,7 @@ declarations of ACLs in the configuration file have the following syntax: \end{description} \end{description} -The following ACLs are pre-defined: +The following \term{ACLName} are pre-defined: \begin{description} \titem{all} Matches any JID. \titem{none} Matches no JID. @@ -1404,15 +1384,11 @@ The following ACLs are pre-defined: \makesubsubsection{AccessRights}{Access Rights} \ind{access}\ind{ACL}\ind{options!acl}\ind{ACL}\ind{Access Control List} -An entry allowing or denying access to different services looks similar to -this: -\begin{verbatim} -{access, <accessname>, [{allow, <aclname>}, - {deny, <aclname>}, - ... - ]}. -\end{verbatim} -When a JID is checked to have access to \term{<accessname>}, the server +An entry allowing or denying access to different services. +The syntax is: +\esyntax{\{access, AccessName, [ \{allow|deny, ACLName\}, ...]\}.} + +When a JID is checked to have access to \term{Accessname}, the server sequentially checks if that JID matches any of the ACLs that are named in the second elements of the tuples in the list. If it matches, the first element of the first matched tuple is returned, otherwise the value `\term{deny}' is @@ -1425,7 +1401,7 @@ Example: {allow, all}]}. \end{verbatim} -The following access rules are pre-defined: +The following \term{AccessName} are pre-defined: \begin{description} \titem{all} Always returns the value `\term{allow}'. \titem{none} Always returns the value `\term{deny}'. @@ -1443,19 +1419,12 @@ can be either a number, or \term{infinity}. The default value is \term{infinity}. The syntax is: -\begin{verbatim} -{access, max_user_sessions, [{<maxnumber>, <aclname>}, - ... - ]}. -\end{verbatim} +\esyntax{\{access, max\_user\_sessions, [ \{MaxNumber, ACLName\}, ...]\}.} -Examples: -\begin{itemize} -\item To limit the number of sessions per user to 10 for all users: +This example limits the number of sessions per user to 5 for all users, and to 10 for admins: \begin{verbatim} -{access, max_user_sessions, [{10, all}]}. +{access, max_user_sessions, [{10, admin}, {5, all}]}. \end{verbatim} -\end{itemize} \makesubsubsection{configmaxs2sconns}{Several connections to a remote Jabber server with ACL} \ind{options!max\_s2s\_connections} @@ -1466,11 +1435,7 @@ The default value is \term{1}. There's also available the access \term{max\_s2s\_connections\_per\_node}. The syntax is: -\begin{verbatim} -{access, max_s2s_connections, [{<maxnumber>, <aclname>}, - ... - ]}. -\end{verbatim} +\esyntax{\{access, max\_s2s\_connections, [ \{MaxNumber, ACLName\}, ...]\}.} Examples: \begin{itemize} @@ -1483,17 +1448,13 @@ Examples: \makesubsection{shapers}{Shapers} \ind{options!shaper}\ind{options!maxrate}\ind{shapers}\ind{maxrate}\ind{traffic speed} -Shapers enable you to limit connection traffic. The syntax of -shapers is like this: -\begin{verbatim} -{shaper, <shapername>, <kind>}. -\end{verbatim} +Shapers enable you to limit connection traffic. +The syntax is: +\esyntax{\{shaper, ShaperName, Kind\}.} Currently only one kind of shaper called \term{maxrate} is available. It has the following syntax: -\begin{verbatim} -{maxrate, <rate>} -\end{verbatim} -where \term{<rate>} stands for the maximum allowed incoming rate in bytes per +\esyntax{\{maxrate, Rate\}} +where \term{Rate} stands for the maximum allowed incoming rate in bytes per second. When a connection exceeds this limit, \ejabberd{} stops reading from the socket until the average rate is again below the allowed maximum. @@ -1517,9 +1478,14 @@ Examples: The option \option{language} defines the default language of server strings that can be seen by \Jabber{} clients. If a \Jabber{} client does not support -\option{xml:lang}, the specified language is used. The default value is -\term{en}. In order to take effect there must be a translation file -\term{<language>.msg} in \ejabberd{}'s \term{msgs} directory. +\option{xml:lang}, the specified language is used. + +The option syntax is: +\esyntax{\{language, Language\}.} + +The default value is \term{en}. +In order to take effect there must be a translation file +\term{Language.msg} in \ejabberd{}'s \term{msgs} directory. For example, to set Russian as default language: \begin{verbatim} @@ -1618,14 +1584,10 @@ _stuns._tcp IN SRV 0 0 5349 stun.example.com. The option \option{include\_config\_file} in a configuration file instructs \ejabberd{} to include other configuration files immediately. -The basic usage is: -\begin{verbatim} -{include_config_file, <filename>}. -\end{verbatim} -It is also possible to specify suboptions: -\begin{verbatim} -{include_config_file, <filename>, [<suboption>, <suboption>, ...]}. -\end{verbatim} +The basic syntax is: +\esyntax{\{include\_config\_file, Filename\}.} +It is possible to specify suboptions using the full syntax: +\esyntax{\{include\_config\_file, Filename, [Suboption, ...]\}.} The filename can be indicated either as an absolute path, or relative to the main \ejabberd{} configuration file. @@ -1634,10 +1596,10 @@ The file must exist and be readable. The allowed suboptions are: \begin{description} - \titem{\{disallow, [<option>, <option>, ...]\}} Disallows the usage of those options in the included configuration file. + \titem{\{disallow, [Optionname, ...]\}} Disallows the usage of those options in the included configuration file. The options that match this criteria are not accepted. The default value is an empty list: \term{[]} - \titem{\{allow\_only, [<option>, <option>, ...]\}} Allows only the usage of those options in the included configuration file. + \titem{\{allow\_only, [Optionname, ...]\}} Allows only the usage of those options in the included configuration file. The options that do not match this criteria are not accepted. The default value is: \term{all} \end{description} @@ -1676,9 +1638,7 @@ it is possible to define a macro for a value and later use this macro when defining an option. A macro is defined with this syntax: -\begin{verbatim} -{define_macro, '<MACRO>', <value>}. -\end{verbatim} +\esyntax{\{define\_macro, 'MACRO', Value\}.} The \term{MACRO} must be surrounded by single quotation marks, and all letters in uppercase; check the examples bellow. The \term{value} can be any valid arbitrary Erlang term. @@ -1697,20 +1657,20 @@ of another macro. There are two ways to use a macro: \begin{description} - \titem{'<MACRO>'} + \titem{'MACRO'} You can put this instead of a value in an \ejabberd{} option, and will be replaced with the \term{value} previously defined. If the macro is not defined previously, the program will crash and report an error. - \titem{\{use\_macro, '<MACRO>', <defaultvalue>\}} + \titem{\{use\_macro, 'MACRO', Defaultvalue\}} Use a macro even if it may not be defined. If the macro is not defined previously, the provided \term{defaultvalue} is used. This usage behaves as if it were defined and used this way: \begin{verbatim} -{define_macro, '<MACRO>', <defaultvalue>}. -'<MACRO>' +{define_macro, 'MACRO', Defaultvalue}. +'MACRO' \end{verbatim} \end{description} @@ -1839,27 +1799,19 @@ interface available, PostgreSQL or MySQL. To use the native MySQL interface, you can pass a tuple of the following form as parameter: -\begin{verbatim} -{mysql, "Server", "Database", "Username", "Password"} -\end{verbatim} +\esyntax{\{mysql, "Server", "Database", "Username", "Password"\}} \term{mysql} is a keyword that should be kept as is. For example: -\begin{verbatim} -{odbc_server, {mysql, "localhost", "test", "root", "password"}}. -\end{verbatim} +\esyntax{\{odbc\_server, \{mysql, "localhost", "test", "root", "password"\}\}.} Optionally, it is possible to define the MySQL port to use. This option is only useful, in very rare cases, when you are not running MySQL with the default port setting. The \term{mysql} parameter can thus take the following form: -\begin{verbatim} -{mysql, "Server", Port, "Database", "Username", "Password"} -\end{verbatim} +\esyntax{\{mysql, "Server", Port, "Database", "Username", "Password"\}} The \term{Port} value should be an integer, without quotes. For example: -\begin{verbatim} -{odbc_server, {mysql, "localhost", Port, "test", "root", "password"}}. -\end{verbatim} +\esyntax{\{odbc\_server, \{mysql, "localhost", Port, "test", "root", "password"\}\}.} By default \ejabberd{} opens 10 connections to the database for each virtual host. Use this option to modify the value: @@ -2017,27 +1969,20 @@ interface available, PostgreSQL or MySQL. To use the native PostgreSQL interface, you can pass a tuple of the following form as parameter: -\begin{verbatim} -{pgsql, "Server", "Database", "Username", "Password"} -\end{verbatim} +\esyntax{\{pgsql, "Server", "Database", "Username", "Password"\}} \term{pgsql} is a keyword that should be kept as is. For example: -\begin{verbatim} -{odbc_server, {pgsql, "localhost", "database", "ejabberd", "password"}}. -\end{verbatim} +\esyntax{\{odbc\_server, \{pgsql, "localhost", "database", "ejabberd", "password"\}\}.} Optionally, it is possible to define the PostgreSQL port to use. This option is only useful, in very rare cases, when you are not running PostgreSQL with the default port setting. The \term{pgsql} parameter can thus take the following form: -\begin{verbatim} -{pgsql, "Server", Port, "Database", "Username", "Password"} -\end{verbatim} +\esyntax{\{pgsql, "Server", Port, "Database", "Username", "Password"\}} The \term{Port} value should be an integer, without quotes. For example: -\begin{verbatim} -{odbc_server, {pgsql, "localhost", 5432, "database", "ejabberd", "password"}}. -\end{verbatim} +\esyntax{\{odbc\_server, \{pgsql, "localhost", 5432, "database", "ejabberd", "password"\}\}.} + By default \ejabberd{} opens 10 connections to the database for each virtual host. Use this option to modify the value: \begin{verbatim} @@ -2170,20 +2115,20 @@ create accounts, change password or edit vCard that is stored in LDAP. Parameters: \begin{description} -\titem{ldap\_servers} \ind{options!ldap\_server}List of IP addresses or DNS names of your +\titem{\{ldap\_servers, [Servers, ...]\}} \ind{options!ldap\_server}List of IP addresses or DNS names of your LDAP servers. This option is required. -\titem{ldap\_encrypt} \ind{options!ldap\_encrypt}Type of connection encryption to the LDAP server. +\titem{\{ldap\_encrypt, none|tls\}} \ind{options!ldap\_encrypt}Type of connection encryption to the LDAP server. Allowed values are: \term{none}, \term{tls}. Note that STARTTLS is not supported. The default value is: \term{none}. -\titem{ldap\_port} \ind{options!ldap\_port}Port to connect to your LDAP server. +\titem{\{ldap\_port, Number\}} \ind{options!ldap\_port}Port to connect to your LDAP server. The default port is~389 if encryption is disabled; and 636 if encryption is enabled. If you configure a value, it is stored in \ejabberd{}'s database. Then, if you remove that value from the configuration file, the value previously stored in the database will be used instead of the default port. -\titem{ldap\_rootdn} \ind{options!ldap\_rootdn}Bind DN. The default value +\titem{\{ldap\_rootdn, RootDN\}} \ind{options!ldap\_rootdn}Bind DN. The default value is~\term{""} which means `anonymous connection'. -\titem{ldap\_password} \ind{options!ldap\_password}Bind password. The default +\titem{\{ldap\_password, Password\}} \ind{options!ldap\_password}Bind password. The default value is \term{""}. \end{description} @@ -2204,15 +2149,15 @@ and SASL authentication. You can authenticate users against an LDAP directory. Available options are: \begin{description} -\titem{ldap\_base}\ind{options!ldap\_base}LDAP base directory which stores +\titem{\{ldap\_base, Base\}}\ind{options!ldap\_base}LDAP base directory which stores users accounts. This option is required. - \titem{ldap\_uids}\ind{options!ldap\_uids}LDAP attribute which holds a list - of attributes to use as alternatives for getting the JID. The value is of - the form: \term{[\{ldap\_uidattr\}]} or \term{[\{ldap\_uidattr, - ldap\_uidattr\_format\}]}. You can use as many comma separated tuples - \term{\{ldap\_uidattr, ldap\_uidattr\_format\}} that is needed. The default - value is \term{[\{"uid", "\%u"\}]}. The defaut \term{ldap\_uidattr\_format} - is \term{"\%u"}. The values for \term{ldap\_uidattr} and + \titem{\{ldap\_uids, [ \{ldap\_uidattr\} | \{ldap\_uidattr, ldap\_uidattr\_format\}, ...]\}}\ind{options!ldap\_uids} + LDAP attribute which holds a list of attributes to use as alternatives for getting the JID. + The default attributes are \term{[\{"uid", "\%u"\}]}. + The attributes are of the form: + \term{[\{ldap\_uidattr\}]} or \term{[\{ldap\_uidattr, ldap\_uidattr\_format\}]}. + You can use as many comma separated attributes as needed. + The values for \term{ldap\_uidattr} and \term{ldap\_uidattr\_format} are described as follow: \begin{description} \titem{ldap\_uidattr}\ind{options!ldap\_uidattr}LDAP attribute which holds @@ -2223,7 +2168,7 @@ You can authenticate users against an LDAP directory. Available options are: user's part of a JID. For example, \term{"\%u@example.org"}. The default value is \term{"\%u"}. \end{description} - \titem{ldap\_filter}\ind{options!ldap\_filter}\ind{protocols!RFC 4515: + \titem{\{ldap\_filter, Filter\}}\ind{options!ldap\_filter}\ind{protocols!RFC 4515: LDAP String Representation of Search Filters} \footahref{http://tools.ietf.org/html/rfc4515}{RFC 4515} LDAP filter. The default is \term{none}. Example: @@ -2232,7 +2177,7 @@ You can authenticate users against an LDAP directory. Available options are: \emph{must not} use \option{ldap\_uidattr} attribute in filter because this attribute will be substituted in LDAP filter automatically. - \titem{ldap\_local\_filter}\ind{options!ldap\_local\_filter} + \titem{\{ldap\_local\_filter, Filter\}}\ind{options!ldap\_local\_filter} If you can't use \term{ldap\_filter} due to performance reasons (the LDAP server has many users registered), you can use this local filter. @@ -2395,6 +2340,9 @@ The option \term{modules} defines the list of modules that will be loaded after element is the name of a module and the second is a list of options for that module. +The syntax is: +\esyntax{\{modules, [ \{ModuleName, ModuleOptions\}, ...]\}.} + Examples: \begin{itemize} \item In this example only the module \modecho{} is loaded and no module @@ -2512,7 +2460,12 @@ this separate section. Many modules define handlers for processing IQ queries of different namespaces to this server or to a user (e.\,g.\ to \jid{example.org} or to \jid{user@example.org}). This option defines processing discipline for -these queries. Possible values are: +these queries. + +The syntax is: +\esyntax{\{iqdisc, Value\}} + +Possible \term{Value} are: \begin{description} \titem{no\_queue} All queries of a namespace with this processing discipline are processed immediately. This also means that no other packets can be processed @@ -2546,7 +2499,12 @@ Example: \ind{options!host} This option defines the Jabber ID of a service provided by an \ejabberd{} module. -The keyword "@HOST@" is replaced at start time with the real virtual host string. + +The syntax is: +\esyntax{\{host, HostName\}} + +If you include the keyword "@HOST@" in the HostName, +it is replaced at start time with the real virtual host string. This example configures the \ind{modules!\modecho{}}echo module to provide its echoing service @@ -2610,7 +2568,7 @@ hosts in ejabberd. Options: \begin{description} -\titem{access} \ind{options!access}This option specifies who is allowed to +\titem{\{access, AccessName\}} \ind{options!access}This option specifies who is allowed to send announcements and to set the message of the day (by default, nobody is able to send such messages). \end{description} @@ -2671,9 +2629,9 @@ Options: \begin{description} \iqdiscitem{Service Discovery (\ns{http://jabber.org/protocol/disco\#items} and \ns{http://jabber.org/protocol/disco\#info})} -\titem{\{extra\_domains, [ Domain ]\}} \ind{options!extra\_domains}With this option, +\titem{\{extra\_domains, [Domain, ...]\}} \ind{options!extra\_domains}With this option, you can specify a list of extra domains that are added to the Service Discovery item list. -\titem{\{server\_info, [ \{Modules, Field, [Value]\} ]\}} \ind{options!server\_info} +\titem{\{server\_info, [ \{Modules, Field, [Value, ...]\}, ... ]\}} \ind{options!server\_info} Specify additional information about the server, as described in Contact Addresses for XMPP Services (\xepref{0157}). \term{Modules} can be the keyword `all', @@ -2816,9 +2774,12 @@ For example: ]}. \end{verbatim} -The maximum inactivity period is by default 30 seconds. -This can be configured with the module option \term{max\_inactivity}. -For example, to set 50 seconds: +Options: +\begin{description} + \titem{\{max\_inactivity, Seconds\}} \ind{options!max\_inactivity} + Define the maximum inactivity period in seconds. + Default value is 30 seconds. + For example, to set 50 seconds: \begin{verbatim} {modules, [ @@ -2827,6 +2788,8 @@ For example, to set 50 seconds: ... ]}. \end{verbatim} +\end{description} + \makesubsection{modhttpfileserver}{\modhttpfileserver{}} \ind{modules!\modhttpfileserver{}}\ind{modhttpfileserver} @@ -2835,22 +2798,26 @@ This simple module serves files from the local disk over HTTP. Options: \begin{description} - \titem{docroot} \ind{options!docroot} + \titem{\{docroot, Path\}} \ind{options!docroot} Directory to serve the files. - \titem{accesslog} \ind{options!accesslog} + \titem{\{accesslog, Path\}} \ind{options!accesslog} File to log accesses using an Apache-like format. No log will be recorded if this option is not specified. - \titem{directory\_indices} \ind{options!directoryindices} + \titem{\{directory\_indices, [Index, ...]\}} \ind{options!directoryindices} Indicate one or more directory index files, similarly to Apache's DirectoryIndex variable. When a web request hits a directory instead of a regular file, those directory indices are looked in order, and the first one found is returned. - \titem{content\_types} \ind{options!contenttypes} + %B \titem{content\_types} \ind{options!contenttypes} + %M \titem{\{content\_types, \{Extension, Type\} \}} \ind{options!contenttypes} + %B \titem{\{content\_types, [ Extension, Type, ... ]\}} \ind{options!contenttypes} + %B \titem{\{content\_types, [ {Extension, Type}, ... ]\}} \ind{options!contenttypes} + %M \titem{\{content\_types, [ \{Extension, Type\}, ... ]\}} \ind{options!contenttypes} Specify a mapping of extensions to content types. There are several content types already defined, with this option you can add new definitions, modify or delete existing ones. To delete an existing definition, simply define it with a value: `undefined'. - \titem{default\_content\_type} \ind{options!defaultcontenttype} + \titem{\{default\_content\_type, Type\}} \ind{options!defaultcontenttype} Specify the content type to use for unknown extensions. Default value is `application/octet-stream'. \end{description} @@ -2929,9 +2896,10 @@ End user information: Options: \begin{description} \hostitem{irc} -\titem{access} \ind{options!access}This option can be used to specify who +\titem{\{access, AccessName\}} \ind{options!access}This option can be used to specify who may use the IRC transport (default value: \term{all}). -\titem{default\_encoding} \ind{options!defaultencoding}Set the default IRC encoding (default value: \term{"koi8-r"}). +\titem{\{default\_encoding, Encoding\}} \ind{options!defaultencoding}Set the default IRC encoding. + Default value: \term{"koi8-r"} \end{description} Examples: @@ -3012,15 +2980,15 @@ on an available node on first connection attempt. Module options: \begin{description} \hostitem{conference} -\titem{access} \ind{options!access}You can specify who is allowed to use +\titem{\{access, AccessName\}} \ind{options!access}You can specify who is allowed to use the Multi-User Chat service. By default everyone is allowed to use it. -\titem{access\_create} \ind{options!access\_create}To configure who is +\titem{\{access\_create, AccessName\}} \ind{options!access\_create}To configure who is allowed to create new rooms at the Multi-User Chat service, this option can be used. By default everybody is allowed to create rooms. -\titem{access\_persistent} \ind{options!access\_persistent}To configure who is +\titem{\{access\_persistent, AccessName\}} \ind{options!access\_persistent}To configure who is allowed to modify the 'persistent' room option. By default everybody is allowed to modify that option. -\titem{access\_admin} \ind{options!access\_admin}This option specifies +\titem{\{access\_admin, AccessName\}} \ind{options!access\_admin}This option specifies who is allowed to administrate the Multi-User Chat service. The default value is \term{none}, which means that only the room creator can administer his room. @@ -3028,7 +2996,7 @@ Module options: and it will be shown in all active rooms as a service message. The administrators can send a groupchat message to the JID of an active room, and the message will be shown in the room as a service message. -\titem{history\_size} \ind{options!history\_size}A small history of +\titem{\{history\_size, Size\}} \ind{options!history\_size}A small history of the current discussion is sent to users when they enter the room. With this option you can define the number of history messages to keep and send to users joining the room. The value is an @@ -3036,35 +3004,35 @@ Module options: and, as a result, nothing is kept in memory. The default value is \term{20}. This value is global and thus affects all rooms on the service. -\titem{max\_users} \ind{options!max\_users} This option defines at +\titem{\{max\_users, Number\}} \ind{options!max\_users} This option defines at the service level, the maximum number of users allowed per room. It can be lowered in each room configuration but cannot be increased in individual room configuration. The default value is 200. -\titem{max\_users\_admin\_threshold} +\titem{\{max\_users\_admin\_threshold, Number\}} \ind{options!max\_users\_admin\_threshold} This option defines the number of service admins or room owners allowed to enter the room when the maximum number of allowed occupants was reached. The default limit is 5. -\titem{max\_user\_conferences} +\titem{\{max\_user\_conferences, Number\}} \ind{options!max\_user\_conferences} This option defines the maximum number of rooms that any given user can join. The default value is 10. This option is used to prevent possible abuses. Note that this is a soft limit: some users can sometimes join more conferences in cluster configurations. -\titem{max\_room\_id} \ind{options!max\_room\_id} +\titem{\{max\_room\_id, Number\}} \ind{options!max\_room\_id} This option defines the maximum number of characters that Room ID can have when creating a new room. The default value is to not limit: infinite. -\titem{max\_room\_name} \ind{options!max\_room\_name} +\titem{\{max\_room\_name, Number\}} \ind{options!max\_room\_name} This option defines the maximum number of characters that Room Name can have when configuring the room. The default value is to not limit: infinite. -\titem{max\_room\_desc} \ind{options!max\_room\_desc} +\titem{\{max\_room\_desc, Number\}} \ind{options!max\_room\_desc} This option defines the maximum number of characters that Room Description can have when configuring the room. The default value is to not limit: infinite. -\titem{min\_message\_interval} \ind{options!min\_message\_interval} +\titem{\{min\_message\_interval, Number\}} \ind{options!min\_message\_interval} This option defines the minimum interval between two messages send by an occupant in seconds. This option is global and valid for all rooms. A decimal value can be used. When this option is not defined, @@ -3074,7 +3042,7 @@ Module options: interval is 0.4 second. If an occupant tries to send messages faster, an error is send back explaining that the message has been discarded and describing the reason why the message is not acceptable. -\titem{min\_presence\_interval} +\titem{\{min\_presence\_interval, Number\}} \ind{options!min\_presence\_interval} This option defines the minimum of time between presence changes coming from a given occupant in seconds. This option is global and valid for all rooms. A @@ -3086,36 +3054,36 @@ Module options: broadcasted to all occupants in the room after expiration of the interval delay. Intermediate presence packets are silently discarded. A good value for this option is 4 seconds. -\titem{default\_room\_options} \ind{options!default\_room\_options} +\titem{\{default\_room\_options, [ \{OptionName, OptionValue\}, ...]\}} \ind{options!default\_room\_options} This module option allows to define the desired default room options. Note that the creator of a room can modify the options of his room at any time using a Jabber client with MUC capability. The available room options and the default values are: \begin{description} - \titem{\{allow\_change\_subj, true\}} Allow occupants to change the subject. - \titem{\{allow\_private\_messages, true\}} Occupants can send private messages to other occupants. - \titem{\{allow\_query\_users, true\}} Occupants can send IQ queries to other occupants. - \titem{\{allow\_user\_invites, false\}} Allow occupants to send invitations. - \titem{\{allow\_visitor\_nickchange, true\}} Allow visitors to + \titem{\{allow\_change\_subj, true|false\}} Allow occupants to change the subject. + \titem{\{allow\_private\_messages, true|false\}} Occupants can send private messages to other occupants. + \titem{\{allow\_query\_users, true|false\}} Occupants can send IQ queries to other occupants. + \titem{\{allow\_user\_invites, false|true\}} Allow occupants to send invitations. + \titem{\{allow\_visitor\_nickchange, true|false\}} Allow visitors to change nickname. - \titem{\{allow\_visitor\_status, true\}} Allow visitors to send + \titem{\{allow\_visitor\_status, true|false\}} Allow visitors to send status text in presence updates. If disallowed, the \term{status} text is stripped before broadcasting the presence update to all the room occupants. - \titem{\{anonymous, true\}} The room is anonymous: + \titem{\{anonymous, true|false\}} The room is anonymous: occupants don't see the real JIDs of other occupants. Note that the room moderators can always see the real JIDs of the occupants. - \titem{\{logging, false\}} The public messages are logged using \term{mod\_muc\_log}. + \titem{\{logging, false|true\}} The public messages are logged using \term{mod\_muc\_log}. \titem{\{max\_users, 200\}} Maximum number of occupants in the room. - \titem{\{members\_by\_default, true\}} The occupants that enter the room are participants by default, so they have 'voice'. - \titem{\{members\_only, false\}} Only members of the room can enter. - \titem{\{moderated, true\}} Only occupants with 'voice' can send public messages. - \titem{\{password, ""\}} Password of the room. You may want to enable the next option too. - \titem{\{password\_protected, false\}} The password is required to enter the room. - \titem{\{persistent, false\}} The room persists even if the last participant leaves. - \titem{\{public, true\}} The room is public in the list of the MUC service, so it can be discovered. - \titem{\{public\_list, true\}} The list of participants is public, without requiring to enter the room. - \titem{\{title, ""\}} A human-readable title of the room. + \titem{\{members\_by\_default, true|false\}} The occupants that enter the room are participants by default, so they have 'voice'. + \titem{\{members\_only, false|true\}} Only members of the room can enter. + \titem{\{moderated, true|false\}} Only occupants with 'voice' can send public messages. + \titem{\{password, "roompass123"\}} Password of the room. You may want to enable the next option too. + \titem{\{password\_protected, false|true\}} The password is required to enter the room. + \titem{\{persistent, false|true\}} The room persists even if the last participant leaves. + \titem{\{public, true|false\}} The room is public in the list of the MUC service, so it can be discovered. + \titem{\{public\_list, true|false\}} The list of participants is public, without requiring to enter the room. + \titem{\{title, "Room Title"\}} A human-readable title of the room. \end{description} All of those room options can be set to \term{true} or \term{false}, except \term{password} and \term{title} which are strings, @@ -3252,53 +3220,52 @@ Features: Options: \begin{description} -\titem{access\_log}\ind{options!access\_log} +\titem{\{access\_log, AccessName\}}\ind{options!access\_log} This option restricts which occupants are allowed to enable or disable room logging. The default value is \term{muc\_admin}. Note for this default setting you need to have an access rule for \term{muc\_admin} in order to take effect. -\titem{cssfile}\ind{options!cssfile} +\titem{\{cssfile, false|URL\}}\ind{options!cssfile} With this option you can set whether the HTML files should have a custom CSS file or if they need to use the embedded CSS file. Allowed values are \term{false} and an URL to a CSS file. With the first value, HTML files will include the embedded CSS code. With the latter, you can specify the URL of the - custom CSS file (for example: `http://example.com/my.css'). The default value + custom CSS file (for example: \term{"http://example.com/my.css"}). The default value is \term{false}. -\titem{dirname}\ind{options!dirname} +\titem{\{dirname, room\_jid|room\_name\}}\ind{options!dirname} Allows to configure the name of the room directory. Allowed values are \term{room\_jid} and \term{room\_name}. With the first value, the room directory name will be the full room JID. With the latter, the room directory name will be only the room name, not including the MUC service name. The default value is \term{room\_jid}. -\titem{dirtype}\ind{options!dirtype} +\titem{\{dirtype, subdirs|plain\}}\ind{options!dirtype} The type of the created directories can be specified with this option. Allowed values are \term{subdirs} and \term{plain}. With the first value, subdirectories are created for each year and month. With the latter, the names of the log files contain the full date, and there are no subdirectories. The default value is \term{subdirs}. -\titem{file\_format}\ind{options!file\_format} +\titem{\{file\_format, html|plaintext\}}\ind{options!file\_format} Define the format of the log files: \term{html} stores in HTML format, \term{plaintext} stores in plain text. The default value is \term{html}. -\titem{outdir}\ind{options!outdir} +\titem{\{outdir, Path\}}\ind{options!outdir} This option sets the full path to the directory in which the HTML files should be stored. Make sure the \ejabberd{} daemon user has write access on that directory. The default value is \term{"www/muc"}. -\titem{spam\_prevention}\ind{options!spam\_prevention} +\titem{\{spam\_prevention true|false\}}\ind{options!spam\_prevention} To prevent spam, the \term{spam\_prevention} option adds a special attribute to links that prevent their indexation by search engines. The default value is \term{true}, which mean that nofollow attributes will be added to user submitted links. -\titem{timezone}\ind{options!timezone} +\titem{\{timezone, local|universal\}}\ind{options!timezone} The time zone for the logs is configurable with this option. Allowed values are \term{local} and \term{universal}. With the first value, the local time, as reported to Erlang by the operating system, will be used. With the latter, GMT/UTC time will be used. The default value is \term{local}. -\titem{top\_link}\ind{options!top\_link} +\titem{\{top\_link, \{URL, Text\}\}}\ind{options!top\_link} With this option you can customize the link on the top right corner of each - log file. The syntax of this option is \term{\{"URL", "Text"\}}. The default - value is \term{\{"/", "Home"\}}. + log file. The default value is \term{\{"/", "Home"\}}. \end{description} Examples: @@ -3367,7 +3334,7 @@ online again. Thus it is very similar to how email works. Note that (see section~\ref{ejabberdctl}). \begin{description} - \titem{access\_max\_user\_messages}\ind{options!access\_max\_user\_messages} + \titem{\{access\_max\_user\_messages, Number\}}\ind{options!access\_max\_user\_messages} This option defines which access rule will be enforced to limit the maximum number of offline messages that a user can have (quota). When a user has too many offline messages, any new messages that he receive are discarded, @@ -3405,7 +3372,7 @@ ping requests, as defined in the protocol. Configuration options: \begin{description} - \titem{\{send\_pings, true | false\}}\ind{options!send\_pings} + \titem{\{send\_pings, true|false\}}\ind{options!send\_pings} If this option is set to \term{true}, the server sends pings to connected clients that are not active in a given interval \term{ping\_interval}. This is useful to keep client connections alive or checking availability. @@ -3416,7 +3383,7 @@ Configuration options: If a client connection does not send or receive any stanza in this interval, a ping request is sent to the client. The default value is 60 seconds. - \titem{\{timeout\_action, none | kill\}}\ind{options!timeout\_action} + \titem{\{timeout\_action, none|kill\}}\ind{options!timeout\_action} What to do when a client does not answer to a server ping request in less than 32 seconds. % Those 32 seconds are defined in ejabberd_local.erl: -define(IQ_TIMEOUT, 32000). The default is to do nothing. @@ -3491,24 +3458,22 @@ XMPP clients. Options: \begin{description} -\titem{host}\ind{options!host}This option defines the hostname of the service. -If this option is not set, the prefix `\jid{proxy.}' is added to \ejabberd{} -hostname. -\titem{name}\ind{options!name}Defines Service Discovery name of the service. +\hostitem{proxy} +\titem{\{name, Text\}}\ind{options!name}Defines Service Discovery name of the service. Default is \term{"SOCKS5 Bytestreams"}. -\titem{ip}\ind{options!ip}This option specifies which network interface +\titem{\{ip, IPTuple\}}\ind{options!ip}This option specifies which network interface to listen for. Default is an IP address of the service's DNS name, or, if fails, \verb|{127,0,0,1}|. -\titem{port}\ind{options!port}This option defines port to listen for +\titem{\{port, Number\}}\ind{options!port}This option defines port to listen for incoming connections. Default is~7777. -\titem{auth\_type}\ind{options!auth\_type}SOCKS5 authentication type. +\titem{\{auth\_type, anonymous|plain\}}\ind{options!auth\_type}SOCKS5 authentication type. Possible values are \term{anonymous} and \term{plain}. Default is \term{anonymous}. -\titem{access}\ind{options!access}Defines ACL for file transfer initiators. +\titem{\{access, AccessName\}}\ind{options!access}Defines ACL for file transfer initiators. Default is \term{all}. -\titem{max\_connections}\ind{options!max\_connections}Maximum number of +\titem{\{max\_connections, Number\}}\ind{options!max\_connections}Maximum number of active connections per file transfer initiator. No limit by default. -\titem{shaper}\ind{options!shaper}This option defines shaper for +\titem{\{shaper, none|ShaperName\}}\ind{options!shaper}This option defines shaper for the file transfer peers. Shaper with the maximum bandwidth will be selected. Default is \term{none}. \end{description} @@ -3560,26 +3525,26 @@ and it requires \modcaps{}. Options: \begin{description} \hostitem{pubsub} -\titem{access\_createnode} \ind{options!access\_createnode} +\titem{\{access\_createnode, AccessName\}} \ind{options!access\_createnode} This option restricts which users are allowed to create pubsub nodes using ACL and ACCESS. The default value is \term{pubsub\_createnode}. % Not clear enough + do not use abbreviations. -\titem{plugins} \ind{options!plugins} +\titem{\{plugins, [ Plugin, ...]\}} \ind{options!plugins} To specify which pubsub node plugins to use. If not defined, the default pubsub plugin is always used. -\titem{nodetree} \ind{options!nodetree} +\titem{\{nodetree, Name\}} \ind{options!nodetree} To specify which nodetree to use. If not defined, the default pubsub nodetree is used. Only one nodetree can be used per host, and is shared by all node plugins. -\titem{pep\_sendlast\_offline} \ind{options!pep\_sendlast\_offline} +\titem{\{pep\_sendlast\_offline, false|true\}} \ind{options!pep\_sendlast\_offline} To specify whether or not we should get last published PEP items from users in our roster which are offline when we connect. Value is true or false. If not defined, pubsub assumes false so we only get last items of online contacts. -\titem{last\_item\_cache} \ind{options!last\_item\_cache} +\titem{\{last\_item\_cache, false|true\}} \ind{options!last\_item\_cache} To specify whether or not pubsub should cache last items. Value is true or false. If not defined, pubsub do not cache last items. On systems with not so many nodes, caching last items speeds up pubsub and allows to raise user connection rate. The cost is memory usage, as every item is stored in memory. -\titem{pep\_mapping} \ind{pep\_mapping} +\titem{\{pep\_mapping, [ \{Key, Value\}, ...]\}} \ind{pep\_mapping} This allow to define a Key-Value list to choose defined node plugins on given PEP namespace. The following example will use node\_tune instead of node\_pep for every PEP node with tune namespace: \begin{verbatim} @@ -3617,15 +3582,15 @@ enables end users to use a \Jabber{} client to: Options: \begin{description} -\titem{access} \ind{options!access}This option can be configured to specify +\titem{\{access, AccessName\}} \ind{options!access}This option can be configured to specify rules to restrict registration. If a rule returns `deny' on the requested user name, registration for that user name is denied. (there are no restrictions by default). -\titem{welcome\_message} \ind{options!welcomem}Set a welcome message that +\titem{\{welcome\_message, Message\}} \ind{options!welcomem}Set a welcome message that is sent to each newly registered account. The first string is the subject, and the second string is the message body. In the body you can set a newline with the characters: \verb|\n| -\titem{registration\_watchers} \ind{options!rwatchers}This option defines a +\titem{\{registration\_watchers, [ JID, ...]\}} \ind{options!rwatchers}This option defines a list of JIDs which will be notified each time a new account is registered. \iqdiscitem{In-Band Registration (\ns{jabber:iq:register})} \end{description} @@ -3701,10 +3666,10 @@ It also supports Roster Versioning (\xepref{0237}). Options: \begin{description} \iqdiscitem{Roster Management (\ns{jabber:iq:roster})} - \titem{\{versioning, false | true\}} \ind{options!versioning}Enables + \titem{\{versioning, false|true\}} \ind{options!versioning}Enables Roster Versioning. This option is disabled by default. - \titem{\{store\_current\_id, false | true\}} \ind{options!storecurrentid} + \titem{\{store\_current\_id, false|true\}} \ind{options!storecurrentid} If this option is enabled, the current version number is stored on the database. If disabled, the version number is calculated on the fly each time. Enabling this option reduces the load for both ejabberd and the database. @@ -3735,7 +3700,7 @@ service(s). Options: \begin{description} -\titem{loggers} \ind{options!loggers}With this option a (list of) service(s) +\titem{\{loggers, [Names, ...]\}} \ind{options!loggers}With this option a (list of) service(s) that will receive the packets can be specified. \end{description} @@ -3938,19 +3903,19 @@ Options: \begin{description} \hostitem{vjud} \iqdiscitem{\ns{vcard-temp}} -\titem{search}\ind{options!search}This option specifies whether the search - functionality is enabled (value: \term{true}) or disabled (value: - \term{false}). If disabled, the option \term{host} will be ignored and the +\titem{\{search, true|false\}}\ind{options!search}This option specifies whether the search + functionality is enabled or not + If disabled, the option \term{host} will be ignored and the \Jabber{} User Directory service will not appear in the Service Discovery item list. The default value is \term{true}. -\titem{matches}\ind{options!matches}With this option, the number of reported +\titem{\{matches, infinity|Number\}}\ind{options!matches}With this option, the number of reported search results can be limited. If the option's value is set to \term{infinity}, all search results are reported. The default value is \term{30}. -\titem{allow\_return\_all}\ind{options!allow\_return\_all}This option enables +\titem{\{allow\_return\_all, false|true\}}\ind{options!allow\_return\_all}This option enables you to specify if search operations with empty input fields should return all users who added some information to their vCard. The default value is \term{false}. -\titem{search\_all\_hosts}\ind{options!search\_all\_hosts}If this option is set +\titem{\{search\_all\_hosts, true|false\}}\ind{options!search\_all\_hosts}If this option is set to \term{true}, search operations will apply to all virtual hosts. Otherwise only the current host will be searched. The default value is \term{true}. This option is available in \modvcard, but not available in \modvcardodbc. @@ -4014,25 +3979,28 @@ consists of the following \modvcardldap{}-specific options: \begin{description} \hostitem{vjud} \iqdiscitem{\ns{vcard-temp}} -\titem{search}\ind{options!search}This option specifies whether the search +\titem{\{search, true|false\}}\ind{options!search}This option specifies whether the search functionality is enabled (value: \term{true}) or disabled (value: \term{false}). If disabled, the option \term{host} will be ignored and the \Jabber{} User Directory service will not appear in the Service Discovery item list. The default value is \term{true}. -\titem{matches}\ind{options!matches}With this option, the number of reported +\titem{\{matches, infinity|Number\}}\ind{options!matches}With this option, the number of reported search results can be limited. If the option's value is set to \term{infinity}, all search results are reported. The default value is \term{30}. -\titem{ldap\_vcard\_map}\ind{options!ldap\_vcard\_map}With this option you can - set the table that maps LDAP attributes to vCard fields. The format is: - \term{[{Name\_of\_vCard\_field, Pattern, List\_of\_LDAP\_attributes}, ...]}.\ind{protocols!RFC 2426: vCard MIME Directory Profile} - \term{Name\_of\_vcard\_field} is the type name of the vCard as defined in - \footahref{http://tools.ietf.org/html/rfc2426}{RFC 2426}. \term{Pattern} is a - string which contains pattern variables \term{"\%u"}, \term{"\%d"} or - \term{"\%s"}. \term{List\_of\_LDAP\_attributes} is the list containing LDAP - attributes. The pattern variables \term{"\%s"} will be sequentially replaced +\titem{\{ldap\_vcard\_map, [ \{Name, Pattern, LDAPattributes\}, ...]\}} \ind{options!ldap\_vcard\_map} + With this option you can set the table that maps LDAP attributes to vCard fields. + \ind{protocols!RFC 2426: vCard MIME Directory Profile} + \term{Name} is the type name of the vCard as defined in + \footahref{http://tools.ietf.org/html/rfc2426}{RFC 2426}. + \term{Pattern} is a string which contains pattern variables + \term{"\%u"}, \term{"\%d"} or \term{"\%s"}. + \term{LDAPattributes} is the list containing LDAP attributes. + The pattern variables + \term{"\%s"} will be sequentially replaced with the values of LDAP attributes from \term{List\_of\_LDAP\_attributes}, - \term{"\%u"} will be replaced with the user part of a JID, and \term{"\%d"} - will be replaced with the domain part of a JID. The default is: + \term{"\%u"} will be replaced with the user part of a JID, + and \term{"\%d"} will be replaced with the domain part of a JID. + The default is: \begin{verbatim} [{"NICKNAME", "%u", []}, {"FN", "%s", ["displayName"]}, @@ -4055,9 +4023,9 @@ consists of the following \modvcardldap{}-specific options: {"ROLE", "%s", ["employeeType"]}, {"PHOTO", "%s", ["jpegPhoto"]}] \end{verbatim} -\titem{ldap\_search\_fields}\ind{options!ldap\_search\_fields}This option - defines the search form and the LDAP attributes to search within. The format - is: \term{[{Name, Attribute}, ...]}. \term{Name} is the name of a search form +\titem{\{ldap\_search\_fields, [ \{Name, Attribute\}, ...]\}}\ind{options!ldap\_search\_fields}This option + defines the search form and the LDAP attributes to search within. + \term{Name} is the name of a search form field which will be automatically translated by using the translation files (see \term{msgs/*.msg} for available words). \term{Attribute} is the LDAP attribute or the pattern \term{"\%u"}. The default is: @@ -4075,11 +4043,11 @@ consists of the following \modvcardldap{}-specific options: {"Organization Name", "o"}, {"Organization Unit", "ou"}] \end{verbatim} -\titem{ldap\_search\_reported}\ind{options!ldap\_search\_reported}This option - defines which search fields should be reported. The format is: - \term{[{Name, vCard\_Name}, ...]}. \term{Name} is the name of a search form +\titem{\{ldap\_search\_reported, [ \{SearchField, VcardField\}, ...]\}}\ind{options!ldap\_search\_reported}This option + defines which search fields should be reported. + \term{SearchField} is the name of a search form field which will be automatically translated by using the translation - files (see \term{msgs/*.msg} for available words). \term{vCard\_Name} is the + files (see \term{msgs/*.msg} for available words). \term{VcardField} is the vCard field name defined in the \option{ldap\_vcard\_map} option. The default is: \begin{verbatim} @@ -4206,7 +4174,7 @@ answers \ejabberd{}'s version when queried. Options: \begin{description} -\titem{show\_os}\ind{options!showos}Should the operating system be revealed or not. +\titem{\{show\_os, true|false\}}\ind{options!showos}Should the operating system be revealed or not. The default value is \term{true}. \iqdiscitem{Software Version (\ns{jabber:iq:version})} \end{description} @@ -4445,11 +4413,11 @@ In that case, authentication information must be provided. In each frontend the \term{AccessCommands} option is defined in a different place. But in all cases the option syntax is the same: \begin{verbatim} -AccessCommands = [ {Access, CommandNames, Arguments} ] +AccessCommands = [ {Access, CommandNames, Arguments}, ...] Access = atom() CommandNames = all | [CommandName] CommandName = atom() -Arguments = [{ArgumentName, ArgumentValue}] +Arguments = [ {ArgumentName, ArgumentValue}, ...] ArgumentName = atom() ArgumentValue = any() \end{verbatim} @@ -4941,10 +4909,7 @@ domain. The default distribution algorithm try to deliver to a local instance of a component. If several local instances are available, one instance is chosen randomly. If no instance is available locally, one instance is chosen randomly among the remote component instances. If you need a different behaviour, you can change the load balancing behaviour with the option \option{domain\_balancing}. The syntax of the option is the following: - -\begin{verbatim} -{domain_balancing, "component.example.com", <balancing_criterium>}. -\end{verbatim} +\esyntax{\{domain\_balancing, "component.example.com", BalancingCriteria\}.} Several balancing criteria are available: \begin{itemize} @@ -4963,10 +4928,8 @@ When there is a risk of failure for a given component, domain balancing can caus In this case, it is best to limit the problem to the sessions handled by the failing component. This is what the \term{domain\_balancing\_component\_number} option does, making the load balancing algorithm not dynamic, but sticky on a fix number of component instances. -The syntax is the following: -\begin{verbatim} -{domain_balancing_component_number, "component.example.com", N} -\end{verbatim} +The syntax is: +\esyntax{\{domain\_balancing\_component\_number, "component.example.com", Number\}.} @@ -4987,8 +4950,10 @@ An \ejabberd{} node writes two log files: \titem{sasl.log} is the Erlang/OTP system log, with the messages reported by Erlang/OTP using SASL (System Architecture Support Libraries) \end{description} -The option \term{loglevel} modifies the verbosity of the file ejabberd.log. -The possible levels are: +The option \term{loglevel} modifies the verbosity of the file ejabberd.log. The syntax is: +\esyntax{\{loglevel, Level\}.} + +The possible \term{Level} are: \begin{description} \titem{0} No ejabberd log at all (not recommended) \titem{1} Critical @@ -5033,6 +4998,9 @@ a message is sent to the Jabber accounts defined with the option \term{watchdog\_admins} \ind{options!watchdog\_admins} in the \ejabberd{} configuration file. +The syntax is: +\esyntax{\{watchdog\_admins, [JID, ...]\}.} + The memory consumed is measured in \term{words}: a word on 32-bit architecture is 4 bytes, and a word on 64-bit architecture is 8 bytes. @@ -5040,6 +5008,9 @@ The threshold by default is 1000000 words. This value can be configured with the option \term{watchdog\_large\_heap}, or in a conversation with the watchdog alert bot. +The syntax is: +\esyntax{\{watchdog\_large\_heap, Number\}.} + Example configuration: \begin{verbatim} {watchdog_admins, ["admin2@localhost", "admin2@example.org"]}. |