From 42115402722e1eb238a472964851dd60f7b39b62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20R=C3=A9mond?= Date: Fri, 22 Sep 2006 07:25:18 +0000 Subject: Improvement coming from trunk (SVN #601): * src/mod_muc/mod_muc.erl: It is now possible to configure the MUC room history feature. A new option has been added in ejabberd muc module configuration (history_size) to define the size of the history. 0 is used to disable the feature. * src/mod_muc/mod_muc_room.erl: Likewise. * doc/guide.tex: Likewise. SVN Revision: 610 --- doc/guide.tex | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'doc/guide.tex') diff --git a/doc/guide.tex b/doc/guide.tex index 0a757ca58..53a07c585 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -1710,6 +1710,13 @@ Options: administer his room). By sending a message to the service JID, administrators can send service messages that will be displayed in every active room. + + \titem{history\_size} \ind{options!history\_size}a small history of the + current discussion is send to users when they enter the room. This option make + it possible to define the number of history messages to keep and send to the + user joining the room. The value is a integer. Setting the value to \term{0} + disable the history feature and nothing is kept in memory. The default value + is \term{20}. This value is global and affects all MUC rooms on the server. \end{description} Examples: @@ -1721,7 +1728,8 @@ Examples: sends a message such as ``Tomorrow, the \Jabber{} server will be moved to new hardware. This will involve service breakdowns around 23:00 UMT. We apologise for this inconvenience.'' to \jid{conference.example.org}, - it will be displayed in all active rooms. + it will be displayed in all active rooms. In this example the history + feature is disabled. \begin{verbatim} {acl, admins, {user, "admin", "example.org"}}. ... @@ -1732,7 +1740,8 @@ Examples: ... {mod_muc, [{access, all}, {access_create, all}, - {access_admin, muc_admins}]}, + {access_admin, muc_admins}, + {history_size, 0}]}, ... ]}. \end{verbatim} @@ -1743,7 +1752,9 @@ Examples: \jid{admin@example.org} sends a message such as ``Tomorrow, the \Jabber{} server will be moved to new hardware. This will involve service breakdowns around 23:00 UMT. We apologise for this inconvenience.'' to - \jid{conference.example.org}, it will be displayed in all active rooms. + \jid{conference.example.org}, it will be displayed in all active rooms. No + \term{history\_size} option is used, this means that the feature is enabled + and the default value of 20 history messages will be send to the users. \begin{verbatim} {acl, paying_customers, {user, "customer1", "example.net"}}. {acl, paying_customers, {user, "customer2", "example.com"}}. -- cgit v1.2.3 From 23b78b0f0c871183a56f40b05fc25e20b4c75a7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20R=C3=A9mond?= Date: Fri, 22 Sep 2006 08:36:09 +0000 Subject: Improvement coming from trunk (SVN #606): * doc/guide.tex: Updated (thanks to Evgeniy Khramtsov) * src/ejabberd_auth_ldap.erl: Better LDAP support (thanks to Evgeniy Khramtsov) * src/mod_vcard_ldap.erl: Likewise * src/eldap/eldap_filter.erl: Likewise SVN Revision: 615 --- doc/guide.tex | 341 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 336 insertions(+), 5 deletions(-) (limited to 'doc/guide.tex') diff --git a/doc/guide.tex b/doc/guide.tex index 53a07c585..ae37b8d04 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -1985,15 +1985,14 @@ Options: Examples: \begin{itemize} -\item Next example prohibits the registration of too short account names and of - account names with exotic characters in it: - \begin{verbatim} +\item Next example prohibits the registration of too short account names: +\begin{verbatim} {acl, shortname, {user_glob, "?"}}. {acl, shortname, {user_glob, "??"}}. - {acl, strangename, {user_regexp, "^..?$"}}. + % The same using regexp: + %{acl, shortname, {user_regexp, "^..?$"}}. ... {access, register, [{deny, shortname}, - {deny, strangename}, {allow, all}]}. ... {modules, @@ -2292,6 +2291,338 @@ Examples: \end{verbatim} \end{itemize} +\subsection{LDAP and \modvcardldap{}} +\label{sec:ldap} +\ind{modules!\modvcardldap{}}\ind{JUD}\ind{Jabber User Directory}\ind{vCard}\ind{protocols!JEP-0054: vcard-temp} + + +\subsubsection{Features} +\label{sec:ldapfeatures} + +\ejabberd{} has built-in LDAP support. You can authenticate users against LDAP +server and use LDAP directory as vCard storage. Shared rosters are not +supported yet. + + +\subsubsection{Connection} +\label{sec:ldapconnection} + +Parameters: + +\begin{description} +\titem{ldap\_server} \ind{options!ldap_server}IP address or dns name of your +LDAP server. This option is required. +\titem{ldap\_port} \ind{options!ldap_port}Port to connect to LDAP server. +Default is~389. +\titem{ldap\_rootdn} \ind{options!ldap_rootdn}Bind DN. Default is~\term{""} +which means anonymous connection. +\titem{ldap\_password} \ind{options!ldap_password}Bind password. Default +is~\term{""}. +\end{description} + +Example: +\begin{verbatim} + {auth_method, ldap}. + {ldap_servers, ["ldap.mydomain.org"]}. + {ldap_port, 389}. + {ldap_rootdn, "cn=Manager,dc=domain,dc=org"}. + {ldap_password, "secret"}. +\end{verbatim} + +Note that current LDAP implementation doesn't support SSL connection and SASL +authentication. + + +\subsubsection{Authentication} +\label{sec:ldapauthentication} + +You can authenticate users against LDAP directory. Available parameters are +listed below: + +\begin{description} +\titem{ldap\_base} \ind{options!ldap_base}LDAP base directory which stores users +accounts. This option is required. +\titem{ldap\_uidattr} \ind{options!ldap_uidattr}LDAP attribute which holds +user's part of JID. Default is \term{"uid"}. +\titem{ldap\_uidattr\_format} \ind{options!ldap_uidattr_format}Format of the +\term{ldap\_uidattr} variable. Format MUST contain one and only one pattern +variable \term{"\%u"} which will be replaced by user's part of JID. For example, +\term{"\%u@mydomain.org"}. Default value is \term{"\%u"}. +\titem{ldap\_filter} \ind{options!ldap_filter}RFC 2254 LDAP filter. Default is +\term{none}. Example: \term{"(\&(objectClass=shadowAccount)(memberOf=Jabber + Users))"}. Please, don't forget closing brackets and don't use superfluous +whitespaces. Also you MUST NOT use \option{ldap\_uidattr} attribute in filter +because this attribute will be substituted in LDAP filter automatically. +\end{description} + + +\subsubsection{vCards and Search} +\label{sec:modvcardldap} + +\ejabberd{} can map LDAP attributes to vCard fields. This behaviour is +implemented in \modvcardldap{} module. This module doesn't depend on +authentication method. \modvcardldap{} module has it's own optional +parameters. The first group of parameters has the same meaning as top-level +LDAP parameters: \option{ldap\_servers}, \option{ldap\_port}, +\option{ldap\_rootdn}, \option{ldap\_password}, \option{ldap\_base}, +\option{ldap\_uidattr}, \option{ldap\_uidattr\_format} and +\option{ldap\_filter}. If one of this option is not set \ejabberd{} will look +for top-level option with the same name. The second group of parameters +consists of the following 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{hosts} 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{ldap\_vcard\_map} \ind{options!ldap_vcard_map}the table which defines +reflection of LDAP attributes to vCard fields. + Format is: + \term{[{Name\_of\_vcard\_field, Pattern, List\_of\_LDAP\_attributes}, ...]} + where + \term{Name\_of\_vcard\_field} is the type name of vCard as defined + in RFC 2426, + Pattern is a string which contains pattern variables \term{"\%u"}, \term{"\%d"} or \term{"\%s"}, + \term{List\_of\_LDAP\_attributes} is the list which contains of LDAP attributes. + 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 + user's part of JID and \term{"\%d"} will be replaced with domain part of JID. + Example: +\begin{verbatim} + {ldap_vcard_map, + [{"NICKNAME", "%u", []}, + {"FN", "%s", ["displayName"]}, + {"CTRY", "Russia", []}, + {"EMAIL", "%u@%d", []}, + {"DESC", "%s\n%s", ["title", "description"]} + ]}, +\end{verbatim} + +Default is: +\begin{verbatim} + [{"NICKNAME", "%u", []}, + {"FN", "%s", ["displayName"]}, + {"FAMILY", "%s", ["sn"]}, + {"GIVEN", "%s", ["givenName"]}, + {"MIDDLE", "%s", ["initials"]}, + {"ORGNAME", "%s", ["o"]}, + {"ORGUNIT", "%s", ["ou"]}, + {"CTRY", "%s", ["c"]}, + {"LOCALITY", "%s", ["l"]}, + {"STREET", "%s", ["street"]}, + {"REGION", "%s", ["st"]}, + {"PCODE", "%s", ["postalCode"]}, + {"TITLE", "%s", ["title"]}, + {"URL", "%s", ["labeleduri"]}, + {"DESC", "%s", ["description"]}, + {"TEL", "%s", ["telephoneNumber"]}, + {"EMAIL", "%s", ["mail"]}, + {"BDAY", "%s", ["birthDay"]}, + {"ROLE", "%s", ["employeeType"]}, + {"PHOTO", "%s", ["jpegPhoto"]}] +\end{verbatim} +\titem{ldap\_search\_fields} \ind{options!ldap_search_fields}This option defines +search form and LDAP attributes to search. + Format: + \term{[{Name, Attribute}, ...]} + where + \term{Name} is the name of field in the search form. Will be automatically + translated according to definitions in translation files (see + \term{msgs/*.msg} for available words). + Attribute is the LDAP attribute or the pattern \term{"\%u"} + Example: +\begin{verbatim} + {ldap_search_fields, + [{"User", "uid"}, + {"Full Name", "displayName"}, + {"Email", "mail"} + ]}, +\end{verbatim} + +Default is: +\begin{verbatim} + [{"User", "%u"}, + {"Full Name", "displayName"}, + {"Given Name", "givenName"}, + {"Middle Name", "initials"}, + {"Family Name", "sn"}, + {"Nickname", "%u"}, + {"Birthday", "birthDay"}, + {"Country", "c"}, + {"City", "l"}, + {"Email", "mail"}, + {"Organization Name", "o"}, + {"Organization Unit", "ou"}] +\end{verbatim} +\titem{ldap\_search\_reported} \ind{options!ldap_search_reported}This option defines search fields to be reported. + Format: + \term{[{Name, VCard\_Name}, ...]} + where + \term{Name} is the name of field in the search form. Will be automatically + translated according to definitions in translation files (see + \term{msgs/*.msg} for available words). + \term{VCard\_Name} is the name of vCard field defined in \option{ldap\_vcard\_map} option. + Example: +\begin{verbatim} + {ldap_search_reported, + [{"Full Name", "FN"}, + {"Email", "EMAIL"}, + {"Birthday", "BDAY"}, + {"Nickname", "NICKNAME"} + ]}, +\end{verbatim} + +Default is: +\begin{verbatim} + [{"Full Name", "FN"}, + {"Given Name", "GIVEN"}, + {"Middle Name", "MIDDLE"}, + {"Family Name", "FAMILY"}, + {"Nickname", "NICKNAME"}, + {"Birthday", "BDAY"}, + {"Country", "CTRY"}, + {"City", "LOCALITY"}, + {"Email", "EMAIL"}, + {"Organization Name", "ORGNAME"}, + {"Organization Unit", "ORGUNIT"}] +\end{verbatim} +\end{description} + + +\subsubsection{Examples} +\label{sec:ldapexamples} + +\paragraph{Common example} + +Let's say \term{ldap.mydomain.org} is the name of our LDAP server. We have +users with their passwords in \term{"ou=Users,dc=mydomain,dc=org"} directory. +Also we have addressbook, which contains users emails and their additional +infos in \term{"ou=AddressBook,dc=mydomain,dc=org"} directory. Corresponding +authentication section should looks like this: + +\begin{verbatim} + %% authentication method + {auth_method, ldap}. + %% DNS name of our LDAP server + {ldap_servers, ["ldap.mydomain.org"]}. + %% Bind to LDAP server as "cn=Manager,dc=mydomain,dc=org" with password "secret" + {ldap_rootdn, "cn=Manager,dc=mydomain,dc=org"}. + {ldap_password, "secret"}. + %% define the user's base + {ldap_base, "ou=Users,dc=mydomain,dc=org"}. + %% We want to authorize users from 'shadowAccount' object class only + {ldap_filter, "(objectClass=shadowAccount)"}. +\end{verbatim} + +Now we want to use users LDAP-info as their vCards. We have four attributes +defined in our LDAP schema: \term{"mail"} --- email address, \term{"givenName"} +--- first name, \term{"sn"} --- second name, \term{"birthDay"} --- birthday. +Also we want users to search each other. Let's see how we can set it up: + +\begin{verbatim} + {modules, + ... + {mod_vcard_ldap, + [ + %% We use the same server and port, but want to bind anonymously because + %% our LDAP server accepts anonymous requests to + %% "ou=AddressBook,dc=mydomain,dc=org" subtree. + {ldap_rootdn, ""}, + {ldap_password, ""}, + %% define the addressbook's base + {ldap_base, "ou=AddressBook,dc=mydomain,dc=org"}, + %% user's part of JID is located in the "mail" attribute + {ldap_uidattr, "mail"}, + %% common format for our emails + {ldap_uidattr_format, "%u@mail.mydomain.org"}, + %% We have to define empty filter here, because entries in addressbook doesn't + %% belong to shadowAccount object class + {ldap_filter, ""}, + %% Now we want to define vCard pattern + {ldap_vcard_map, + [{"NICKNAME", "%u", []}, % just use user's part of JID as his nickname + {"GIVEN", "%s", ["givenName"]}, + {"FAMILY", "%s", ["sn"]}, + {"FN", "%s, %s", ["sn", "givenName"]}, % example: "Smith, John" + {"EMAIL", "%s", ["mail"]}, + {"BDAY", "%s", ["birthDay"]}]}, + %% Search form + {ldap_search_fields, + [{"User", "%u"}, + {"Name", "givenName"}, + {"Family Name", "sn"}, + {"Email", "mail"}, + {"Birthday", "birthDay"}]}, + %% vCard fields to be reported + %% Note that JID is always returned with search results + {ldap_search_reported, + [{"Full Name", "FN"}, + {"Nickname", "NICKNAME"}, + {"Birthday", "BDAY"}]} + ]} + ... + }. +\end{verbatim} + +Note that \modvcardldap{} module checks an existence of the user before +searching his info in LDAP. + + +\paragraph{Active Directory} + +Active Directory is just an LDAP-server with predefined attributes. Sample +config file is listed below: + +\begin{verbatim} + {auth_method, ldap}. + {ldap_servers, ["office.org"]}. % List of LDAP servers + {ldap_base, "DC=office,DC=org"}. % Search base of LDAP directory + {ldap_rootdn, "CN=Administrator,CN=Users,DC=office,DC=org"}. % LDAP manager + {ldap_password, "*******"}. % Password to LDAP manager + {ldap_uidattr, "sAMAccountName"}. + {ldap_filter, "(memberOf=*)"}. + + {mod_vcard_ldap, + [{ldap_vcard_map, + [{"NICKNAME", "%u", []}, + {"GIVEN", "%s", ["givenName"]}, + {"MIDDLE", "%s", ["initials"]}, + {"FAMILY", "%s", ["sn"]}, + {"FN", "%s", ["displayName"]}, + {"EMAIL", "%s", ["mail"]}, + {"ORGNAME", "%s", ["company"]}, + {"ORGUNIT", "%s", ["department"]}, + {"CTRY", "%s", ["c"]}, + {"LOCALITY", "%s", ["l"]}, + {"STREET", "%s", ["streetAddress"]}, + {"REGION", "%s", ["st"]}, + {"PCODE", "%s", ["postalCode"]}, + {"TITLE", "%s", ["title"]}, + {"URL", "%s", ["wWWHomePage"]}, + {"DESC", "%s", ["description"]}, + {"TEL", "%s", ["telephoneNumber"]}]}, + {ldap_search_fields, + [{"User", "%u"}, + {"Name", "givenName"}, + {"Family Name", "sn"}, + {"Email", "mail"}, + {"Company", "company"}, + {"Department", "department"}, + {"Role", "title"}, + {"Description", "description"}, + {"Phone", "telephoneNumber"}]}, + {ldap_search_reported, + [{"Full Name", "FN"}, + {"Nickname", "NICKNAME"}, + {"Email", "EMAIL"}]} + ] + }. +\end{verbatim} + + \subsection{\modversion{}} \label{sec:modversion} \ind{modules!\modversion{}}\ind{protocols!JEP-0092: Software Version} -- cgit v1.2.3 From 8583e3f9be0ef2f7b7c66550b3028241a7574670 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20R=C3=A9mond?= Date: Fri, 22 Sep 2006 08:42:41 +0000 Subject: Bugfixes coming from trunk (SVN #607): * doc/guide.tex: Minor fix on index generation. SVN Revision: 616 --- doc/guide.tex | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'doc/guide.tex') diff --git a/doc/guide.tex b/doc/guide.tex index ae37b8d04..c9443da5c 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -2310,13 +2310,13 @@ supported yet. Parameters: \begin{description} -\titem{ldap\_server} \ind{options!ldap_server}IP address or dns name of your +\titem{ldap\_server} \ind{options!ldap\_server}IP address or dns name of your LDAP server. This option is required. -\titem{ldap\_port} \ind{options!ldap_port}Port to connect to LDAP server. +\titem{ldap\_port} \ind{options!ldap\_port}Port to connect to LDAP server. Default is~389. -\titem{ldap\_rootdn} \ind{options!ldap_rootdn}Bind DN. Default is~\term{""} +\titem{ldap\_rootdn} \ind{options!ldap\_rootdn}Bind DN. Default is~\term{""} which means anonymous connection. -\titem{ldap\_password} \ind{options!ldap_password}Bind password. Default +\titem{ldap\_password} \ind{options!ldap\_password}Bind password. Default is~\term{""}. \end{description} @@ -2340,15 +2340,15 @@ You can authenticate users against LDAP directory. Available parameters are listed below: \begin{description} -\titem{ldap\_base} \ind{options!ldap_base}LDAP base directory which stores users +\titem{ldap\_base} \ind{options!ldap\_base}LDAP base directory which stores users accounts. This option is required. -\titem{ldap\_uidattr} \ind{options!ldap_uidattr}LDAP attribute which holds +\titem{ldap\_uidattr} \ind{options!ldap\_uidattr}LDAP attribute which holds user's part of JID. Default is \term{"uid"}. -\titem{ldap\_uidattr\_format} \ind{options!ldap_uidattr_format}Format of the +\titem{ldap\_uidattr\_format} \ind{options!ldap\_uidattr\_format}Format of the \term{ldap\_uidattr} variable. Format MUST contain one and only one pattern variable \term{"\%u"} which will be replaced by user's part of JID. For example, \term{"\%u@mydomain.org"}. Default value is \term{"\%u"}. -\titem{ldap\_filter} \ind{options!ldap_filter}RFC 2254 LDAP filter. Default is +\titem{ldap\_filter} \ind{options!ldap\_filter}RFC 2254 LDAP filter. Default is \term{none}. Example: \term{"(\&(objectClass=shadowAccount)(memberOf=Jabber Users))"}. Please, don't forget closing brackets and don't use superfluous whitespaces. Also you MUST NOT use \option{ldap\_uidattr} attribute in filter @@ -2378,7 +2378,7 @@ consists of the following options: (value: \term{false}). If disabled, the option \term{hosts} 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{ldap\_vcard\_map} \ind{options!ldap_vcard_map}the table which defines +\titem{ldap\_vcard\_map} \ind{options!ldap\_vcard\_map}the table which defines reflection of LDAP attributes to vCard fields. Format is: \term{[{Name\_of\_vcard\_field, Pattern, List\_of\_LDAP\_attributes}, ...]} @@ -2424,7 +2424,7 @@ Default is: {"ROLE", "%s", ["employeeType"]}, {"PHOTO", "%s", ["jpegPhoto"]}] \end{verbatim} -\titem{ldap\_search\_fields} \ind{options!ldap_search_fields}This option defines +\titem{ldap\_search\_fields} \ind{options!ldap\_search\_fields}This option defines search form and LDAP attributes to search. Format: \term{[{Name, Attribute}, ...]} @@ -2457,7 +2457,7 @@ Default is: {"Organization Name", "o"}, {"Organization Unit", "ou"}] \end{verbatim} -\titem{ldap\_search\_reported} \ind{options!ldap_search_reported}This option defines search fields to be reported. +\titem{ldap\_search\_reported} \ind{options!ldap\_search\_reported}This option defines search fields to be reported. Format: \term{[{Name, VCard\_Name}, ...]} where -- cgit v1.2.3 From 1632aec61e84630085268d26f5bc39e34c2465fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20R=C3=A9mond?= Date: Fri, 22 Sep 2006 09:16:31 +0000 Subject: Improvement coming from trunk (SVN #617): * doc/guide.tex: Large improvements for ejabberd 1.1.2 (thanks to Sander Devrieze) * doc/version.tex: Likewise. * doc/features.tex: Likewise. * doc/Makefile: Likewise. * doc/dev.tex: Likewise. SVN Revision: 618 --- doc/guide.tex | 2622 +++++++++++++++++++++++++++++++++------------------------ 1 file changed, 1514 insertions(+), 1108 deletions(-) (limited to 'doc/guide.tex') diff --git a/doc/guide.tex b/doc/guide.tex index c9443da5c..468f7143d 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -78,10 +78,15 @@ the processing discipline for #1 IQ queries \newcommand{\hostitem}[1]{ \titem{hosts} \ind{options!hosts} This option defines the hostnames of the service (see section~\ref{sec:modhostsoption}). If neither \texttt{hosts} nor - the old \texttt{host} is present, the prefix ``\jid{#1.}'' is added to all + the old \texttt{host} is present, the prefix `\jid{#1.}' is added to all \ejabberd{} hostnames. } +%\newcommand{\quoting}[2][yozhik]{\begin{quotation}\textcolor{#1}{\textit{#2}}\end{quotation}} % Quotes enabled +%\renewcommand{command}[args][default]{def} +%\renewcommand{\headrule}{{\color{ejblue}% +%\hrule width\headwidth height\headrulewidth \vskip-\headrulewidth}} + %% Title page \include{version} \title{Ejabberd \version\ Installation and Operation Guide} @@ -92,9 +97,11 @@ the processing discipline for #1 IQ queries %% Options \newcommand{\marking}[1]{#1} % Marking disabled \newcommand{\quoting}[2][yozhik]{} % Quotes disabled -\newcommand{\new}{\begin{latexonly}\marginpar{\textsc{new}}\end{latexonly}} % Highlight new features -\newcommand{\improved}{\begin{latexonly}\marginpar{\textsc{improved}}\end{latexonly}} % Highlight improved features -\newcommand{\moreinfo}[1]{} % Hide details +\newcommand{\new}{\marginpar{\textsc{new}}} % Highlight new features +\newcommand{\improved}{\marginpar{\textsc{improved}}} % Highlight improved features + +%% To by-pass errors in the HTML version. +\newstyle{SPAN}{width:20\%; float:right; text-align:left; margin-left:auto;} %% Footnotes \begin{latexonly} @@ -108,7 +115,7 @@ the processing discipline for #1 IQ queries \begin{document} -\label{sec:titlepage} +\label{titlepage} \begin{titlepage} \maketitle{} @@ -118,7 +125,7 @@ the processing discipline for #1 IQ queries } \end{center} - \begin{quotation}\textit{I can thoroughly recommend ejabberd for ease of setup -- + \begin{quotation}\textit{I can thoroughly recommend ejabberd for ease of setup --- Kevin Smith, Current maintainer of the Psi project}\end{quotation} \end{titlepage} @@ -135,31 +142,30 @@ the processing discipline for #1 IQ queries % Input introduction.tex \input{introduction} -\section{Installation from Source} -\label{sec:installation} +\section{\aname{installsource}{Installation from Source}} +\label{sec:installsource} \ind{installation} -\subsection{Installation Requirements} +\subsection{\aname{installreq}{Installation Requirements}} \label{sec:installreq} +\ind{installation!requirements} -\subsubsection{``Unix-like'' operating systems} +\subsubsection{\aname{installrequnix}{`Unix-like' operating systems}} \label{sec:installrequnix} -\ind{installation!requirements for ``Unix-like'' operating systems} -To compile \ejabberd{} on a ``Unix-like'' operating system, you need: +To compile \ejabberd{} on a `Unix-like' operating system, you need: \begin{itemize} -\item GNU Make; -\item GCC; -\item libexpat 1.95 or higher; -\item Erlang/OTP R9C-2 or higher; -\item OpenSSL 0.9.6 or higher (optional). -\item Zlib 1.2.3 or higher (optional). -\item GNU Iconv 1.8 or higher (optional, not needed at all on systems with GNU libc). +\item GNU Make +\item GCC +\item libexpat 1.95 or higher +\item Erlang/OTP R9C-2 or higher +\item OpenSSL 0.9.6 or higher (optional) +\item Zlib 1.2.3 or higher (optional) +\item GNU Iconv 1.8 or higher (optional, not needed on systems with GNU libc) \end{itemize} -\subsubsection{Windows} +\subsubsection{\aname{installreqwin}{Windows}} \label{sec:installreqwin} -\ind{installation!requirements for Windows} To compile \ejabberd{} on a Windows flavour, you need: \begin{itemize} @@ -174,7 +180,7 @@ To compile \ejabberd{} on a Windows flavour, you need: \item \footahref{http://www.zlib.net/}{Zlib 1.2.3 or higher} \end{itemize} -\subsection{Obtaining \ejabberd{}} +\subsection{\aname{obtaining}{Obtaining \ejabberd{}}} \label{sec:obtaining} \ind{download} @@ -187,15 +193,14 @@ The latest development version can be retrieved from the Subversion repository\@ svn co http://svn.process-one.net/ejabberd/trunk ejabberd \end{verbatim} -\subsection{Compilation} -\label{sec:compilation} -\ind{compilation} +\subsection{\aname{compile}{Compilation}} +\label{sec:compile} +\ind{installation!compilation} -\subsubsection{``Unix-like'' operating systems} -\label{sec:compilationunix} -\ind{compilation!on ``Unix-like'' operating systems} +\subsubsection{\aname{compileunix}{`Unix-like' operating systems}} +\label{sec:compileunix} -Compile \ejabberd{} on a ``Unix-like'' operating system by executing: +Compile \ejabberd{} on a `Unix-like' operating system by executing: \begin{verbatim} ./configure @@ -211,9 +216,12 @@ These commands will: \item create a directory called \verb|/var/log/ejabberd| to store log files. \end{itemize} -\subsubsection{Windows} -\label{sec:compilationwin} -\ind{compilation!on Windows} +Note: if you want to use an external database, you need to execute the configure +script with the option(s) \term{--enable-odbc} or \term{--enable-odbc +--enable-mssql}. See section~\ref{sec:database} for more information. + +\subsubsection{\aname{compilewin}{Windows}} +\label{sec:compilewin} \begin{itemize} \item Install Erlang emulator (for example, into \verb|C:\Program Files\erl5.3|). @@ -246,9 +254,12 @@ werl -s ejabberd -name ejabberd \end{verbatim} \end{itemize} -\subsection{Starting} -\label{sec:starting} +%TODO: how to compile database support on windows? + +\subsection{\aname{start}{Starting}} +\label{sec:start} \ind{starting} +%TODO: update when the ejabberdctl script is made more userfriendly Execute the following command to start \ejabberd{}: \begin{verbatim} @@ -259,7 +270,7 @@ or erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd \end{verbatim} In the latter case the Erlang node will be identified using only the first part -of the host name, i.\,e. other Erlang nodes outside this domain can't contact +of the host name, i.\,e. other Erlang nodes outside this domain cannot contact this node. Note that when using the above command, \ejabberd{} will search for the @@ -297,11 +308,8 @@ To reduce memory usage, you may set the environment variable But in this case \ejabberd{} can start to work slower. -\section{Configuration} -\label{sec:configuration} - -\subsection{Initial Configuration} -\label{sec:initconfig} +\section{\aname{basicconfig}{Basic Configuration}} +\label{sec:basicconfig} \ind{configuration file} The configuration file will be loaded the first time you start \ejabberd{}. The @@ -311,7 +319,7 @@ configuration file are appended to the entries in the database. The configuration file contains a sequence of Erlang terms. Lines beginning with a \term{`\%'} sign are ignored. Each term is a tuple of which the first element is 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 +configuration file do not contain for instance the `hosts' option, the old host name(s) stored in the database will be used. @@ -325,8 +333,8 @@ the configuration file: With these lines the old global options, local options and ACLs will be removed before new ones are added. -\subsubsection{Host Names} -\label{sec:confighostname} +\subsection{\aname{hostnames}{Host Names}} +\label{sec:hostnames} \ind{options!hosts}\ind{host names} The option \option{hosts} defines a list containing one or more domains that @@ -335,191 +343,64 @@ The option \option{hosts} defines a list containing one or more domains that Examples: \begin{itemize} \item Serving one domain: -\begin{itemize} -\item \begin{verbatim} + \begin{verbatim} {hosts, ["example.org"]}. \end{verbatim} -\item Backwards compatibility with older \ejabberd{} versions can be retained - with: +\item Serving one domain, and backwards compatible with older \ejabberd{} + versions: \begin{verbatim} {host, "example.org"}. \end{verbatim} -\end{itemize} \item Serving two domains: \begin{verbatim} {hosts, ["example.net", "example.com"]}. \end{verbatim} \end{itemize} -\subsubsection{Default Language} -\label{sec:configlanguage} -\ind{options!language}\ind{language} - -The option \option{language} defines the default language of server strings that -can be seen by \Jabber{} clients. If a \Jabber{} client do not support -\option{xml:lang}, the specified language is used. The default value for the -option \option{language} is \term{"en"}. In order to take effect there must be a -translation file \term{.msg} in \ejabberd{}'s \term{msgs} directory. - -Examples: -\begin{itemize} -\item To set Russian as default language: -\begin{verbatim} - {language, "ru"}. -\end{verbatim} -\item To set Spanish as default language: -\begin{verbatim} - {language, "es"}. -\end{verbatim} -\end{itemize} - -\subsubsection{Access Rules} -\label{sec:configaccess} -\ind{options!acl}\ind{access rules}\ind{ACL}\ind{Access Control List} - -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, , {, ...}}. -\end{verbatim} - -\term{} can be one of the following: -\begin{description} -\titem{all} Matches all JIDs. Example: -\begin{verbatim} -{acl, all, all}. -\end{verbatim} -\titem{\{user, \}} Matches the user with the name - \term{} at the first virtual host. Example: -\begin{verbatim} -{acl, admin, {user, "yozhik"}}. -\end{verbatim} -\titem{\{user, , \}} Matches the user with the JID - \term{@} and any resource. Example: -\begin{verbatim} -{acl, admin, {user, "yozhik", "example.org"}}. -\end{verbatim} -\titem{\{server, \}} Matches any JID from server - \term{}. Example: -\begin{verbatim} -{acl, exampleorg, {server, "example.org"}}. -\end{verbatim} -\titem{\{user\_regexp, \}} Matches any local user with a name that - matches \term{} at the first virtual host. Example: -\begin{verbatim} -{acl, tests, {user, "^test[0-9]*$"}}. -\end{verbatim} -%$ -\titem{\{user\_regexp, , \}} Matches any user with a name - that matches \term{} at server \term{}. Example: -\begin{verbatim} -{acl, tests, {user, "^test", "example.org"}}. -\end{verbatim} -\titem{\{server\_regexp, \}} Matches any JID from the server that - matches \term{}. Example: -\begin{verbatim} -{acl, icq, {server, "^icq\\."}}. -\end{verbatim} -\titem{\{node\_regexp, , \}} Matches any user - with a name that matches \term{} at any server that matches - \term{}. Example: -\begin{verbatim} -{acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}. -\end{verbatim} -\titem{\{user\_glob, \}} -\titem{\{user\_glob, , \}} -\titem{\{server\_glob, \}} -\titem{\{node\_glob, , \}} 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} - \titem{*} matches any string including the null string. - \titem{?} matches any single character. - \titem{[...]} matches any of the enclosed characters. Character - ranges are specified by a pair of characters separated by a \term{`-'}. - If the first character after \term{`['} is a \term{`!'}, any - character not enclosed is matched. - \end{description} -\end{description} - -The following ACLs are pre-defined: -\begin{description} -\titem{all} Matches any JID. -\titem{none} Matches no JID. -\end{description} - -An entry allowing or denying access to different services looks similar to -this: -\begin{verbatim} - {access, , [{allow, }, - {deny, }, - ... - ]}. -\end{verbatim} -When a JID is checked to have access to \term{}, the server -sequentially checks if that JID mathes 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 ``\term{deny}'' is returned. - -Example: -\begin{verbatim} - {access, configure, [{allow, admin}]}. - {access, something, [{deny, badmans}, - {allow, all}]}. -\end{verbatim} - -The following access rules are pre-defined: -\begin{description} -\titem{all} Always returns ``\term{allow}'' -\titem{none} Always returns ``\term{deny}'' -\end{description} - -\subsubsection{Shapers} -\label{sec:configshaper} -\ind{options!shaper}\ind{options!maxrate}\ind{shapers}\ind{maxrate}\ind{traffic speed} +\subsection{\aname{virtualhost}{Virtual Hosting}} +\label{sec:virtualhost} +\ind{virtual hosting}\ind{virtual hosts}\ind{virtual domains} -Shapers enable you to limit connection traffic. The syntax of -shapers is like this: -\begin{verbatim} - {shaper, , }. -\end{verbatim} -Currently only one kind of shaper called \term{maxrate} is available. It has the -following syntax: +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} - {maxrate, } + {host_config, , [