forked from processone/ejabberd
-
Notifications
You must be signed in to change notification settings - Fork 0
/
guide.tex
6026 lines (5232 loc) · 243 KB
/
guide.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass[a4paper,10pt]{book}
%% Packages
\usepackage{float}
\usepackage{graphics}
\usepackage{hevea}
\usepackage[pdftex,colorlinks,unicode,urlcolor=blue,linkcolor=blue,
pdftitle=Ejabberd\ Installation\ and\ Operation\ Guide,pdfauthor=ProcessOne,pdfsubject=ejabberd,pdfkeywords=ejabberd,
pdfpagelabels=false]{hyperref}
\usepackage{makeidx}
%\usepackage{showidx} % Only for verifying the index entries.
\usepackage{verbatim}
\usepackage{geometry}
\usepackage{fancyhdr}
\pagestyle{fancy} %Forces the page to use the fancy template
\renewcommand{\chaptermark}[1]{\markboth{\textbf{\thechapter}.\ \emph{#1}}{}}
\renewcommand{\sectionmark}[1]{\markright{\thesection\ \boldmath\textbf{#1}\unboldmath}}
\fancyhf{}
\fancyhead[LE,RO]{\textbf{\thepage}} %Displays the page number in bold in the header,
% to the left on even pages and to the right on odd pages.
\fancyhead[RE]{\nouppercase{\leftmark}} %Displays the upper-level (chapter) information---
% as determined above---in non-upper case in the header, to the right on even pages.
\fancyhead[LO]{\rightmark} %Displays the lower-level (section) information---as
% determined above---in the header, to the left on odd pages.
\renewcommand{\headrulewidth}{0.5pt} %Underlines the header. (Set to 0pt if not required).
\renewcommand{\footrulewidth}{0.5pt} %Underlines the footer. (Set to 0pt if not required).
%% Index
\makeindex
% Remove the index anchors from the HTML version to save size and bandwith.
\newcommand{\ind}[1]{\begin{latexonly}\index{#1}\end{latexonly}}
\newcommand{\makechapter}[2]{ \aname{#1}{} \chapter{\ahrefloc{#1}{#2}} \label{#1} }
\newcommand{\makesection}[2]{ \aname{#1}{} \section{\ahrefloc{#1}{#2}} \label{#1} }
\newcommand{\makesubsection}[2]{ \aname{#1}{} \subsection{\ahrefloc{#1}{#2}} \label{#1} }
\newcommand{\makesubsubsection}[2]{ \aname{#1}{} \subsubsection{\ahrefloc{#1}{#2}} \label{#1} }
\newcommand{\makeparagraph}[2]{ \aname{#1}{} \paragraph{\ahrefloc{#1}{#2}} \label{#1} }
%% 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{\bracehack}{\def\{{\char"7B}\def\}{\char"7D}}
\newcommand{\titem}[1]{\item[\bracehack\texttt{#1}]}
\newcommand{\ns}[1]{\texttt{#1}}
\newcommand{\jid}[1]{\texttt{#1}}
\newcommand{\option}[1]{\texttt{#1}}
\newcommand{\poption}[1]{{\bracehack\texttt{#1}}}
\newcommand{\node}[1]{\texttt{#1}}
\newcommand{\term}[1]{\texttt{#1}}
\newcommand{\shell}[1]{\texttt{#1}}
\newcommand{\ejabberd}{\texttt{ejabberd}}
\newcommand{\Jabber}{Jabber}
\newcommand{\XMPP}{XMPP}
\newcommand{\esyntax}[1]{\begin{description}\titem{#1}\end{description}}
%% Modules
\newcommand{\module}[1]{\texttt{#1}}
\newcommand{\modadhoc}{\module{mod\_adhoc}}
\newcommand{\modannounce}{\module{mod\_announce}}
\newcommand{\modblocking}{\module{mod\_blocking}}
\newcommand{\modcaps}{\module{mod\_caps}}
\newcommand{\modconfigure}{\module{mod\_configure}}
\newcommand{\moddisco}{\module{mod\_disco}}
\newcommand{\modecho}{\module{mod\_echo}}
\newcommand{\modhttpbind}{\module{mod\_http\_bind}}
\newcommand{\modhttpfileserver}{\module{mod\_http\_fileserver}}
\newcommand{\modlast}{\module{mod\_last}}
\newcommand{\modmuc}{\module{mod\_muc}}
\newcommand{\modmuclog}{\module{mod\_muc\_log}}
\newcommand{\modmulticast}{\module{mod\_multicast}}
\newcommand{\modoffline}{\module{mod\_offline}}
\newcommand{\modping}{\module{mod\_ping}}
\newcommand{\modprescounter}{\module{mod\_pres\_counter}}
\newcommand{\modprivacy}{\module{mod\_privacy}}
\newcommand{\modprivate}{\module{mod\_private}}
\newcommand{\modproxy}{\module{mod\_proxy65}}
\newcommand{\modpubsub}{\module{mod\_pubsub}}
\newcommand{\modpubsubodbc}{\module{mod\_pubsub\_odbc}}
\newcommand{\modregister}{\module{mod\_register}}
\newcommand{\modregisterweb}{\module{mod\_register\_web}}
\newcommand{\modroster}{\module{mod\_roster}}
\newcommand{\modservicelog}{\module{mod\_service\_log}}
\newcommand{\modsharedroster}{\module{mod\_shared\_roster}}
\newcommand{\modsharedrosterldap}{\module{mod\_shared\_roster\_ldap}}
\newcommand{\modsic}{\module{mod\_sic}}
\newcommand{\modstats}{\module{mod\_stats}}
\newcommand{\modtime}{\module{mod\_time}}
\newcommand{\modvcard}{\module{mod\_vcard}}
\newcommand{\modvcardldap}{\module{mod\_vcard\_ldap}}
\newcommand{\modvcardxupdate}{\module{mod\_vcard\_xupdate}}
\newcommand{\modversion}{\module{mod\_version}}
%% Contributed modules
%\usepackage{ifthen}
%\newboolean{modhttpbind}
%\newcommand{\modhttpbind}{\module{mod\_http\_bind}}
%\include{contributed_modules}
%
% Then in the document you can input the partial tex file with:
%\ifthenelse{\boolean{modhttpbind}}{\input{mod_http_bind.tex}}{}
%% Common options
\newcommand{\iqdiscitem}[1]{\titem{\{iqdisc, Discipline\}} \ind{options!iqdisc}This specifies
the processing discipline for #1 IQ queries (see section~\ref{modiqdiscoption}).}
\newcommand{\hostitem}[1]{
\titem{\{host, HostName\}} \ind{options!host}
This option defines the Jabber ID of the service.
If the option is not specified, the Jabber ID of the service will be the
hostname of the virtual host preceded with `\jid{#1.}'.
For more details see \ref{modhostoption}.
}
\newcommand{\backend}[1]{\titem{\{backend, mnesia|odbc\}} \ind{options!backend}
Specify the backend used to store the tables: #1.
The default value is \term{mnesia}.
If configured to \term{odbc}, then you must also configure in ejabberd
the database connection (see the subsections of \ref{database}).
}
%% Title page
\include{version}
\newlength{\larg}
\setlength{\larg}{14.5cm}
\title{
{\rule{\larg}{1mm}}\vspace{7mm}
\begin{tabular}{r}
{\huge {\bf ejabberd \version\ }} \\
\\
{\huge Installation and Operation Guide}
\end{tabular}\\
\vspace{2mm}
{\rule{\larg}{1mm}}
\begin{latexonly}
\vspace{2mm} \\
\vspace{5.5cm}
\end{latexonly}
}
\begin{latexonly}
\author{\begin{tabular}{p{13.7cm}}
ejabberd Development Team
\end{tabular}}
\date{}
\end{latexonly}
%% Options
\newcommand{\marking}[1]{#1} % Marking disabled
\newcommand{\quoting}[2][yozhik]{} % Quotes disabled
%\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;}
\newstyle{H1.titlemain HR}{display:none;}
\newstyle{TABLE.title}{border-top:1px solid grey;border-bottom:1px solid grey; background: \#efefef}
\newstyle{H1.chapter A, H2.section A, H3.subsection A, H4.subsubsection A, H5.paragraph A}
{color:\#000000; text-decoration:none;}
\newstyle{H1.chapter, H2.section, H3.subsection, H4.subsubsection, H5.paragraph}
{border-top: 1px solid grey; background: \#efefef; padding: 0.5ex}
\newstyle{pre.verbatim}{margin:1ex 2ex;border:1px dashed lightgrey;background-color:\#f9f9f9;padding:0.5ex;}
\newstyle{.dt-description}{margin:0ex 2ex;}
\newstyle{table[border="1"]}{border-collapse:collapse;margin-bottom:1em;}
\newstyle{table[border="1"] td}{border:1px solid \#aaa;padding:2px}
% Don't display <hr> before and after tables or images:
\newstyle{BLOCKQUOTE.table DIV.center DIV.center HR}{display:none;}
\newstyle{BLOCKQUOTE.figure DIV.center DIV.center HR}{display:none;}
%% Footnotes
\begin{latexonly}
\global\parskip=9pt plus 3pt minus 1pt
\global\parindent=0pt
\gdef\ahrefurl#1{\href{#1}{\texttt{#1}}}
\gdef\footahref#1#2{#2\footnote{\href{#1}{\texttt{#1}}}}
\end{latexonly}
\newcommand{\txepref}[2]{\footahref{http://xmpp.org/extensions/xep-#1.html}{#2}}
\newcommand{\xepref}[1]{\txepref{#1}{XEP-#1}}
\begin{document}
\label{titlepage}
\begin{titlepage}
\maketitle{}
%% Commenting. Breaking clean layout for now:
%% \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}
% Set the page counter to 2 so that the titlepage and the second page do not
% have the same page number. This fixes the PDFLaTeX warning "destination with
% the same identifier".
\begin{latexonly}
\setcounter{page}{2}
\end{latexonly}
\label{toc}
\tableofcontents{}
% Input introduction.tex
\input{introduction}
\makechapter{installing}{Installing \ejabberd{}}
\makesection{install.binary}{Installing \ejabberd{} with Binary Installer}
Probably the easiest way to install an \ejabberd{} instant messaging server
is using the binary installer published by ProcessOne.
The binary installers of released \ejabberd{} versions
are available in the ProcessOne \ejabberd{} downloads page:
\ahrefurl{http://www.process-one.net/en/ejabberd/downloads}
The installer will deploy and configure a full featured \ejabberd{}
server and does not require any extra dependencies.
In *nix systems, remember to set executable the binary installer before starting it. For example:
\begin{verbatim}
chmod +x ejabberd-2.0.0_1-linux-x86-installer.bin
./ejabberd-2.0.0_1-linux-x86-installer.bin
\end{verbatim}
\ejabberd{} can be started manually at any time,
or automatically by the operating system at system boot time.
To start and stop \ejabberd{} manually,
use the desktop shortcuts created by the installer.
If the machine doesn't have a graphical system, use the scripts 'start'
and 'stop' in the 'bin' directory where \ejabberd{} is installed.
The Windows installer also adds ejabberd as a system service,
and a shortcut to a debug console for experienced administrators.
If you want ejabberd to be started automatically at boot time,
go to the Windows service settings and set ejabberd to be automatically started.
Note that the Windows service is a feature still in development,
and for example it doesn't read the file ejabberdctl.cfg.
On a *nix system, if you want ejabberd to be started as daemon at boot time,
copy \term{ejabberd.init} from the 'bin' directory to something like \term{/etc/init.d/ejabberd}
(depending on your distribution).
Create a system user called \term{ejabberd},
give it write access to the directories \term{database/} and \term{logs/}, and set that as home;
the script will start the server with that user.
Then you can call \term{/etc/inid.d/ejabberd start} as root to start the server.
If \term{ejabberd} doesn't start correctly in Windows,
try to start it using the shortcut in desktop or start menu.
If the window shows error 14001, the solution is to install:
"Microsoft Visual C++ 2005 SP1 Redistributable Package".
You can download it from
\footahref{http://www.microsoft.com/}{www.microsoft.com}.
Then uninstall \ejabberd{} and install it again.
If \term{ejabberd} doesn't start correctly and a crash dump is generated,
there was a severe problem.
You can try starting \term{ejabberd} with
the script \term{bin/live.bat} in Windows,
or with the command \term{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 \term{ejabberdctl} administration script is included in the \term{bin} directory.
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}
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
administrator account. Some examples are Debian and Gentoo. Consult the
resources provided by your Operating System for more information.
Usually those packages create a script like \term{/etc/init.d/ejabberd}
to start and stop \ejabberd{} as a service at boot time.
\makesection{install.cean}{Installing \ejabberd{} with CEAN}
\footahref{http://cean.process-one.net/}{CEAN}
(Comprehensive Erlang Archive Network) is a repository that hosts binary
packages from many Erlang programs, including \ejabberd{} and all its dependencies.
The binaries are available for many different system architectures, so this is an
alternative to the binary installer and Operating System's \ejabberd{} packages.
You will have to create your own \ejabberd{} start
script depending of how you handle your CEAN installation.
The default \term{ejabberdctl} script is located
into \ejabberd{}'s priv directory and can be used as an example.
\makesection{installation}{Installing \ejabberd{} from Source Code}
\ind{install}
The canonical form for distribution of \ejabberd{} stable releases is the source code package.
Compiling \ejabberd{} from source code is quite easy in *nix systems,
as long as your system have all the dependencies.
\makesubsection{installreq}{Requirements}
\ind{installation!requirements}
To compile \ejabberd{} on a `Unix-like' operating system, you need:
\begin{itemize}
\item GNU Make
\item GCC
\item Erlang/OTP R12B-5 or higher. The recommended versions are R12B-5, R13B04 and R14B01.
Don't use R14A or R14B because \footahref{http://www.erlang.org/cgi-bin/ezmlm-cgi/4/54598}{they have a bug}.
\item exmpp 0.9.6 or higher
\item OpenSSL 0.9.8 or higher, for STARTTLS, SASL and SSL encryption.
\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 ESASL library. Optional. For SASL GSSAPI authentication. See section \ref{gssapi}.
\item ImageMagick's Convert program. Optional. For CAPTCHA challenges. See section \ref{captcha}.
\end{itemize}
\makesubsection{download}{Download Source Code}
\ind{install!download}
Released versions of \ejabberd{} are available in the ProcessOne \ejabberd{} downloads page:
\ahrefurl{http://www.process-one.net/en/ejabberd/downloads}
\ind{Git repository}
Alternatively, the latest development source code can be retrieved from the Git repository using the commands:
\begin{verbatim}
git clone git://git.process-one.net/ejabberd/mainline.git ejabberd
cd ejabberd
\end{verbatim}
\makesubsection{compile}{Compile}
\ind{install!compile}
To compile \ejabberd{} execute the commands:
\begin{verbatim}
./configure
make
\end{verbatim}
If you get an error like:
\term{``./configure: No such file or directory''}
the solution is to first execute:
\begin{verbatim}
aclocal
autoconf
\end{verbatim}
The build configuration script allows several options.
To get the full list run the command:
\begin{verbatim}
./configure --help
\end{verbatim}
Some options that you may be interested in modifying:
\begin{description}
\titem{--prefix=/}
Specify the path prefix where the files will be copied when running
the \term{make install} command.
\titem{--enable-user[=USER]}
Allow this normal system user to execute the ejabberdctl script
(see section~\ref{ejabberdctl}),
read the configuration files,
read and write in the spool directory,
read and write in the log directory.
The account user and group must exist in the machine
before running \term{make install}.
This account doesn't need an explicit HOME directory, because
\term{/var/lib/ejabberd/} will be used by default.
\titem{--enable-pam}
Enable the PAM authentication method (see section \ref{pam}).
\titem{--enable-odbc or --enable-mssql}
Required if you want to use an external database.
See section~\ref{database} for more information.
\titem{--enable-full-xml}
Enable the use of XML based optimisations.
It will for example use CDATA to escape characters in the XMPP stream.
Use this option only if you are sure your XMPP clients include a fully compliant XML parser.
\titem{--disable-transient-supervisors}
Disable the use of Erlang/OTP supervision for transient processes.
\titem{--enable-flash-hack}
Enable support for non-standard XML socket clients of Adobe Flash 8 and lower.
\end{description}
\makesubsection{install}{Install}
\ind{install!install}
To install \ejabberd{} in the destination directories, run the command:
\begin{verbatim}
make install
\end{verbatim}
Note that you probably need administrative privileges in the system
to install \term{ejabberd}.
The files and directories created are, by default:
\begin{description}
\titem{/etc/ejabberd/} Configuration directory:
\begin{description}
\titem{ejabberd.cfg} ejabberd configuration file
\titem{ejabberdctl.cfg} Configuration file of the administration script
\titem{inetrc} Network DNS configuration file
\end{description}
\titem{/lib/ejabberd/}
\begin{description}
\titem{ebin/} Erlang binary files (*.beam)
\titem{include/} Erlang header files (*.hrl)
\titem{priv/} Additional files required at runtime
\begin{description}
\titem{bin/} Executable programs
\titem{lib/} Binary system libraries (*.so)
\titem{msgs/} Translation files (*.msgs)
\end{description}
\end{description}
\titem{/sbin/ejabberdctl} Administration script (see section~\ref{ejabberdctl})
\titem{/share/doc/ejabberd/} Documentation of ejabberd
\titem{/var/lib/ejabberd/} Spool directory:
\begin{description}
\titem{.erlang.cookie} Erlang cookie file (see section \ref{cookie})
\titem{acl.DCD, ...} Mnesia database spool files (*.DCD, *.DCL, *.DAT)
\end{description}
\titem{/var/log/ejabberd/} Log directory (see section~\ref{logfiles}):
\begin{description}
\titem{ejabberd.log} ejabberd service log
\titem{erlang.log} Erlang/OTP system log
\end{description}
\end{description}
\makesubsection{start}{Start}
\ind{install!start}
You can use the \term{ejabberdctl} command line administration script to start and stop \ejabberd{}.
If you provided the configure option \term{--enable-user=USER} (see \ref{compile}),
you can execute \term{ejabberdctl} with either that system account or root.
Usage example:
\begin{verbatim}
ejabberdctl start
ejabberdctl status
The node ejabberd@localhost is started with status: started
ejabberd is running in that node
ejabberdctl stop
\end{verbatim}
If \term{ejabberd} doesn't start correctly and a crash dump is generated,
there was a severe problem.
You can try starting \term{ejabberd} with
the command \term{ejabberdctl live}
to see the error message provided by Erlang
and can identify what is exactly the problem.
Please refer to the section~\ref{ejabberdctl} for details about \term{ejabberdctl},
and configurable options to fine tune the Erlang runtime system.
If you want ejabberd to be started as daemon at boot time,
copy \term{ejabberd.init} to something like \term{/etc/init.d/ejabberd}
(depending on your distribution).
Create a system user called \term{ejabberd};
it will be used by the script to start the server.
Then you can call \term{/etc/inid.d/ejabberd start} as root to start the server.
\makesubsection{bsd}{Specific Notes for BSD}
\ind{install!bsd}
The command to compile \ejabberd{} in BSD systems is:
\begin{verbatim}
gmake
\end{verbatim}
\makesubsection{solaris}{Specific Notes for Sun Solaris}
\ind{install!solaris}
You need to have \term{GNU install},
but it isn't included in Solaris.
It can be easily installed if your Solaris system
is set up for \footahref{http://www.blastwave.org/}{blastwave.org}
package repository.
Make sure \term{/opt/csw/bin} is in your \term{PATH} and run:
\begin{verbatim}
pkg-get -i fileutils
\end{verbatim}
If that program is called \term{ginstall},
modify the \ejabberd{} \term{Makefile} script to suit your system,
for example:
\begin{verbatim}
cat Makefile | sed s/install/ginstall/ > Makefile.gi
\end{verbatim}
And finally install \ejabberd{} with:
\begin{verbatim}
gmake -f Makefile.gi ginstall
\end{verbatim}
\makesubsection{windows}{Specific Notes for Microsoft Windows}
\ind{install!windows}
\makesubsubsection{windowsreq}{Requirements}
To compile \ejabberd{} on a Microsoft Windows system, you need:
\begin{itemize}
\item MS Visual C++ 6.0 Compiler
\item \footahref{http://www.erlang.org/download.html}{Erlang/OTP R12B-5}. Support for R13 or higher is experimental.
\item \footahref{http://support.process-one.net/doc/display/EXMPP}{exmpp 0.9.5 or higher}
\item \footahref{http://www.slproweb.com/products/Win32OpenSSL.html}{Shining Light OpenSSL 0.9.8d or higher}
(to enable SSL connections)
\end{itemize}
\makesubsubsection{windowscom}{Compilation}
We assume that we will try to put as much library as possible into \verb|C:\sdk\| to make it easier to track what is install for \ejabberd{}.
\begin{enumerate}
\item Install Erlang emulator (for example, into \verb|C:\sdk\erl5.6.5|).
\item Install OpenSSL in \verb|C:\sdk\OpenSSL| and add \verb|C:\sdk\OpenSSL\lib\VC| to your path or copy the binaries to your system directory.
\item Make sure the you can access Erlang binaries from your path. For example: \verb|set PATH=%PATH%;"C:\sdk\erl5.6.5\bin"|
\item Depending on how you end up actually installing the library you might need to check and tweak the paths in the file configure.erl.
\item While in the directory \verb|ejabberd\src| run:
\begin{verbatim}
configure.bat
nmake -f Makefile.win32
\end{verbatim}
\item Edit the file \verb|ejabberd\src\ejabberd.cfg| and run
\begin{verbatim}
werl -s ejabberd -name ejabberd
\end{verbatim}
\end{enumerate}
%TODO: how to compile database support on windows?
\makesection{initialadmin}{Create a XMPP Account for Administration}
You need a XMPP account and grant him administrative privileges
to enter the \ejabberd{} Web Admin:
\begin{enumerate}
\item Register a XMPP account on your \ejabberd{} server, for example \term{admin1@example.org}.
There are two ways to register a XMPP account:
\begin{enumerate}
\item Using \term{ejabberdctl}\ind{ejabberdctl} (see section~\ref{ejabberdctl}):
\begin{verbatim}
ejabberdctl register admin1 example.org FgT5bk3
\end{verbatim}
\item Using a XMPP client and In-Band Registration (see section~\ref{modregister}).
\end{enumerate}
\item Edit the \ejabberd{} configuration file to give administration rights to the XMPP account you created:
\begin{verbatim}
{acl, admin, {user, "admin1", "example.org"}}.
{access, configure, [{allow, admin}]}.
\end{verbatim}
You can grant administrative privileges to many XMPP accounts,
and also to accounts in other XMPP servers.
\item Restart \ejabberd{} to load the new configuration.
\item Open the Web Admin (\verb|http://server:port/admin/|) in your
favourite browser. Make sure to enter the \emph{full} JID as username (in this
example: \jid{admin1@example.org}. The reason that you also need to enter the
suffix, is because \ejabberd{}'s virtual hosting support.
\end{enumerate}
\makesection{upgrade}{Upgrading \ejabberd{}}
To upgrade an ejabberd installation to a new version,
simply uninstall the old version, and then install the new one.
Of course, it is important that the configuration file
and Mnesia database spool directory are not removed.
\ejabberd{} automatically updates the Mnesia table definitions at startup when needed.
If you also use an external database for storage of some modules,
check if the release notes of the new ejabberd version
indicates you need to also update those tables.
\makechapter{configure}{Configuring \ejabberd{}}
\ind{configuration file}
\makesection{basicconfig}{Basic Configuration}
The configuration file will be loaded the first time you start \ejabberd{}. The
content from this file will be parsed and stored in the internal \ejabberd{} database. Subsequently the
configuration will be loaded from the database and any commands in the
configuration file are appended to the entries in the database.
Note that \ejabberd{} never edits the configuration file.
So, the configuration changes done using the Web Admin
are stored in the database, but are not reflected in the configuration file.
If you want those changes to be use after \ejabberd{} restart, you can either
edit the configuration file, or remove all its content.
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
host name(s) stored in the database will be used.
You can override the old values stored in the database by adding next lines to
the beginning of the configuration file:
\begin{verbatim}
override_global.
override_local.
override_acls.
\end{verbatim}
With these lines the old global options (shared between all \ejabberd{} nodes in a
cluster), local options (which are specific for this particular \ejabberd{} node)
and ACLs will be removed before new ones are added.
\makesubsection{hostnames}{Host Names}
\ind{options!hosts}\ind{host names}
The option \option{hosts} defines a list containing one or more domains that
\ejabberd{} will serve.
The syntax is:
\esyntax{\{hosts, [HostName, ...]\}.}
Examples:
\begin{itemize}
\item Serving one domain:
\begin{verbatim}
{hosts, ["example.org"]}.
\end{verbatim}
\item Serving three domains:
\begin{verbatim}
{hosts, ["example.net", "example.com", "jabber.somesite.org"]}.
\end{verbatim}
\end{itemize}
\makesubsection{virtualhost}{Virtual Hosting}
\ind{virtual hosting}\ind{virtual hosts}\ind{virtual domains}
Options can be defined separately for every virtual host using the
\term{host\_config} option.
The syntax is: \ind{options!host\_config}
\esyntax{\{host\_config, HostName, [Option, ...]\}}
Examples:
\begin{itemize}
\item Domain \jid{example.net} is using the internal authentication method while
domain \jid{example.com} is using the \ind{LDAP}LDAP server running on the
domain \jid{localhost} to perform authentication:
\begin{verbatim}
{host_config, "example.net", [{auth_method, storage},
{auth_storage, mnesia}]}.
{host_config, "example.com", [{auth_method, ldap],
{ldap_servers, ["localhost"]},
{ldap_uids, [{"uid"}]},
{ldap_rootdn, "dc=localdomain"},
{ldap_rootdn, "dc=example,dc=com"},
{ldap_password, ""}]}.
\end{verbatim}
\item Domain \jid{example.net} is using \ind{ODBC}ODBC to perform authentication
while domain \jid{example.com} is using the LDAP servers running on the domains
\jid{localhost} and \jid{otherhost}:
\begin{verbatim}
{host_config, "example.net", [{auth_method, storage},
{auth_storage, odbc},
{odbc_server, "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"}]}.
{host_config, "example.com", [{auth_method, ldap},
{ldap_servers, ["localhost", "otherhost"]},
{ldap_uids, [{"uid"}]},
{ldap_rootdn, "dc=localdomain"},
{ldap_rootdn, "dc=example,dc=com"},
{ldap_password, ""}]}.
\end{verbatim}
\end{itemize}
To define specific ejabberd modules in a virtual host,
you can define the global \term{modules} option with the common modules,
and later add specific modules to certain virtual hosts.
To accomplish that, instead of defining each option in \term{host\_config} with the general syntax
\esyntax{\{OptionName, OptionValue\}}
use this syntax:
\esyntax{\{\{add, OptionName\}, OptionValue\}}
In this example three virtual hosts have some similar modules, but there are also
other different modules for some specific virtual hosts:
\begin{verbatim}
%% This ejabberd server has three vhosts:
{hosts, ["one.example.org", "two.example.org", "three.example.org"]}.
%% Configuration of modules that are common to all vhosts
{modules,
[
{mod_roster, []},
{mod_configure, []},
{mod_disco, []},
{mod_private, []},
{mod_time, []},
{mod_last, []},
{mod_version, []}
]}.
%% Add some modules to vhost one:
{host_config, "one.example.org",
[{{add, modules}, [
{mod_echo, [{host, "echo-service.one.example.org"}]}
{mod_http_bind, []},
{mod_logxml, []}
]
}
]}.
%% Add a module just to vhost two:
{host_config, "two.example.org",
[{{add, modules}, [
{mod_echo, [{host, "mirror.two.example.org"}]}
]
}
]}.
\end{verbatim}
\makesubsection{listened}{Listening Ports}
\ind{options!listen}
The option \option{listen} defines for which ports, addresses and network protocols \ejabberd{}
will listen and what services will be run on them. Each element of the list is a
tuple with the following elements:
\begin{itemize}
\item Port number. Optionally also the IP address and/or a transport protocol.
\item Listening module that serves this port.
\item Options for the TCP socket and for the listening module.
\end{itemize}
The option syntax is:
\esyntax{\{listen, [Listener, ...]\}.}
To define a listener there are several syntax.
\esyntax{\{PortNumber, Module, [Option, ...]\}}
\esyntax{\{\{PortNumber, IPaddress\}, Module, [Option, ...]\}}
\esyntax{\{\{PortNumber, TransportProtocol\}, Module, [Option, ...]\}}
\esyntax{\{\{PortNumber, IPaddress, TransportProtocol\}, Module, [Option, ...]\}}
\makesubsubsection{listened-port}{Port Number, IP Address and Transport Protocol}
The port number defines which port to listen for incoming connections.
It can be a Jabber/XMPP standard port
(see section \ref{firewall}) or any other valid port number.
The IP address can be represented with a string
or an Erlang tuple with decimal or hexadecimal numbers.
The socket will listen only in that network interface.
It is possible to specify a generic address,
so \ejabberd{} will listen in all addresses.
Depending in the type of the IP address, IPv4 or IPv6 will be used.
When not specified the IP address, it will listen on all IPv4 network addresses.
Some example values for IP address:
\begin{itemize}
\item \verb|"0.0.0.0"| to listen in all IPv4 network interfaces. This is the default value when no IP is specified.
\item \verb|"::"| to listen in all IPv6 network interfaces
\item \verb|"10.11.12.13"| is the IPv4 address \verb|10.11.12.13|
\item \verb|"::FFFF:127.0.0.1"| is the IPv6 address \verb|::FFFF:127.0.0.1/128|
\item \verb|{10, 11, 12, 13}| is the IPv4 address \verb|10.11.12.13|
\item \verb|{0, 0, 0, 0, 0, 65535, 32512, 1}| is the IPv6 address \verb|::FFFF:127.0.0.1/128|
\item \verb|{16#fdca, 16#8ab6, 16#a243, 16#75ef, 0, 0, 0, 1}| is the IPv6 address \verb|FDCA:8AB6:A243:75EF::1/128|
\end{itemize}
The transport protocol can be \term{tcp} or \term{udp}.
Default is \term{tcp}.
\makesubsubsection{listened-module}{Listening Module}
\ind{modules!ejabberd\_c2s}\ind{modules!ejabberd\_s2s\_in}\ind{modules!ejabberd\_service}\ind{modules!ejabberd\_http}\ind{protocols!XEP-0114: Jabber Component Protocol}
The available modules, their purpose and the options allowed by each one are:
\begin{description}
\titem{\texttt{ejabberd\_c2s}}
Handles c2s connections.\\
Options: \texttt{access}, \texttt{certfile}, \texttt{max\_fsm\_queue},
\texttt{max\_stanza\_size}, \texttt{shaper},
\texttt{starttls}, \texttt{starttls\_required}, \texttt{tls},
\texttt{zlib}
\titem{\texttt{ejabberd\_s2s\_in}}
Handles incoming s2s connections.\\
Options: \texttt{max\_stanza\_size}, \texttt{shaper}
\titem{\texttt{ejabberd\_service}}
Interacts with an \footahref{http://www.ejabberd.im/tutorials-transports}{external component}
(as defined in the Jabber Component Protocol (\xepref{0114}).\\
Options: \texttt{access}, \texttt{hosts}, \texttt{max\_fsm\_queue},
\texttt{service\_check\_from}, \texttt{shaper}
\titem{\texttt{ejabberd\_stun}}
Handles STUN Binding requests as defined in
\footahref{http://tools.ietf.org/html/rfc5389}{RFC 5389}.\\
Options: \texttt{certfile}
\titem{\texttt{ejabberd\_http}}
Handles incoming HTTP connections.\\
Options: \texttt{captcha}, \texttt{certfile}, \texttt{http\_bind}, \texttt{http\_poll},
\texttt{request\_handlers}, \texttt{tls}, \texttt{trusted\_proxies}, \texttt{web\_admin}\\
\end{description}
\makesubsubsection{listened-options}{Options}
This is a detailed description of each option allowed by the listening modules:
\begin{description}
\titem{\{access, AccessName\}} \ind{options!access}This option defines
access to the port. The default value is \term{all}.
\titem{\{backlog, Value\}} \ind{options!backlog}The backlog value
defines the maximum length that the queue of pending connections may
grow to. This should be increased if the server is going to handle
lots of new incoming connections as they may be dropped if there is
no space in the queue (and ejabberd was not able to accept them
immediately). Default value is 5.
\titem{captcha} \ind{options!http-captcha}
Simple web page that allows a user to fill a CAPTCHA challenge (see section \ref{captcha}).
\titem{\{certfile, Path\}} Full path to a file containing the default SSL certificate.
To define a certificate file specific for a given domain, use the global option \term{domain\_certfile}.
\titem{\{hosts, [Hostname, ...], [HostOption, ...]\}} \ind{options!hosts}
The external Jabber component that connects to this \term{ejabberd\_service}
can serve one or more hostnames.
As \term{HostOption} you can define options for the component;
currently the only allowed option is the password required to the component
when attempt to connect to ejabberd: \poption{\{password, Secret\}}.
Note that you cannot define in a single \term{ejabberd\_service} components of
different services: add an \term{ejabberd\_service} for each service,
as seen in an example below.
\titem{http\_bind} \ind{options!http\_bind}\ind{protocols!XEP-0206: HTTP Binding}\ind{JWChat}\ind{web-based XMPP client}
This option enables HTTP Binding (\xepref{0124} and \xepref{0206}) support. HTTP Bind
enables access via HTTP requests to \ejabberd{} from behind firewalls which
do not allow outgoing sockets on port 5222.
Remember that you must also install and enable the module mod\_http\_bind.
If HTTP Bind is enabled, it will be available at
\verb|http://server:port/http-bind/|. Be aware that support for HTTP Bind
is also needed in the \XMPP{} client. Remark also that HTTP Bind can be
interesting to host a web-based \XMPP{} client such as
\footahref{http://jwchat.sourceforge.net/}{JWChat}
(check the tutorials to install JWChat with ejabberd and an
\footahref{http://www.ejabberd.im/jwchat-localserver}{embedded local web server}
or \footahref{http://www.ejabberd.im/jwchat-apache}{Apache}).
\titem{http\_poll} \ind{options!http\_poll}\ind{protocols!XEP-0025: HTTP Polling}\ind{JWChat}\ind{web-based XMPP client}
This option enables HTTP Polling (\xepref{0025}) support. HTTP Polling
enables access via HTTP requests to \ejabberd{} from behind firewalls which
do not allow outgoing sockets on port 5222.
If HTTP Polling is enabled, it will be available at
\verb|http://server:port/http-poll/|. Be aware that support for HTTP Polling
is also needed in the \XMPP{} client. Remark also that HTTP Polling can be
interesting to host a web-based \XMPP{} client such as
\footahref{http://jwchat.sourceforge.net/}{JWChat}.
The maximum period of time to keep a client session active without
an incoming POST request can be configured with the global option
\term{http\_poll\_timeout}. The default value is five minutes.
The option can be defined in \term{ejabberd.cfg}, expressing the time
in seconds: \verb|{http_poll_timeout, 300}.|
\titem{\{max\_fsm\_queue, Size\}}
This option specifies the maximum number of elements in the queue of the FSM
(Finite State Machine).
Roughly speaking, each message in such queues represents one XML
stanza queued to be sent into its relevant outgoing stream. If queue size
reaches the limit (because, for example, the receiver of stanzas is too slow),
the FSM and the corresponding connection (if any) will be terminated
and error message will be logged.
The reasonable value for this option depends on your hardware configuration.
However, there is no much sense to set the size above 1000 elements.
This option can be specified for \term{ejabberd\_service} and
\term{ejabberd\_c2s} listeners,
or also globally for \term{ejabberd\_s2s\_out}.
If the option is not specified for \term{ejabberd\_service} or
\term{ejabberd\_c2s} listeners,
the globally configured value is used.
The allowed values are integers and 'undefined'.
Default value: 'undefined'.
\titem{\{max\_stanza\_size, Size\}}
\ind{options!max\_stanza\_size}This option specifies an
approximate maximum size in bytes of XML stanzas. Approximate,
because it is calculated with the precision of one block of read
data. For example \verb|{max_stanza_size, 65536}|. The default
value is \term{infinity}. Recommended values are 65536 for c2s
connections and 131072 for s2s connections. s2s max stanza size
must always much higher than c2s limit. Change this value with
extreme care as it can cause unwanted disconnect if set too low.
\titem{\{request\_handlers, [ \{Path, Module\}, ...]\}} To define one or several handlers that will serve HTTP requests.
The Path is a list of strings; so the URIs that start with that Path will be served by Module.
For example, if you want \term{mod\_foo} to serve the URIs that start with \term{/a/b/},
and you also want \term{mod\_http\_bind} to serve the URIs \term{/http-bind/},
use this option: \term{\{request\_handlers, [\{["a", "b"], mod\_foo\}, \{["http-bind"], mod\_http\_bind\}]\}}
\titem{\{service\_check\_from, true|false\}}
\ind{options!service\_check\_from}
This option can be used with \term{ejabberd\_service} only.
\xepref{0114} requires that the domain must match the hostname of the component.
If this option is set to \term{false}, \ejabberd{} will allow the component
to send stanzas with any arbitrary domain in the 'from' attribute.
Only use this option if you are completely sure about it.
The default value is \term{true}, to be compliant with \xepref{0114}.
\titem{\{shaper, none|ShaperName\}} \ind{options!shaper}This option defines a
shaper for the port (see section~\ref{shapers}). The default value
is \term{none}.
\titem{starttls} \ind{options!starttls}\ind{STARTTLS}This option
specifies that STARTTLS encryption is available on connections to the port.
You should also set the \option{certfile} option.
You can define a certificate file for a specific domain using the global option \option{domain\_certfile}.
\titem{starttls\_required} \ind{options!starttls\_required}This option
specifies that STARTTLS encryption is required on connections to the port.
No unencrypted connections will be allowed.
You should also set the \option{certfile} option.
You can define a certificate file for a specific domain using the global option \option{domain\_certfile}.
\titem{tls} \ind{options!tls}\ind{TLS}This option specifies that traffic on
the port will be encrypted using SSL immediately after connecting.
This was the traditional encryption method in the early Jabber software,
commonly on port 5223 for client-to-server communications.
But this method is nowadays deprecated and not recommended.
The preferable encryption method is STARTTLS on port 5222, as defined
\footahref{http://xmpp.org/rfcs/rfc3920.html\#tls}{RFC 3920: XMPP Core},
which can be enabled in \ejabberd{} with the option \term{starttls}.
If this option is set, you should also set the \option{certfile} option.
The option \term{tls} can also be used in \term{ejabberd\_http} to support HTTPS.
\titem{\{trusted\_proxies, all | [IpString]\}} \ind{options!trusted\_proxies}
Specify what proxies are trusted when an HTTP request contains the header \term{X-Forwarded-For}
You can specify \term{all} to allow all proxies, or specify a list of IPs in string format.
The default value is: \term{["127.0.0.1"]}
\titem{web\_admin} \ind{options!web\_admin}\ind{web admin}This option
enables the Web Admin for \ejabberd{} administration which is available
at \verb|http://server:port/admin/|. Login and password are the username and
password of one of the registered users who are granted access by the
`configure' access rule.
\titem{zlib} \ind{options!zlib}\ind{protocols!XEP-0138: Stream Compression}\ind{Zlib}This
option specifies that Zlib stream compression (as defined in \xepref{0138})
is available on connections to the port.
\end{description}
There are some additional global options that can be specified in the ejabberd configuration file (outside \term{listen}):
\begin{description}
\titem{\{s2s\_use\_starttls, false|optional|required|required\_trusted\}}
\ind{options!s2s\_use\_starttls}\ind{STARTTLS}This option defines if
s2s connections don't use STARTTLS encryption; if STARTTLS can be used optionally;
if STARTTLS is required to establish the connection;
or if STARTTLS is required and the remote certificate must be valid and trusted.
The default value is to not use STARTTLS: \term{false}.
\titem{\{s2s\_certfile, Path\}} \ind{options!s2s\_certificate}Full path to a
file containing a SSL certificate.
\titem{\{domain\_certfile, Domain, Path\}} \ind{options!domain\_certfile}
Full path to the file containing the SSL certificate for a specific domain.
\titem{\{outgoing\_s2s\_options, [Family, ...], Timeout\}} \ind{options!outgoing\_s2s\_options}
Specify which address families to try, in what order, and connect timeout in milliseconds.
By default it first tries connecting with IPv4, if that fails it tries using IPv6,
with a timeout of 10000 milliseconds.
\titem{\{outgoing\_s2s\_local\_address, IPaddress\}} \ind{options!outgoing\_s2s\_local\_address}
Specify which local IP address is desired for the outgoing S2S connections.
This option is used only if the local and remote addresses
are of the same IP version (either 4 or 6).
If this option is not defined, and the \term{ejabberd\_s2s\_in}
listener address is defined, then that one is used.
\titem{\{s2s\_dns\_options, [ \{Property, Value\}, ...]\}}
\ind{options!s2s\_dns\_options}Define properties to use for DNS resolving.
Allowed Properties are: \term{timeout} in seconds which default value is \term{10}
and \term{retries} which default value is \term{2}.
\titem{\{s2s\_default\_policy, allow|deny\}}
The default policy for incoming and outgoing s2s connections to other XMPP servers.
The default value is \term{allow}.
\titem{\{\{s2s\_host, Host\}, allow|deny\}}
Defines if incoming and outgoing s2s connections with a specific remote host are allowed or denied.
This allows to restrict ejabberd to only establish s2s connections
with a small list of trusted servers, or to block some specific servers.
\titem{\{s2s\_max\_retry\_delay, Seconds\}} \ind{options!s2s\_max\_retry\_delay}
The maximum allowed delay for retry to connect after a failed connection attempt.
Specified in seconds. The default value is 300 seconds (5 minutes).
\titem{\{max\_fsm\_queue, Size\}}
This option specifies the maximum number of elements in the queue of the FSM
(Finite State Machine).
Roughly speaking, each message in such queues represents one XML
stanza queued to be sent into its relevant outgoing stream. If queue size
reaches the limit (because, for example, the receiver of stanzas is too slow),
the FSM and the corresponding connection (if any) will be terminated
and error message will be logged.
The reasonable value for this option depends on your hardware configuration.
However, there is no much sense to set the size above 1000 elements.
This option can be specified for \term{ejabberd\_service} and
\term{ejabberd\_c2s} listeners,
or also globally for \term{ejabberd\_s2s\_out}.
If the option is not specified for \term{ejabberd\_service} or
\term{ejabberd\_c2s} listeners,
the globally configured value is used.