From d2eab0d5350cd2fc09987d43f39b7f00dde406d6 Mon Sep 17 00:00:00 2001 From: Alexey Shchepin Date: Fri, 9 Jul 2004 22:34:26 +0000 Subject: * doc/guide.tex: Updated * src/msgs/fr.msg: Updated (thanks to Sergei Golovan) * src/mod_irc/mod_irc.erl: Added handler for disco items requests (thanks to Sergei Golovan) * src/mod_vcard.erl: Added option for JUD disabling (thanks to Sergei Golovan) * src/mod_configure2.erl: Fixed module stopping (thanks to Sergei Golovan) * src/mod_last.erl: Likewise * src/mod_privacy.erl: Likewise * src/mod_register.erl: Likewise * src/mod_roster.erl: Likewise * src/mod_vcard.erl: Likewise * src/jd2ejd.erl: Added emergency catches (thanks to Sergei Golovan) * src/mod_last.erl: Likewise * src/ejabberd_sm.erl: Removed needless call to mod_disco:unregister_feature (thanks to Sergei Golovan) * src/ejabberd_local.erl: Better support for mod_disco (thanks to Sergei Golovan) * src/mod_disco.erl: Likewise * src/translate.erl: Suport for "default language" option (thanks to Sergei Golovan) * src/ejabberd_config.erl: Likewise * src/ejabberd_c2s.erl: Likewise * src/ejabberd.hrl: Added 'MYLANG' macros * src/ejabberd.cfg.example: Updated (thanks to Sergei Golovan) * doc/guide.tex: Updated (thanks to Sergei Golovan) * src/win32/ejabberd.cfg: Updated (thanks to Sergei Golovan) SVN Revision: 241 --- doc/guide.html | 343 +++++++++++++++++++++------------------------------ doc/guide.tex | 177 +++++++++++--------------- doc/webadmmain.png | Bin 0 -> 23928 bytes doc/webadmmainru.png | Bin 0 -> 24539 bytes 4 files changed, 216 insertions(+), 304 deletions(-) create mode 100644 doc/webadmmain.png create mode 100644 doc/webadmmainru.png (limited to 'doc') diff --git a/doc/guide.html b/doc/guide.html index c896d836a..19038a75a 100644 --- a/doc/guide.html +++ b/doc/guide.html @@ -56,56 +56,49 @@ 3.1  Initial Configuration -
  • 3.2  Online Configuration and Monitoring - +
  • 3.2  Online Configuration and Monitoring -
  • 4  Distribution +
  • 4  Distribution -
  • A  Built-in Modules +
  • A  Built-in Modules -
  • B  I18n/L10n +
  • B  I18n/L10n @@ -131,6 +124,7 @@ Works on most of popular platforms: *nix (tested on Linux, FreeBSD and
  • Built-in IRC transport
  • Built-in Publish-Subscribe service
  • Built-in Jabber Users Directory service based on users vCards +
  • Built-in web-based administration interface
  • Built-in HTTP Polling service
  • SSL support
  • Support for LDAP authentification @@ -328,13 +322,25 @@ adding new ones.
    Option hostname defines name of Jabber domain that ejabberd -serves. E. g. to use jabber.org domain add following line in config: +serves. E. g. to use jabber.org domain add the following line in the config: 
       {host, "jabber.org"}.
    + + +

    3.1.2  Default Language

    + + +Option language defines default language of ejabberd messages, sent +to users. Default value is "en". In order to take effect there must be a +translation file <language>.msg in ejabberd msgs directory. +E. g. to use Russian as default language add the following line in the config: +
    +  {language, "ru"}.
+
    -

    3.1.2  Access Rules

    +

    3.1.3  Access Rules

    Access control in ejabberd is performed via Access Control Lists (ACL). The @@ -420,7 +426,7 @@ Following access rules pre-defined: -

    3.1.3  Shapers Configuration

    +

    3.1.4  Shapers Configuration

    With shapers is possible to bound connection traffic. The declarations of @@ -439,7 +445,7 @@ E. g. to define shaper with name ``normal'' and maximum allowed ra -

    3.1.4  Listened Sockets

    +

    3.1.5  Listened Sockets

    Option listen defines list of listened sockets and what services @@ -499,19 +505,23 @@ For example, the following configuration defines that: C2S connections are listened on port 5222 and 5223 (SSL) and denied for user ``bad''
  • S2S connections are listened on port 5269 +
  • HTTP connections are listened on port 5280 and administration interface + and HTTP Polling support are enabled
  • All users except admins have traffic limit 1000 B/s -
  • AIM service aim.example.org is connected to port 5233 with +
  • AIM transport aim.example.org is connected to port 5233 with password ``aimsecret'' -
  • JIT services icq.example.org and sms.example.org are +
  • JIT transports icq.example.org and sms.example.org are connected to port 5234 with password ``jitsecret'' -
  • MSN service msn.example.org is connected to port 5235 with +
  • MSN transport msn.example.org is connected to port 5235 with password ``msnsecret'' -
  • Yahoo! service yahoo.example.org is connected to port 5236 with +
  • Yahoo! transport yahoo.example.org is connected to port 5236 with password ``yahoosecret'' -
  • ILE service ile.example.org is connected to port 5237 with +
  • Gadu-Gadu transport gg.example.org is connected to port 5237 with + password ``ggsecret'' +
  • ILE service ile.example.org is connected to port 5238 with password ``ilesecret'' - 
    +
       {acl, blocked, {user, "bad"}}.
   {access, c2s, [{deny, blocked},
                  {allow, all}]}.
@@ -523,6 +533,7 @@ C2S connections are listened on port 5222 and 5223 (SSL) and denied for
     {5223, ejabberd_c2s,     [{access, c2s},
                               ssl, {certfile, "/path/to/ssl.pem"}]},
     {5269, ejabberd_s2s_in,  []},
+    {5280, ejabberd_http,    [http_poll, web_admin]},
     {5233, ejabberd_service, [{host, "aim.example.org",
                                [{password, "aimsecret"}]}]},
     {5234, ejabberd_service, [{hosts, ["icq.example.org", "sms.example.org"],
@@ -571,7 +582,7 @@ transports log and do XDB by themselves:
 
    
 
 
-
    3.1.5  Modules
    
+
    3.1.6  Modules
    
 
 
 Option modules defines the list of modules that will be loaded after
@@ -602,146 +613,54 @@ Example:
    -

    3.2  Online Configuration and Monitoring

    +

    3.2  Online Configuration and Monitoring

    -To perform online reconfiguration of ejabberd you will need to have -mod_configure loaded (see section A.2). It is also highly -recommended to load mod_disco as well (see section A.3), -because mod_configure is highly integrated with it. Additionally it is -recommended to use a disco- and xdata-capable client such as -Tkabber -(which was developed synchronously with ejabberd, its CVS version -supports most of ejabberd features).
    -
    -On disco query ejabberd returns following items (see figure 1): - -
    - - - - -
    -
    Figure 1: Tkabber Discovery window

    - - -
    - - -

    3.2.1  Node config: Global Configuration

    - -Under this node the following nodes exist:
    -
    - - -
    Node config/hostname
    - -Via ejabberd:config queries to this node possible to change host name of -this ejabberd server. (See figure 2) (Currently this works -correctly only after a restart) -
    - - - - -
    -
    Figure 2: Editing of hostname

    - - -
    - - -
    Node config/acls
    - -Via ejabberd:config queries to this node it is possible to edit ACLs list. -(See figure 3) -
    - - - - -
    -
    Figure 3: Editing of ACLs

    - - -
    - - -
    Node config/access
    - -Via ejabberd:config queries to this node it is possible to edit access -rules.
    -
    - - -
    Node config/remusers
    - -Via ejabberd:config queries to this node it is possible to remove users. If -removed user is online, then he will be disconnected. Also user-related data -(e.g. his roster) is removed (but appropriate module must be loaded).
    -
    - - -

    3.2.2  Node online users: List of Online Users

    - - - -

    3.2.3  Node all users: List of Registered Users

    - -
    - - - - -
    -
    Figure 4: Discovery all users

    - - -
    - - -

    3.2.4  Node outgoing s2s: List of Outgoing S2S connections

    - - - -

    3.2.5  Node running nodes: List of Running ejabberd Nodes

    - +To perform online reconfiguration of ejabberd you need to enable +ejabberd_http listener with option web_admin (see +section 3.1.5). After that you can open URL +http://server:port/admin/ with you favorite web-browser and enter +username and password of ejabberd administrator. E. g. with such config: +
    +  ...
+  {host, "example.org"}.
+  ...
+  {listen,
+   [...
+    {5280, ejabberd_http, [web_admin]},
+    ...
+   ]
+  }.
+
    you should enter URL http://example.org:5280/admin/. After +authentification you should see something like in figure 1.
    - +
    -
    Figure 5: Discovery running nodes

    +
    Figure 1: Web-administration top page

    - +
    - - -

    3.2.6  Node stopped nodes: List of Stopped Nodes

    - -TBD
    +Here you can edit access restrictions, manage users, create backup files, +manage DB, enable/disable listened ports, and view statistics.

    -

    4  Distribution

    +

    4  Distribution

    -

    4.1  How it works

    +

    4.1  How it works

    A Jabber domain is served by one or more ejabberd nodes. These nodes can -be run on different machines that are connected via a network. They all must -have the ability to connect to port 4369 of all another nodes, and must have -the same magic cookie (see Erlang/OTP documentation, in other words the file -~ejabberd/.erlang.cookie must be the same on all nodes). This is +be runned on different machines that are connected via a network. They all +must have the ability to connect to port 4369 of all another nodes, and must +have the same magic cookie (see Erlang/OTP documentation, in other words the +file ~ejabberd/.erlang.cookie must be the same on all nodes). This is needed because all nodes exchange information about connected users, S2S connections, registered services, etc...

    @@ -754,7 +673,7 @@ router; -

    4.1.1  Router

    +

    4.1.1  Router

    This module is the main router of Jabber packets on each node. It routes them based on their destinations domains. It has two tables: local and global @@ -766,7 +685,7 @@ manager.

    -

    4.1.2  Local Router

    +

    4.1.2  Local Router

    This module routes packets which have a destination domain equal to this server name. If destination JID has a non-empty user part, then it routed to the @@ -774,7 +693,7 @@ session manager, else it is processed depending on it's content.

    -

    4.1.3  Session Manager

    +

    4.1.3  Session Manager

    This module routes packets to local users. It searches for what user resource packet must be sended via presence table. If this resource is connected to @@ -783,7 +702,7 @@ the packet is sent to session manager on that node.

    -

    4.1.4  S2S Manager

    +

    4.1.4  S2S Manager

    This module routes packets to other Jabber servers. First, it checks if an open S2S connection from the domain of the packet source to the domain of @@ -794,12 +713,12 @@ does not exist, then it is opened and registered.

    -

    A  Built-in Modules

    +

    A  Built-in Modules

    -

    A.1  Common Options

    +

    A.1  Common Options

    The following options are used by many modules, so they are described in @@ -807,7 +726,7 @@ separate section.

    -

    A.1.1  Option iqdisc

    +

    A.1.1  Option iqdisc

    Many modules define handlers for processing IQ queries of different namespaces @@ -840,7 +759,7 @@ Example: -

    A.1.2  Option host

    +

    A.1.2  Option host

    This option explicitly defines hostname for the module which acts as a service.
    @@ -856,7 +775,7 @@ Example: -

    A.2  mod_configure

    +

    A.2  mod_configure

    Options: @@ -866,7 +785,7 @@ discipline (see A.1.1). -

    A.3  mod_disco

    +

    A.3  mod_disco

    This module adds support for JEP-0030 (Service Discovery).
    @@ -891,7 +810,7 @@ Example: -

    A.4  mod_echo

    +

    A.4  mod_echo

    This module acts as a service and simply returns to sender any Jabber packet. Module may be @@ -905,7 +824,7 @@ then prefix echo. is added to main ejabberd hostname. -

    A.5  mod_irc

    +

    A.5  mod_irc

    This module implements IRC transport.
    @@ -918,7 +837,7 @@ then prefix irc. is added to main ejabberd hostname. -

    A.6  mod_last

    +

    A.6  mod_last

    This module adds support for JEP-0012 (Last Activity)
    @@ -930,7 +849,7 @@ discipline (see A.1.1). -

    A.7  mod_muc

    +

    A.7  mod_muc

    This module implements JEP-0045 (Multi-User Chat) service.
    @@ -965,14 +884,14 @@ Example: -

    A.8  mod_offline

    +

    A.8  mod_offline

    This module implements offline message storage.

    -

    A.9  mod_privacy

    +

    A.9  mod_privacy

    This module implements Privacy Rules as defined in XMPP IM @@ -985,7 +904,7 @@ discipline (see A.1.1). -

    A.10  mod_private

    +

    A.10  mod_private

    This module adds support of JEP-0049 (Private XML Storage).
    @@ -997,7 +916,7 @@ discipline (see A.1.1). -

    A.11  mod_pubsub

    +

    A.11  mod_pubsub

    This module implements JEP-0060 (Publish-Subscribe Service).
    @@ -1022,7 +941,7 @@ Example: -

    A.12  mod_register

    +

    A.12  mod_register

    This module adds support for JEP-0077 (In-Band Registration). @@ -1054,7 +973,7 @@ Example: -

    A.13  mod_roster

    +

    A.13  mod_roster

    This module implements roster management.
    @@ -1066,7 +985,7 @@ discipline (see A.1.1). -

    A.14  mod_stats

    +

    A.14  mod_stats

    This module adds support for JEP-0039 (Statistics Gathering).
    @@ -1080,7 +999,7 @@ TBD about access.

    -

    A.15  mod_time

    +

    A.15  mod_time

    This module answers UTC time on jabber:iq:time queries.
    @@ -1092,7 +1011,7 @@ discipline (see A.1.1). -

    A.16  mod_vcard

    +

    A.16  mod_vcard

    This module implements simple Jabber User Directory (based on user vCards) @@ -1105,10 +1024,22 @@ Options: then prefix vjud. is added to main ejabberd hostname.
    iqdisc
    vcard-temp IQ queries processing discipline (see A.1.1). +
    search
    Specifies wheather search is enabled (value is true, default) or +disabled (value is false) by the service. If search is set to false, +option host is ignored and service does not appear in Jabber Discovery items. +Example: +
    +  {modules,
+   [
+    ...
+    {mod_vcard, [{search, false}]}
+    ...
+   ]}.
+
    -

    A.17  mod_version

    +

    A.17  mod_version

    This module answers ejabberd version on jabber:iq:version queries.
    @@ -1120,12 +1051,11 @@ discipline (see A.1.1). -

    B  I18n/L10n

    +

    B  I18n/L10n

    All built-in modules support xml:lang attribute inside IQ queries. -E. g. on figure 6 (compare it with figure 1) -showed reply on following query: +E. g. on figure 2 showed the reply on the following query: 
       <iq id='5'
       to='e.localhost'
@@ -1140,10 +1070,23 @@ showed reply on following query:
  
 
  
    
-
    Figure 6: Discovery result when xml:lang='ru'

    
+
    Figure 2: Discovery result when xml:lang='ru'

    
 
  
 
    
+Also web-interface supports Accept-Language HTTP header (see
+figure 3, compare it with figure 1)
+
    
+ 
+ 
+ 
+
+ 
    
+
    Figure 3: Web-administration top page with HTTP header
+ ``Accept-Language: ru''

    
+
+ 
+
    
 
 
 
diff --git a/doc/guide.tex b/doc/guide.tex
index c763710a7..1752a8606 100644
--- a/doc/guide.tex
+++ b/doc/guide.tex
@@ -111,6 +111,7 @@ The main features of \ejabberd{} are:
 \item Built-in IRC transport
 \item Built-in \tjepref{0060}{Publish-Subscribe} service
 \item Built-in Jabber Users Directory service based on users vCards
+\item Built-in web-based administration interface
 \item Built-in \tjepref{0025}{HTTP Polling} service
 \item SSL support
 \item Support for LDAP authentification
@@ -311,13 +312,24 @@ adding new ones.
 \label{sec:confighostname}
 
 Option \option{hostname} defines name of \Jabber{} domain that \ejabberd{}
-serves.  E.\,g.\ to use \jid{jabber.org} domain add following line in config:
+serves.  E.\,g.\ to use \jid{jabber.org} domain add the following line in the config:
 \begin{verbatim}
   {host, "jabber.org"}.
 \end{verbatim}
 
 %This option is mandatory.
 
+\subsubsection{Default Language}
+\label{sec:configlanguage}
+
+Option \option{language} defines default language of \ejabberd{} messages, sent
+to users. Default value is \term{"en"}. In order to take effect there must be a
+translation file \term{.msg} in \ejabberd{} \term{msgs} directory.
+E.\,g.\ to use Russian as default language add the following line in the config:
+\begin{verbatim}
+  {language, "ru"}.
+\end{verbatim}
+
 
 \subsubsection{Access Rules}
 \label{sec:configaccess}
@@ -505,18 +517,20 @@ For example, the following configuration defines that:
 \item HTTP connections are listened on port 5280 and administration interface
   and HTTP Polling support are enabled
 \item All users except admins have traffic limit 1000\,B/s
-\item AIM service \jid{aim.example.org} is connected to port 5233 with
+\item AIM transport \jid{aim.example.org} is connected to port 5233 with
   password ``\term{aimsecret}''
-\item JIT services \jid{icq.example.org} and \jid{sms.example.org} are
+\item JIT transports \jid{icq.example.org} and \jid{sms.example.org} are
   connected to port 5234 with password ``\term{jitsecret}''
-\item MSN service \jid{msn.example.org} is connected to port 5235 with
+\item MSN transport \jid{msn.example.org} is connected to port 5235 with
   password ``\term{msnsecret}''
-\item Yahoo! service \jid{yahoo.example.org} is connected to port 5236 with
+\item Yahoo! transport \jid{yahoo.example.org} is connected to port 5236 with
   password ``\term{yahoosecret}''
-\item ILE service \jid{ile.example.org} is connected to port 5237 with
+\item Gadu-Gadu transport \jid{gg.example.org} is connected to port 5237 with
+  password ``\term{ggsecret}''
+\item ILE service \jid{ile.example.org} is connected to port 5238 with
   password ``\term{ilesecret}''
 \end{itemize}
-  \begin{verbatim}
+\begin{verbatim}
   {acl, blocked, {user, "bad"}}.
   {access, c2s, [{deny, blocked},
                  {allow, all}]}.
@@ -612,103 +626,35 @@ Example:
 \subsection{Online Configuration and Monitoring}
 \label{sec:onlineconfig}
 
-To perform online reconfiguration of \ejabberd{} you will need to have
-\modconfigure{} loaded (see section~\ref{sec:modconfigure}). It is also highly
-recommended to load \moddisco{} as well (see section~\ref{sec:moddisco}),
-because \modconfigure{} is highly integrated with it.  Additionally it is
-recommended to use a disco- and xdata-capable client such as
-\footahref{http://tkabber.jabber.ru/}{Tkabber}
-(which was developed synchronously with \ejabberd{}, its CVS version
-supports most of \ejabberd{} features).
-
-
-On disco query \ejabberd{} returns following items (see figure~\ref{fig:disco}):
-\begin{itemize}
-\item Identity of server.
-\item List of features, including defined namespaces.
-\item List of JIDs from route table.
-\item List of disco-nodes described in following subsections.
-\end{itemize}
-\begin{figure}[htbp]
-  \centering
-  \insimg{disco.png}
-  \caption{Tkabber Discovery window}
-  \label{fig:disco}
-\end{figure}
-
-\subsubsection{Node \node{config}: Global Configuration}
-
-Under this node the following nodes exist:
-
-\paragraph{Node \node{config/hostname}}
-
-Via \ns{ejabberd:config} queries to this node possible to change host name of
-this \ejabberd{} server. (See figure~\ref{fig:hostname}) (Currently this works
-correctly only after a restart)
-\begin{figure}[htbp]
-  \centering
-  \insimg{confhostname.png}
-  \caption{Editing of hostname}
-  \label{fig:hostname}
-\end{figure}
-
-\paragraph{Node \node{config/acls}}
-
-Via \ns{ejabberd:config} queries to this node it is possible to edit ACLs list.
-(See figure~\ref{fig:acls})
-\begin{figure}[htbp]
-  \centering
-  \insimg{confacls.png}
-  \caption{Editing of ACLs}
-  \label{fig:acls}
-\end{figure}
-
-
-\paragraph{Node \node{config/access}}
-
-Via \ns{ejabberd:config} queries to this node it is possible to edit access
-rules.
-
-
-\paragraph{Node \node{config/remusers}}
-
-Via \ns{ejabberd:config} queries to this node it is possible to remove users.  If
-removed user is online, then he will be disconnected.  Also user-related data
-(e.g. his roster) is removed (but appropriate module must be loaded).
-
-\subsubsection{Node \node{online users}: List of Online Users}
-
-\subsubsection{Node \node{all users}: List of Registered Users}
-
-\begin{figure}[htbp]
-  \centering
-  \insimg{discoallusers.png}
-  \caption{Discovery all users}
-  \label{fig:discoallusers}
-\end{figure}
-
-
-\subsubsection{Node \node{outgoing s2s}: List of Outgoing S2S connections}
-
-\subsubsection{Node \node{running nodes}: List of Running \ejabberd{} Nodes}
-
+To perform online reconfiguration of \ejabberd{} you need to enable
+\term{ejabberd\_http} listener with option \term{web\_admin} (see
+section~\ref{sec:configlistened}).  After that you can open URL
+\verb|http://server:port/admin/| with you favorite web-browser and enter
+username and password of \ejabberd{} administrator.  E.\,g. with such config:
+\begin{verbatim}
+  ...
+  {host, "example.org"}.
+  ...
+  {listen,
+   [...
+    {5280, ejabberd_http, [web_admin]},
+    ...
+   ]
+  }.
+\end{verbatim}
+you should enter URL \verb|http://example.org:5280/admin/|.  After
+authentification you should see something like in figure~\ref{fig:webadmmain}.
 \begin{figure}[htbp]
   \centering
-  \insimg{discorunnodes.png}
-  \caption{Discovery running nodes}
-  \label{fig:discorunnodes}
+  \insimg{webadmmain.png}
+  \caption{Web-administration top page}
+  \label{fig:webadmmain}
 \end{figure}
-
-\subsubsection{Node \node{stopped nodes}: List of Stopped Nodes}
-
-
-
+Here you can edit access restrictions, manage users, create backup files,
+manage DB, enable/disable listened ports, and view statistics.
 
 
 
-
-TBD
-
 \section{Distribution}
 \label{sec:distribution}
 
@@ -717,10 +663,10 @@ TBD
 \label{sec:howitworks}
 
 A \Jabber{} domain is served by one or more \ejabberd{} nodes.  These nodes can
-be run on different machines that are connected via a network.  They all must
-have the ability to connect to port 4369 of all another nodes, and must have
-the same magic cookie (see Erlang/OTP documentation, in other words the file
-\term{\~{}ejabberd/.erlang.cookie} must be the same on all nodes). This is
+be runned on different machines that are connected via a network.  They all
+must have the ability to connect to port 4369 of all another nodes, and must
+have the same magic cookie (see Erlang/OTP documentation, in other words the
+file \term{\~{}ejabberd/.erlang.cookie} must be the same on all nodes). This is
 needed because all nodes exchange information about connected users, S2S
 connections, registered services, etc\ldots
 
@@ -1061,8 +1007,21 @@ Options:
 \begin{description}
 \hostitem{vjud}
 \iqdiscitem{\ns{vcard-temp}}
+\titem{search} Specifies wheather search is enabled (value is \term{true}, default) or
+disabled (value is \term{false}) by the service. If \term{search} is set to \term{false},
+option \term{host} is ignored and service does not appear in Jabber Discovery items.
 \end{description}
 
+Example:
+\begin{verbatim}
+  {modules,
+   [
+    ...
+    {mod_vcard, [{search, false}]}
+    ...
+   ]}.
+\end{verbatim}
+
 
 \subsection{\modversion{}}
 \label{sec:modversion}
@@ -1079,8 +1038,7 @@ Options:
 \label{sec:i18nl10n}
 
 All built-in modules support \texttt{xml:lang} attribute inside IQ queries.
-E.\,g.\ on figure~\ref{fig:discorus} (compare it with figure~\ref{fig:disco})
-showed reply on following query:
+E.\,g.\ on figure~\ref{fig:discorus} showed the reply on the following query:
 \begin{verbatim}