diff options
Diffstat (limited to 'doc/dev.tex')
| -rw-r--r-- | doc/dev.tex | 470 |
1 files changed, 0 insertions, 470 deletions
diff --git a/doc/dev.tex b/doc/dev.tex deleted file mode 100644 index 4e63b95ce..000000000 --- a/doc/dev.tex +++ /dev/null @@ -1,470 +0,0 @@ -\documentclass[a4paper,10pt]{article} - -%% Packages -\usepackage{graphics} -\usepackage{hevea} -\usepackage{makeidx} -\usepackage{verbatim} - -%% Index -\makeindex -% Remove the index anchors from the HTML version to save size and bandwith. -\newcommand{\ind}[1]{\begin{latexonly}\index{#1}\end{latexonly}} - -%% Images -\newcommand{\logoscale}{0.7} -\newcommand{\imgscale}{0.58} -\newcommand{\insimg}[1]{\insscaleimg{\imgscale}{#1}} -\newcommand{\insscaleimg}[2]{ - \imgsrc{#2}{} - \begin{latexonly} - \scalebox{#1}{\includegraphics{#2}} - \end{latexonly} -} - -%% Various -\newcommand{\ns}[1]{\texttt{#1}} -\newcommand{\ejabberd}{\texttt{ejabberd}} -\newcommand{\Jabber}{Jabber} -\newcommand{\XMPP}{XMPP} - -%% Modules -\newcommand{\module}[1]{\texttt{#1}} -\newcommand{\modadhoc}{\module{mod\_adhoc}} -\newcommand{\modannounce}{\module{mod\_announce}} -\newcommand{\modconfigure}{\module{mod\_configure}} -\newcommand{\moddisco}{\module{mod\_disco}} -\newcommand{\modecho}{\module{mod\_echo}} -\newcommand{\modirc}{\module{mod\_irc}} -\newcommand{\modlast}{\module{mod\_last}} -\newcommand{\modlastodbc}{\module{mod\_last\_odbc}} -\newcommand{\modmuc}{\module{mod\_muc}} -\newcommand{\modmuclog}{\module{mod\_muc\_log}} -\newcommand{\modoffline}{\module{mod\_offline}} -\newcommand{\modofflineodbc}{\module{mod\_offline\_odbc}} -\newcommand{\modprivacy}{\module{mod\_privacy}} -\newcommand{\modprivate}{\module{mod\_private}} -\newcommand{\modpubsub}{\module{mod\_pubsub}} -\newcommand{\modregister}{\module{mod\_register}} -\newcommand{\modroster}{\module{mod\_roster}} -\newcommand{\modrosterodbc}{\module{mod\_roster\_odbc}} -\newcommand{\modservicelog}{\module{mod\_service\_log}} -\newcommand{\modsharedroster}{\module{mod\_shared\_roster}} -\newcommand{\modstats}{\module{mod\_stats}} -\newcommand{\modtime}{\module{mod\_time}} -\newcommand{\modvcard}{\module{mod\_vcard}} -\newcommand{\modvcardldap}{\module{mod\_vcard\_ldap}} -\newcommand{\modvcardodbc}{\module{mod\_vcard\_odbc}} -\newcommand{\modversion}{\module{mod\_version}} - -%% Title page -\include{version} -\title{Ejabberd \version\ Developers Guide} -\author{Alexey Shchepin \\ - \ahrefurl{mailto:alexey@sevcom.net} \\ - \ahrefurl{xmpp:aleksey@jabber.ru}} - -%% 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 - -%% Footnotes -\newcommand{\txepref}[2]{\footahref{http://www.xmpp.org/extensions/xep-#1.html}{#2}} -\newcommand{\xepref}[1]{\txepref{#1}{XEP-#1}} - -\begin{document} - -\label{titlepage} -\begin{titlepage} - \maketitle{} - - \begin{center} - {\insscaleimg{\logoscale}{logo.png} - \par - } - \end{center} - - \begin{quotation}\textit{I can thoroughly recommend ejabberd for ease of setup -- - Kevin Smith, Current maintainer of the Psi project}\end{quotation} - -\end{titlepage} - -\tableofcontents{} - -% Input introduction.tex -\input{introduction} - -\section{How it Works} -\label{howitworks} - - -A \XMPP{} 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 -\texttt{\~{}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 - - - -Each \ejabberd{} node have following modules: -\begin{itemize} -\item router; -\item local router. -\item session manager; -\item S2S manager; -\end{itemize} - - -\subsection{Router} - -This module is the main router of \XMPP{} packets on each node. It routes -them based on their destinations domains. It has two tables: local and global -routes. First, domain of packet destination searched in local table, and if it -found, then the packet is routed to appropriate process. If no, then it -searches in global table, and is routed to the appropriate \ejabberd{} node or -process. If it does not exists in either tables, then it sent to the S2S -manager. - - -\subsection{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 -session manager, else it is processed depending on it's content. - - -\subsection{Session Manager} - -This module routes packets to local users. It searches for what user resource -packet must be sent via presence table. If this resource is connected to -this node, it is routed to C2S process, if it connected via another node, then -the packet is sent to session manager on that node. - - -\subsection{S2S Manager} - -This module routes packets to other \XMPP{} servers. First, it checks if an -open S2S connection from the domain of the packet source to the domain of -packet destination already exists. If it is open on another node, then it -routes the packet to S2S manager on that node, if it is open on this node, then -it is routed to the process that serves this connection, and if a connection -does not exist, then it is opened and registered. - - -\section{Authentication} - -\subsubsection{External} -\label{externalauth} -\ind{external authentication} - -The external authentication script follows -\footahref{http://www.erlang.org/doc/tutorial/c_portdriver.html}{the erlang port driver API}. - -That script is supposed to do theses actions, in an infinite loop: -\begin{itemize} -\item read from stdin: AABBBBBBBBB..... - \begin{itemize} - \item A: 2 bytes of length data (a short in network byte order) - \item B: a string of length found in A that contains operation in plain text - operation are as follows: - \begin{itemize} - \item auth:User:Server:Password (check if a username/password pair is correct) - \item isuser:User:Server (check if it's a valid user) - \item setpass:User:Server:Password (set user's password) - \item tryregister:User:Server:Password (try to register an account) - \item removeuser:User:Server (remove this account) - \item removeuser3:User:Server:Password (remove this account if the password is correct) - \end{itemize} - \end{itemize} -\item write to stdout: AABB - \begin{itemize} - \item A: the number 2 (coded as a short, which is bytes length of following result) - \item B: the result code (coded as a short), should be 1 for success/valid, or 0 for failure/invalid - \end{itemize} -\end{itemize} - -Example python script -\begin{verbatim} -#!/usr/bin/python - -import sys -from struct import * - -def from_ejabberd(): - input_length = sys.stdin.read(2) - (size,) = unpack('>h', input_length) - return sys.stdin.read(size).split(':') - -def to_ejabberd(bool): - answer = 0 - if bool: - answer = 1 - token = pack('>hh', 2, answer) - sys.stdout.write(token) - sys.stdout.flush() - -def auth(username, server, password): - return True - -def isuser(username, server): - return True - -def setpass(username, server, password): - return True - -while True: - data = from_ejabberd() - success = False - if data[0] == "auth": - success = auth(data[1], data[2], data[3]) - elif data[0] == "isuser": - success = isuser(data[1], data[2]) - elif data[0] == "setpass": - success = setpass(data[1], data[2], data[3]) - to_ejabberd(success) -\end{verbatim} - -\section{XML Representation} -\label{xmlrepr} - -Each XML stanza is represented as the following tuple: -\begin{verbatim} -XMLElement = {xmlelement, Name, Attrs, [ElementOrCDATA]} - Name = string() - Attrs = [Attr] - Attr = {Key, Val} - Key = string() - Val = string() - ElementOrCDATA = XMLElement | CDATA - CDATA = {xmlcdata, string()} -\end{verbatim} -E.\,g. this stanza: -\begin{verbatim} -<message to='test@conference.example.org' type='groupchat'> - <body>test</body> -</message> -\end{verbatim} -is represented as the following structure: -\begin{verbatim} -{xmlelement, "message", - [{"to", "test@conference.example.org"}, - {"type", "groupchat"}], - [{xmlelement, "body", - [], - [{xmlcdata, "test"}]}]}} -\end{verbatim} - - - -\section{Module \texttt{xml}} -\label{xmlmod} - -\begin{description} -\item{\verb|element_to_string(El) -> string()|} -\begin{verbatim} -El = XMLElement -\end{verbatim} - Returns string representation of XML stanza \texttt{El}. - -\item{\verb|crypt(S) -> string()|} -\begin{verbatim} -S = string() -\end{verbatim} - Returns string which correspond to \texttt{S} with encoded XML special - characters. - -\item{\verb|remove_cdata(ECList) -> EList|} -\begin{verbatim} -ECList = [ElementOrCDATA] -EList = [XMLElement] -\end{verbatim} - \texttt{EList} is a list of all non-CDATA elements of ECList. - - - -\item{\verb|get_path_s(El, Path) -> Res|} -\begin{verbatim} -El = XMLElement -Path = [PathItem] -PathItem = PathElem | PathAttr | PathCDATA -PathElem = {elem, Name} -PathAttr = {attr, Name} -PathCDATA = cdata -Name = string() -Res = string() | XMLElement -\end{verbatim} - If \texttt{Path} is empty, then returns \texttt{El}. Else sequentially - consider elements of \texttt{Path}. Each element is one of: - \begin{description} - \item{\verb|{elem, Name}|} \texttt{Name} is name of subelement of - \texttt{El}, if such element exists, then this element considered in - following steps, else returns empty string. - \item{\verb|{attr, Name}|} If \texttt{El} have attribute \texttt{Name}, then - returns value of this attribute, else returns empty string. - \item{\verb|cdata|} Returns CDATA of \texttt{El}. - \end{description} - -\item{TODO:} -\begin{verbatim} - get_cdata/1, get_tag_cdata/1 - get_attr/2, get_attr_s/2 - get_tag_attr/2, get_tag_attr_s/2 - get_subtag/2 -\end{verbatim} -\end{description} - - -\section{Module \texttt{xml\_stream}} -\label{xmlstreammod} - -\begin{description} -\item{\verb!parse_element(Str) -> XMLElement | {error, Err}!} -\begin{verbatim} -Str = string() -Err = term() -\end{verbatim} - Parses \texttt{Str} using XML parser, returns either parsed element or error - tuple. -\end{description} - - -\section{Modules} -\label{emods} - - -%\subsection{gen\_mod behaviour} -%\label{genmod} - -%TBD - -\subsection{Module gen\_iq\_handler} -\label{geniqhandl} - -The module \verb|gen_iq_handler| allows to easily write handlers for IQ packets -of particular XML namespaces that addressed to server or to users bare JIDs. - -In this module the following functions are defined: -\begin{description} -\item{\verb|add_iq_handler(Component, Host, NS, Module, Function, Type)|} -\begin{verbatim} -Component = Module = Function = atom() -Host = NS = string() -Type = no_queue | one_queue | parallel -\end{verbatim} - Registers function \verb|Module:Function| as handler for IQ packets on - virtual host \verb|Host| that contain child of namespace \verb|NS| in - \verb|Component|. Queueing discipline is \verb|Type|. There are at least - two components defined: - \begin{description} - \item{\verb|ejabberd_local|} Handles packets that addressed to server JID; - \item{\verb|ejabberd_sm|} Handles packets that addressed to users bare JIDs. - \end{description} -\item{\verb|remove_iq_handler(Component, Host, NS)|} -\begin{verbatim} -Component = atom() -Host = NS = string() -\end{verbatim} - Removes IQ handler on virtual host \verb|Host| for namespace \verb|NS| from - \verb|Component|. -\end{description} - -Handler function must have the following type: -\begin{description} -\item{\verb|Module:Function(From, To, IQ)|} -\begin{verbatim} -From = To = jid() -\end{verbatim} -\end{description} - - - -\begin{verbatim} --module(mod_cputime). - --behaviour(gen_mod). - --export([start/2, - stop/1, - process_local_iq/3]). - --include("ejabberd.hrl"). --include("jlib.hrl"). - --define(NS_CPUTIME, "ejabberd:cputime"). - -start(Host, Opts) -> - IQDisc = gen_mod:get_opt(iqdisc, Opts, one_queue), - gen_iq_handler:add_iq_handler(ejabberd_local, Host, ?NS_CPUTIME, - ?MODULE, process_local_iq, IQDisc). - -stop(Host) -> - gen_iq_handler:remove_iq_handler(ejabberd_local, Host, ?NS_CPUTIME). - -process_local_iq(From, To, {iq, ID, Type, XMLNS, SubEl}) -> - case Type of - set -> - {iq, ID, error, XMLNS, - [SubEl, ?ERR_NOT_ALLOWED]}; - get -> - CPUTime = element(1, erlang:statistics(runtime))/1000, - SCPUTime = lists:flatten(io_lib:format("~.3f", CPUTime)), - {iq, ID, result, XMLNS, - [{xmlelement, "query", - [{"xmlns", ?NS_CPUTIME}], - [{xmlelement, "cputime", [], [{xmlcdata, SCPUTime}]}]}]} - end. -\end{verbatim} - - -\subsection{Services} -\label{services} - -%TBD - - -%TODO: use \verb|proc_lib| -\begin{verbatim} --module(mod_echo). - --behaviour(gen_mod). - --export([start/2, init/1, stop/1]). - --include("ejabberd.hrl"). --include("jlib.hrl"). - -start(Host, Opts) -> - MyHost = gen_mod:get_opt(host, Opts, "echo." ++ Host), - register(gen_mod:get_module_proc(Host, ?PROCNAME), - spawn(?MODULE, init, [MyHost])). - -init(Host) -> - ejabberd_router:register_local_route(Host), - loop(Host). - -loop(Host) -> - receive - {route, From, To, Packet} -> - ejabberd_router:route(To, From, Packet), - loop(Host); - stop -> - ejabberd_router:unregister_route(Host), - ok; - _ -> - loop(Host) - end. - -stop(Host) -> - Proc = gen_mod:get_module_proc(Host, ?PROCNAME), - Proc ! stop, - {wait, Proc}. -\end{verbatim} - - - -\end{document} |