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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD><TITLE>Ejabberd Installation and Operation Guide</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=ISO8859-1">
<META name="GENERATOR" content="hevea 1.06">
</HEAD>
<BODY >
<!--HEVEA command line is: /usr/bin/hevea -charset ISO8859-1 guide.tex -->
<!--HTMLHEAD-->
<!--ENDHTML-->
<!--PREFIX <ARG ></ARG>-->
<!--CUT DEF section 1 -->
<H1 ALIGN=center>Ejabberd Installation and Operation Guide</H1>
<H3 ALIGN=center>Alexey Shchepin<BR>
<A HREF="mailto:alexey@sevcom.net"><TT>mailto:alexey@sevcom.net</TT></A><BR>
<A HREF="xmpp:aleksey@jabber.ru"><TT>xmpp:aleksey@jabber.ru</TT></A></H3>
<H3 ALIGN=center>July 12, 2003</H3><DIV ALIGN=center>
<IMG SRC="logo.png">
</DIV><BR>
<BR>
<!--TOC section Table of Contents-->
<H2>Table of Contents</H2><!--SEC END -->
<UL><LI>
<A HREF="#htoc1">1 Introduction</A>
<LI><A HREF="#htoc2">2 Installation</A>
<UL><LI>
<A HREF="#htoc3">2.1 Installation Requirements</A>
<UL><LI>
<A HREF="#htoc4">2.1.1 Unix</A>
<LI><A HREF="#htoc5">2.1.2 Windows</A>
</UL>
<LI><A HREF="#htoc6">2.2 Obtaining</A>
<LI><A HREF="#htoc7">2.3 Compilation</A>
<UL><LI>
<A HREF="#htoc8">2.3.1 Unix</A>
<LI><A HREF="#htoc9">2.3.2 Windows</A>
</UL>
<LI><A HREF="#htoc10">2.4 Starting</A>
</UL>
<LI><A HREF="#htoc11">3 Configuration</A>
<UL><LI>
<A HREF="#htoc12">3.1 Initial Configuration</A>
<UL><LI>
<A HREF="#htoc13">3.1.1 Host Name</A>
<LI><A HREF="#htoc14">3.1.2 Access Rules</A>
<LI><A HREF="#htoc15">3.1.3 Shapers Configuration</A>
<LI><A HREF="#htoc16">3.1.4 Listened Sockets</A>
<LI><A HREF="#htoc17">3.1.5 Modules</A>
</UL>
<LI><A HREF="#htoc18">3.2 Online Configuration and Monitoring</A>
<UL><LI>
<A HREF="#htoc19">3.2.1 Node <TT>config</TT>: Global Configuration</A>
<LI><A HREF="#htoc20">3.2.2 Node <TT>online users</TT>: List of Online Users</A>
<LI><A HREF="#htoc21">3.2.3 Node <TT>all users</TT>: List of Registered Users</A>
<LI><A HREF="#htoc22">3.2.4 Node <TT>outgoing s2s</TT>: List of Outgoing S2S connections</A>
<LI><A HREF="#htoc23">3.2.5 Node <TT>running nodes</TT>: List of Running <TT>ejabberd</TT> Nodes</A>
<LI><A HREF="#htoc24">3.2.6 Node <TT>stopped nodes</TT>: List of Stopped Nodes</A>
</UL>
</UL>
<LI><A HREF="#htoc25">4 Distribution</A>
<UL><LI>
<A HREF="#htoc26">4.1 How it works</A>
<UL><LI>
<A HREF="#htoc27">4.1.1 Router</A>
<LI><A HREF="#htoc28">4.1.2 Local Router</A>
<LI><A HREF="#htoc29">4.1.3 Session Manager</A>
<LI><A HREF="#htoc30">4.1.4 S2S Manager</A>
</UL>
</UL>
<LI><A HREF="#htoc31">A Built-in Modules</A>
<UL><LI>
<A HREF="#htoc32">A.1 Common Options</A>
<UL><LI>
<A HREF="#htoc33">A.1.1 Option <TT>iqdisc</TT></A>
<LI><A HREF="#htoc34">A.1.2 Option <TT>host</TT></A>
</UL>
<LI><A HREF="#htoc35">A.2 <TT>mod_register</TT></A>
<LI><A HREF="#htoc36">A.3 <TT>mod_roster</TT></A>
<LI><A HREF="#htoc37">A.4 <TT>mod_configure</TT></A>
<LI><A HREF="#htoc38">A.5 <TT>mod_disco</TT></A>
<LI><A HREF="#htoc39">A.6 <TT>mod_stats</TT></A>
<LI><A HREF="#htoc40">A.7 <TT>mod_vcard</TT></A>
<LI><A HREF="#htoc41">A.8 <TT>mod_offline</TT></A>
<LI><A HREF="#htoc42">A.9 <TT>mod_echo</TT></A>
<LI><A HREF="#htoc43">A.10 <TT>mod_private</TT></A>
<LI><A HREF="#htoc44">A.11 <TT>mod_time</TT></A>
<LI><A HREF="#htoc45">A.12 <TT>mod_version</TT></A>
</UL>
<LI><A HREF="#htoc46">B I18n/L10n</A>
</UL>
<!--TOC section Introduction-->
<H2><A NAME="htoc1">1</A> Introduction</H2><!--SEC END -->
<A NAME="sec:intro"></A>
<TT>ejabberd</TT> is a Free and Open Source fault-tolerant distributed Jabber
server. It is writen mostly in Erlang.<BR>
<BR>
The main features of <TT>ejabberd</TT> is:
<UL><LI>
Works on most of popular platforms: *nix (tested on Linux, FreeBSD and
NetBSD) and Win32
<LI>Distributed: You can run <TT>ejabberd</TT> on a cluster of machines and all of
them will serve one Jabber domain.
<LI>Fault-tolerance: You can setup an <TT>ejabberd</TT> cluster so that all the
information required for a properly working service will be stored
permanently on more than one node. This means that if one of the nodes
crashes, then the others will continue working without disruption.
You can also add or replace more nodes ``on the fly''.
<LI>Built-in <A HREF="http://www.jabber.org/jeps/jep-0045.html">Multi-User
Chat</A> service
<LI>Built-in IRC transport
<LI>Built-in
<A HREF="http://www.jabber.org/jeps/jep-0060.html">Publish-Subscribe</A>
service
<LI>Built-in Jabber Users Directory service based on users vCards
<LI>SSL support
<LI>Ability to interface with external components (JIT, MSN-t, Yahoo-t, etc)
<LI>Migration from jabberd14 is possible
<LI>Mostly XMPP-compliant
<LI>Support for
<A HREF="http://www.jabber.org/jeps/jep-0030.html">JEP-0030</A>
(Service Discovery).
<LI>Support for
<A HREF="http://www.jabber.org/jeps/jep-0039.html">JEP-0039</A>
(Statistics Gathering).
<LI>Support for <TT>xml:lang</TT> attribute in many XML elements
</UL>
The misfeatures of <TT>ejabberd</TT> is:
<UL><LI>
No support for external authentification
<LI>No support for virtual domains
<LI>No support for STARTTLS
</UL>
<!--TOC section Installation-->
<H2><A NAME="htoc2">2</A> Installation</H2><!--SEC END -->
<A NAME="sec:installation"></A>
<!--TOC subsection Installation Requirements-->
<H3><A NAME="htoc3">2.1</A> Installation Requirements</H3><!--SEC END -->
<A NAME="sec:installreq"></A>
<!--TOC subsubsection Unix-->
<H4><A NAME="htoc4">2.1.1</A> Unix</H4><!--SEC END -->
<A NAME="sec:installrequnix"></A>
To compile <TT>ejabberd</TT>, you will need the following packages:
<UL><LI>
GNU Make;
<LI>GCC;
<LI>libexpat 1.95 or later;
<LI>Erlang/OTP R8B or later.
</UL>
<!--TOC subsubsection Windows-->
<H4><A NAME="htoc5">2.1.2</A> Windows</H4><!--SEC END -->
<A NAME="sec:installreqwin"></A>
To compile <TT>ejabberd</TT> in MS Windows environment, you will need the following
packages:
<UL><LI>
MS Visual C++ 6.0 Compiler
<LI><A HREF="http://www.erlang.org/download/otp_win32_R8B-2.exe">Erlang
emulator version 5.1.2</A>
<LI><A HREF="http://prdownloads.sourceforge.net/expat/expat_win32bin_1_95_6.exe?download">Expat 1.95.6</A>
<LI><A HREF="http://prdownloads.sourceforge.net/gnuwin32/libiconv-1.8-1-lib.exe?download">Iconv 1.8</A> (optional)
</UL>
<!--TOC subsection Obtaining-->
<H3><A NAME="htoc6">2.2</A> Obtaining</H3><!--SEC END -->
<A NAME="sec:obtaining"></A>
Currently no stable version has been released.<BR>
<BR>
The latest alpha version can be retrieved from CVS.
<UL><LI>
<TT>export CVSROOT=:pserver:anonymous@jabberstudio.org:/home/cvs</TT>
<LI><TT>cvs login</TT>
<LI>Press Enter when asked for a password
<LI><TT>cvs -z3 co ejabberd</TT>
</UL>
<!--TOC subsection Compilation-->
<H3><A NAME="htoc7">2.3</A> Compilation</H3><!--SEC END -->
<A NAME="sec:compilation"></A>
<!--TOC subsubsection Unix-->
<H4><A NAME="htoc8">2.3.1</A> Unix</H4><!--SEC END -->
<A NAME="sec:compilationunix"></A>
<PRE>
./configure
make
</PRE>
TBD<BR>
<BR>
<!--TOC subsubsection Windows-->
<H4><A NAME="htoc9">2.3.2</A> Windows</H4><!--SEC END -->
<A NAME="sec:compilationwin"></A>
<OL type=1><LI>
Install Erlang emulator (for example, into <CODE>C:\Program Files\erl5.1.2</CODE>).
<LI>Install Expat library into <CODE>C:\Program Files\Expat-1.95.6</CODE>
directory. Copy file <CODE>C:\Program Files\Expat-1.95.6\Libs\libexpat.dll</CODE>
to your Windows system directory (for example, <CODE>C:\WINNT</CODE> or
<CODE>C:\WINNT\System32</CODE>)
<LI>Install Iconv library into <CODE>C:\Program Files\GnuWin32</CODE> directory.
Copy file <CODE>C:\Program Files\GnuWin32\bin\libiconv-2.dll</CODE> to your
Windows system directory.<BR>
<BR>
Note: Instead of copying libexpat.dll and libiconv-2.dll to Windows
directory, you can add directories
<CODE>C:\Program Files\Expat-1.95.6\Libs</CODE> and
<CODE>C:\Program Files\GnuWin32\bin</CODE> to <CODE>PATH</CODE> environment
variable.
<LI>Being in <CODE>ejabberd\src</CODE> directory run:
<PRE>
configure
nmake -f Makefile.win32
</PRE><LI>To build MUC, IRC and pub/sub modules run
<PRE>
nmake -f Makefile.win32
</PRE>in <CODE>ejabberd\src\mod_muc</CODE>, <CODE>ejabberd\src\mod_muc</CODE> and
<CODE>ejabberd\src\mod_pubsub</CODE> directories
<LI>Edit file <CODE>ejabberd\src\ejabberd.cfg</CODE> and run
<PRE>
werl -s ejabberd -name ejabberd
</PRE><LI>Enjoy!
</OL>
Some recent versions of Erlang distribution it seems have bug in crypto
application, so ejabberd could be built but users can't use digest
authentication (only plain-text). Also it seems SSL support is broken in
Windows distribution of Erlang emulator.<BR>
<BR>
<!--TOC subsection Starting-->
<H3><A NAME="htoc10">2.4</A> Starting</H3><!--SEC END -->
<A NAME="sec:starting"></A>
To start <TT>ejabberd</TT>, use the following command:
<PRE>
erl -name ejabberd -s ejabberd
</PRE>or
<PRE>
erl -sname ejabberd -s ejabberd
</PRE>In second case Erlang node will be identified using only first part of host
name, i. e. other Erlang nodes not inside this domain can't contact this node.<BR>
<BR>
To specify path to config file, use command like this:
<PRE>
erl -sname ejabberd -s ejabberd -ejabberd config \"/etc/ejabberd/ejabberd.cfg\"
</PRE>
To use more than 1024 connections, you will need to set environment variable
<CODE>ERL_MAX_PORTS</CODE>:
<PRE>
export ERL_MAX_PORTS=32000
</PRE>Note that with this value <TT>ejabberd</TT> will use more memory (approximately 6MB
more).<BR>
<BR>
To reduce memory usage, you can set environment variable
<CODE>ERL_FULLSWEEP_AFTER</CODE>:
<PRE>
export ERL_FULLSWEEP_AFTER=0
</PRE>But in this case <TT>ejabberd</TT> can start to work slower.<BR>
<BR>
<!--TOC section Configuration-->
<H2><A NAME="htoc11">3</A> Configuration</H2><!--SEC END -->
<A NAME="sec:configuration"></A>
<!--TOC subsection Initial Configuration-->
<H3><A NAME="htoc12">3.1</A> Initial Configuration</H3><!--SEC END -->
<A NAME="sec:initconfig"></A>
The configuration file is initially loaded the first time <TT>ejabberd</TT> is
executed, when it is parsed and stored in a database. Subsiquently the
configuration is loaded from the database and any commands in the configuration
file are appended to the entries in the database. The configuration file
consists of a sequence of Erlang terms. Parts of lines after <TT>`%'</TT> sign
are ignored. Each term is tuple, where first element is name of option, and
other are option values. E. g. if this file does not contain a ``host''
definition, then old value stored in the database will be used.<BR>
<BR>
To override old values stored in the database the following lines can be added
in config:
<PRE>
override_global.
override_local.
override_acls.
</PRE>With this lines old global or local options or ACLs will be removed before
adding new ones.<BR>
<BR>
<!--TOC subsubsection Host Name-->
<H4><A NAME="htoc13">3.1.1</A> Host Name</H4><!--SEC END -->
<A NAME="sec:confighostname"></A>
Option <TT>hostname</TT> defines name of Jabber domain that <TT>ejabberd</TT>
serves. E. g. to use <TT>jabber.org</TT> domain add following line in config:
<PRE>
{host, "jabber.org"}.
</PRE>
<!--TOC subsubsection Access Rules-->
<H4><A NAME="htoc14">3.1.2</A> Access Rules</H4><!--SEC END -->
<A NAME="sec:configaccess"></A>
Access control in <TT>ejabberd</TT> is performed via Access Control Lists (ACL). The
declarations of ACL in config file have following syntax:
<PRE>
{acl, <aclname>, {<acltype>, ...}}.
</PRE>
<TT><acltype></TT> can be one of following:
<DL COMPACT=compact><DT>
<B><TT>all</TT></B><DD> Matches all JIDs. Example:
<PRE>
{acl, all, all}.
</PRE><DT><B><TT>{user, <username>}</TT></B><DD> Matches local user with name
<TT><username></TT>. Example:
<PRE>
{acl, admin, {user, "aleksey"}}.
</PRE><DT><B><TT>{user, <username>, <server>}</TT></B><DD> Matches user with JID
<TT><username>@<server></TT> and any resource. Example:
<PRE>
{acl, admin, {user, "aleksey", "jabber.ru"}}.
</PRE><DT><B><TT>{server, <server>}</TT></B><DD> Matches any JID from server
<TT><server></TT>. Example:
<PRE>
{acl, jabberorg, {server, "jabber.org"}}.
</PRE><DT><B><TT>{user_regexp, <regexp>}</TT></B><DD> Matches local user with name that
matches <TT><regexp></TT>. Example:
<PRE>
{acl, tests, {user, "^test[0-9]*$"}}.
</PRE><DT><B><TT>{user_regexp, <regexp>, <server>}</TT></B><DD> Matches user with name
that matches <TT><regexp></TT> and from server <TT><server></TT>. Example:
<PRE>
{acl, tests, {user, "^test", "localhost"}}.
</PRE><DT><B><TT>{server_regexp, <regexp>}</TT></B><DD> Matches any JID from server that
matches <TT><regexp></TT>. Example:
<PRE>
{acl, icq, {server, "^icq\\."}}.
</PRE><DT><B><TT>{node_regexp, <user_regexp>, <server_regexp>}</TT></B><DD> Matches user
with name that matches <TT><user_regexp></TT> and from server that matches
<TT><server_regexp></TT>. Example:
<PRE>
{acl, aleksey, {node_regexp, "^aleksey", "^jabber.(ru|org)$"}}.
</PRE><DT><B><TT>{user_glob, <glob>}</TT></B><DD>
<DT><B><TT>{user_glob, <glob>, <server>}</TT></B><DD>
<DT><B><TT>{server_glob, <glob>}</TT></B><DD>
<DT><B><TT>{node_glob, <user_glob>, <server_glob>}</TT></B><DD> This is same as
above, but uses shell glob patterns instead of regexp. These patterns can
have following special characters:
<DL COMPACT=compact><DT>
<B><TT>*</TT></B><DD> matches any string including the null string.
<DT><B><TT>?</TT></B><DD> matches any single character.
<DT><B><TT>[...]</TT></B><DD> matches any of the enclosed characters. Character
ranges are specified by a pair of characters separated by a <TT>`-'</TT>.
If the first character after <TT>`['</TT> is a <TT>`!'</TT>, then any
character not enclosed is matched.
</DL>
</DL>
The following ACLs pre-defined:
<DL COMPACT=compact><DT>
<B><TT>all</TT></B><DD> Matches all JIDs.
<DT><B><TT>none</TT></B><DD> Matches none JIDs.
</DL>
An entry allowing or denying different services would look similar to this:
<PRE>
{access, <accessname>, [{allow, <aclname>},
{deny, <aclname>},
...
]}.
</PRE>When a JID is checked to have access to <TT><accessname></TT>, the server
sequentially checks if this JID mathes one of the ACLs that are second elements
in each tuple in list. If it is matched, then the first element of matched
tuple is returned else ``<TT>deny</TT>'' is returned.<BR>
<BR>
Example:
<PRE>
{access, configure, [{allow, admin}]}.
{access, something, [{deny, badmans},
{allow, all}]}.
</PRE>
Following access rules pre-defined:
<DL COMPACT=compact><DT>
<B><TT>all</TT></B><DD> Always return ``<TT>allow</TT>''
<DT><B><TT>none</TT></B><DD> Always return ``<TT>deny</TT>''
</DL>
<!--TOC subsubsection Shapers Configuration-->
<H4><A NAME="htoc15">3.1.3</A> Shapers Configuration</H4><!--SEC END -->
<A NAME="sec:configshaper"></A>
With shapers is possible to bound connection traffic. The declarations of
shapers in config file have following syntax:
<PRE>
{shaper, <shapername>, <kind>}.
</PRE>Currently implemented only one kind of shaper: <TT>maxrate</TT>. It have
following syntax:
<PRE>
{maxrate, <rate>}
</PRE>where <TT><rate></TT> means maximum allowed incomig rate in bytes/second.
E. g. to define shaper with name ``<TT>normal</TT>'' and maximum allowed rate
1000 bytes/s, add following line in config:
<PRE>
{shaper, normal, {maxrate, 1000}}.
</PRE>
<!--TOC subsubsection Listened Sockets-->
<H4><A NAME="htoc16">3.1.4</A> Listened Sockets</H4><!--SEC END -->
<A NAME="sec:configlistened"></A>
Option <TT>listen</TT> defines list of listened sockets and what services
runned on them. Each element of list is a tuple with following elements:
<UL><LI>
Port number;
<LI>Module that serves this port;
<LI>Options to this module.
</UL>
Currently three modules are implemented:
<DL COMPACT=compact><DT>
<CODE><B>ejabberd_c2s</B></CODE><DD> This module serves C2S connections.<BR>
<BR>
The following options are defined:
<DL COMPACT=compact><DT>
<CODE><B>{access, <access rule>}</B></CODE><DD> This option defines access of users
to this C2S port. Default value is ``<TT>all</TT>''.
<DT><CODE><B>{shaper, <access rule>}</B></CODE><DD> This option is like previous, but
use shapers instead of ``<TT>allow</TT>'' and ``<TT>deny</TT>''. Default
value is ``<TT>none</TT>''.
<DT><CODE><B>{ssl, SSLOpts}</B></CODE><DD> This option defines that traffic on this port
will be encrypted using SSL. SSL options are the same as described by
``<CODE>erl -man ssl</CODE>'' command
</DL>
<DT><CODE><B>ejabberd_s2s_in</B></CODE><DD> This module serves incoming S2S connections.
<DT><CODE><B>ejabberd_service</B></CODE><DD> This module serves connections from Jabber
services (i. e. that use the <TT>jabber:component:accept</TT> namespace).
</DL>
For example, the following configuration defines that C2S connections are
listened on port 5222 and 5223 (SSL) and denied for user ``<TT>bad</TT>'', S2S
on port 5269, and that service <TT>conference.example.org</TT> must be
connected to port 8888 with a password ``<TT>secret</TT>''. Also all users
except admins have traffic limit 1000 b/s.
<PRE>
{acl, blocked, {user, "bad"}}.
{access, c2s, [{deny, blocked},
{allow, all}]}.
{shaper, normal, {maxrate, 1000}}.
{access, c2s_shaper, [{none, admin},
{normal, all}]}.
{listen, [{5222, ejabberd_c2s, [{access, c2s},
{shaper, c2s_shaper}]},
{5223, ejabberd_c2s, [{access, c2s},
{ssl, [{certfile, "/path/to/ssl.pem"}]}]},
{5269, ejabberd_s2s_in, []},
{8888, ejabberd_service,
[{hosts, ["conference.example.org"], [{password, "secret"}]}]}
]}.
</PRE>
<!--TOC subsubsection Modules-->
<H4><A NAME="htoc17">3.1.5</A> Modules</H4><!--SEC END -->
<A NAME="sec:configmodules"></A>
Option <TT>modules</TT> defines the list of modules that will be loaded after
<TT>ejabberd</TT> startup. Each list element is a tuple where first element is a
name of a module and second is list of options to this module. See
section <A HREF="#sec:modules">A</A> for detailed information on each module.<BR>
<BR>
Example:
<PRE>
{modules, [
{mod_register, []},
{mod_roster, []},
{mod_configure, []},
{mod_disco, []},
{mod_stats, []},
{mod_vcard, []},
{mod_offline, []},
{mod_echo, [{host, "echo.localhost"}]},
{mod_private, []},
{mod_time, [{iqdisc, no_queue}]},
{mod_version, []}
]}.
</PRE>
<!--TOC subsection Online Configuration and Monitoring-->
<H3><A NAME="htoc18">3.2</A> Online Configuration and Monitoring</H3><!--SEC END -->
<A NAME="sec:onlineconfig"></A>
To perform online reconfiguration of <TT>ejabberd</TT> you will need to have
<TT>mod_configure</TT> loaded (see section <A HREF="#sec:modconfigure">A.4</A>). It is also highly
recommended to load <TT>mod_disco</TT> as well (see section <A HREF="#sec:moddisco">A.5</A>),
because <TT>mod_configure</TT> is highly integrated with it. Additionally it is
recommended to use a disco- and xdata-capable client such as
<A HREF="http://www.jabber.ru/projects/tkabber/index_en.html">Tkabber</A>
(which was developed synchronously with <TT>ejabberd</TT>, its CVS version
supports most of <TT>ejabberd</TT> features).<BR>
<BR>
On disco query <TT>ejabberd</TT> returns following items:
<UL><LI>
Identity of server.
<LI>List of features, including defined namespaces.
<LI>List of JIDs from route table.
<LI>List of disco-nodes described in following subsections.
</UL>
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="disco.png">
<BR>
<DIV ALIGN=center>Figure 1: Tkabber Discovery window</DIV><BR>
<A NAME="fig:disco"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
<!--TOC subsubsection Node <TT>config</TT>: Global Configuration-->
<H4><A NAME="htoc19">3.2.1</A> Node <TT>config</TT>: Global Configuration</H4><!--SEC END -->
Under this node the following nodes exists:<BR>
<BR>
<!--TOC paragraph Node <TT>config/hostname</TT>-->
<H5>Node <TT>config/hostname</TT></H5><!--SEC END -->
Via <TT>jabber:x:data</TT> queries to this node possible to change host name of
this <TT>ejabberd</TT> server. (See figure <A HREF="#fig:hostname">2</A>) (Currently this works
correctly only after a restart)
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="confhostname.png">
<BR>
<DIV ALIGN=center>Figure 2: Editing of hostname</DIV><BR>
<A NAME="fig:hostname"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
<!--TOC paragraph Node <TT>config/acls</TT>-->
<H5>Node <TT>config/acls</TT></H5><!--SEC END -->
Via <TT>jabber:x:data</TT> queries to this node it is possible to edit ACLs list.
(See figure <A HREF="#fig:acls">3</A>)
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="confacls.png">
<BR>
<DIV ALIGN=center>Figure 3: Editing of ACLs</DIV><BR>
<A NAME="fig:acls"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
<!--TOC paragraph Node <TT>config/access</TT>-->
<H5>Node <TT>config/access</TT></H5><!--SEC END -->
Via <TT>jabber:x:data</TT> queries to this node it is possible to edit access
rules.<BR>
<BR>
<!--TOC paragraph Node <TT>config/remusers</TT>-->
<H5>Node <TT>config/remusers</TT></H5><!--SEC END -->
Via <TT>jabber:x:data</TT> queries to this node it is possible to remove users. If
removed user is online, then he will be disconnected. Also user-related data
(e.g. his roster) is removed (but appropriate module must be loaded).<BR>
<BR>
<!--TOC subsubsection Node <TT>online users</TT>: List of Online Users-->
<H4><A NAME="htoc20">3.2.2</A> Node <TT>online users</TT>: List of Online Users</H4><!--SEC END -->
<!--TOC subsubsection Node <TT>all users</TT>: List of Registered Users-->
<H4><A NAME="htoc21">3.2.3</A> Node <TT>all users</TT>: List of Registered Users</H4><!--SEC END -->
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="discoallusers.png">
<BR>
<DIV ALIGN=center>Figure 4: Discovery all users</DIV><BR>
<A NAME="fig:discoallusers"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
<!--TOC subsubsection Node <TT>outgoing s2s</TT>: List of Outgoing S2S connections-->
<H4><A NAME="htoc22">3.2.4</A> Node <TT>outgoing s2s</TT>: List of Outgoing S2S connections</H4><!--SEC END -->
<!--TOC subsubsection Node <TT>running nodes</TT>: List of Running <TT>ejabberd</TT> Nodes-->
<H4><A NAME="htoc23">3.2.5</A> Node <TT>running nodes</TT>: List of Running <TT>ejabberd</TT> Nodes</H4><!--SEC END -->
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="discorunnodes.png">
<BR>
<DIV ALIGN=center>Figure 5: Discovery running nodes</DIV><BR>
<A NAME="fig:discorunnodes"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
<!--TOC subsubsection Node <TT>stopped nodes</TT>: List of Stopped Nodes-->
<H4><A NAME="htoc24">3.2.6</A> Node <TT>stopped nodes</TT>: List of Stopped Nodes</H4><!--SEC END -->
TBD<BR>
<BR>
<!--TOC section Distribution-->
<H2><A NAME="htoc25">4</A> Distribution</H2><!--SEC END -->
<A NAME="sec:distribution"></A>
<!--TOC subsection How it works-->
<H3><A NAME="htoc26">4.1</A> How it works</H3><!--SEC END -->
<A NAME="sec:howitworks"></A>
A Jabber domain is served by one or more <TT>ejabberd</TT> 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
<TT>~ejabberd/.erlang.cookie</TT> must be the same on all nodes). This is
needed because all nodes exchange information about connected users, S2S
connections, registered services, etc...<BR>
<BR>
Each <TT>ejabberd</TT> node have following modules:
<UL><LI>
router;
<LI>local router.
<LI>session manager;
<LI>S2S manager;
</UL>
<!--TOC subsubsection Router-->
<H4><A NAME="htoc27">4.1.1</A> Router</H4><!--SEC END -->
This module is the main router of Jabber packets on each node. It routes
them based on their destinations domains. It has two tables: local and global
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 <TT>ejabberd</TT> node or
process. If it does not exists in either tables, then it sent to the S2S
manager.<BR>
<BR>
<!--TOC subsubsection Local Router-->
<H4><A NAME="htoc28">4.1.2</A> Local Router</H4><!--SEC END -->
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.<BR>
<BR>
<!--TOC subsubsection Session Manager-->
<H4><A NAME="htoc29">4.1.3</A> Session Manager</H4><!--SEC END -->
This module routes packets to local users. It searches for what user resource
packet must be sended via presence table. If this resource is connected to
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.<BR>
<BR>
<!--TOC subsubsection S2S Manager-->
<H4><A NAME="htoc30">4.1.4</A> S2S Manager</H4><!--SEC END -->
This module routes packets to other Jabber servers. First, it checks if an
open S2S connection from the domain of the packet source to the domain of
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.<BR>
<BR>
<!--TOC section Built-in Modules-->
<H2><A NAME="htoc31">A</A> Built-in Modules</H2><!--SEC END -->
<A NAME="sec:modules"></A>
<!--TOC subsection Common Options-->
<H3><A NAME="htoc32">A.1</A> Common Options</H3><!--SEC END -->
<A NAME="sec:modcommonopts"></A>
The following options are used by many modules, so they are described in
separate section.<BR>
<BR>
<!--TOC subsubsection Option <TT>iqdisc</TT>-->
<H4><A NAME="htoc33">A.1.1</A> Option <TT>iqdisc</TT></H4><!--SEC END -->
Many modules define handlers for processing IQ queries of different namespaces
to this server or to user (e. g. to <TT>example.org</TT> or to
<TT>user@example.org</TT>). This option defines processing discipline of
these queries. Possible values are:
<DL COMPACT=compact><DT>
<B><TT>no_queue</TT></B><DD> All queries of namespace with this processing
discipline processed immediately. This also means that no other packets can
be processed until finished this. Hence this discipline is not recommended
if processing of query can take relative many time.
<DT><B><TT>one_queue</TT></B><DD> In this case created separate queue for processing
of IQ queries of namespace with this discipline, and processing of this queue
is done in parallel with processing of other packets. This discipline is most
recommended.
<DT><B><TT>parallel</TT></B><DD> In this case for all packets with this discipline
spawned separate Erlang process, so all these packets processed in parallel.
Although spawning of Erlang process have relatively low cost, this can broke
server normal work, because Erlang emulator have limit on number of processes
(32000 by default).
</DL>
Example:
<PRE>
{modules, [
...
{mod_time, [{iqdisc, no_queue}]},
...
]}.
</PRE>
<!--TOC subsubsection Option <TT>host</TT>-->
<H4><A NAME="htoc34">A.1.2</A> Option <TT>host</TT></H4><!--SEC END -->
Some modules may act as services, and wants to have different domain name.
This option explicitly defines this name.<BR>
<BR>
Example:
<PRE>
{modules, [
...
{mod_echo, [{host, "echo.example.org"}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_register</TT>-->
<H3><A NAME="htoc35">A.2</A> <TT>mod_register</TT></H3><!--SEC END -->
<A NAME="sec:modregister"></A>
This module adds support for
<A HREF="http://www.jabber.org/jeps/jep-0077.html">JEP-0077</A> (In-Band
Registration). There is possible to restrict registration via ``register''
access rule. If this rule returns ``deny'' on requested user name, then
registration is not allowed for it.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:register</TT> IQ queries processing
discipline.
</DL>
Example:
<PRE>
% Deny registration for users with too short name
{acl, shortname, {user_glob, "?"}}.
{acl, shortname, {user_glob, "??"}}.
% Another variant: {acl, shortname, {user_regexp, "^..?$"}}.
{access, register, [{deny, shortname},
{allow, all}]}.
{modules, [
...
{mod_register, []},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_roster</TT>-->
<H3><A NAME="htoc36">A.3</A> <TT>mod_roster</TT></H3><!--SEC END -->
<A NAME="sec:modroster"></A>
<!--TOC subsection <TT>mod_configure</TT>-->
<H3><A NAME="htoc37">A.4</A> <TT>mod_configure</TT></H3><!--SEC END -->
<A NAME="sec:modconfigure"></A>
<!--TOC subsection <TT>mod_disco</TT>-->
<H3><A NAME="htoc38">A.5</A> <TT>mod_disco</TT></H3><!--SEC END -->
<A NAME="sec:moddisco"></A>
This module adds support for
<A HREF="http://www.jabber.org/jeps/jep-0030.html">JEP-0030</A> (Service
Discovery).<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>http://jabber.org/protocol/disco#items</TT> and
<TT>http://jabber.org/protocol/disco#info</TT> IQ queries processing discipline.
<DT><B><TT>extra_domains</TT></B><DD> List of domains that will be added to server
items reply
</DL>
Example:
<PRE>
{modules, [
...
{mod_disco, [{extra_domains, ["jit.example.com",
"etc.example.com"]}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_stats</TT>-->
<H3><A NAME="htoc39">A.6</A> <TT>mod_stats</TT></H3><!--SEC END -->
<A NAME="sec:modstats"></A>
This module adds support for
<A HREF="http://www.jabber.org/jeps/jep-0039.html">JEP-0039</A> (Statistics
Gathering).<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>http://jabber.org/protocol/stats</TT> IQ queries
processing discipline.
</DL>
TBD about access.<BR>
<BR>
<!--TOC subsection <TT>mod_vcard</TT>-->
<H3><A NAME="htoc40">A.7</A> <TT>mod_vcard</TT></H3><!--SEC END -->
<A NAME="sec:modvcard"></A>
<!--TOC subsection <TT>mod_offline</TT>-->
<H3><A NAME="htoc41">A.8</A> <TT>mod_offline</TT></H3><!--SEC END -->
<A NAME="sec:modoffline"></A>
<!--TOC subsection <TT>mod_echo</TT>-->
<H3><A NAME="htoc42">A.9</A> <TT>mod_echo</TT></H3><!--SEC END -->
<A NAME="sec:modecho"></A>
<!--TOC subsection <TT>mod_private</TT>-->
<H3><A NAME="htoc43">A.10</A> <TT>mod_private</TT></H3><!--SEC END -->
<A NAME="sec:modprivate"></A>
This module adds support of
<A HREF="http://www.jabber.org/jeps/jep-0049.html">JEP-0049</A> (Private XML
Storage).<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:private</TT> IQ queries processing discipline.
</DL>
<!--TOC subsection <TT>mod_time</TT>-->
<H3><A NAME="htoc44">A.11</A> <TT>mod_time</TT></H3><!--SEC END -->
<A NAME="sec:modtime"></A>
This module answers UTC time on <TT>jabber:iq:time</TT> queries.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:time</TT> IQ queries processing discipline.
</DL>
<!--TOC subsection <TT>mod_version</TT>-->
<H3><A NAME="htoc45">A.12</A> <TT>mod_version</TT></H3><!--SEC END -->
<A NAME="sec:modversion"></A>
This module answers <TT>ejabberd</TT> version on <TT>jabber:iq:version</TT> queries.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:version</TT> IQ queries processing discipline.
</DL>
<!--TOC section I18n/L10n-->
<H2><A NAME="htoc46">B</A> I18n/L10n</H2><!--SEC END -->
<A NAME="sec:i18nl10n"></A>
Many modules supports <TT>xml:lang</TT> attribute inside IQ queries. E. g.
on figure <A HREF="#fig:discorus">6</A> (compare it with figure <A HREF="#fig:disco">1</A>) showed
reply on following query:
<PRE>
<iq id='5'
to='e.localhost'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#items'
xml:lang='ru'/>
</iq>
</PRE>
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="discorus.png">
<BR>
<DIV ALIGN=center>Figure 6: Discovery result when <TT>xml:lang='ru'</TT></DIV><BR>
<A NAME="fig:discorus"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<HR SIZE=2>
<BLOCKQUOTE><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>.
</EM></BLOCKQUOTE>
</BODY>
</HTML>
|
