查看源代码

[[Category:XMPP服务器]]
[[Category:翻译中]]

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

'''ejabberd 2.1.3 安装和管理指南'''

==绪论==

ejabberd是一个用[http://www.erlang.org/ 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种语言.
** 支持[http://www.ietf.org/rfc/rfc3490.txt IDNA]. 
* 开放标准: ejabberd是的一个完全支持XMPP标准的开源Jabber服务器.
** 完全兼容XMPP.
** 基于XML的协议.
** 支持的[http://www.ejabberd.im/protocols 协议]很多.

===额外功能===

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

* 模块化
** 只装在你想要的模块.
** 在你自己的自定义模块扩展ejabberd. 
* 安全性
** 支持c2s和s2s连接的SASL和STARTTLS.
** 支持s2s连接的STARTTLS和Dialback.
** 可通过HTTPS安全访问的Web管理. 
* 数据库
** 快速布署的内部数据库(Mnesia).
** 原生的MySQL支持.
** 原生的PostgreSQL支持.
** 支持ODBC数据存储.
** 支持Microsoft SQL Server. 
* 验证
** 内部验证.
** PAM, LDAP 和 ODBC.
** 外部验证脚本. 
* 其他
** 支持虚拟主机.
** XML流压缩 ([http://xmpp.org/extensions/xep-0138.html XEP-0138]).
** 统计 ([http://xmpp.org/extensions/xep-0039.html XEP-0039]).
** 支持IPv6的c2s和s2s连接.
** 支持集群和HTML日志的[[XEP-0045|多用户聊天]]模块.
** 基于用户vCards的用户目录.
** 支持[http://xmpp.org/extensions/xep-0163.html 基于PubSub的个人事件]的[http://xmpp.org/extensions/xep-0060.html 发行-订阅]组件.
** 支持web客户端: [http://xmpp.org/extensions/xep-0025.html HTTP轮询]和[http://xmpp.org/extensions/xep-0206.html HTTP绑定(BOSH)]服务.
** IRC网关.
** 组件支持: 安装特定网关之后和外部网络的接口，如 AIM, ICQ 和 MSN.

==安装Installing ejabberd==
===用ejabberd二进制安装包安装===

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

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

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

<source lang="bash">
chmod +x ejabberd-2.0.0_1-linux-x86-installer.bin
./ejabberd-2.0.0_1-linux-x86-installer.bin
</source>

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运行时系统的可配置选项，详见 [[Ejabberd2:安装和操作指南#ejabberdctl|4.1]] 章.

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

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

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

===用CEAN安装ejabberd===

[http://cean.process-one.net/ 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 或更高版本, 用于支持流压缩 ([http://xmpp.org/extensions/xep-0138.html XEP-0138]). 可选的.
* Erlang mysql library. 可选的. 用于支持 MySQL 验证或存储. 见 [[Ejabberd2:安装和操作指南#MySQL|3.2.1]] 节.
* Erlang pgsql library. 可选的. 用于支持 PostgreSQL 验证或存储. 见 [[Ejabberd2:安装和操作指南#PostgreSQL|3.2.3]] 节.
* PAM library. 可选的. 用于F 可插拔的验证模块 (PAM). 见 [[Ejabberd2:安装和操作指南#PAM验证|3.1.4]] 节.
* GNU Iconv 1.8 或更高版本, 用于 IRC 网关 (mod_irc). 可选的. 在系统里不需要 GNU Libc. 见 [[Ejabberd2:安装和操作指南#mod_irc|3.3.8]] 节.
* ImageMagick’s 转换程序. 可选的. 用于 CAPTCHA 挑战. 见 [[Ejabberd2:安装和操作指南#CAPTCHA|3.1.8]] 节.
* exmpp 0.9.2 或更高版本. 可选的. 用于以 [http://xmpp.org/extensions/xep-0227.html XEP-0227] XML文件格式导入/导出用户数据.

====下载源码====

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

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

<source lang="bash">
git clone git://git.process-one.net/ejabberd/mainline.git ejabberd
cd ejabberd
git checkout -b 2.1.x origin/2.1.x
</source>

====编译====

编译ejabberd可执行以下命令:

<source lang="bash">
./configure
make
</source>

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

<source lang="bash">
./configure --help
</source>

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

'''--prefix=/'''

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

'''--enable-user[=USER]'''

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

'''--enable-pam'''

允许PAM验证方法 (参见 [[Ejabberd2:安装和操作指南#PAM验证|3.1.4]] 节).

'''--enable-odbc or --enable-mssql'''

如果你想使用外部数据库则需要这个选项. 详见 [[Ejabberd2:安装和操作指南#数据库和LDAP配置|3.2]] 节.

'''--enable-full-xml'''

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

'''--disable-transient-supervisors'''

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

====安装====

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

<source lang="bash">
make install
</source>

注意安装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'''
    管理脚本(见 [[Ejabberd2:安装和操作指南#ejabberdctl|4.1]] 节) 

 '''/share/doc/ejabberd/'''
    ejabberd文档

 '''/var/lib/ejabberd/'''
    Spool目录:
    '''.erlang.cookie'''
        Erlang cookie文件(见 [[Ejabberd2:安装和操作指南# Erlang Cookie|5.3]] 节) 
    '''acl.DCD, ...'''
        Mnesia数据库spool文件(*.DCD, *.DCL, *.DAT) 

 '''/var/log/ejabberd/'''
    日志目录(见 [[Ejabberd2:安装和操作指南#日志文件|7.1]] 节):
    '''ejabberd.log'''
        ejabberd服务日志
    '''erlang.log'''
        Erlang/OTP系统日志

====启动====

你可以使用ejabberdctl命令行管理脚本来启动和停止ejabberd. 如果你提供了配置选项 --enable-user=USER (见 [[Ejabberd2:安装和操作指南#编译|2.4.3]] 节), 你可以以那个系统帐号或root的身份执行ejabberdctl.

用法示例:

<source lang="bash">
ejabberdctl start

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

ejabberdctl stop
</source>

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

关于ejabberdctl和微调Erlang运行时系统的可配置选项，详见 [[Ejabberd2:安装和操作指南#ejabberdctl|4.1]] 节.

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

====BSD的具体说明====

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

<source lang="xml">
gmake
</source>

====Sun Solaris的具体说明====

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

<source lang="bash">
pkg-get -i fileutils
</source>

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

<source lang="bash">
cat Makefile | sed s/install/ginstall/ > Makefile.gi
</source>

最终这样安装ejabberd:

<source lang="bash">
gmake -f Makefile.gi ginstall
</source>

====Microsoft Windows的具体说明====
=====需求=====

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

* MS Visual C++ 6.0 Compiler
* [http://www.erlang.org/download.html Erlang/OTP R11B-5]
* [http://sourceforge.net/project/showfiles.php?group_id=10127&package_id=11277 Expat 2.0.0或更高版本]
* [http://www.gnu.org/software/libiconv/ GNU Iconv 1.9.2 (可选的)]
* [http://www.slproweb.com/products/Win32OpenSSL.html Shining Light OpenSSL 0.9.8d或更高版本(使能SSL连接)]
* [http://www.zlib.net/ 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中运行:

<source lang="bash">
      configure.bat
      nmake -f Makefile.win32
</source>

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

<source lang="bash">
      werl -s ejabberd -name ejabberd
</source>

===新建XMPP管理帐号===

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

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

:1.1. 使用ejabberdctl (见 4.1 节):

<source lang="bash">
            ejabberdctl register admin1 example.org FgT5bk3
</source>

:1.2. 使用一个XMPP客户端进行带内注册(见 3.3.18 节). 

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

<source lang="text">
      {acl, admins, {user, "admin1", "example.org"}}.
      {access, configure, [{allow, admins}]}.
</source>

你可以赋予管理权限给多个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)将被启用.

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

<source lang="ini">
override_global.
override_local.
override_acls.
</source>

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

====主机名====

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

语法是:

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

示例:

* 服务一个域:

<source lang="ini">
      {hosts, ["example.org"]}.
</source>

* 服务多个域:

<source lang="ini">
      {hosts, ["example.net", "example.com", "jabber.somesite.org"]}.
</source>

====虚拟主机====

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

语法是:

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

示例:

* 域example.net使用内部验证方法，同时域example.com使用运行在域localhost的LDAP服务器来进行验证:

<source lang="ini">
      {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, ""}]}.
</source>

* 域example.net使用ODBC来进行验证，同时域example.com使用运行在域localhost和otherhost的LDAP服务器:

<source lang="ini">
      {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, ""}]}.
</source>

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

'''{OptionName, OptionValue}'''

使用这个语法:

'''{{add, OptionName}, OptionValue}'''

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

<source lang="ini">
%% 这个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"}]}
                   ]
  }
 ]}.
</source>

====Listening Ports====
====Authentication====
====Access Rules====
====Shapers====
====Default Language====
====CAPTCHA====
====STUN====
====Include Additional Configuration Files====
====Option Macros in Configuration File====