1
2=head1 NAME
3
4DJabberd::Config - Configuration options in djabberd.conf
5
6=head1 DESCRIPTION
7
8The following describes the format and allowed options of
9F<djabberd.conf>.  F<djabberd.conf> is formatted similarly to Apache
10configuration files; that is:
11
12   # Lines beginning with '#' are comments
13   SomeGlobalOption on
14
15   <VHost vhost.example.com>
16      # Options herein apply only to this vhost
17   </VHost>
18
19Configuration directives are not case sensitive.  Directives which
20take a "boolean" value can be passed any commonly-understood
21expression of a boolean; C<1>, C<y>, C<yes>, C<true>, C<t>, C<on>,
22C<enable>, or C<enabled> for truth, or C<0>, C<n>, C<no>, C<false>,
23C<f>, C<off>, C<disable>, or C<disabled> for false.
24
25=head1 GLOBAL CONFIGURATION
26
27=head2 DeclareMonitor C<IP address>
28
29Declares that a given IP address is used only for checking
30connectivity to the server, and should not be logged or assigned an
31internal ID.  Useful if you have a C<nagios> host.
32
33=head2 SSLCertificateKeyFile C</path/to/key.pem>
34
35Sets the path to the private key file for the server.  This key should
36be in PEM format and only readable by the server, and is used to
37encrypt traffic to clients to ask for TLS.  If it is not set, the
38server will not support TLS.
39
40=head2 SSLCertificateFile C</path/to/cert.pem>
41
42Sets the path to the certificate file for the server.  This
43certificate should be in PEM format, and will be presented to the
44clients who ask for TLS.  If it is not set, the server will not
45support TLS.
46
47=head2 SSLCertificateChainFile C</path/to/cert-chain.pem>
48
49Sets the path to the certificate chain file for the server. This is
50needed if the server certificate is signed by an intermediate
51certificate from a certificate authority. This file should be in PEM
52format. It must contain the server's certificate, followed by the
53intermediate certificates, then finally the root certificate.
54C<SSLCertificateKeyFile> and C<SSLCertificateFile> are required when
55using this option.
56
57=head2 OldSSL C<boolean>
58
59Defaults to off; if set, the server will also listen on port 5223, and
60immediately attempt TLS negotiation on all opened connections.  As the
61name implies, this is deprecated, and C<StartTLS> stanzas are now the
62preferred method to enable TLS communication with clients.
63
64=head2 UnixDomainSocket C</path/to/socket>
65
66Defaults to unset; if set, specifies the absolute path to a UNIX
67domain socket to listen on, in addition to any TCP ports (set by
68L</ClientPort> and L</ServerPort>).
69
70=head2 ClientPort C<port>
71
72Sets the port to listen for client-to-server connections on; defaults
73to 5222.  May also specify an IP address to bind to, in addition to a
74port, such as C<127.0.0.1:5222>.
75
76=head2 ServerPort C<port>
77
78Sets the port to listen for server-to-server connection on; defaults
79to 5269.  If explicitly set to 0, disables server-to-server listening
80for all virtual hosts.  May also specify an IP address to bind to, in
81addition to a port, such as C<127.0.0.1:5222>.
82
83=head2 AdminPort C<port>
84
85Sets the port to listen for administrative connections on; defaults to
86off.  For security reasons, you will most certainly want to bind this
87to a specific IP address, to prevent access by unauthorized users.
88See L<DJabberd::Connection::Admin>.
89
90=head2 IntraDomainListen C<port>
91
92Sets the port to listen for inter-cluster messages; defaults to off.
93Clustering support is still in development.
94
95=head2 PidFile C</path/to/pidfile>
96
97If set, writes the server's PID to the given file.
98
99=head2 CaseSensitive C<boolean>
100
101If set to a true value, Jabber IDs will be treated as entirely
102case-sensitive; defaults to off.  This setting exists purely for
103backwards compatibility, as previous versions incorrectly treated
104Jabber IDs as case-sensitive.
105
106=head2 ShareParsers C<boolean>
107
108Defaults to on; controls whether L<DJabberd::XMLParser> objects are
109held onto between stanzas.
110
111
112
113=head1 VIRTUAL HOST CONFIGURATION
114
115Each virtual host is configured with a block which declares the name
116of the virtual host:
117
118    <VHost jabber.example.com>
119      # Configuration for jabber.example.com
120    </VHost>
121
122Virtual hosts can effectively be nested, using the Subdomain block:
123
124    <VHost jabber.example.com>
125      # Configuration for jabber.example.com
126      <Subdomain muc>
127        # Configuration for muc.jabber.example.com
128      </Subdomain>
129    </VHost>
130
131=head2 QuirksMode C<boolean>
132
133Enables or disables "quirks mode"; defaults to on.  See
134F<doc/quirks-mode.txt> for a list of workaround this enables.
135
136=head2 S2S C<boolean>
137
138Enables or disables server-to-server communication, or "federation."
139Defaults to off; note that C</ServerPort> being set to 0 will override
140this configuration.
141
142=head2 InBandReg C<boolean>
143
144If set, enables in-band registration of new users; defaults to off.
145
146=head2 ChildService C<JID> C<description>
147
148Adds a mapping between a JID on this server, and the given
149description; this is used for client service auto-discovery.
150
151=head2 RequireSSL C<boolean>
152
153If set, requires that clients have negotiated a TLS before
154authentication information is sent.
155
156
157
158=head1 PLUGIN CONFIGURATION
159
160Plugins can only be configured on a per virtual host basis.  Each
161plugin defines its own configuration parameters.  Plugins bundled with
162the base DJabberd server include:
163
164=over
165
166=item L<DJabberd::Delivery::ComponentConnection>
167
168Delivery through a JEP-0114 component connection.
169
170=item L<DJabberd::Delivery::Local>
171
172Delivery to local users; implicitly added by default.
173
174=item L<DJabberd::Delivery::S2S>
175
176Delivery via server-to-server connection; implicitly added if L</S2S>
177is enabled.
178
179=item L<DJabberd::Delivery::LocalVHosts>
180
181Delivery to locally configured virtual hosts; implicitly added between
182a virtual host and all of its configured subdomains.
183
184=item L<DJabberd::RosterStorage::InMemoryOnly>
185
186Store rosters in memory only.  See L<DJabberd::RosterStorage::SQLite>
187for a common, more persistent, alternative.
188
189=item L<DJabberd::Authen::AllowedUsers>
190
191Only allow the given users to connect.
192
193=item L<DJabberd::Authen::StaticPassword>
194
195Set a static password for all users.
196
197=item L<DJabberd::Authen::InMemoryOnly>
198
199Store users' correct passwords (set on in-band registration, for
200instance) in memory only.
201
202=item L<DJabberd::Bot::Admin>
203
204Provides an alternative interface to L<DJabberd::Connection::Admin>
205for certain users.
206
207=item L<DJabberd::SASL> and subclasses
208
209Enables a particular type of SASL negotiation.
210
211=back
212
213=cut
214
215