Ejabberd2:安装和操作指南

来自Jabber/XMPP中文翻译计划
(版本间的差异)
跳转到: 导航, 搜索
(选项)
(选项)
第586行: 第586行:
 
'''{max_fsm_queue, Size}'''
 
'''{max_fsm_queue, Size}'''
 
:这个选项指定在一个FSM(有限状态机)队列里元素的最大数量. 大概来说, 在每个队列的每个消息展示一个准备发送到它想要的外发的流的XML节. 如果队列大小达到限制(因为, 例如, 节的接收者太慢), 这个FSM和相应的连接(如果有)将被终止并且记录一个出错信息. 这个选项的合理的值依赖于你的硬件配置. 无论如何, 把这个大小设为1000个元素以上应该没什么感觉. 这个选项可被指定给 ejabberd_service 和 ejabberd_c2s listeners, 或也可以全局地指定给 ejabberd_s2s_out. 如果这个选项没有指定给 ejabberd_service 或 ejabberd_c2s listeners, 则使用全局配置的值. 允许的值为整数和 ’undefined’. 缺省值为: ’undefined’.  
 
:这个选项指定在一个FSM(有限状态机)队列里元素的最大数量. 大概来说, 在每个队列的每个消息展示一个准备发送到它想要的外发的流的XML节. 如果队列大小达到限制(因为, 例如, 节的接收者太慢), 这个FSM和相应的连接(如果有)将被终止并且记录一个出错信息. 这个选项的合理的值依赖于你的硬件配置. 无论如何, 把这个大小设为1000个元素以上应该没什么感觉. 这个选项可被指定给 ejabberd_service 和 ejabberd_c2s listeners, 或也可以全局地指定给 ejabberd_s2s_out. 如果这个选项没有指定给 ejabberd_service 或 ejabberd_c2s listeners, 则使用全局配置的值. 允许的值为整数和 ’undefined’. 缺省值为: ’undefined’.  
{max_stanza_size, Size}
+
'''{max_stanza_size, 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 readed data. For example {max_stanza_size, 65536}. The default value is 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.  
+
:这个选项指定一个XML节的近似最大字节数. 近似的, 是因为它计算的精度是以一个被读数据块来的. 例如 {max_stanza_size, 65536}. 缺省值是无穷大. 推荐的值对于c2s连接是 65536,对于s2s连接 是 131072 . s2s 最大节数必须总是比 c2s 的限制更高. 谨慎修改此值,因为如果设置得太小可能导致意料之外的断链.  
{request_handlers, [ {Path, Module}, ...]}
+
'''{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 mod_foo to serve the URIs that start with /a/b/, and you also want mod_http_bind to serve the URIs /http-bind/, use this option: {request_handlers, [{["a", "b"], mod_foo}, {["http-bind"], mod_http_bind}]}  
+
:指定一个或多个 handlers 来伺服HTTP请求. Path是一个字符串列表; 所以以那个 Path 启动的 URIs 将被 Module 伺服. 例如, 你希望 mod_foo to 伺服以 /a/b/ 开头的URIs, 同时你也希望 mod_http_bind 伺服 URIs /http-bind/, 使用这个选项: {request_handlers, [{["a", "b"], mod_foo}, {["http-bind"], mod_http_bind}]}  
{service_check_from, true|false}
+
'''{service_check_from, true|false}'''
    By enabling this option, ejabberd allows the component to send packets with any arbitrary domain in the ’from’ attribute. Note that XEP-0114 requires that the domain must match the hostname of the component. Only enable this option if you are completely sure you need to enable it. Default value: false.  
+
:通过使能这个选项, ejabberd 允许组件发送的包的’from’属性可以是任何随意的域. 注意 XEP-0114 要求域必须和组件的主机名吻合. 只有你确保自己需要的情况下才应该激活这个选项. 缺省值是: false.  
{shaper, none|ShaperName}
+
'''{shaper, none|ShaperName}'''
    This option defines a shaper for the port (see section 3.1.6). The default value is none.  
+
:这个选项为端口定义一个 shaper (3.1.6 ). 缺省值是 none.  
 
starttls
 
starttls
 
     This option specifies that STARTTLS encryption is available on connections to the port. You should also set the certfile option. You can define a certificate file for a specific domain using the global option domain_certfile.  
 
     This option specifies that STARTTLS encryption is available on connections to the port. You should also set the certfile option. You can define a certificate file for a specific domain using the global option domain_certfile.  

2010年6月2日 (三) 14:33的版本


本文的英文原文来自 http://www.process-one.net/en/ejabberd/guide_en

ejabberd 2.1.3 安装和管理指南

目录

绪论

ejabberd是一个用Erlang/OTP语言写的自由和开源的即时消息服务器.

ejabberd是跨平台,分布式, 容错, 并基于开放标准的实时通讯系统.

ejabberd的设计坚若磐石,是一个功能服丰富的XMPP服务器.

ejabberd同时适合小规模布署和超大规模布署, 无论它们是否需要可伸缩性.

关键功能

ejabberd是:

  • 跨平台的: ejabberd可以运行在Microsoft Windows和Unix派生系统,例如Linux, FreeBSD和NetBSD.
  • 分布式的: 你可以在一个集群的机器上运行ejabberd,并且所有的机器都服务于同一个或一些Jabbe域. 当你需要更大容量的时候,你可以简单地增加一个廉价节点到你的集群里. 因此, 你不需要买一个昂贵的高端机器来支持上万个并发用户.
  • 容错: 你可以布署一个ejabberd集群,这样一个正常运行的服务的所有必需信息将被复制到所有节点. 这意味着如果其中一个节点崩溃了, 其他节点将无中断的继续运行. 另外, 也可以‘不停机’增加或更换节点.
  • 易于管理: ejabberd建立于开源的Erlang. 所以你不需要安装外部服数据库, 外部web服务器, 除此以外因为每个东西都已经包含在里面, 并且处于开箱可用状态. 其他管理上的好处包括:
    • 详尽的文档.
    • 便捷的安装程序,包括在Linux, Mac OS X, 以及Windows系统下.
    • Web管理.
    • 共享名册组.
    • 命令行管理工具.
    • 可外部集成的验证机制.
    • 发送匿名消息的能力.
  • 国际化: ejabberd领导国际化. 非常适合全球化. 相关功能包括:
    • 翻译成25种语言.
    • 支持IDNA.
  • 开放标准: ejabberd是的一个完全支持XMPP标准的开源Jabber服务器.
    • 完全兼容XMPP.
    • 基于XML的协议.
    • 支持的协议很多.

额外功能

而且, ejabberd广泛支持的其他先进特性:

  • 模块化
    • 只装在你想要的模块.
    • 在你自己的自定义模块扩展ejabberd.
  • 安全性
    • 支持c2s和s2s连接的SASL和STARTTLS.
    • 支持s2s连接的STARTTLS和Dialback.
    • 可通过HTTPS安全访问的Web管理.
  • 数据库
    • 快速布署的内部数据库(Mnesia).
    • 原生的MySQL支持.
    • 原生的PostgreSQL支持.
    • 支持ODBC数据存储.
    • 支持Microsoft SQL Server.
  • 验证
    • 内部验证.
    • PAM, LDAP 和 ODBC.
    • 外部验证脚本.
  • 其他

安装Installing ejabberd

用ejabberd二进制安装包安装

最简单的安装ejabberd即时消息服务器的方法可能是使用ProcessOne发布的二进制安装包. 已发布的ejabberd版本的二进制安装包在 ProcessOne ejabberd 下载页可以找到: http://www.process-one.net/en/ejabberd/downloads

安装包将布署和配置一个完整的不需要任何依赖的ejabberd服务器.

在 *nix 系统里, 记住启动之前把二进制安装包文件的属性设置成可执行的. 例如:

chmod +x ejabberd-2.0.0_1-linux-x86-installer.bin
./ejabberd-2.0.0_1-linux-x86-installer.bin

ejabberd可以任何时候手工启动, 或在系统启动时由操作系统自动启动.

要手动启动和停止, 可使用安装包建立的桌面快捷方式. 如果机器没有图形系统, 使用在ejabberd安装目录下的 ’bin’ 目录脚本 ’start’ 和 ’stop’.

Windows安装包把ejabberd安装成了系统服务, 同时有一个快捷方式可以启动一个调试控制台给有经验的管理员使用. 如果你想ejabberd在开机时自动启动, 进入Windows服务设置界面并把ejabberd设置成自动启动. 注意Windows服务还是一个开发中的特性, 例如它不能读取ejabberdctl.cfg文件.

在一个 *nix 系统, 如果你想ejabberd在开机时启动成为一个服务, 从 ’bin’目录拷贝 ejabberd.init 到类似 /etc/init.d/ejabberd (取决于你的操作系统的把本). 新建一个系统用户 ejabberd; 它将用于启动该服务的脚本. 然后你可以以root身份调用 /etc/inid.d/ejabberd 来启动服务.

如果ejabberd不能在Windows里正确地启动, 尝试用启动菜单或桌面的快捷方式启动它. 如果window显式错误14001, 解决方案是安装: "Microsoft Visual C++ 2005 SP1 Redistributable Package". 你可以从 http://www.microsoft.com/ 下载它. 然后卸载并再次安装ejabberd.

如果ejabberd不能正确启动并且生成一个崩溃的dump, 表示有严重问题. 在Windows下你可以尝试使用 bin/live.bat 脚本启动ejabberd, 或在其它操作系统执行命令 bin/ejabberdctl live . 用这个办法你可以看到Erlang提供的错误消息并且辨别出确切的问题.

ejabberdctl管理脚本位于 bin 目录. 关于ejabberdctl和用于微调Erlang运行时系统的可配置选项,详见 4.1 章.

用操作系统特定的包安装ejabberd

一些操作系统提供了特定的适应系统体系结构和库的ejabberd包. 它经常也会检查依赖的包并执行基本的配置任务,类似新建初始管理帐号. 例如Debian和Gentoo. 更多信息请查找你的操作系统提供的资源.

那些包经常新建一个脚本,类似 /etc/init.d/ejabberd,在开机时启动和停止 ejabberd 服务.

用CEAN安装ejabberd

CEAN (Comprehensive Erlang Archive Network) 是一个存放了很多Erlang程序二进制包的仓库,包括了ejabberd和它所有的依赖包. 这些二进制包可用于多种不同的系统结构, 所以对于二进制安装包和操作系统的ejabberd包来说,这是一个备选.

根据你如何处理你的CEAN安装而定,你需要新建自己的 ejabberd 启动脚本. 缺省的ejabberdctl脚本位于 ejabberd 的 priv 目录并且用作一个示例.

从源码安装ejabberd

发布ejabberd稳定版的规范方式是源码包. 从源码编译ejabberd在 *nix 系统是非常容易的, 只要你的系统拥有所有的依赖包.

需求

为了在一个‘类Unix’ 操作系统编译ejabberd, 你需要:

  • GNU Make
  • GCC
  • Libexpat 1.95 或更高版本
  • Erlang/OTP R10B-9 或更高版本. 推荐的版本是 R12B-5. 对 R13 的支持是实验性质的.
  • OpenSSL 0.9.6 或更高版本, 用于 STARTTLS, SASL 和 SSL 加密. 可选的, 高度推荐.
  • Zlib 1.2.3 或更高版本, 用于支持流压缩 (XEP-0138). 可选的.
  • Erlang mysql library. 可选的. 用于支持 MySQL 验证或存储. 见 3.2.1 节.
  • Erlang pgsql library. 可选的. 用于支持 PostgreSQL 验证或存储. 见 3.2.3 节.
  • PAM library. 可选的. 用于F 可插拔的验证模块 (PAM). 见 3.1.4 节.
  • GNU Iconv 1.8 或更高版本, 用于 IRC 网关 (mod_irc). 可选的. 在系统里不需要 GNU Libc. 见 3.3.8 节.
  • ImageMagick’s 转换程序. 可选的. 用于 CAPTCHA 挑战. 见 3.1.8 节.
  • exmpp 0.9.2 或更高版本. 可选的. 用于以 XEP-0227 XML文件格式导入/导出用户数据.

下载源码

ejabberd的发布版本在 ProcessOne ejabberd 下载页: http://www.process-one.net/en/ejabberd/downloads

另外, 最新的开发源码可使用命令行从 Git 仓库获得:

git clone git://git.process-one.net/ejabberd/mainline.git ejabberd
cd ejabberd
git checkout -b 2.1.x origin/2.1.x

编译

编译ejabberd可执行以下命令:

./configure
make

编译配置脚本允许很多选项. 要获得所有选项列表执行以下命令:

./configure --help

一些你可能有兴趣修改的选项如下:

--prefix=/

指定运行make install命令时文件将要拷贝的路径.

--enable-user[=USER]

允许普通系统用户执行ejabberdctl脚本 (参见 4.1 节), 读取配置, 读写 spool 目录, 读写 log 目录. 这个帐号的用户和组必须在运行make install之前就存在于机器上. 这个帐号不需要一个暴露的 HOME 目录, 因为缺省将使用 /var/lib/ejabberd/ .

--enable-pam

允许PAM验证方法 (参见 3.1.4 节).

--enable-odbc or --enable-mssql

如果你想使用外部数据库则需要这个选项. 详见 3.2 节.

--enable-full-xml

允许使用基于XML的优化. 例如它将使用 CDATA 来逃逸 XMPP 流中的字符串. 只有你确定你的XMPP客户端有一个全兼容的XML分析器才使用这个选项.

--disable-transient-supervisors

对临时进程禁止使用Erlang/OTP监督.

安装

安装ejabberd到目标目录, 执行以下命令:

make install

注意安装ejabberd的时候你可能需要系统管理员的权限.

缺省的新建文件和目录如下:

/etc/ejabberd/
   配置文件目录:
   ejabberd.cfg
       ejabberd配置文件
   ejabberdctl.cfg
       管理脚本配置文件
   inetrc
       网络DNS配置文件
/lib/ejabberd/
   ebin/
       Erlang二进制文件(*.beam) 
   include/
       Erlang头文件(*.hrl) 
   priv/
       运行时需要的其他文件
       bin/
           可执行程序
       lib/
           二进制系统文件(*.so) 
       msgs/
           翻译文件(*.msgs) 
/sbin/ejabberdctl
   管理脚本(见 4.1 节) 
/share/doc/ejabberd/
   ejabberd文档
/var/lib/ejabberd/
   Spool目录:
   .erlang.cookie
       Erlang cookie文件(见 5.3 节) 
   acl.DCD, ...
       Mnesia数据库spool文件(*.DCD, *.DCL, *.DAT) 
/var/log/ejabberd/
   日志目录(见 7.1 节):
   ejabberd.log
       ejabberd服务日志
   erlang.log
       Erlang/OTP系统日志

启动

你可以使用ejabberdctl命令行管理脚本来启动和停止ejabberd. 如果你提供了配置选项 --enable-user=USER (见 2.4.3 节), 你可以以那个系统帐号或root的身份执行ejabberdctl.

用法示例:

ejabberdctl start
 
ejabberdctl status
The node ejabberd@localhost is started with status: started
ejabberd is running in that node
 
ejabberdctl stop

如果ejabberd无法启动并生成一个崩溃dump, 表示有严重问题. 你可以尝试使用命令ejabberdctl live启动ejabberd来查看由Erlang提供的出错信息并识别出确切的问题.

关于ejabberdctl和微调Erlang运行时系统的可配置选项,详见 4.1 节.

如果你希望ejabberd在开机时以服务身份启动, 拷贝 ejabberd.init 到类似 /etc/init.d/ejabberd 目录(取决于你的操作系统版本). 新建一个系统用户ejabberd; 它将被启动该服务的脚本使用. 然后你可以以root身份在开机时调用 /etc/inid.d/ejabberd 来启动该服务.

BSD的具体说明

在BSD系统编译ejabberd的命令为:

gmake

Sun Solaris的具体说明

你需要一个GNU install, 但是Solaris里没有带. 如果你的Solaris系统是为 blastwave.org 包仓库配置的,这将很容易安装. 确保 /opt/csw/bin 目录在你的 PATH 参数里,然后运行:

pkg-get -i fileutils

如果那个软件名为 ginstall, 修改 ejabberd Makefile 脚本以适应你的系统, 例如:

cat Makefile | sed s/install/ginstall/ > Makefile.gi

最终这样安装ejabberd:

gmake -f Makefile.gi ginstall

Microsoft Windows的具体说明

需求

要在一个Microsoft Windows系统里编译ejabberd, 你需要:

编译

我们假定你将把很多库文件尽可能放在 C:\sdk\ 目录,这样更容易跟踪为了安装ejabberd都需要些什么.

1. 安装 Erlang emulator (例如, 在 C:\sdk\erl5.5.5).

2. 安装 Expat 库文件到 C:\sdk\Expat-2.0.0 目录.

拷贝文件 C:\sdk\Expat-2.0.0\Libs\libexpat.dll 到你的Windows系统目录(例如, C:\WINNT 或 C:\WINNT\System32)

3. 编译和安装 Iconv 库到目录 C:\sdk\GnuWin32.

拷贝文件 C:\sdk\GnuWin32\bin\lib*.dll 到你的Windows系统目录(更多安装指引可在iconv分发版的 README.woe32 文件找到 ).

注意: 也可以不拷贝 libexpat.dll 和 iconv.dll 到Windows系统目录, 而是把目录 C:\sdk\Expat-2.0.0\Libs 和 C:\sdk\GnuWin32\bin 加到 PATH 环境变量去.

4. 安装 OpenSSL 到 C:\sdk\OpenSSL 目录并增加 C:\sdk\OpenSSL\lib\VC 到你的环境变量或拷贝二进制文件到你的系统目录.

5. 安装 ZLib 到 C:\sdk\gnuWin32 目录. 拷贝 C:\sdk\GnuWin32\bin\zlib1.dll 到你的系统目录. 如果你修改了你的 path ,它应该在安装 libiconv 之后已经设置好了.

6. 确保你能从你的路径访问Erlang二进制文件. 例如: set PATH=%PATH%;"C:\sdk\erl5.6.5\bin"

7. 取决于你如果结束实际的库文件安装,你可能需要在文件configure.erl中检查和调整路径.

8. 在目录ejabberd\src中运行:

      configure.bat
      nmake -f Makefile.win32

9. 编辑文件 ejabberd\src\ejabberd.cfg 并运行

      werl -s ejabberd -name ejabberd

新建XMPP管理帐号

你需要一个XMPP帐号并赋予他管理权限来进行ejabberd Web管理:

1. 在你的ejabberd服务器注册一个XMPP帐号, 例如admin1@example.org. 有两个办法来注册一个XMPP帐号:

1.1. 使用ejabberdctl (见 4.1 节):
            ejabberdctl register admin1 example.org FgT5bk3
1.2. 使用一个XMPP客户端进行带内注册(见 3.3.18 节).

2. 编辑ejabberd配置文件来给你创建的XMPP帐号赋予管理权限:

      {acl, admins, {user, "admin1", "example.org"}}.
      {access, configure, [{allow, admins}]}.

你可以赋予管理权限给多个XMPP帐号, 也可以赋予权限给其他XMPP服务器.

3. 重启ejabberd以装载新配置.

4. 用你的浏览器打开Web管理界面(http://server:port/admin/). 确保键入了完整的JID作为用户名(在这个例子里是: admin1@example.org. 你需要加一个后缀的原因是因为ejabberd支持虚拟主机.

升级ejabberd

要升级一个ejabberd安装到一个新版本, 简单地卸载这个旧版本, 然后安装新版本就可以了. 当然, 重要的是配置文件和Mnesia数据库spool目录不能删除.

在它需要的时候ejabberd在启动时会自动更新Mnesia数据表. 如果你也使用一个外部数据库来存储一些模块, 检查新的ejabberd版本的发布备注(release notes)是否指出也需要更新那些表.

配置ejabberd

基本配置

配置文件将在你第一次启动ejabberd时装载. 从该文件获得的内容将被解析并存储到内部的ejabberd数据库. 以后的配置将从数据库装载,并且任何配置文件里的命令都会被添加到数据库里.

注意 ejabberd永远不编辑配置文件. 所以, 使用Web管理修改的配置被存储在数据库, 而不是反射到配置文件. 如果你想那些修改在ejabberd重启后还有效, 你可以同时也修改配置文件, 或删除它的所有内容.

配置文件包含一系列Erlang条款. 以‘%’ 标志开始的行被忽略. 每个条款是一组元素,第一个元素是一个选项的名称, 任何更多的元素则是该选项的值. 如果配置文件不包含类似‘hosts’选项, 旧的存储在数据库的主机名(s)将被启用.

你可以重写存储在数据库的值,通过在配置文件的开始部分增加下面几行:

override_global.
override_local.
override_acls.

有了这些行,旧的全局选项(在一个集群的所有ejabberd节点之间分享), 本地选项(特有的用于本地ejabberd节点的) 以及 ACLs 将在新配置添加之前被移除.

主机名

选项 hosts 定义了包含一个或多个ejabberd将为其提供服务的域名的列表.

语法是:

{hosts, [HostName, ...]}.

示例:

  • 服务一个域:
      {hosts, ["example.org"]}.
  • 服务多个域:
      {hosts, ["example.net", "example.com", "jabber.somesite.org"]}.

虚拟主机

每个虚拟主机的选项可以被独立定义,使用 host_config 选项.

语法是:

{host_config, HostName, [Option, ...]}

示例:

  • 域example.net使用内部验证方法,同时域example.com使用运行在域localhost的LDAP服务器来进行验证:
      {host_config, "example.net", [{auth_method,   internal}]}.
 
      {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, ""}]}.
  • 域example.net使用ODBC来进行验证,同时域example.com使用运行在域localhost和otherhost的LDAP服务器:
      {host_config, "example.net", [{auth_method, 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, ""}]}.

为了给一个虚拟主机指定特定的ejabberd模块, 你可能先为常规模块定义全局模块选项, 之后增加指定的模块给特定的虚拟主机. 为此, 把定义host_config的每个选项改成通用语法

{OptionName, OptionValue}

使用这个语法:

{{add, OptionName}, OptionValue}

在这个例子里,三个虚拟主机有一些相同的模块, 但是特定的虚拟主机也有不同的模块:

%% 这个ejabberd服务器有三个虚拟主机:
{hosts, ["one.example.org", "two.example.org", "three.example.org"]}.
 
%% 这些是所有主机通用模块的配置
{modules,
 [
  {mod_roster,     []},
  {mod_configure,  []},
  {mod_disco,      []},
  {mod_private,    []},
  {mod_time,       []},
  {mod_last,       []},
  {mod_version,    []}
 ]}.
 
%% 增加一些模块给 vhost one:
{host_config, "one.example.org",
 [{{add, modules}, [
                    {mod_echo,       [{host, "echo-service.one.example.org"}]}
                    {mod_http_bind,  []},
                    {mod_logxml,     []}
                   ]
  }
 ]}.
 
%% 只增加一个模块给 vhost two:
{host_config, "two.example.org",
 [{{add, modules}, [
                    {mod_echo,       [{host, "mirror.two.example.org"}]}
                   ]
  }
 ]}.

监听端口

选项 listen 定义ejabberd将监听哪些端口, 地址和网络协议,以及什么服务将运行在它们上面. 这个列表的每个元素是一组以下的元素:

  • 端口号. 还有可选的IP地址和/或一个传输协议.
  • 监听这个端口的模块.
  • TCP socke和监听中的模块的选项.

这个选项的语法是:

{listen, [Listener, ...]}.

定义一个 listener 有很多语法.

{PortNumber, Module, [Option, ...]}

{{PortNumber, IPaddress}, Module, [Option, ...]}

{{PortNumber, TransportProtocol}, Module, [Option, ...]}

{{PortNumber, IPaddress, TransportProtocol}, Module, [Option, ...]}

端口号,IP地址和传输协议

端口号定义哪个端口监听链入的连接. 它可能是一个Jabber/XMPP标准端口(见 5.1 节) 或任何其他合法的端口号.

IP地址可能被表达为一个字符串或一个十进制或十六进制的 Erlang 组. socket 将只监听那个网络接口. 也可能指定一个通用地址, 这样ejabberd将监听所有地址. 取决于IP地址的类型, 将使用IPv4或IPv6. 当没有指定IP地址时, 它将监听所有IPv4网络地址.

一些IP地址的示例值:

  • "0.0.0.0" 监听所有IPv4网络接口. 这是当没有指定IP地址时的缺省值.
  • "::" 监听所有IPv6网络接口
  • "10.11.12.13" 监听IPv4地址 10.11.12.13
  • "::FFFF:127.0.0.1" 是IPv6地址 ::FFFF:127.0.0.1/128
  • {10, 11, 12, 13} 是IPv4地址 10.11.12.13
  • {0, 0, 0, 0, 0, 65535, 32512, 1} 是IPv6地址 ::FFFF:127.0.0.1/128
  • {16#fdca, 16#8ab6, 16#a243, 16#75ef, 0, 0, 0, 1} 是IPv6地址 FDCA:8AB6:A243:75EF::1/128

传输协议可能是 tcp 或 udp. 缺省是 tcp.

监听的模块

可用的模块, 它们的目的以及允许使用哪些选项:

ejabberd_c2s

处理c2s连接.
选项: access, certfile, max_fsm_queue, max_stanza_size, shaper, starttls, starttls_required, tls, zlib

ejabberd_s2s_in

处理链入的s2s连接.
选项: max_stanza_size

ejabberd_service

和一个外部组件的接口(定义于Jabber组件协议(XEP-0114).
选项: access, hosts, max_fsm_queue, shaper, service_check_from

ejabberd_stun

处理STUN绑定请求,定义于 RFC 5389.
选项: certfile

ejabberd_http

处理链入的HTTP连接.
选项: captcha, certfile, http_bind, http_poll, request_handlers, tls, web_admin
选项

这是每个监听的模块允许使用的选项的详细描述:

{access, AccessName}

这个选项定义访问的端口. 缺省值是 all.

{backlog, Value}

这个backlog值定义等待中的连接的队列可以达到的最大长度. 如果服务器想处理很多的新链入连接,这个值需要增加。因为如果队列里没有足够的空间(ejabberd不能立刻接受它们),这些新连接可能被抛弃. 缺省值是 5.

{certfile, Path}

包含缺省的SSL证书的文件的完整路径. 为一个给定的域定义一个证书文件, 使用全局选项 domain_certfile.

{service_check_from, true|false}

这个选项只能被用于ejabberd_service. 它被用于禁止控制一个从外部组件发送的包的from字段. 这个选项要么是 true 要么是 false. 缺省值是 true ,它遵循 XEP-0114.

{hosts, [Hostname, ...], [HostOption, ...]}

连接到ejabberd_service的外部Jabber组件可能服务一个或多个hostnames. 所以你可以为这个组件定义选项 HostOption ; 目前只允许的选项是当组件尝试连接到ejabberd时必需提供的密码: {password, Secret}. 注意你不能在不同的服务里定义同一个 ejabberd_service 组件: 为每个服务增加一个 ejabberd_service , 示例如下.

captcha

简单的web页面,允许一个用户填一个 CAPTCHA 挑战(见 3.1.8 节).

http_bind

这个选项允许支持HTTP绑定(XEP-0124XEP-0206) . HTTP绑定允许通过HTTP请求,从那些不允许从5222端口链出socket的防火墙后面访问ejabberd.
记住你也必须安装和激活mod_http_bind模块.
如果HTTP绑定激活了, 它将可以使用 http://server:port/http-bind/. 注意对HTTP绑定的支持也需要XMPP客户端. 也要注意HTTP绑定对一个基于web的XMPP客户端的主机也是很有意义的,例如JWChat (检查教程来给ejabberd安装JWChat,以及一个 内嵌的本地web服务器Apache).

http_poll

这个选项允许支持HTTP轮询(XEP-0025). HTTP轮询允许通过HTTP请求,从那些不允许从5222端口链出socket的防火墙后面访问ejabberd.
如果激活了HTTP轮询, 它可以用 http://server:port/http-poll/. 注意对HTTP轮询的支持也需要XMPP客户端. 也要注意HTTP轮询对一个基于web的XMPP客户端的主机是很有意义的,例如JWChat.
在没有链入的POST请求时一个客户端会话保持激活状态的最大时间段,可以用全局选项 http_poll_timeout 配置. 缺省值为5分钟. 这个选项可在 ejabberd.cfg 文件里定义, 时间的单位为秒: {http_poll_timeout, 300}.

{max_fsm_queue, Size}

这个选项指定在一个FSM(有限状态机)队列里元素的最大数量. 大概来说, 在每个队列的每个消息展示一个准备发送到它想要的外发的流的XML节. 如果队列大小达到限制(因为, 例如, 节的接收者太慢), 这个FSM和相应的连接(如果有)将被终止并且记录一个出错信息. 这个选项的合理的值依赖于你的硬件配置. 无论如何, 把这个大小设为1000个元素以上应该没什么感觉. 这个选项可被指定给 ejabberd_service 和 ejabberd_c2s listeners, 或也可以全局地指定给 ejabberd_s2s_out. 如果这个选项没有指定给 ejabberd_service 或 ejabberd_c2s listeners, 则使用全局配置的值. 允许的值为整数和 ’undefined’. 缺省值为: ’undefined’.

{max_stanza_size, Size}

这个选项指定一个XML节的近似最大字节数. 近似的, 是因为它计算的精度是以一个被读数据块来的. 例如 {max_stanza_size, 65536}. 缺省值是无穷大. 推荐的值对于c2s连接是 65536,对于s2s连接 是 131072 . s2s 最大节数必须总是比 c2s 的限制更高. 谨慎修改此值,因为如果设置得太小可能导致意料之外的断链.

{request_handlers, [ {Path, Module}, ...]}

指定一个或多个 handlers 来伺服HTTP请求. Path是一个字符串列表; 所以以那个 Path 启动的 URIs 将被 Module 伺服. 例如, 你希望 mod_foo to 伺服以 /a/b/ 开头的URIs, 同时你也希望 mod_http_bind 伺服 URIs /http-bind/, 使用这个选项: {request_handlers, [{["a", "b"], mod_foo}, {["http-bind"], mod_http_bind}]}

{service_check_from, true|false}

通过使能这个选项, ejabberd 允许组件发送的包的’from’属性可以是任何随意的域. 注意 XEP-0114 要求域必须和组件的主机名吻合. 只有你确保自己需要的情况下才应该激活这个选项. 缺省值是: false.

{shaper, none|ShaperName}

这个选项为端口定义一个 shaper (见 3.1.6 节). 缺省值是 none.

starttls

   This option specifies that STARTTLS encryption is available on connections to the port. You should also set the certfile option. You can define a certificate file for a specific domain using the global option domain_certfile. 

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 certfile option. You can define a certificate file for a specific domain using the global option domain_certfile. 

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 RFC 3920: XMPP Core, which can be enabled in ejabberd with the option starttls. If this option is set, you should also set the certfile option. The option tls can also be used in ejabberd_http to support HTTPS. 

web_admin

   This option enables the Web Admin for ejabberd administration which is available at 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. 

zlib

   This option specifies that Zlib stream compression (as defined in XEP-0138) is available on connections to the port. 

There are some additional global options that can be specified in the ejabberd configuration file (outside listen):

{s2s_use_starttls, true|false}

   This option defines whether to use STARTTLS for s2s connections. 

{s2s_certfile, Path}

   Full path to a file containing a SSL certificate. 

{domain_certfile, Domain, Path}

   Full path to the file containing the SSL certificate for a specific domain. 

{outgoing_s2s_options, Methods, Timeout}

   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. 

{s2s_dns_options, [ {Property, Value}, ...]}

   Define properties to use for DNS resolving. Allowed Properties are: timeout in seconds which default value is 10 and retries which default value is 2. 

{s2s_default_policy, allow|deny}

   The default policy for incoming and outgoing s2s connections to other XMPP servers. The default value is allow. 

{{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. 

{s2s_max_retry_delay, Seconds}

   The maximum allowed delay for retry to connect after a failed connection attempt. Specified in seconds. The default value is 300 seconds (5 minutes). 

{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 ejabberd_service and ejabberd_c2s listeners, or also globally for ejabberd_s2s_out. If the option is not specified for ejabberd_service or ejabberd_c2s listeners, the globally configured value is used. The allowed values are integers and ’undefined’. Default value: ’undefined’. 

{route_subdomains, local|s2s}

   Defines if ejabberd must route stanzas directed to subdomains locally (compliant with RFC 3920: XMPP Core), or to foreign server using S2S (compliant with RFC 3920 bis).

Authentication

Access Rules

Shapers

Default Language

CAPTCHA

STUN

Include Additional Configuration Files

Option Macros in Configuration File

个人工具