diff --git a/ChangeLog b/ChangeLog index a0b37b5b5..75b6a2a3e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2008-10-06 Jerome Sautret + + * src/ejabberd_rdbms.erl: fix SQL database reconnection + issues (EJAB-764) and add odbc_start_interval configuration + directive (default to 30 seconds). + * src/odbc/ejabberd_odbc.erl: likewise. + * src/odbc/ejabberd_odbc_sup.erl: likewise. + * doc/guide.tex: likewise. + 2008-10-03 Jerome Sautret * src/odbc/odbc_queries.erl: Fix syntax error on update_roster_sql query. diff --git a/doc/guide.tex b/doc/guide.tex index be8fa7939..8e279aa2b 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -102,7 +102,7 @@ \include{contributed_modules} %% Common options -\newcommand{\iqdiscitem}[1]{\titem{iqdisc} \ind{options!iqdisc}This specifies +\newcommand{\iqdiscitem}[1]{\titem{iqdisc} \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 @@ -159,8 +159,8 @@ ejabberd Development Team \newstyle{table[border="1"]}{border-collapse:collapse;margin-bottom:1em;} \newstyle{table[border="1"] td}{border:1px solid \#aaa;padding:2px} % Don't display
before and after tables or images: -\newstyle{BLOCKQUOTE.table DIV.center DIV.center HR}{display:none;} -\newstyle{BLOCKQUOTE.figure DIV.center DIV.center HR}{display:none;} +\newstyle{BLOCKQUOTE.table DIV.center DIV.center HR}{display:none;} +\newstyle{BLOCKQUOTE.figure DIV.center DIV.center HR}{display:none;} %% Footnotes \begin{latexonly} @@ -208,8 +208,8 @@ ejabberd Development Team \makesection{install.binary}{Installing \ejabberd{} with Binary Installer} Probably the easiest way to install an \ejabberd{} instant messaging server -is using the binary installer published by ProcessOne. -The binary installers of released \ejabberd{} versions +is using the binary installer published by ProcessOne. +The binary installers of released \ejabberd{} versions are available in the ProcessOne \ejabberd{} downloads page: \ahrefurl{http://www.process-one.net/en/ejabberd/downloads} @@ -227,17 +227,17 @@ or automatically by the operating system at system boot time. To start and stop \ejabberd{} manually, use the desktop shortcuts created by the installer. -If the machine doesn't have a graphical system, use the scripts 'start' +If the machine doesn't have a graphical system, use the scripts 'start' and 'stop' in the 'bin' directory where \ejabberd{} is installed. The Windows installer also adds ejabberd as a system service, and a shortcut to a debug console for experienced administrators. -If you want ejabberd to be started automatically at boot time, +If you want ejabberd to be started automatically at boot time, go to the Windows service settings and set ejabberd to be automatically started. -Note that the Windows service is a feature still in development, +Note that the Windows service is a feature still in development, and for example it doesn't read the file ejabberdctl.cfg. -On a *nix system, if you want ejabberd to be started as daemon at boot time, +On a *nix system, if you want ejabberd to be started as daemon at boot time, copy \term{ejabberd.init} from the 'bin' directory to something like \term{/etc/init.d/ejabberd} (depending on your distribution) and call \term{/etc/inid.d/ejabberd start} to start it. @@ -263,9 +263,9 @@ and configurable options to fine tune the Erlang runtime system. \makesection{install.os}{Installing \ejabberd{} with Operating System specific packages} -Some Operating Systems provide a specific \ejabberd{} package adapted to +Some Operating Systems provide a specific \ejabberd{} package adapted to the system architecture and libraries. -It usually also checks dependencies +It usually also checks dependencies and performs basic configuration tasks like creating the initial administrator account. Some examples are Debian and Gentoo. Consult the resources provided by your Operating System for more information. @@ -282,7 +282,7 @@ The binaries are available for many different system architectures, so this is a alternative to the binary installer and Operating System's \ejabberd{} packages. You will have to create your own \ejabberd{} start -script depending of how you handle your CEAN installation. +script depending of how you handle your CEAN installation. The default \term{ejabberdctl} script is located into \ejabberd{}'s priv directory and can be used as an example. @@ -290,7 +290,7 @@ into \ejabberd{}'s priv directory and can be used as an example. \ind{install} The canonical form for distribution of \ejabberd{} stable releases is the source code package. -Compiling \ejabberd{} from source code is quite easy in *nix systems, +Compiling \ejabberd{} from source code is quite easy in *nix systems, as long as your system have all the dependencies. \makesubsection{installreq}{Requirements} @@ -337,23 +337,23 @@ To get the full list run the command: Some options that you may be interested in modifying: \begin{description} - \titem{--prefix=/} + \titem{--prefix=/} Specify the path prefix where the files will be copied when running the make install command. - \titem{--enable-pam} + \titem{--enable-pam} Enable the PAM authentication method (see section \ref{pam}). \titem{--enable-odbc or --enable-mssql} Required if you want to use an external database. See section~\ref{database} for more information. - \titem{--enable-full-xml} + \titem{--enable-full-xml} Enable the use of XML based optimisations. - It will for example use CDATA to escape characters in the XMPP stream. + It will for example use CDATA to escape characters in the XMPP stream. Use this option only if you are sure your Jabber clients include a fully compliant XML parser. \titem{--disable-transient-supervisors} - Disable the use of Erlang/OTP supervision for transient processes. + Disable the use of Erlang/OTP supervision for transient processes. \end{description} @@ -437,8 +437,8 @@ gmake You need to have \term{GNU install}, but it isn't included in Solaris. It can be easily installed if your Solaris system -is set up for \footahref{http://www.blastwave.org/}{blastwave.org} -package repository. +is set up for \footahref{http://www.blastwave.org/}{blastwave.org} +package repository. Make sure \term{/opt/csw/bin} is in your \term{PATH} and run: \begin{verbatim} pkg-get -i fileutils @@ -500,8 +500,8 @@ We assume that we will try to put as much library as possible into \verb|C:\sdk\ \verb|C:\sdk\GnuWin32\bin| to the \verb|PATH| environment variable. \item Install OpenSSL in \verb|C:\sdk\OpenSSL| and add \verb|C:\sdk\OpenSSL\lib\VC| to your path or copy the binaries to your system directory. -\item Install ZLib in \verb|C:\sdk\gnuWin32|. Copy - \verb|C:\sdk\GnuWin32\bin\zlib1.dll| to your system directory. If you change your path it should already be set after libiconv install. +\item Install ZLib in \verb|C:\sdk\gnuWin32|. Copy + \verb|C:\sdk\GnuWin32\bin\zlib1.dll| to your system directory. If you change your path it should already be set after libiconv install. \item Make sure the you can access Erlang binaries from your path. For example: \verb|set PATH=%PATH%;"C:\sdk\erl5.5.5\bin"| \item Depending on how you end up actually installing the library you might need to check and tweak the paths in the file configure.erl. \item While in the directory \verb|ejabberd\src| run: @@ -523,20 +523,20 @@ werl -s ejabberd -name ejabberd You need a Jabber account and grant him administrative privileges to enter the \ejabberd{} Web Admin: \begin{enumerate} -\item Register a Jabber account on your \ejabberd{} server, for example \term{admin1@example.org}. +\item Register a Jabber account on your \ejabberd{} server, for example \term{admin1@example.org}. There are two ways to register a Jabber account: \begin{enumerate} \item Using \term{ejabberdctl}\ind{ejabberdctl} (see section~\ref{ejabberdctl}): \begin{verbatim} ejabberdctl register admin1 example.org FgT5bk3 -\end{verbatim} +\end{verbatim} \item Using a Jabber client and In-Band Registration (see section~\ref{modregister}). \end{enumerate} \item Edit the \ejabberd{} configuration file to give administration rights to the Jabber account you created: \begin{verbatim} {acl, admins, {user, "admin1", "example.org"}}. {access, configure, [{allow, admins}]}. -\end{verbatim} +\end{verbatim} You can grant administrative privileges to many Jabber accounts, and also to accounts in other Jabber servers. \item Restart \ejabberd{} to load the new configuration. @@ -550,7 +550,7 @@ ejabberdctl register admin1 example.org FgT5bk3 To upgrade an ejabberd installation to a new version, simply uninstall the old version, and then install the new one. -Of course, it is important that the configuration file +Of course, it is important that the configuration file and Mnesia database spool directory are not removed. \ejabberd{} automatically updates the Mnesia table definitions at startup when needed. @@ -567,9 +567,9 @@ indicates you need to also update those tables. The configuration file will be loaded the first time you start \ejabberd{}. The content from this file will be parsed and stored in the internal \ejabberd{} database. Subsequently the configuration will be loaded from the database and any commands in the -configuration file are appended to the entries in the database. +configuration file are appended to the entries in the database. -Note that \ejabberd{} never edits the configuration file. +Note that \ejabberd{} never edits the configuration file. So, the configuration changes done using the Web Admin are stored in the database, but are not reflected in the configuration file. If you want those changes to be use after \ejabberd{} restart, you can either @@ -656,7 +656,7 @@ Examples: {ldap_password, ""}]}. \end{verbatim} \end{itemize} - + 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. @@ -721,7 +721,7 @@ tuple with the following elements: \ind{modules!ejabberd\_c2s}\ind{modules!ejabberd\_s2s\_in}\ind{modules!ejabberd\_service}\ind{modules!ejabberd\_http}\ind{protocols!XEP-0114: Jabber Component Protocol} The available modules, their purpose and the options allowed by each one are: \begin{description} - \titem{\texttt{ejabberd\_c2s}} + \titem{\texttt{ejabberd\_c2s}} Handles c2s connections.\\ Options: \texttt{access}, \texttt{certfile}, \texttt{inet6}, \texttt{ip}, \texttt{max\_stanza\_size}, \texttt{shaper}, @@ -731,7 +731,7 @@ The available modules, their purpose and the options allowed by each one are: Handles incoming s2s connections.\\ Options: \texttt{inet6}, \texttt{ip}, \texttt{max\_stanza\_size} \titem{\texttt{ejabberd\_service}} - Interacts with an \footahref{http://www.ejabberd.im/tutorials-transports}{external component} + Interacts with an \footahref{http://www.ejabberd.im/tutorials-transports}{external component} (as defined in the Jabber Component Protocol (\xepref{0114}).\\ Options: \texttt{access}, \texttt{hosts}, \texttt{inet6}, \texttt{ip}, \texttt{shaper}, \texttt{service\_check\_from} @@ -772,7 +772,7 @@ This is a detailed description of each option allowed by the listening modules: \verb|http://server:port/http-bind/|. Be aware that support for HTTP Bind is also needed in the \Jabber{} client. Remark also that HTTP Bind can be interesting to host a web-based \Jabber{} client such as - \footahref{http://jwchat.sourceforge.net/}{JWChat} + \footahref{http://jwchat.sourceforge.net/}{JWChat} (check the tutorials to install JWChat with ejabberd and an \footahref{http://www.ejabberd.im/jwchat-localserver}{embedded local web server} or \footahref{http://www.ejabberd.im/jwchat-apache}{Apache}). @@ -788,7 +788,7 @@ This is a detailed description of each option allowed by the listening modules: \footahref{http://jwchat.sourceforge.net/}{JWChat}. \titem{inet6} \ind{options!inet6}\ind{IPv6}Set up the socket for IPv6 instead of IPv4. Note: this option is not required for S2S outgoing connections, - because when ejabberd attempts to establish a S2S outgoing connection + because when ejabberd attempts to establish a S2S outgoing connection it first tries IPv4, and if that fails it attempts with IPv6. \titem{\{ip, IPAddress\}} \ind{options!ip}This option specifies which network interface to listen for. For example \verb|{ip, {192, 168, 1, 1}}|. @@ -820,7 +820,7 @@ This is a detailed description of each option allowed by the listening modules: You can define a certificate file for a specific domain using the global option \option{domain\_certfile}. \titem{starttls\_required} \ind{options!starttls\_required}This option specifies that STARTTLS encryption is required on connections to the port. - No unencrypted connections will be allowed. + No unencrypted connections will be allowed. You should also set the \option{certfile} option. You can define a certificate file for a specific domain using the global option \option{domain\_certfile}. \titem{tls} \ind{options!tls}\ind{TLS}This option specifies that traffic on @@ -853,7 +853,7 @@ There are some additional global options: The default value is \term{allow}. \titem{\{\{s2s\_host, Host\}, allow|deny\}} Defines if incoming and outgoing s2s connections with a specific remote host are allowed or denied. - This allows to restrict ejabberd to only establish s2s connections + This allows to restrict ejabberd to only establish s2s connections with a small list of trusted servers, or to block some specific servers. \titem{\{s2s\_max\_retry\_delay, Seconds\}} \ind{options!s2s\_max\_retry\_delay} The maximum allowed delay for retry to connect after a failed connection attempt. @@ -864,7 +864,7 @@ For example, the following simple configuration defines: \begin{itemize} \item There are three domains. The default certificate file is \term{server.pem}. However, the c2s and s2s connections to the domain \term{example.com} use the file \term{example\_com.pem}. -\item Port 5222 listens for c2s connections with STARTTLS, +\item Port 5222 listens for c2s connections with STARTTLS, and also allows plain connections for old clients. \item Port 5223 listens for c2s connections with the old SSL. \item Port 5269 listens for s2s connections with STARTTLS. @@ -877,7 +877,7 @@ However, the c2s and s2s connections to the domain \term{example.com} use the fi {listen, [ {5222, ejabberd_c2s, [ - {access, c2s}, + {access, c2s}, {shaper, c2s_shaper}, starttls, {certfile, "/etc/ejabberd/server.pem"}, {max_stanza_size, 65536} @@ -917,7 +917,7 @@ In this example, the following configuration defines that: \item Port 5280 is serving the Web Admin and the HTTP Polling service. Note that it is also possible to serve them on different ports. The second example in section~\ref{webadmin} shows how exactly this can be done. -\item All users except for the administrators have a traffic of limit +\item All users except for the administrators have a traffic of limit 1,000\,Bytes/second \item \ind{transports!AIM}The \footahref{http://www.ejabberd.im/pyaimt}{AIM transport} @@ -1350,7 +1350,7 @@ following syntax: \end{verbatim} where \term{} stands for the maximum allowed incoming rate in bytes per second. -When a connection exceeds this limit, \ejabberd{} stops reading from the socket +When a connection exceeds this limit, \ejabberd{} stops reading from the socket until the average rate is again below the allowed maximum. Examples: @@ -1388,6 +1388,152 @@ Examples: \end{verbatim} \end{itemize} +<<<<<<< .courant +======= +Appendix \ref{i18ni10n} provides more details about internationalization and localization. + + +\makesubsection{includeconfigfile}{Include Additional Configuration Files} +\ind{options!includeconfigfile}\ind{includeconfigfile} + +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, }. +\end{verbatim} +It is also possible to specify suboptions: +\begin{verbatim} +{include_config_file, , [, , ...]}. +\end{verbatim} + +The filename can be indicated either as an absolute path, +or relative to the main \ejabberd{} configuration file. +It isn't possible to use wildcards. +The file must exist and be readable. + +The allowed suboptions are: +\begin{description} + \titem{\{disallow, [