diff --git a/ChangeLog b/ChangeLog index bea8772d9..7315272f2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,24 @@ +2008-12-16 Badlop + + * doc/guide.tex: Fix capitalization of some section titles + + * doc/guide.tex: Mention as optional Requirements: mysql, pgsql + and pam + + * src/ejabberd_ctl.erl: Command reopen-log must also rotate + sasl.log (thanks to Alexander Tsvyashchenko)(EJAB-711) + * src/ejabberd_logger_h.erl: Export the function rotate_log/1 + * doc/guide.tex: Improve explanation of log files rotation + + * doc/guide.tex: Improve explanation of watchdog admins + option: only useful for developers (EJAB-816) + * src/ejabberd.cfg.example: Likewise + + * doc/guide.tex: Say 'higher' instead of 'newer' in requirements + * README: Likewise + + * doc/guide.tex: Simplify example mod_muc configuration + 2008-12-08 Christophe Romain * src/ejabberd_c2s.erl: Reduce memory consumption due to caps handling diff --git a/README b/README index df5c68281..43f9c3d82 100644 --- a/README +++ b/README @@ -9,7 +9,7 @@ To compile ejabberd you need: - GNU Make - GCC - libexpat 1.95 or higher - - Erlang/OTP R10B-9 or newer + - Erlang/OTP R10B-9 or higher - OpenSSL 0.9.6 or higher, for STARTTLS, SASL and SSL encryption. Optional, highly recommended. - Zlib 1.2.3 or higher, for Stream Compression support diff --git a/doc/guide.html b/doc/guide.html index 590c1e7f9..56fbf2e5c 100644 --- a/doc/guide.html +++ b/doc/guide.html @@ -96,7 +96,7 @@ BLOCKQUOTE.figure DIV.center DIV.center HR{display:none;}
  • Chapter 2  Installing ejabberd -
  • Chapter 4  Managing an ejabberd server +
  • Chapter 4  Managing an ejabberd Server
  • Chapter 6  Clustering
    • @@ -197,9 +197,9 @@ BLOCKQUOTE.figure DIV.center DIV.center HR{display:none;}
  • Chapter 7  Debugging
  • Appendix A  Internationalization and Localization
  • Appendix B  Release Notes @@ -302,8 +302,8 @@ or with the command bin/ejabberdctl live in other Operating Systems. This way you see the error message provided by Erlang and can identify what is exactly the problem.

    The ejabberdctl administration script is included in the bin directory. Please refer to the section 4.1 for details about ejabberdctl, -and configurable options to fine tune the Erlang runtime system.

    -

    2.2  Installing ejabberd with Operating System specific packages

    Some Operating Systems provide a specific ejabberd package adapted to +and configurable options to fine tune the Erlang runtime system.

    +

    2.2  Installing ejabberd with Operating System Specific Packages

    Some Operating Systems provide a specific ejabberd package adapted to the system architecture and libraries. It usually also checks dependencies and performs basic configuration tasks like creating the initial @@ -328,10 +328,13 @@ as long as your system have all the dependencies.

  • GCC
  • Libexpat 1.95 or higher -
  • Erlang/OTP R10B-9 or newer. +
  • Erlang/OTP R10B-9 or higher.
  • OpenSSL 0.9.6 or higher, for STARTTLS, SASL and SSL encryption. Optional, highly recommended.
  • Zlib 1.2.3 or higher, for Stream Compression support (XEP-0138). Optional. -
  • GNU Iconv 1.8 or higher, for the IRC Transport (mod_irc). Optional. Not needed on systems with GNU Libc. +
  • Erlang mysql library. Optional. For MySQL authentication or storage. See section 3.2.1. +
  • Erlang pgsql library. Optional. For PostgreSQL authentication or storage. See section 3.2.3. +
  • PAM library. Optional. For Pluggable Authentication Modules (PAM). See section 3.1.4. +
  • GNU Iconv 1.8 or higher, for the IRC Transport (mod_irc). Optional. Not needed on systems with GNU Libc. See section 3.3.6.

    • 2.4.2  Download Source Code

    Released versions of ejabberd are available in the ProcessOne ejabberd downloads page: @@ -383,7 +386,7 @@ to install ejabberd.

    The files and directories created are, by de

    msgs
    Translated strings (*.msgs)
    -
    /var/log/ejabberd/
    Log files (see section 7.2): +
    /var/log/ejabberd/
    Log files (see section 7.1):
    ejabberd.log
    ejabberd service log
    sasl.log
    Erlang/OTP system log @@ -2000,16 +2003,16 @@ to new hardware. This will involve service breakdowns around 23:00 UMT. We apologise for this inconvenience.’ to conference.example.org, it will be displayed in all active rooms. In this example the history feature is disabled. -
    {acl, admins, {user, "admin", "example.org"}}.
+
    {acl, admin, {user, "admin", "example.org"}}.
 
-{access, muc_admins, [{allow, admins}]}.
+{access, muc_admin, [{allow, admin}]}.
 
 {modules,
  [
   ...
   {mod_muc, [{access, all},
              {access_create, all},
-             {access_admin, muc_admins},
+             {access_admin, muc_admin},
              {history_size, 0}]},
   ...
  ]}.
@@ -2026,20 +2029,20 @@ and the default value of 20 history messages will be send to the users.
 
    {acl, paying_customers, {user, "customer1", "example.net"}}.
 {acl, paying_customers, {user, "customer2", "example.com"}}.
 {acl, paying_customers, {user, "customer3", "example.org"}}.
-{acl, admins, {user, "admin", "example.org"}}.
+{acl, admin, {user, "admin", "example.org"}}.
 
-{access, muc_admins, [{allow, admins},
+{access, muc_admin, [{allow, admin},
                       {deny, all}]}.
 {access, muc_access, [{allow, paying_customers},
-                      {allow, admins},
+                      {allow, admin},
                       {deny, all}]}.
 
 {modules,
  [
   ...
   {mod_muc, [{access, muc_access},
-             {access_create, muc_admins},
-             {access_admin, muc_admins}]},
+             {access_create, muc_admin},
+             {access_admin, muc_admin}]},
   ...
  ]}.
 
  • In the following example, MUC anti abuse options are used. An
@@ -2058,7 +2061,7 @@ the newly created rooms have by default those options.
  [
   ...
   {mod_muc, [{access, muc_access},
-             {access_create, muc_admins},
+             {access_create, muc_admin},
              {default_room_options,
               [
                {allow_change_subj, false},
@@ -2068,7 +2071,7 @@ the newly created rooms have by default those options.
                {title, "New chatroom"},
                {anonymous, false}
               ]},
-             {access_admin, muc_admins}]},
+             {access_admin, muc_admin}]},
   ...
  ]}.
 
    •   
    
@@ -2778,8 +2781,8 @@ answers ejabberd’s version when queried.
    Options:
 The default value is true.
    iqdisc
    This specifies the processing discipline for Software Version (jabber:iq:version) IQ queries (see section 3.3.2). -

    -

    Chapter 4  Managing an ejabberd server

    +

    +

    Chapter 4  Managing an ejabberd Server

    4.1  ejabberdctl

    4.1.1  Commands

    The ejabberdctl command line administration script allows to start, stop and perform many other administrative tasks in a local or remote ejabberd server.

    When ejabberdctl is executed without any parameter, @@ -2795,8 +2798,9 @@ The more interesting ones are:

    status
    Check the status of the ejabberd server.
    stop
    Stop the ejabberd server which is running in the machine. -
    reopen-log
    If you use a tool to rotate logs, you have to configure it -so that this command is executed after each rotation. +
    reopen-log
    Reopen the log files after they were renamed. +If the old files were not renamed before calling this command, +they are automatically renamed to "*-old.log". See section 7.1.
    backup, restore, install-fallback, dump, load
    You can use these commands to create and restore backups.
    import-file, import-dir
    @@ -2813,8 +2817,8 @@ error is represented by 1, and other codes may be used for specifical results. This can be used by other scripts to determine automatically if a command succedded or failed, -for example using: echo $?

    -

    4.1.2  Erlang runtime system

    ejabberd is an Erlang/OTP application that runs inside an Erlang runtime system. +for example using: echo $?

    +

    4.1.2  Erlang Runtime System

    ejabberd is an Erlang/OTP application that runs inside an Erlang runtime system. This system is configured using environment variables and command line parameters. The ejabberdctl administration script uses many of those possibilities. You can configure some of them with the file ejabberdctl.cfg, @@ -3008,8 +3012,8 @@ However, the cookie system is not ultimately effective to prevent unauthorized access or intrusion to an Erlang node. The communication between Erlang nodes are not encrypted, so the cookie could be read sniffing the traffic on the network. -The recommended way to secure the Erlang node is to block the port 4369.

    -

    5.4  Erlang node name

    An Erlang node may have a node name. +The recommended way to secure the Erlang node is to block the port 4369.

    +

    5.4  Erlang Node Name

    An Erlang node may have a node name. The name can be short (if indicated with the command-line parameter -sname) or long (if indicated with the parameter -name). Starting an Erlang node with -sname limits the communication between Erlang nodes to the LAN.

    Using the option -sname instead of -name is a simple method @@ -3017,8 +3021,8 @@ to difficult unauthorized access to your Erlang node. However, it is not ultimately effective to prevent access to the Erlang node, because it may be possible to fake the fact that you are on another network using a modified version of Erlang epmd. -The recommended way to secure the Erlang node is to block the port 4369.

    -

    5.5  Securing sensible files

    ejabberd stores sensible data in the file system either in plain text or binary files. +The recommended way to secure the Erlang node is to block the port 4369.

    +

    5.5  Securing Sensible Files

    ejabberd stores sensible data in the file system either in plain text or binary files. The file system permissions should be set to only allow the proper user to read, write and execute those files and directories.

    ejabberd configuration file: /etc/ejabberd/ejabberd.cfg
    @@ -3131,20 +3135,8 @@ domain.

    Chapter 7  Debugging

    -

    -

    7.1  Watchdog Alerts

    -

    ejabberd includes a watchdog mechanism. -If a process in the ejabberd server consumes too much memory, -a message is sent to the Jabber accounts defined with the option -watchdog_admins - in the ejabberd configuration file. -Example configuration: -

    {watchdog_admins, ["admin2@localhost", "admin2@example.org"]}.
-

    To remove watchdog admins, remove them in the option. -To remove all watchdog admins, set the option with an empty list: -

    {watchdog_admins, []}.
-

    -

    7.2  Log Files

    An ejabberd node writes two log files: +

    +

    7.1  Log Files

    An ejabberd node writes two log files:

    ejabberd.log
    is the ejabberd service log, with the messages reported by ejabberd code
    sasl.log
    is the Erlang/OTP system log, with the messages reported by Erlang/OTP using SASL (System Architecture Support Libraries) @@ -3160,12 +3152,32 @@ The possible levels are:

    For example, the default configuration is: 

    {loglevel, 4}.
-

    -

    7.3  Debug Console

    The Debug Console is an Erlang shell attached to an already running ejabberd server. +

    The log files grow continually, so it is recommended to rotate them periodically. +To rotate the log files, rename the files and then reopen them. +The ejabberd command reopen-log +(please refer to section 4.1.1) +reopens the log files, +and also renames the old ones if you didn’t rename them.

    +

    7.2  Debug Console

    The Debug Console is an Erlang shell attached to an already running ejabberd server. With this Erlang shell, an experienced administrator can perform complex tasks.

    This shell gives complete control over the ejabberd server, so it is important to use it with extremely care. There are some simple and safe examples in the article -Interconnecting Erlang Nodes

    To exit the shell, close the window or press the keys: control+c control+c.

    +Interconnecting Erlang Nodes

    To exit the shell, close the window or press the keys: control+c control+c.

    +

    7.3  Watchdog Alerts

    +

    ejabberd includes a watchdog mechanism that may be useful to developers +when troubleshooting a problem related to memory usage. +If a process in the ejabberd server consumes a lot of memory, +a message is sent to the Jabber accounts defined with the option +watchdog_admins + in the ejabberd configuration file. +Note that the threshold to define what is too much memory usage +is only configurable editing the source code. +Example configuration: +

    {watchdog_admins, ["admin2@localhost", "admin2@example.org"]}.
+

    To remove watchdog admins, remove them in the option. +To remove all watchdog admins, set the option with an empty list: +

    {watchdog_admins, []}.
+

    Appendix A  Internationalization and Localization

    All built-in modules support the xml:lang attribute inside IQ queries. Figure A.1, for example, shows the reply to the following query: diff --git a/doc/guide.tex b/doc/guide.tex index 6bea241a2..f1e25fb72 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -261,7 +261,7 @@ The \term{ejabberdctl} administration script is included in the \term{bin} direc Please refer to the section~\ref{ejabberdctl} for details about \term{ejabberdctl}, and configurable options to fine tune the Erlang runtime system. -\makesection{install.os}{Installing \ejabberd{} with Operating System specific packages} +\makesection{install.os}{Installing \ejabberd{} with Operating System Specific Packages} Some Operating Systems provide a specific \ejabberd{} package adapted to the system architecture and libraries. @@ -301,10 +301,13 @@ To compile \ejabberd{} on a `Unix-like' operating system, you need: \item GNU Make \item GCC \item Libexpat 1.95 or higher -\item Erlang/OTP R10B-9 or newer. +\item Erlang/OTP R10B-9 or higher. \item OpenSSL 0.9.6 or higher, for STARTTLS, SASL and SSL encryption. Optional, highly recommended. \item Zlib 1.2.3 or higher, for Stream Compression support (\xepref{0138}). Optional. -\item GNU Iconv 1.8 or higher, for the IRC Transport (mod\_irc). Optional. Not needed on systems with GNU Libc. +\item Erlang mysql library. Optional. For MySQL authentication or storage. See section \ref{compilemysql}. +\item Erlang pgsql library. Optional. For PostgreSQL authentication or storage. See section \ref{compilepgsql}. +\item PAM library. Optional. For Pluggable Authentication Modules (PAM). See section \ref{pam}. +\item GNU Iconv 1.8 or higher, for the IRC Transport (mod\_irc). Optional. Not needed on systems with GNU Libc. See section \ref{modirc}. \end{itemize} \makesubsection{download}{Download Source Code} @@ -2583,16 +2586,16 @@ Examples: it will be displayed in all active rooms. In this example the history feature is disabled. \begin{verbatim} -{acl, admins, {user, "admin", "example.org"}}. +{acl, admin, {user, "admin", "example.org"}}. -{access, muc_admins, [{allow, admins}]}. +{access, muc_admin, [{allow, admin}]}. {modules, [ ... {mod_muc, [{access, all}, {access_create, all}, - {access_admin, muc_admins}, + {access_admin, muc_admin}, {history_size, 0}]}, ... ]}. @@ -2611,20 +2614,20 @@ Examples: {acl, paying_customers, {user, "customer1", "example.net"}}. {acl, paying_customers, {user, "customer2", "example.com"}}. {acl, paying_customers, {user, "customer3", "example.org"}}. -{acl, admins, {user, "admin", "example.org"}}. +{acl, admin, {user, "admin", "example.org"}}. -{access, muc_admins, [{allow, admins}, +{access, muc_admin, [{allow, admin}, {deny, all}]}. {access, muc_access, [{allow, paying_customers}, - {allow, admins}, + {allow, admin}, {deny, all}]}. {modules, [ ... {mod_muc, [{access, muc_access}, - {access_create, muc_admins}, - {access_admin, muc_admins}]}, + {access_create, muc_admin}, + {access_admin, muc_admin}]}, ... ]}. \end{verbatim} @@ -2651,7 +2654,7 @@ defined, but some user restriction could be added as well: [ ... {mod_muc, [{access, muc_access}, - {access_create, muc_admins}, + {access_create, muc_admin}, {default_room_options, [ {allow_change_subj, false}, @@ -2661,7 +2664,7 @@ defined, but some user restriction could be added as well: {title, "New chatroom"}, {anonymous, false} ]}, - {access_admin, muc_admins}]}, + {access_admin, muc_admin}]}, ... ]}. \end{verbatim} @@ -3541,7 +3544,7 @@ Options: \iqdiscitem{Software Version (\ns{jabber:iq:version})} \end{description} -\makechapter{manage}{Managing an \ejabberd{} server} +\makechapter{manage}{Managing an \ejabberd{} Server} \makesection{ejabberdctl}{\term{ejabberdctl}} @@ -3566,8 +3569,9 @@ The more interesting ones are: \begin{description} \titem{status} Check the status of the \ejabberd{} server. \titem{stop} Stop the \ejabberd{} server which is running in the machine. -\titem{reopen-log} If you use a tool to rotate logs, you have to configure it - so that this command is executed after each rotation. +\titem{reopen-log} Reopen the log files after they were renamed. + If the old files were not renamed before calling this command, + they are automatically renamed to \term{"*-old.log"}. See section \ref{logfiles}. \titem {backup, restore, install-fallback, dump, load} You can use these commands to create and restore backups. %%More information about backuping can @@ -3595,7 +3599,7 @@ if a command succedded or failed, for example using: \term{echo \$?} -\makesubsection{erlangconfiguration}{Erlang runtime system} +\makesubsection{erlangconfiguration}{Erlang Runtime System} \ejabberd{} is an Erlang/OTP application that runs inside an Erlang runtime system. This system is configured using environment variables and command line parameters. @@ -3849,7 +3853,7 @@ so the cookie could be read sniffing the traffic on the network. The recommended way to secure the Erlang node is to block the port 4369. -\makesection{nodename}{Erlang node name} +\makesection{nodename}{Erlang Node Name} An Erlang node may have a node name. The name can be short (if indicated with the command-line parameter \term{-sname}) @@ -3864,7 +3868,7 @@ using a modified version of Erlang \term{epmd}. The recommended way to secure the Erlang node is to block the port 4369. -\makesection{secure-files}{Securing sensible files} +\makesection{secure-files}{Securing Sensible Files} \ejabberd{} stores sensible data in the file system either in plain text or binary files. The file system permissions should be set to only allow the proper user to read, @@ -4084,26 +4088,6 @@ The syntax is the following: \makechapter{debugging}{Debugging} \ind{debugging} -\makesection{watchdog}{Watchdog Alerts} -\ind{debugging!watchdog} - -\ejabberd{} includes a watchdog mechanism. -If a process in the \ejabberd{} server consumes too much memory, -a message is sent to the Jabber accounts defined with the option -\term{watchdog\_admins} -\ind{options!watchdog\_admins} in the \ejabberd{} configuration file. -Example configuration: -\begin{verbatim} -{watchdog_admins, ["admin2@localhost", "admin2@example.org"]}. -\end{verbatim} - -To remove watchdog admins, remove them in the option. -To remove all watchdog admins, set the option with an empty list: -\begin{verbatim} -{watchdog_admins, []}. -\end{verbatim} - - \makesection{logfiles}{Log Files} An \ejabberd{} node writes two log files: @@ -4127,6 +4111,13 @@ For example, the default configuration is: {loglevel, 4}. \end{verbatim} +The log files grow continually, so it is recommended to rotate them periodically. +To rotate the log files, rename the files and then reopen them. +The ejabberd command \term{reopen-log} +(please refer to section \ref{commands}) +reopens the log files, +and also renames the old ones if you didn't rename them. + \makesection{debugconsole}{Debug Console} @@ -4141,6 +4132,29 @@ There are some simple and safe examples in the article To exit the shell, close the window or press the keys: control+c control+c. +\makesection{watchdog}{Watchdog Alerts} +\ind{debugging!watchdog} + +\ejabberd{} includes a watchdog mechanism that may be useful to developers +when troubleshooting a problem related to memory usage. +If a process in the \ejabberd{} server consumes a lot of memory, +a message is sent to the Jabber accounts defined with the option +\term{watchdog\_admins} +\ind{options!watchdog\_admins} in the \ejabberd{} configuration file. +Note that the threshold to define what is too much memory usage +is only configurable editing the source code. +Example configuration: +\begin{verbatim} +{watchdog_admins, ["admin2@localhost", "admin2@example.org"]}. +\end{verbatim} + +To remove watchdog admins, remove them in the option. +To remove all watchdog admins, set the option with an empty list: +\begin{verbatim} +{watchdog_admins, []}. +\end{verbatim} + + \appendix{} \makechapter{i18ni10n}{Internationalization and Localization} diff --git a/src/ejabberd.cfg.example b/src/ejabberd.cfg.example index e86f9cb3f..7528615b0 100644 --- a/src/ejabberd.cfg.example +++ b/src/ejabberd.cfg.example @@ -72,8 +72,9 @@ {loglevel, 4}. %% -%% watchdog_admins: If an ejabberd process consumes too much memory, -%% send live notifications to those Jabber accounts. +%% watchdog_admins: Only useful for developers: if an ejabberd process +%% consumes a lot of memory, send live notifications to these Jabber +%% accounts. %% %%{watchdog_admins, ["bob@example.com"]}. diff --git a/src/ejabberd_ctl.erl b/src/ejabberd_ctl.erl index 74f1b6c28..239679dec 100644 --- a/src/ejabberd_ctl.erl +++ b/src/ejabberd_ctl.erl @@ -99,6 +99,14 @@ process(["restart"]) -> process(["reopen-log"]) -> ejabberd_logger_h:reopen_log(), + case application:get_env(sasl,sasl_error_logger) of + {ok, {file, SASLfile}} -> + error_logger:delete_report_handler(sasl_report_file_h), + ejabberd_logger_h:rotate_log(SASLfile), + error_logger:add_report_handler(sasl_report_file_h, + {SASLfile, get_sasl_error_logger_type()}); + _ -> false + end, ?STATUS_SUCCESS; process(["register", User, Server, Password]) -> @@ -401,3 +409,13 @@ dump_tab(F, T) -> fun() -> mnesia:match_object(T, W, read) end), lists:foreach( fun(Term) -> io:format(F,"~p.~n", [setelement(1, Term, T)]) end, All). + +%% Function copied from Erlang/OTP lib/sasl/src/sasl.erl which doesn't export it +get_sasl_error_logger_type () -> + case application:get_env (sasl, errlog_type) of + {ok, error} -> error; + {ok, progress} -> progress; + {ok, all} -> all; + {ok, Bad} -> exit ({bad_config, {sasl, {errlog_type, Bad}}}); + _ -> all + end. diff --git a/src/ejabberd_logger_h.erl b/src/ejabberd_logger_h.erl index 2e750ca34..e8e6f3baa 100644 --- a/src/ejabberd_logger_h.erl +++ b/src/ejabberd_logger_h.erl @@ -31,7 +31,7 @@ %% gen_event callbacks -export([init/1, handle_event/2, handle_call/2, handle_info/2, terminate/2, - code_change/3, reopen_log/0]). + code_change/3, reopen_log/0, rotate_log/1]). -record(state, {fd, file}). @@ -206,10 +206,11 @@ write_time({{Y,Mo,D},{H,Mi,S}}, Type) -> io_lib:format("~n=~s==== ~w-~.2.0w-~.2.0w ~.2.0w:~.2.0w:~.2.0w ===~n", [Type, Y, Mo, D, H, Mi, S]). -%% Rename the log file if it the filename exists +%% @doc Rename the log file if exists, to "*-old.log". %% This is needed in systems when the file must be closed before rotation (Windows). %% On most Unix-like system, the file can be renamed from the command line and -%%the log can directly be reopened. +%% the log can directly be reopened. +%% @spec (Filename::string()) -> ok rotate_log(Filename) -> case file:read_file_info(Filename) of {ok, _FileInfo} ->