.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DJabberd::Config 3"
.TH DJabberd::Config 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
DJabberd::Config \- Configuration options in djabberd.conf
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The following describes the format and allowed options of
\&\fIdjabberd.conf\fR.  \fIdjabberd.conf\fR is formatted similarly to Apache
configuration files; that is:
.PP
.Vb 2
\&   # Lines beginning with \*(Aq#\*(Aq are comments
\&   SomeGlobalOption on
\&   
\&   <VHost vhost.example.com>
\&      # Options herein apply only to this vhost
\&   </VHost>
.Ve
.PP
Configuration directives are not case sensitive.  Directives which
take a "boolean" value can be passed any commonly-understood
expression of a boolean; \f(CW1\fR, \f(CW\*(C`y\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`t\*(C'\fR, \f(CW\*(C`on\*(C'\fR,
\&\f(CW\*(C`enable\*(C'\fR, or \f(CW\*(C`enabled\*(C'\fR for truth, or \f(CW0\fR, \f(CW\*(C`n\*(C'\fR, \f(CW\*(C`no\*(C'\fR, \f(CW\*(C`false\*(C'\fR,
\&\f(CW\*(C`f\*(C'\fR, \f(CW\*(C`off\*(C'\fR, \f(CW\*(C`disable\*(C'\fR, or \f(CW\*(C`disabled\*(C'\fR for false.
.SH "GLOBAL CONFIGURATION"
.IX Header "GLOBAL CONFIGURATION"
.ie n .SS "DeclareMonitor ""IP address"""
.el .SS "DeclareMonitor \f(CWIP address\fP"
.IX Subsection "DeclareMonitor IP address"
Declares that a given IP address is used only for checking
connectivity to the server, and should not be logged or assigned an
internal ID.  Useful if you have a \f(CW\*(C`nagios\*(C'\fR host.
.ie n .SS "SSLCertificateKeyFile ""/path/to/key.pem"""
.el .SS "SSLCertificateKeyFile \f(CW/path/to/key.pem\fP"
.IX Subsection "SSLCertificateKeyFile /path/to/key.pem"
Sets the path to the private key file for the server.  This key should
be in PEM format and only readable by the server, and is used to
encrypt traffic to clients to ask for TLS.  If it is not set, the
server will not support TLS.
.ie n .SS "SSLCertificateFile ""/path/to/cert.pem"""
.el .SS "SSLCertificateFile \f(CW/path/to/cert.pem\fP"
.IX Subsection "SSLCertificateFile /path/to/cert.pem"
Sets the path to the certificate file for the server.  This
certificate should be in PEM format, and will be presented to the
clients who ask for TLS.  If it is not set, the server will not
support TLS.
.ie n .SS "SSLCertificateChainFile ""/path/to/cert\-chain.pem"""
.el .SS "SSLCertificateChainFile \f(CW/path/to/cert\-chain.pem\fP"
.IX Subsection "SSLCertificateChainFile /path/to/cert-chain.pem"
Sets the path to the certificate chain file for the server. This is
needed if the server certificate is signed by an intermediate
certificate from a certificate authority. This file should be in PEM
format. It must contain the server's certificate, followed by the
intermediate certificates, then finally the root certificate.
\&\f(CW\*(C`SSLCertificateKeyFile\*(C'\fR and \f(CW\*(C`SSLCertificateFile\*(C'\fR are required when
using this option.
.ie n .SS "OldSSL ""boolean"""
.el .SS "OldSSL \f(CWboolean\fP"
.IX Subsection "OldSSL boolean"
Defaults to off; if set, the server will also listen on port 5223, and
immediately attempt TLS negotiation on all opened connections.  As the
name implies, this is deprecated, and \f(CW\*(C`StartTLS\*(C'\fR stanzas are now the
preferred method to enable TLS communication with clients.
.ie n .SS "UnixDomainSocket ""/path/to/socket"""
.el .SS "UnixDomainSocket \f(CW/path/to/socket\fP"
.IX Subsection "UnixDomainSocket /path/to/socket"
Defaults to unset; if set, specifies the absolute path to a UNIX
domain socket to listen on, in addition to any TCP ports (set by
"ClientPort" and "ServerPort").
.ie n .SS "ClientPort ""port"""
.el .SS "ClientPort \f(CWport\fP"
.IX Subsection "ClientPort port"
Sets the port to listen for client-to-server connections on; defaults
to 5222.  May also specify an IP address to bind to, in addition to a
port, such as \f(CW\*(C`127.0.0.1:5222\*(C'\fR.
.ie n .SS "ServerPort ""port"""
.el .SS "ServerPort \f(CWport\fP"
.IX Subsection "ServerPort port"
Sets the port to listen for server-to-server connection on; defaults
to 5269.  If explicitly set to 0, disables server-to-server listening
for all virtual hosts.  May also specify an IP address to bind to, in
addition to a port, such as \f(CW\*(C`127.0.0.1:5222\*(C'\fR.
.ie n .SS "AdminPort ""port"""
.el .SS "AdminPort \f(CWport\fP"
.IX Subsection "AdminPort port"
Sets the port to listen for administrative connections on; defaults to
off.  For security reasons, you will most certainly want to bind this
to a specific IP address, to prevent access by unauthorized users.
See DJabberd::Connection::Admin.
.ie n .SS "IntraDomainListen ""port"""
.el .SS "IntraDomainListen \f(CWport\fP"
.IX Subsection "IntraDomainListen port"
Sets the port to listen for inter-cluster messages; defaults to off.
Clustering support is still in development.
.ie n .SS "PidFile ""/path/to/pidfile"""
.el .SS "PidFile \f(CW/path/to/pidfile\fP"
.IX Subsection "PidFile /path/to/pidfile"
If set, writes the server's PID to the given file.
.ie n .SS "CaseSensitive ""boolean"""
.el .SS "CaseSensitive \f(CWboolean\fP"
.IX Subsection "CaseSensitive boolean"
If set to a true value, Jabber IDs will be treated as entirely
case-sensitive; defaults to off.  This setting exists purely for
backwards compatibility, as previous versions incorrectly treated
Jabber IDs as case-sensitive.
.ie n .SS "ShareParsers ""boolean"""
.el .SS "ShareParsers \f(CWboolean\fP"
.IX Subsection "ShareParsers boolean"
Defaults to on; controls whether DJabberd::XMLParser objects are
held onto between stanzas.
.SH "VIRTUAL HOST CONFIGURATION"
.IX Header "VIRTUAL HOST CONFIGURATION"
Each virtual host is configured with a block which declares the name
of the virtual host:
.PP
.Vb 3
\&    <VHost jabber.example.com>
\&      # Configuration for jabber.example.com
\&    </VHost>
.Ve
.PP
Virtual hosts can effectively be nested, using the Subdomain block:
.PP
.Vb 6
\&    <VHost jabber.example.com>
\&      # Configuration for jabber.example.com
\&      <Subdomain muc>
\&        # Configuration for muc.jabber.example.com
\&      </Subdomain>
\&    </VHost>
.Ve
.ie n .SS "QuirksMode ""boolean"""
.el .SS "QuirksMode \f(CWboolean\fP"
.IX Subsection "QuirksMode boolean"
Enables or disables "quirks mode"; defaults to on.  See
\&\fIdoc/quirks\-mode.txt\fR for a list of workaround this enables.
.ie n .SS "S2S ""boolean"""
.el .SS "S2S \f(CWboolean\fP"
.IX Subsection "S2S boolean"
Enables or disables server-to-server communication, or "federation."
Defaults to off; note that \f(CW\*(C`/ServerPort\*(C'\fR being set to 0 will override
this configuration.
.ie n .SS "InBandReg ""boolean"""
.el .SS "InBandReg \f(CWboolean\fP"
.IX Subsection "InBandReg boolean"
If set, enables in-band registration of new users; defaults to off.
.ie n .SS "ChildService ""JID"" ""description"""
.el .SS "ChildService \f(CWJID\fP \f(CWdescription\fP"
.IX Subsection "ChildService JID description"
Adds a mapping between a JID on this server, and the given
description; this is used for client service auto-discovery.
.ie n .SS "RequireSSL ""boolean"""
.el .SS "RequireSSL \f(CWboolean\fP"
.IX Subsection "RequireSSL boolean"
If set, requires that clients have negotiated a TLS before
authentication information is sent.
.SH "PLUGIN CONFIGURATION"
.IX Header "PLUGIN CONFIGURATION"
Plugins can only be configured on a per virtual host basis.  Each
plugin defines its own configuration parameters.  Plugins bundled with
the base DJabberd server include:
.IP DJabberd::Delivery::ComponentConnection 4
.IX Item "DJabberd::Delivery::ComponentConnection"
Delivery through a JEP\-0114 component connection.
.IP DJabberd::Delivery::Local 4
.IX Item "DJabberd::Delivery::Local"
Delivery to local users; implicitly added by default.
.IP DJabberd::Delivery::S2S 4
.IX Item "DJabberd::Delivery::S2S"
Delivery via server-to-server connection; implicitly added if "S2S"
is enabled.
.IP DJabberd::Delivery::LocalVHosts 4
.IX Item "DJabberd::Delivery::LocalVHosts"
Delivery to locally configured virtual hosts; implicitly added between
a virtual host and all of its configured subdomains.
.IP DJabberd::RosterStorage::InMemoryOnly 4
.IX Item "DJabberd::RosterStorage::InMemoryOnly"
Store rosters in memory only.  See DJabberd::RosterStorage::SQLite
for a common, more persistent, alternative.
.IP DJabberd::Authen::AllowedUsers 4
.IX Item "DJabberd::Authen::AllowedUsers"
Only allow the given users to connect.
.IP DJabberd::Authen::StaticPassword 4
.IX Item "DJabberd::Authen::StaticPassword"
Set a static password for all users.
.IP DJabberd::Authen::InMemoryOnly 4
.IX Item "DJabberd::Authen::InMemoryOnly"
Store users' correct passwords (set on in-band registration, for
instance) in memory only.
.IP DJabberd::Bot::Admin 4
.IX Item "DJabberd::Bot::Admin"
Provides an alternative interface to DJabberd::Connection::Admin
for certain users.
.IP "DJabberd::SASL and subclasses" 4
.IX Item "DJabberd::SASL and subclasses"
Enables a particular type of SASL negotiation.