Ejabberd2:安装和操作指南
本文的英文原文来自 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.
- 外部验证脚本.
- 其他
- 支持虚拟主机.
- XML流压缩 (XEP-0138).
- 统计 (XEP-0039).
- 支持IPv6的c2s和s2s连接.
- 支持集群和HTML日志的多用户聊天模块.
- 基于用户vCards的用户目录.
- 支持基于PubSub的个人事件的发行-订阅组件.
- 支持web客户端: HTTP轮询和HTTP绑定(BOSH)服务.
- IRC网关.
- 组件支持: 安装特定网关之后和外部网络的接口，如 AIM, ICQ 和 MSN.
安装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的命令为:
gmakeSun 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, 你需要:
- MS Visual C++ 6.0 Compiler
- Erlang/OTP R11B-5
- Expat 2.0.0或更高版本
- GNU Iconv 1.9.2 (可选的)
- Shining Light OpenSSL 0.9.8d或更高版本(使能SSL连接)
- Zlib 1.2.3或更高版本
编译
我们假定你将把很多库文件尽可能放在 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.win329. 编辑文件 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
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-0124和XEP-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
- 这个选项定义 STARTTLS 加密可以用于连接某端口. 你应该也设置 certfile 选项. 你可以使用全局选项 domain_certfile为一个特定的域定义一个证书文件.
starttls_required
- 这个选项指定在连接到某端口时 STARTTLS 加密是必需的. 不允许不加密的连接. 你应该也设置 certfile 选项. 你可以使用全局选项 domain_certfile为一个特定的域定义一个证书文件.
tls
- 这个选项指定某端口的通讯在连接之后将立刻使用SSL加密. 这是一个早期的Jabber软件使用的传统加密方法, 通常是在端口 5223 ，用于客户端－服务器通讯. 但是这个方法今天已经被藐视和不推荐了. 可取的加密方法是在端口5222使用 STARTTLS , 定义于 RFC 3920: XMPP核心, 这个方法在 ejabberd 里可以使用 starttls 选项来激活. 如果这个选项被设置了, 你应该同时设置 certfile 选项. 选项 tls 也可用于 ejabberd_http 以支持 HTTPS.
web_admin
- 这个选项激活为ejabberd管理激活 Web Admin ，可在 http://server:port/admin/ 访问. 登录和密码就是某个你在‘configure’ access rule里授权了的已注册用户的用户名和密码.
zlib
- 这个选项指定在某端口的连接可使用 Zlib 流压缩(定义于 XEP-0138).
有一些额外的全局选项(listen之外的)可以在ejabberd配置文件指定:
{s2s_use_starttls, true|false}
- 这个选项定义是否为s2s连接使用 STARTTLS .
{s2s_certfile, Path}
- 一个包含SSL证书的文件的全路径.
{domain_certfile, Domain, Path}
- 包含一个特定域的SSL证书的文件的全路径.
{outgoing_s2s_options, Methods, Timeout}
- 指定用哪个地址尝试连接, 以什么顺序, 以及连接超时时间(以毫秒计). 缺省第一次尝试连接使用IPv4地址, 如果失败它将尝试使用IPv6, 超时时间为 10000 毫秒.
{s2s_dns_options, [ {Property, Value}, ...]}
- 指定用于DNS解析的 properties. 允许的 Properties 有: 以秒计的缺省值为10的 timeout 和缺省值为2的重试次数.
{s2s_default_policy, allow|deny}
- 对于链入和链出到其他XMPP服务器的s2s连接的缺省策略. 缺省值是 allow.
{{s2s_host, Host}, allow|deny}
- 指定是否允许一个特定远程主机的链入和链出s2s连接. 这允许限制 ejabberd 只和少数信任的服务器建立s2s连接, 或禁止一些特定的服务器.
{s2s_max_retry_delay, Seconds}
- 连接失败后重试连接的最大允许延迟时间. 以秒计算. 这个缺省值是 300 秒 (5分钟).
{max_fsm_queue, Size}
- 这个选项指定FSM(有限状态机)的队列里元素的最大数量. 大概来说, 在这些队列里每个消息展示一个准备发送到它想要的外发的流的XML节. 如果队列大小达到限制(因为, 例如, 节的接收者太慢), 这个FSM和相应的连接(如果有)将被终止并且记录一个出错信息. 这个选项的合理的值依赖于你的硬件配置. 无论如何, 把这个大小设为1000个元素以上应该没什么感觉. 这个选项可被指定给 ejabberd_service 和 ejabberd_c2s listeners, 或也可以全局地指定给 ejabberd_s2s_out. 如果这个选项没有指定给 ejabberd_service 或 ejabberd_c2s listeners, 则使用全局配置的值. 允许的值为整数和 ’undefined’. 缺省值为: ’undefined’.
{route_subdomains, local|s2s}
- 定义 ejabberd 是必须直接把节从本地路由到子域 subdomains(兼容 RFC 3920: XMPP核心), 还是使用S2S到外部服务器 (兼容 RFC 3920 bis).
示例
例如, 以下简单配置定义:
- 有三个域. 缺省证书文件是 server.pem. 然而, 连接到域example.com的c2s和s2s使用文件example_com.pem.
- 端口 5222 使用 STARTTLS 监听 c2s 连接, 同时允许简单连接用于旧的客户端.
- 端口 5223 使用旧的 SSL 监听 c2s 连接 .
- 端口 5269 使用 STARTTLS 监听 s2s 连接. 这个socket设为IPv6而不是IPv4.
- 端口 3478 监听通过 UDP 发出的 STUN 请求 .
- 端口 5280 监听 HTTP 请求, 并伺服 HTTP 轮询服务.
- 端口 5281 监听 HTTP 请求, 并使用 HTTPS 伺服 Web Admin (见 4.3 节). 这个socket只监听来自IP地址127.0.0.1的连接.
{hosts, ["example.com", "example.org", "example.net"]}. {listen, [ {5222, ejabberd_c2s, [ {access, c2s}, {shaper, c2s_shaper}, starttls, {certfile, "/etc/ejabberd/server.pem"}, {max_stanza_size, 65536} ]}, {5223, ejabberd_c2s, [ {access, c2s}, {shaper, c2s_shaper}, tls, {certfile, "/etc/ejabberd/server.pem"}, {max_stanza_size, 65536} ]}, {{5269, "::"}, ejabberd_s2s_in, [ {shaper, s2s_shaper}, {max_stanza_size, 131072} ]}, {{3478, udp}, ejabberd_stun, []}, {5280, ejabberd_http, [ http_poll ]}, {{5281, "127.0.0.1"}, ejabberd_http, [ web_admin, tls, {certfile, "/etc/ejabberd/server.pem"}, ]} ] }. {s2s_use_starttls, true}. {s2s_certfile, "/etc/ejabberd/server.pem"}. {domain_certfile, "example.com", "/etc/ejabberd/example_com.pem"}.
在这个例子, 定义了以下配置:
- 端口 5222 (所有IPv4地址)和端口5223 (SSL, IP 192.168.0.1 和 fdca:8ab6:a243:75ef::1)监听c2s连接 ，并禁止名为 ‘bad’的用户.
- 端口 5269 (所有IPv4地址)为了允许安全通讯而使用STARTTLS监听s2s连接. 远程XMPP服务器的链入和链出连接被禁止, 只有两个服务器可以连接: "jabber.example.org" 和 "example.com".
- 端口 5280 在所有的IPv4地址伺服 Web Admin 和 HTTP Polling 服务. 注意它也可能在不同端口伺服它们. 4.3 节的第二个例子展示了怎样确切的做法.
- 除了管理员，所有用户的通讯流量限制为 1,000 Bytes/second
- AIM 网关 aim.example.org 被连接到localhost IP 地址(127.0.0.1 and ::1)的 5233 端口 ， 连接密码为‘aimsecret’.
- ICQ 网关 JIT (icq.example.org and sms.example.org) 被以密码‘jitsecret’连接到端口 5234 .
- MSN 网关 msn.example.org 被以密码‘msnsecret’连接到端口 5235 .
- Yahoo! 网关 yahoo.example.org 被以密码‘yahoosecret’连接到端口 5236 .
- Gadu-Gadu 网关 gg.example.org 被以密码‘ggsecret’连接到端口 5237 .
- Jabber Mail 组件 jmc.example.org 被以密码‘jmsecret’连接到端口 5238 .
- 服务自定义允许特别的选项用来逃避对从这个组件发送的包里检查from属性. 这个组件可以从服务器以任何用户的身份发送包, 或者甚至以任何服务器的身份.
{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, {192, 168, 0, 1}}, ejabberd_c2s, [ {access, c2s}, ssl, {certfile, "/path/to/ssl.pem"} ]}, {{5223, {16#fdca, 16#8ab6, 16#a243, 16#75ef, 0, 0, 0, 1}}, ejabberd_c2s, [ {access, c2s}, ssl, {certfile, "/path/to/ssl.pem"} ]}, {5269, ejabberd_s2s_in, []}, {{5280, {0, 0, 0, 0}}, ejabberd_http, [ http_poll, web_admin ]}, {{5233, {127, 0, 0, 1}}, ejabberd_service, [ {hosts, ["aim.example.org"], [{password, "aimsecret"}]} ]}, {{5233, "::1"}, ejabberd_service, [ {hosts, ["aim.example.org"], [{password, "aimsecret"}]} ]}, {5234, ejabberd_service, [{hosts, ["icq.example.org", "sms.example.org"], [{password, "jitsecret"}]}]}, {5235, ejabberd_service, [{hosts, ["msn.example.org"], [{password, "msnsecret"}]}]}, {5236, ejabberd_service, [{hosts, ["yahoo.example.org"], [{password, "yahoosecret"}]}]}, {5237, ejabberd_service, [{hosts, ["gg.example.org"], [{password, "ggsecret"}]}]}, {5238, ejabberd_service, [{hosts, ["jmc.example.org"], [{password, "jmcsecret"}]}]}, {5239, ejabberd_service, [{hosts, ["custom.example.org"], [{password, "customsecret"}]}, {service_check_from, false}]} ] }. {s2s_use_starttls, true}. {s2s_certfile, "/path/to/ssl.pem"}. {s2s_default_policy, deny}. {{s2s_host,"jabber.example.org"}, allow}. {{s2s_host,"example.com"}, allow}.
注意, 对基于 jabberd14 或 WPJabber 的服务，你不得不做一个网关日志并通过它们本身做 XDB :
<!--
You have to add elogger and rlogger entries here when using ejabberd.
In this case the transport will do the logging.
-->
<log id='logger'>
<host/>
<logtype/>
<format>%d: [%t] (%h): %s</format>
<file>/var/log/jabber/service.log</file>
</log>
<!--
Some XMPP server implementations do not provide
XDB services (for example, jabberd2 and ejabberd).
xdb_file.so is loaded in to handle all XDB requests.
-->
<xdb id="xdb">
<host/>
<load>
<!-- this is a lib of wpjabber or jabberd14 -->
<xdb_file>/usr/lib/jabber/xdb_file.so</xdb_file>
</load>
<xdb_file xmlns="jabber:config:xdb_file">
<spool><jabberd:cmdline flag='s'>/var/spool/jabber</jabberd:cmdline></spool>
</xdb_file>
</xdb>验证
选项 auth_method 定义了用于验证用户的验证方法. 语法是:
{auth_method, [Method, ...]}.
ejabberd支持以下验证方法:
- internal (缺省) — 见 3.1.4. 节
- external — 有一些示例验证代码.
- ldap — 见 3.2.5. 节
- odbc — 见 3.2.1, 3.2.3, 3.2.2 和 3.2.4. 节
- anonymous — 见 3.1.4. 节
- pam — 见 3.1.4. 节
只有internal 和 odbc 方法支持新建帐号.
内部
ejabberd使用它的内部Mnesia数据库作为缺省的验证方法. 这个值 internal 将允许内部验证方法.
例子:
- 在example.org使用内部验证, 在example.net使用LDAP验证:
{host_config, "example.org", [{auth_method, [internal]}]}. {host_config, "example.net", [{auth_method, [ldap]}]}.
- 在所有虚拟主机使用内部验证:
{auth_method, internal}.
SASL匿名和匿名登录
这个值 anonymous 将允许内部验证方法.
匿名验证方法可以由以下选项配置. 记住你可以用 host_config 选项设置虚拟主机个别特有的选项(见 3.1.2 节). 注意关于SASL匿名和匿名登录配置也有一个详细的教程 .
{allow_multiple_connections, false|true}
- 这个选项只用于匿名模式已经被允许的时候. 设置它为 true 意味着在匿名登录模式里，如果使用不同的资源来连接，同样的用户名可以被使用多次. 这个选项只在非常特殊的情况下有用. 缺省值是 false.
{anonymous_protocol, sasl_anon | login_anon | both}
- sasl_anon 意味着将使用 SASL 匿名方法. login_anon 意味着将使用匿名登录方法. both 意味着SASL匿名和匿名登录都允许.
那些选项为每个虚拟主机定义的选项 host_config 参数 (见 3.1.2 节).
例子:
- 在所有虚拟主机上允许匿名登录:
{auth_method, [anonymous]}. {anonymous_protocol, login_anon}.
- 类似前例, 但限于 public.example.org:
{host_config, "public.example.org", [{auth_method, [anonymous]}, {anonymous_protocol, login_anon}]}.
- 在一个虚拟主机允许匿名登录和内部验证:
{host_config, "public.example.org", [{auth_method, [internal,anonymous]}, {anonymous_protocol, login_anon}]}.
- 在一个虚拟主机允许SASL匿名:
{host_config, "public.example.org", [{auth_method, [anonymous]}, {anonymous_protocol, sasl_anon}]}.
- 在一个虚拟主机允许SASL匿名和匿名登录:
{host_config, "public.example.org", [{auth_method, [anonymous]}, {anonymous_protocol, both}]}.
- 在一个虚拟主机允许SASL匿名, 匿名登录, 和内部验证:
{host_config, "public.example.org", [{auth_method, [internal,anonymous]}, {anonymous_protocol, both}]}.
PAM验证
ejabberd支持通过可插拔的验证模块(PAM)来验证. PAM 目前在 AIX, FreeBSD, HP-UX, Linux, Mac OS X, NetBSD 和 Solaris里都支持. PAM 验证缺省是被禁止的, 所以你不得不使用 PAM support enabled 选项来配置并编译ejabberd:
./configure --enable-pam && make install
选项:
{pam_service, Name}
- 这个选项定义了PAM服务名. 缺省是 "ejabberd". 更多信息请参考你的操作系统的 PAM 文档.
例子:
{auth_method, [pam]}. {pam_service, "ejabberd"}.
虽然很容易在ejabberd里配置PAM支持, PAM本身介绍了一些安全问题:
- 为执行PAM验证，ejabberd使用名为 epam 的外部C程序. 缺省的, 它位于 /var/lib/ejabberd/priv/bin/ 目录. 在这个例子里，如果你的PAM模块要求root权限(例如pam_unix.so)，你不得不把它设为root可执行. 你也不得不为ejabberd赋予访问这个文件的权限，并移除所有其他权限. 以root权限执行以下命令:
chown root:ejabberd /var/lib/ejabberd/priv/bin/epam chmod 4750 /var/lib/ejabberd/priv/bin/epam
- 确保你已在你的系统安装了最新版本的PAM. 一些旧版本的PAM模块会导致内存溢出. 如果你不能使用最新版本, 你可以定期杀掉(1) epam 进程以减少它的内存消耗: ejabberd将立刻重启这个进程.
- epam程序在验证失败时尝试关闭延迟. 然而, 一些PAM模块忽略这个行为并依靠它们自己的配置选项. 你可以新建一个配置文件ejabberd.pam. 这个例子展示如何在pam_unix.so模块关闭延迟:
#%PAM-1.0
auth sufficient pam_unix.so likeauth nullok nodelay
account sufficient pam_unix.so- 这不是一个已准备好使用的配置文件: 当你建立你自己的PAM配置时，你必须示意使用它. 注意如果你想在PAM配置文见里设置在验证失败时禁止延迟, 你不得不限制访问这个文件, 这样恶意用户就不能使用你的配置来执行暴力攻击.
- 你可能希望只允许特定用户登录访问. pam_listfile.so 模块提供这个功能.
- 如果你使用 pam_winbind 来对一个Windows Active Directory授权, 那么 /etc/nssswitch.conf 必须被配置成使用winbind.
访问规则
ACL定义
在ejabberd里访问控制是通过访问控制列表(ACLs)来实现的. 配置文件中ACLs的声明语法如下:
{acl, ACLName, ACLValue}.
ACLValue 可以是以下之一:
all
- 匹配所有JIDs. 例子:
{acl, all, all}.
{user, Username}
- 匹配第一个虚拟主机，名字为 Username 的用户. 例子:
{acl, admin, {user, "yozhik"}}.
{user, Username, Server}
- 匹配JID为Username@Server加任何资源的用户. 例子:
{acl, admin, {user, "yozhik", "example.org"}}.
{server, Server}
- 匹配从服务器Server来的任何JID. 例子:
{acl, exampleorg, {server, "example.org"}}.
{resource, Resource}
- 匹配任何资源为Resource的JID. 例子:
{acl, mucklres, {resource, "muckl"}}.
{shared_group, Groupname}
- 匹配这个虚拟主机上的共享名册组Groupname的任何成员. 例子:
{acl, techgroupmembers, {shared_group, "techteam"}}.
{shared_group, Groupname, Server}
- 匹配虚拟主机Server上的共享名册组Groupname的任何成员. 例子:
{acl, techgroupmembers, {shared_group, "techteam", "example.org"}}.
{user_regexp, Regexp}
- 匹配本地虚拟主机（们）上的任何名字符合Regexp的本地用户. 例子:
{acl, tests, {user_regexp, "^test[0-9]*$"}}.
{user_regexp, UserRegexp, Server}
- 匹配服务器Server上名字符合UserRegexp的任何用户. 例子:
{acl, tests, {user_Userregexp, "^test", "example.org"}}.
{server_regexp, Regexp}
- 匹配来自符合server_regexp的服务器的任何JID. 例子:
{acl, icq, {server_regexp, "^icq\\."}}.
{resource_regexp, Regexp}
- 匹配资源符合resource_regexp的任何JID. 例子:
{acl, icq, {resource_regexp, "^laptop\\."}}.
{node_regexp, UserRegexp, ServerRegexp}
- 匹配任何名字符合ServerRegexp的服务器上的任何名字符合UserRegexp的用户. Example:
{acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}.
{user_glob, Glob} {user_glob, Glob, Server} {server_glob, Glob} {resource_glob, Glob} {node_glob, UserGlob, ServerGlob}
- 这和上面一样. 然而, 它使用 shell glob 模式而不是 regexp. 这些模式能拥有以下特别的字符:
- *
- 匹配任何包含null字符的字符串.
- ?
- 匹配任何单个字符.
- [...]
- 匹配任何封闭的字符串. 字符范围由一对使用‘-’分割的字符串定义. 如果在 ‘[’之后的第一个字符是一个‘!’, 匹配任何不封闭的字符.
以下 ACLName 是预定义的:
all
- 匹配任何JID.
none
- 不匹配任何JID.
访问权限
一个允许或禁止访问不同服务的条目. 语法是:
{access, AccessName, [ {allow|deny, ACLName}, ...]}.
当一个JID被检查到可以访问 Accessname, 服务器顺序检查是否那个 JID 匹配任何在列表里这一元组的第二个元素命名的 ACLs. 如果匹配, 返回第一个匹配的元组的第一个元素, 否则返回值‘deny’.
如果你在一个虚拟主机定义了特定的访问权限, 记住全局定义的访问权限比它们拥有优先权. 这意味着, 当发生冲突的时候, 使用这个全局服务器上的赋予或禁止访问，而虚拟主机配置的访问控制无效.
例子:
{access, configure, [{allow, admin}]}. {access, something, [{deny, badmans}, {allow, all}]}.
以下 AccessName 是预定义的:
all
- 总是返回值‘allow’.
none
- 总是返回值‘deny’.
使用ACL限制打开的会话
特别的 access max_user_sessions 定义了每个用户的会话(已验证的连接)的最大数量. 如果一个用户尝试通过使用不同的资源打开更多的会话, 第一个打开的会话将被断掉连接. 这个 会话替换 的错误信息将被发送到断链的会话. 这个选项的值可能是一个数字, 或 infinity. 缺省值是 infinity.
语法是:
{access, max_user_sessions, [ {MaxNumber, ACLName}, ...]}.
这个例子对所有用户限制每用户会话数为5, 对管理员限制为 10:
{access, max_user_sessions, [{10, admin}, {5, all}]}.
使用ACL限制到一个远程XMPP服务器的多个连接
特别的 access max_s2s_connections 定义了可以建立多少个连接到一个特定的远程XMPP服务器. 缺省值是 infinity. 也可以使用 access max_s2s_connections_per_node.
语法是:
{access, max_s2s_connections, [ {MaxNumber, ACLName}, ...]}.
例子:
- 允许每个远程服务器最多3个连接:
{access, max_s2s_connections, [{3, all}]}.
