From 78f3e2edb04648bb15b9f33c04c9baa64b19f74d Mon Sep 17 00:00:00 2001 From: Alexey Shchepin Date: Mon, 18 Apr 2005 14:47:13 +0000 Subject: [PATCH] * doc/guide.tex: Updated SVN Revision: 312 --- ChangeLog | 2 + doc/guide.html | 229 +++++++++++++++++++++++++++++++------------------ doc/guide.tex | 107 ++++++++++++++++------- 3 files changed, 225 insertions(+), 113 deletions(-) diff --git a/ChangeLog b/ChangeLog index bf0c9448c..0aaf53893 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,7 @@ 2005-04-18 Alexey Shchepin + * doc/guide.tex: Updated + * src/msgs/pl.msg: New Polish translation (thanks to Andrew Smyk) 2005-04-17 Alexey Shchepin diff --git a/doc/guide.html b/doc/guide.html index 9609458aa..bcb4f57b1 100644 --- a/doc/guide.html +++ b/doc/guide.html @@ -4,7 +4,7 @@ Ejabberd Installation and Operation Guide - + @@ -55,7 +55,7 @@ @@ -127,6 +128,7 @@ Works on most of popular platforms: *nix (tested on Linux, FreeBSD and permanently on more than one node. This means that if one of the nodes crashes, then the others will continue working without disruption. You can also add or replace nodes ``on the fly''. +
  • Support for virtual hosting
  • Built-in Multi-User Chat service
  • Built-in IRC transport
  • Built-in Publish-Subscribe service @@ -144,8 +146,9 @@ Works on most of popular platforms: *nix (tested on Linux, FreeBSD and The misfeatures of ejabberd are:
    • -No support for virtual domains -
    • No support for authentication and STARTTLS in S2S connections +No support for authentication and STARTTLS in S2S connections +
    • Access rules can be defined only for global conext, not for specific + virtual host
    @@ -324,15 +327,25 @@ in config: With this lines old global or local options or ACLs will be removed before adding new ones.

    - + -

    3.1.1  Host Name

    +

    3.1.1  Host Names

    -Option hostname defines name of Jabber domain that ejabberd -serves. E. g. to use jabber.org domain add the following line in the config: +Option hosts defines a list of Jabber domains that ejabberd +serves. E. g. to serve example.org and example.com domains add +the following line in the config: 
    -  {host, "jabber.org"}.
+  {hosts, ["example.org", "example.com"]}.
+
    +Option host defines one Jabber domain that ejabberd serves. +E. g. to serve only example.org domain add the following line in the +config: +
    +  {host, "example.org"}.
+
    It have the same effect as +
    +  {hosts, ["example.org"]}.
    @@ -361,8 +374,8 @@ declarations of ACL in config file have following syntax: all
    Matches all JIDs. Example: 
     {acl, all, all}.
-
    {user, <username>}
    Matches local user with name - <username>. Example: +
    {user, <username>}
    Matches user with name + <username> at the first virtual host. Example: 
     {acl, admin, {user, "aleksey"}}.
    {user, <username>, <server>}
    Matches user with JID @@ -374,7 +387,7 @@ declarations of ACL in config file have following syntax: 
     {acl, jabberorg, {server, "jabber.org"}}.
    {user_regexp, <regexp>}
    Matches local user with name that - matches <regexp>. Example: + matches <regexp> at the first virtual host. Example: 
     {acl, tests, {user, "^test[0-9]*$"}}.
    {user_regexp, <regexp>, <server>}
    Matches user with name @@ -405,7 +418,7 @@ declarations of ACL in config file have following syntax: character not enclosed is matched. -The following ACLs pre-defined: +The following ACLs are pre-defined:
    all
    Matches all JIDs.
    none
    Matches none JIDs. @@ -430,8 +443,8 @@ Example: Following access rules pre-defined:
    -all
    Always return ``allow'' -
    none
    Always return ``deny'' +all
    Always returns ``allow'' +
    none
    Always returns ``deny''
    @@ -617,6 +630,7 @@ Example: {mod_stats, []}, {mod_vcard, []}, {mod_offline, []}, + {mod_announce, [{access, announce}]}, {mod_echo, [{host, "echo.localhost"}]}, {mod_private, []}, {mod_irc, []}, @@ -892,29 +906,50 @@ Example: ... ]}. + + +

    A.1.3  hosts

    + + +This option explicitly defines a list of hostnames for the module which acts as +a service.
    +
    +Example: +
    +  {modules,
+   [
+    ...
+    {mod_echo, [{hosts, ["echo.example.org", "echo.example.com"]}]},
+    ...
+   ]}.
+
    -

    A.2  mod_announce

    +

    A.2  mod_announce

    This module adds support for broadcast announce messages and MOTD. When the module is loaded, it handles messages sent to the following JID's (suppose that main server has address example.org):
    -example.org/announce/all
    Message is sent to all registered users. -If the user is online and connected to several resources, only resource with -the highest priority will receive the message. If the registered user is -not connected, the message will be stored offline (if oflline storage is -available). -
    example.org/announce/online
    Message is sent to all connected users. -If the user is online and connected to several resources, all resources -will receive the message. +example.org/announce/all
    Message is sent to all registered users at +example.org. If the user is online and connected to several resources, +only resource with the highest priority will receive the message. If the +registered user is not connected, the message will be stored offline (if +oflline storage is available). +
    example.org/announce/online
    Message is sent to all connected users at +example.org. If the user is online and connected to several resources, +all resources will receive the message. +
    example.org/announce/all-hosts/online
    Message is sent to all connected +users at every virtual host. If the user is online and connected to several +resources, all resources will receive the message.
    example.org/announce/motd
    Message is set as MOTD (Message of the Day) -and will be sent to users as they login. In addition the message is sent to -all connected users (similar to announce/online resource). -
    example.org/announce/motd/update
    Message is set as MOTD (Message of the Day) -and will be sent to users as they login. The message is not sent to -all connected users. +and is sent to users at example.org as they login. In addition the +message is sent to all connected users (similar to announce/online +resource). +
    example.org/announce/motd/update
    Message is set as MOTD (Message of the +Day) and is sent to users at example.org as they login. The message +is not sent to all connected users.
    example.org/announce/motd/delete
    Any message sent to this JID removes existing MOTD.
    @@ -937,7 +972,7 @@ Example: -

    A.3  mod_configure

    +

    A.3  mod_configure

    Options: @@ -947,7 +982,7 @@ discipline (see A.1.1).
    -

    A.4  mod_disco

    +

    A.4  mod_disco

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

    A.5  mod_echo

    +

    A.5  mod_echo

    This module acts as a service and simply returns to sender any Jabber packet. Module may be @@ -980,22 +1015,30 @@ useful for debugging.

    Options:
    -host
    Defines hostname of service -(see A.1.2). If not present -then prefix echo. is added to main ejabberd hostname. + + host
    Defines hostname of the service + (see A.1.2). +
    hosts
    Defines hostnames of the service + (see A.1.3). If neither host nor hosts + are not present, then prefix echo. is added to all ejabberd hostnames. +
    -

    A.6  mod_irc

    +

    A.6  mod_irc

    This module implements IRC transport.

    Options:
    -host
    Defines hostname of service -(see A.1.2). If not present -then prefix irc. is added to main ejabberd hostname. + + host
    Defines hostname of the service + (see A.1.2). +
    hosts
    Defines hostnames of the service + (see A.1.3). If neither host nor hosts + are not present, then prefix irc. is added to all ejabberd hostnames. +
    access
    Specifies who is allowed to use IRC transport (default value is all).
    Example: @@ -1009,7 +1052,7 @@ Example: -

    A.7  mod_last

    +

    A.7  mod_last

    This module adds support for JEP-0012 (Last Activity)
    @@ -1021,16 +1064,20 @@ discipline (see A.1.1). -

    A.8  mod_muc

    +

    A.8  mod_muc

    This module implements JEP-0045 (Multi-User Chat) service.

    Options:
    -host
    Defines hostname of service -(see A.1.2). If not present -then prefix conference. is added to main ejabberd hostname. + + host
    Defines hostname of the service + (see A.1.2). +
    hosts
    Defines hostnames of the service + (see A.1.3). If neither host nor hosts + are not present, then prefix conference. is added to all ejabberd hostnames. +
    access
    Specifies who is allowed to use MUC service (default value is all).
    access_create
    Specifies who is allowed to create new rooms at MUC service (default value is all). @@ -1056,14 +1103,14 @@ Example: -

    A.9  mod_offline

    +

    A.9  mod_offline

    This module implements offline message storage.

    -

    A.10  mod_privacy

    +

    A.10  mod_privacy

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

    A.11  mod_private

    +

    A.11  mod_private

    This module adds support of JEP-0049 (Private XML Storage).
    @@ -1088,16 +1135,20 @@ discipline (see A.1.1). -

    A.12  mod_pubsub

    +

    A.12  mod_pubsub

    This module implements JEP-0060 (Publish-Subscribe Service).

    Options:
    -host
    Defines hostname of service -(see A.1.2). If not present -then prefix pubsub. is added to main ejabberd hostname. + + host
    Defines hostname of the service + (see A.1.2). +
    hosts
    Defines hostnames of the service + (see A.1.3). If neither host nor hosts + are not present, then prefix pubsub. is added to all ejabberd hostnames. +
    served_hosts
    Specifies which hosts are served by the service. If absent then only main ejabberd host is served.
    @@ -1113,7 +1164,7 @@ Example: -

    A.13  mod_register

    +

    A.13  mod_register

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

    A.14  mod_roster

    +

    A.14  mod_roster

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

    A.15  mod_service_log

    +

    A.15  mod_service_log

    This module adds support for logging of user packets via any jabber service. @@ -1181,7 +1232,7 @@ Example: -

    A.16  mod_stats

    +

    A.16  mod_stats

    This module adds support for JEP-0039 (Statistics Gathering).
    @@ -1193,7 +1244,7 @@ discipline (see A.1.1). -

    A.17  mod_time

    +

    A.17  mod_time

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

    A.18  mod_vcard

    +

    A.18  mod_vcard

    This module implements simple Jabber User Directory (based on user vCards) @@ -1213,29 +1264,41 @@ and answers server vCard on vcard-temp queries.

    Options:
    -host
    Defines hostname of service -(see A.1.2). If not present -then prefix vjud. is added to main ejabberd hostname. + + host
    Defines hostname of the service + (see A.1.2). +
    hosts
    Defines hostnames of the service + (see A.1.3). If neither host nor hosts + are not present, then prefix vjud. is added to all ejabberd hostnames. +
    iqdisc
    vcard-temp IQ queries processing discipline (see A.1.1). -
    search
    Specifies wheather search is enabled (value is true, default) or +
    search
    Specifies whether 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.
    matches
    Limits the number of reported search results. If value is set to infinity then all search results are reported. Default value is 30. +
    allow_return_all
    Specifies whether search with empty input fields can +return all known users. Default is false. +
    search_all_hosts
    If set in true then search returns matched +items at all virtual hosts. Otherwise only current host items are returned. +Default is true.
    Example: 
       {modules,
    [
     ...
-    {mod_vcard, [{search, false}, {matches, 20}]}
+    {mod_vcard, [{search, true},
+                 {matches, 20},
+                 {allow_return_all, true},
+                 {search_all_hosts, false}]}
     ...
    ]}.
    -

    A.19  mod_version

    +

    A.19  mod_version

    This module answers ejabberd version on jabber:iq:version queries.
    @@ -1247,7 +1310,7 @@ discipline (see A.1.1). -

    B  I18n/L10n

    +

    B  I18n/L10n

    All built-in modules support xml:lang attribute inside IQ queries. diff --git a/doc/guide.tex b/doc/guide.tex index 2ced9bc60..4d2d4789c 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -69,9 +69,13 @@ \newcommand{\iqdiscitem}[1]{\titem{iqdisc} #1 IQ queries processing discipline (see~\ref{sec:modiqdiscoption}).} -\newcommand{\hostitem}[1]{\titem{host} Defines hostname of service -(see~\ref{sec:modhostoption}). If not present -then prefix \jid{#1.} is added to main \ejabberd{} hostname.} +\newcommand{\hostitem}[1]{ + \titem{host} Defines hostname of the service + (see~\ref{sec:modhostoption}). + \titem{hosts} Defines hostnames of the service + (see~\ref{sec:modhostsoption}). If neither \texttt{host} nor \texttt{hosts} + are not present, then prefix \jid{#1.} is added to all \ejabberd{} hostnames. +} \title{Ejabberd Installation and Operation Guide} \author{Alexey Shchepin \\ @@ -109,6 +113,7 @@ The main features of \ejabberd{} are: permanently on more than one node. This means that if one of the nodes crashes, then the others will continue working without disruption. You can also add or replace nodes ``on the fly''. +\item Support for virtual hosting \item Built-in \tjepref{0045}{Multi-User Chat} service \item Built-in IRC transport \item Built-in \tjepref{0060}{Publish-Subscribe} service @@ -127,8 +132,9 @@ The main features of \ejabberd{} are: The misfeatures of \ejabberd{} are: \begin{itemize} -\item No support for virtual domains \item No support for authentication and STARTTLS in S2S connections +\item Access rules can be defined only for global conext, not for specific + virtual host \end{itemize} @@ -309,13 +315,25 @@ With this lines old global or local options or ACLs will be removed before adding new ones. -\subsubsection{Host Name} +\subsubsection{Host Names} \label{sec:confighostname} -Option \option{hostname} defines name of \Jabber{} domain that \ejabberd{} -serves. E.\,g.\ to use \jid{jabber.org} domain add the following line in the config: +Option \option{hosts} defines a list of \Jabber{} domains that \ejabberd{} +serves. E.\,g.\ to serve \jid{example.org} and \jid{example.com} domains add +the following line in the config: \begin{verbatim} - {host, "jabber.org"}. + {hosts, ["example.org", "example.com"]}. +\end{verbatim} + +Option \option{host} defines one \Jabber{} domain that \ejabberd{} serves. +E.\,g.\ to serve only \jid{example.org} domain add the following line in the +config: +\begin{verbatim} + {host, "example.org"}. +\end{verbatim} +It have the same effect as +\begin{verbatim} + {hosts, ["example.org"]}. \end{verbatim} %This option is mandatory. @@ -347,8 +365,8 @@ declarations of ACL in config file have following syntax: \begin{verbatim} {acl, all, all}. \end{verbatim} -\titem{\{user, \}} Matches local user with name - \term{}. Example: +\titem{\{user, \}} Matches user with name + \term{} at the first virtual host. Example: \begin{verbatim} {acl, admin, {user, "aleksey"}}. \end{verbatim} @@ -363,7 +381,7 @@ declarations of ACL in config file have following syntax: {acl, jabberorg, {server, "jabber.org"}}. \end{verbatim} \titem{\{user\_regexp, \}} Matches local user with name that - matches \term{}. Example: + matches \term{} at the first virtual host. Example: \begin{verbatim} {acl, tests, {user, "^test[0-9]*$"}}. \end{verbatim} @@ -400,7 +418,7 @@ declarations of ACL in config file have following syntax: \end{description} \end{description} -The following ACLs pre-defined: +The following ACLs are pre-defined: \begin{description} \titem{all} Matches all JIDs. \titem{none} Matches none JIDs. @@ -428,8 +446,8 @@ Example: Following access rules pre-defined: \begin{description} -\titem{all} Always return ``\term{allow}'' -\titem{none} Always return ``\term{deny}'' +\titem{all} Always returns ``\term{allow}'' +\titem{none} Always returns ``\term{deny}'' \end{description} @@ -620,6 +638,7 @@ Example: {mod_stats, []}, {mod_vcard, []}, {mod_offline, []}, + {mod_announce, [{access, announce}]}, {mod_echo, [{host, "echo.localhost"}]}, {mod_private, []}, {mod_irc, []}, @@ -895,6 +914,22 @@ Example: ]}. \end{verbatim} +\subsubsection{\option{hosts}} +\label{sec:modhostsoption} + +This option explicitly defines a list of hostnames for the module which acts as +a service. + +Example: +\begin{verbatim} + {modules, + [ + ... + {mod_echo, [{hosts, ["echo.example.org", "echo.example.com"]}]}, + ... + ]}. +\end{verbatim} + \subsection{\modannounce{}} \label{sec:modannounce} @@ -903,20 +938,24 @@ This module adds support for broadcast announce messages and MOTD. When the module is loaded, it handles messages sent to the following JID's (suppose that main server has address \jid{example.org}): \begin{description} -\titem{example.org/announce/all} Message is sent to all registered users. -If the user is online and connected to several resources, only resource with -the highest priority will receive the message. If the registered user is -not connected, the message will be stored offline (if oflline storage is -available). -\titem{example.org/announce/online} Message is sent to all connected users. -If the user is online and connected to several resources, all resources -will receive the message. +\titem{example.org/announce/all} Message is sent to all registered users at +\jid{example.org}. If the user is online and connected to several resources, +only resource with the highest priority will receive the message. If the +registered user is not connected, the message will be stored offline (if +oflline storage is available). +\titem{example.org/announce/online} Message is sent to all connected users at +\jid{example.org}. If the user is online and connected to several resources, +all resources will receive the message. +\titem{example.org/announce/all-hosts/online} Message is sent to all connected +users at every virtual host. If the user is online and connected to several +resources, all resources will receive the message. \titem{example.org/announce/motd} Message is set as MOTD (Message of the Day) -and will be sent to users as they login. In addition the message is sent to -all connected users (similar to \term{announce/online} resource). -\titem{example.org/announce/motd/update} Message is set as MOTD (Message of the Day) -and will be sent to users as they login. The message is \emph{not sent} to -all connected users. +and is sent to users at \jid{example.org} as they login. In addition the +message is sent to all connected users (similar to \term{announce/online} +resource). +\titem{example.org/announce/motd/update} Message is set as MOTD (Message of the +Day) and is sent to users at \jid{example.org} as they login. The message +is \emph{not sent} to all connected users. \titem{example.org/announce/motd/delete} Any message sent to this JID removes existing MOTD. \end{description} @@ -1207,11 +1246,16 @@ Options: \begin{description} \hostitem{vjud} \iqdiscitem{\ns{vcard-temp}} -\titem{search} Specifies wheather search is enabled (value is \term{true}, default) or +\titem{search} Specifies whether 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. \titem{matches} Limits the number of reported search results. If value is set to -\term{infinity} then all search results are reported. Default value is \term{30}. +\term{infinity} then all search results are reported. Default value is \term{30}. +\titem{allow\_return\_all} Specifies whether search with empty input fields can +return all known users. Default is \term{false}. +\titem{search\_all\_hosts} If set in \term{true} then search returns matched +items at all virtual hosts. Otherwise only current host items are returned. +Default is \term{true}. \end{description} Example: @@ -1219,7 +1263,10 @@ Example: {modules, [ ... - {mod_vcard, [{search, false}, {matches, 20}]} + {mod_vcard, [{search, true}, + {matches, 20}, + {allow_return_all, true}, + {search_all_hosts, false}]} ... ]}. \end{verbatim}