diff options
Diffstat (limited to 'doc/guide.tex')
| -rw-r--r-- | doc/guide.tex | 142 |
1 files changed, 138 insertions, 4 deletions
diff --git a/doc/guide.tex b/doc/guide.tex index 21e66a084..5f8d13de9 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -93,6 +93,7 @@ \newcommand{\modsharedroster}{\module{mod\_shared\_roster}} \newcommand{\modsharedrosterldap}{\module{mod\_shared\_roster\_ldap}} \newcommand{\modsic}{\module{mod\_sic}} +\newcommand{\modsip}{\module{mod\_sip}} \newcommand{\modstats}{\module{mod\_stats}} \newcommand{\modtime}{\module{mod\_time}} \newcommand{\modvcard}{\module{mod\_vcard}} @@ -871,9 +872,11 @@ The available modules, their purpose and the options allowed by each one are: \titem{\texttt{ejabberd\_c2s}} Handles c2s connections.\\ Options: \texttt{access}, \texttt{certfile}, \texttt{ciphers}, \texttt{protocol\_options} - \texttt{max\_fsm\_queue}, - \texttt{max\_stanza\_size}, \texttt{shaper}, - \texttt{starttls}, \texttt{starttls\_required}, \texttt{tls}, + \texttt{max\_ack\_queue}, \texttt{max\_fsm\_queue}, + \texttt{max\_stanza\_size}, \texttt{resend\_on\_timeout}, + \texttt{resume\_timeout}, \texttt{shaper}, + \texttt{starttls}, \texttt{starttls\_required}, + \texttt{stream\_management}, \texttt{tls}, \texttt{zlib}, \texttt{tls\_compression} \titem{\texttt{ejabberd\_s2s\_in}} Handles incoming s2s connections.\\ @@ -883,6 +886,10 @@ The available modules, their purpose and the options allowed by each one are: (as defined in the Jabber Component Protocol (\xepref{0114}).\\ Options: \texttt{access}, \texttt{hosts}, \texttt{max\_fsm\_queue}, \texttt{service\_check\_from}, \texttt{shaper\_rule} + \titem{\texttt{ejabberd\_sip}} + Handles SIP requests as defined in + \footahref{http://tools.ietf.org/html/rfc3261}{RFC 3261}.\\ + Options: \texttt{certfile}, \texttt{tls} \titem{\texttt{ejabberd\_stun}} Handles STUN Binding requests as defined in \footahref{http://tools.ietf.org/html/rfc5389}{RFC 5389}.\\ @@ -967,6 +974,13 @@ This is a detailed description of each option allowed by the listening modules: \term{http\_poll\_timeout}. The default value is five minutes. The option can be defined in \term{ejabberd.yml}, expressing the time in seconds: \verb|{http_poll_timeout, 300}.| + \titem{max\_ack\_queue: Size} + This option specifies the maximum number of unacknowledged stanzas + queued for possible retransmission if \term{stream\_management} is + enabled. When the limit is reached, the first stanza is dropped from + the queue before adding the next one. This option can be specified + for \term{ejabberd\_c2s} listeners. The allowed values are positive + integers and \term{infinity}. Default value: \term{500}. \titem{max\_fsm\_queue: Size} This option specifies the maximum number of elements in the queue of the FSM (Finite State Machine). @@ -1004,6 +1018,23 @@ request_handlers: /"a"/"b": mod_foo /"http-bind": mod_http_bind \end{verbatim} + \titem{resend\_on\_timeout: true|false} + If \term{stream\_management} is enabled and this option is set to + \term{true}, any stanzas that weren't acknowledged by the client + will be resent on session timeout. This behavior might often be + desired, but could have unexpected results under certain + circumstances. For example, a message that was sent to two resources + might get resent to one of them if the other one timed out. + Therefore, the default value for this option is \term{false}, which + tells ejabberd to generate an error message instead. The option can + be specified for \term{ejabberd\_c2s} listeners. + \titem{resume\_timeout: Seconds} + This option configures the number of seconds until a session times + out if the connection is lost. During this period of time, a client + may resume the session if \term{stream\_management} is enabled. This + option can be specified for \term{ejabberd\_c2s} listeners. Setting + it to \term{0} effectively disables session resumption. The default + value is \term{300}. \titem{service\_check\_from: true|false} \ind{options!service\_check\_from} This option can be used with \term{ejabberd\_service} only. @@ -1027,6 +1058,10 @@ request_handlers: 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{stream\_management: true|false} + Setting this option to \term{false} disables ejabberd's support for + \ind{protocols!XEP-0198: Stream Management}. It can be specified for + \term{ejabberd\_c2s} listeners. The default value is \term{true}. \titem{timeout: Integer} \ind{options!timeout} Timeout of the connections, expressed in milliseconds. Default: 5000 @@ -1961,7 +1996,7 @@ listen: \ejabberd{} is able to act as a stand-alone STUN server (\footahref{http://tools.ietf.org/html/rfc5389}{RFC 5389}). Currently only Binding usage -is supported. In that role \ejabberd{} helps clients with Jingle ICE (\xepref{0176}) support to discover their external addresses and ports. +is supported. In that role \ejabberd{} helps clients with ICE (\footahref{http://tools.ietf.org/html/rfc5245}{RFC 5245}) or Jingle ICE (\xepref{0176}) support to discover their external addresses and ports. You should configure \term{ejabberd\_stun} listening module as described in \ref{listened} section. If \option{certfile} option is defined, \ejabberd{} multiplexes TCP and @@ -2001,6 +2036,61 @@ _stun._tcp IN SRV 0 0 3478 stun.example.com. _stuns._tcp IN SRV 0 0 5349 stun.example.com. \end{verbatim} +\makesubsection{sip}{SIP} +\ind{options!sip}\ind{sip} + +\ejabberd{} has built-in SIP support. In order to activate it you need to add +listeners for it, configure DNS properly and enable \modsip{} for +the desired virtual host. + +To add a listener you should configure \term{ejabberd\_sip} listening module as +described in \ref{listened} section. If option \option{tls} is specified, option +\option{certfile} must be specified as well, otherwise incoming TLS connections would fail. + +Example configuration with standard ports +(as per \footahref{http://tools.ietf.org/html/rfc3261}{RFC 3261}): +\begin{verbatim} +listen: + ... + - + port: 5060 + transport: udp + module: ejabberd_sip + - + port: 5060 + module: ejabberd_sip + - + port: 5061 + module: ejabberd_sip + tls: true + certfile: "/etc/ejabberd/server.pem" + ... +\end{verbatim} + +Note that there is no StartTLS support in SIP and \footahref{http://en.wikipedia.org/wiki/Server\_Name\_Indication}{SNI} support is somewhat tricky, so for TLS you have to configure +different virtual hosts on different ports if you have different certificate files for them. + +Next you need to configure DNS SIP records for your virtual domains. +Refer to \footahref{http://tools.ietf.org/html/rfc3263}{RFC 3263} for the detailed explanation. +Simply put, you should add NAPTR and SRV records for your domains. +Skip NAPTR configuration if your DNS provider doesn't support this type of records. +It's not fatal, however, highly recommended. + +Example configuration of NAPTR records: +\begin{verbatim} +example.com IN NAPTR 10 0 "s" "SIPS+D2T" "" _sips._tcp.example.com. +example.com IN NAPTR 20 0 "s" "SIP+D2T" "" _sip._tcp.example.com. +example.com IN NAPTR 30 0 "s" "SIP+D2U" "" _sip._udp.example.com. +\end{verbatim} + +Example configuration of SRV records with standard ports +(as per \footahref{http://tools.ietf.org/html/rfc3261}{RFC 3261}): +\begin{verbatim} +_sip._udp IN SRV 0 0 5060 sip.example.com. +_sip._tcp IN SRV 0 0 5060 sip.example.com. +_sips._tcp IN SRV 0 0 5061 sip.example.com. +\end{verbatim} + \makesubsection{includeconfigfile}{Include Additional Configuration Files} \ind{options!includeconfigfile}\ind{includeconfigfile} @@ -2578,6 +2668,7 @@ The following table lists all modules included in \ejabberd{}. \hline \ahrefloc{modsharedroster}{\modsharedroster{}} & Shared roster management & \modroster{} \\ \hline \ahrefloc{modsharedrosterldap}{\modsharedrosterldap{}} & LDAP Shared roster management & \modroster{} \\ \hline \ahrefloc{modsic}{\modsic{}} & Server IP Check (\xepref{0279}) & \\ + \hline \ahrefloc{modsip}{\modsip{}} & SIP Registrar/Proxy (\footahref{http://tools.ietf.org/html/rfc3261}{RFC 3261}) & \term{ejabberd\_sip} \\ \hline \ahrefloc{modstats}{\modstats{}} & Statistics Gathering (\xepref{0039}) & \\ \hline \ahrefloc{modtime}{\modtime{}} & Entity Time (\xepref{0202}) & \\ \hline \ahrefloc{modvcard}{\modvcard{}} & vcard-temp (\xepref{0054}) & \\ @@ -4618,6 +4709,49 @@ Options: \iqdiscitem{\ns{urn:xmpp:sic:0}} \end{description} +\makesubsection{modsip}{\modsip{}} +\ind{modules!\modsip{}} +This module adds SIP proxy/registrar support for the corresponding virtual host. +Note that it is not enough to just load this module only. You should also configure +listeners and DNS records properly. See section \ref{sip} for the full explanation. + +Example configuration: +\begin{verbatim} +modules: + ... + mod_sip: {} + ... +\end{verbatim} + +Options: +\begin{description} +\titem{via: [\{type: Type, host: Host, port: Port\}]}\ind{options!via}With +this option for every \term{Type} you can specify \term{Host} and \term{Port} +to set in \term{Via} header of outgoing SIP messages, where \term{Type} can be +\term{udp}, \term{tcp} or \term{tls}. \term{Host} is a string and \term{Port} is +a non negative integer. This is useful if you're running your server in a non-standard +network topology. Example configuration: +\begin{verbatim} +modules: + ... + mod_sip: + via: + - + type: tls + host: "sip-tls.example.com" + port: 5061 + - + type: tcp + host: "sip-tcp.example.com" + port: 5060 + - + type: udp + host: "sip-udp.example.com" + port: 5060 + ... +\end{verbatim} +\end{description} + \makesubsection{modstats}{\modstats{}} \ind{modules!\modstats{}}\ind{protocols!XEP-0039: Statistics Gathering}\ind{statistics} |