Ejabberd源码解析前奏--管理
一、ejabberdctl
?
????使用ejabberdctl命令行管理腳本，你可以執行ejabberdctl命令和一些普通的ejabberd命令(后面會詳細解說)。這意味著你可以在一個本地或遠程ejabberd服務器(通過提供參數 --node NODENAME)上啟動、停止以及執行很多其它管理任務。
????ejabberdctl腳本可在文件 ejabberdctl.cfg 里配置. 這個文件包含每個可配置選項的詳細信息.
????ejabberdctl腳本返回一個數字狀態碼. 成功顯示為0, 錯誤顯示為1, 其它碼可被用于特定結果. 這可以由其它腳本使用，來自動決定一個命令成功與否, 例如使用: echo $?。
?
1、ejabberdctl命令
?
????不帶任何參數執行ejabberdctl時, 它顯示可用的選項. 如果沒有一個ejabberd服務器在運行, 可用的參數如下:
????start
????以后臺模式啟動ejabberd. 這是缺省方法.
????debug
????連接一個 Erlang shell 到一個已存在的 ejabberd 服務器. 這允許在ejabberd服務器上執行交互命令.
????live
????以live模式啟動ejabberd: shell保持連接到已啟動的服務器, 顯示日志信息并允許執行交互命令.
????如果已經有一個ejabberd服務器在系統里運行, ejabberdctl 展示以下 ejabberdctl 命令描述以及那臺服務器上所有可用的 ejabberd命令.
????ejabberdctl命令如下:
????help
????獲得關于ejabberdctl或任何可用命令的幫助. 試下ejabberdctl help help.
????status
????檢查ejabberd服務器的狀態.
????stop
????停止ejabberd服務器.
????restart
????重啟ejabberd服務器.
????mnesia
????獲得關于Mnesia數據庫的信息.
????ejabberdctl腳本可被限制為需要驗證并執行一些ejabberd命令，增加這個選項到文件 ejabberd.cfg. 下面例子表示沒有限制:
????{ejabberdctl_access_commands,?[]}.
????如果帳號robot1@example.org被注冊到ejabberd，密碼為abcdef(作MD5后為E8B501798950FC58AAD83C8C14978E), 并且 ejabberd.cfg 包含以下設定:
????{hosts,?["example.org"]}.?
????{acl, bots,?{user,?"robot1",?"example.org"}}.?
????{access, ctlaccess,?[{allow, bots}]}.?
????{ejabberdctl_access_commands,?[?{ctlaccess,?[registered_users, register],?[]}?]}.
????那么你可以在 shell 里這么做:
????$ ejabberdctl registered_users example.org
????Error: no_auth_provided
????$ ejabberdctl?--auth?robot1 example.org E8B501798950FC58AAD83C8C14978E registered_users example.org
????robot1
????testuser1
????testuser2
?
2、Erlang運行時系統
?
????ejabberd是一個 Erlang/OTP 應用，運行在一個Erlang運行時系統內部. 這個系統是用環境變量和命令行參數來配置的. ejabberdctl管理腳本可能會使用其中的一些. 你可以在ejabberdctl.cfg文件里配置其中的一部分, 配置文件里面已包含了關于它們的詳細描述. 本節描述所有環境變量和命令行參數的意義.
????環境變量:
????EJABBERD_CONFIG_PATH
????ejabberd配置文件的路徑.
????EJABBERD_MSGS_PATH
????翻譯字符串的目錄路徑.
????EJABBERD_LOG_PATH
????ejabberd服務日志文件的路徑.
????EJABBERD_SO_PATH
????二進制系統庫的目錄路徑.
????EJABBERD_DOC_PATH
????ejabberd文檔的目錄路徑.
????EJABBERD_PID_PATH
????ejabberd啟動時建立PID文件的路徑.
????HOME
????ejabberd的Home目錄的路徑. 這個路徑用于讀取文件.erlang.cookie.
????ERL_CRASH_DUMP
????崩潰報告dump文件的路徑.
????ERL_INETRC
????指示使用名字解析的IP. 如果使用 -sname, 要么指定這個選項，要么指定 -kernel inetrc filepath.
????ERL_MAX_PORTS
????并發開放的Erlang端口的最大數量.
????ERL_MAX_ETS_TABLES
????ETS和Mnesia表的最大數量.
????命令行參數:
????-sname ejabberd
????這個Erlang節點將只使用主機名的第一部分來指定, 即本域之外的其它Erlang節點不能夠聯系聯絡這個節點. 在大多數情況下這是更可取的選擇.
????-name ejabberd
????這個Erlang節點將被完全指定. 這只在你計劃在不同的網絡配置一個ejabberd集群時有用.
????-kernel inetrc ’"/etc/ejabberd/inetrc"’
????指出使用名字解析的IP. 如果使用 -sname, 要么指定這個選項，要么指定 ERL_INETRC.
????-kernel inet_dist_listen_min 4200 inet_dist_listen_min 4210
????定義 epmd 可以監聽的第一個和最后一個端口.
????-detached
????啟動Erlang系統并從系統控制臺分離. 運行守護進程和后臺進程時有用.
????-noinput
????確保Erlang系統不嘗試讀任何輸入. 運行守護進程和后臺進程時有用.
????-pa /var/lib/ejabberd/ebin
????指定Erlang二進制文件(*.beam)所在目錄.
????-s ejabberd
????告訴Erlang運行時系統啟動ejabberd應用.
????-mnesia dir ’"/var/lib/ejabberd/"’
????指定Mnesia數據庫目錄.
????-sasl sasl_error_logger {file, "/var/log/ejabberd/erlang.log"}
????Erlang/OTP系統日志文件的路徑. 這里SASL意味著 系統架構支持庫“System Architecture Support Libraries” 而不是 簡單認證和安全層 “Simple Authentication and Security Layer”.
????+K [true|false]
????內核輪詢.
????-smp [auto|enable|disable]
????SMP(多CPU)支持.
????+P 250000
????Erlang進程的最大數量.
????-remsh ejabberd@localhost
????在一個遠程Erlang節點上打開一個Erlang shell.
????-hidden
????到其它節點的連接是隱藏的(沒有公開發布)，結果是這個節點不被認為是集群的一部分. 當啟動一個臨時的ctl或debug節點的時候這是很重要的.
????注意：當使用shell腳本的時候，需要避免使用一些字符, 例如 " 和 {}. 你可在Erlang手冊頁 (erl -man erl)找到其它選項.
?
二、ejabberd命令
?
????一個ejabberd命令是一個通過名字指定的抽象函數, 該函數在ejabberd_commands服務里注冊，并指定調用參數的編號和類型以及輸出類型. 那些命令能被定義在任何Erlang模塊里，并能使用任何合法的前端執行.
????ejabberd包含一個前端用來執行ejabberd命令即腳本ejabberdctl. 其它已知可執行ejabberd命令的前端有: ejabberd_xmlrpc (XML-RPC 服務), mod_rest (HTTP POST 服務), mod_shcommands (ejabberd WebAdmin 頁面).
?
1、ejabberd命令清單
?
????ejabberd缺省包含了一些ejabberd命令. 當更多模塊被安裝時, 在前端又會有新命令可以用.
????獲得可用命令和幫助的最簡單方法是使用ejabberdctl腳本:
????$ ejabberdctl?help?
????Usage: ejabberdctl?[--node nodename]?[--auth user host password]?command?[options]
????Available commands?in?this ejabberd node:??
????backup?file?????????????? ? Store the database to backup?file?
????connected_users????? ? ??????List all established sessions??
????connected_users_number ????? Get the number of established sessions??
????...
????最令人感興趣的是:
????reopen_log
????在日志文件改名之后重新打開它們. 如果在調用此命令之前舊文件沒有被改名, 則它們自動改名為 "*-old.log".關于這點后文書還會詳述.
????backup ejabberd.backup
????存儲內部 Mnesia 數據庫到一個二進制備份文件.
????restore ejabberd.backup
????立刻從一個二進制文件恢復內部 Mnesia 數據庫. 如果你有一個很大的數據庫，這將消耗很多內存, 所以最好使用 install_fallback.
????install_fallback ejabberd.backup
? ? 將二進制備份文件安裝程序fallback，這樣，它將在下一次ejabberd啟動的時候被用于恢復數據庫. 這意味著, 在運行這個命令之后, 你不得不重啟 ejabberd. 這個命令比restore需要更少的內存.
????dump ejabberd.dump
????Dump內部的 Mnesia 數據庫到一個文本文件 dump.
????load ejabberd.dump
????立刻從一個文本文件dump恢復. 這不建議用于大數據庫, 因為它將消耗很多時間、內存和cpu. 那種情況下更適合使用 backup 和 install_fallback.
????import_piefxis, export_piefxis, export_piefxis_host
????這些選項可用于使用?XEP-0227?格式的 XML文件 從/到 另外一個 Jabber/XMPP 服務器遷移帳號或轉移一個虛擬主機的用戶到另一個 ejabberd 安裝環境. 可以參見?ejabberd遷移工具.
????import_file, import_dir
????這些選項可被用于遷移使用jabberd1.4格式的XML文件的帳戶, 從其他 Jabber/XMPP 服務器. 已經有?從其他軟件遷移到ejabberd的教程.
????delete_expired_messages
????這個選項可被用于刪除舊的離線消息. 當離線消息數量非常高的時候有用.
????delete_old_messages days
????刪除指定天數之前的離線消息.
????register user host password
????在那個域用給定的密碼注冊一個帳號.
????unregister user host
????????? ? 注銷給定帳號.
?
2、以AccessCommands限制執行
?
????前端可能被配置成限制訪問某些命令. 在那種情況下, 必須提供認證信息. 在每個前端 AccessCommands 選項被定義在不同的地方. 但是所有情況下這個選項的語法都是相同的:
????AccessCommands?=?[?{Access, CommandNames, Arguments}, ...]?
????Access?=?atom()?
????CommandNames?=?all |?[CommandName]?
????CommandName?=?atom()?
????Arguments?=?[?{ArgumentName, ArgumentValue}, ...]?
????ArgumentName?=?atom()?
????ArgumentValue?=?any()
????缺省值是不定義任何限制: []. 當執行一個命令時提供認證信息, 這些信息為一個被允許執行相應命令的本地XMPP帳號的Username、Hostname和Password . 這意味著這個帳號必須在本地ejabberd已經注冊, 因為這個信息將被驗證. 可能提供純文本密碼或它的 MD5 哈希值.
????當定義了一個或多個訪問限制，并且提供了認證信息, 每個限制被驗證直到某人完全符合: 這個帳號和 Access rule匹配, 命令名字列于 CommandNames 之中, 并且提供的參數和Arguments不抵觸.
????以下例子用來理解這個語法, 讓我們假設那些選項:? ??
????{hosts,?["example.org"]}.?
????{acl, bots,?{user,?"robot1",?"example.org"}}.?
????{access, commaccess,?[{allow, bots}]}.
? ? 這個訪問限制的列表只允許 robot1@example.org 執行所有命令:
????[{commaccess, all,?[]}]
????看看另一個限制列表 (相應的 ACL 和 ACCESS 沒有顯示):
????[?
????????%% 這個 bot 能執行所有命令:?
????????{bot, all,?[]},?
????????%% 這個 bot 只能執行命令 'dump'. 不限制參數:?
????????{bot_backups,?[dump],?[]}?%% 這個 bot 可執行所有命令,
????????%% 但是如果使用 'host' 參數, 它必須是?"example.org":?
????????{bot_all_example, all,?[{host,?"example.org"}]},?
????????%% 這個 bot 只能執行命令 'register',?
????????%% 并且如果使用參數 'host' , 它必須是?"example.org":?
????????{bot_reg_example,?[register],?[{host,?"example.org"}]},?
????????%% 這個 bot 能執行命令 'register' 和 'unregister',?
????????%% 如果使用參數 host , 它必須是?"test.org":?
????????{_bot_reg_test,?[register, unregister],?[{host,?"test.org"}]}?
????]
?
三、Web管理
?
????ejabberd Web管理允許使用web瀏覽器管理大部分ejabberd.
????這個功能缺省是激活的: 一個使用選項 web_admin 的 ejabberd_http 監聽者被包含在監聽的端口里. 然后你可以在你喜歡的wen瀏覽器里打開?http://server:port/admin/?. 你將被要求鍵入一個擁有管理員權限的ejabberd用戶的 username (全 Jabber ID) 和 password . 在認證之后你將看到一個類似下圖的頁面.
圖1 Web管理
????這里你可以編輯訪問限制、管理用戶、創建備份、管理數據庫、允許/禁止監聽的端口、查看服務器統計數據,…
????access rule 配置決定那些帳號可以訪問Web管理以及修改它. access rule webadmin_view 僅被授予查看權限: 那些帳號能以只讀方式瀏覽Web管理.
????示例配置:
? ? ????（1）你可以把Web管理伺服于和HTTP 輪詢界面相同的端口. 在這個了例子里你應該把你的web瀏覽器指向?http://example.org:5280/admin/?來管理所有虛擬主機或指向?http://example.org:5280/admin/server/example.com/?來管理虛擬主機 example.com. 在你訪問Web管理之前，你需要鍵入用戶信息，包括username、JID 和 password . 在這個例子里你可鍵入 username ‘admin@example.net’ 來管理所有虛擬主機 (第一個 URL). 如果你以‘admin@example.com’登錄到http://example.org:5280/admin/server/example.com/，你只能管理虛擬主機 example.com. 帳號‘reviewer@example.com’可以只讀模式瀏覽虛擬主機.? ? ??
????{acl, admins,?{user,?"admin",?"example.net"}}.?
????{host_config,?"example.com",?[{acl, admins,?{user,?"admin",?"example.com"}}]}.?
????{host_config,?"example.com",?[{acl, viewers,?{user,?"reviewer",?"example.com"}}]}.??
????{access, configure,?[{allow, admins}]}.?{access, webadmin_view,?[{allow, viewers}]}.??
????{hosts,?["example.org"]}.??
????{listen,?
????????[?
????????????...?
????????????{5280, ejabberd_http,?[http_poll, web_admin]},? ? ? ??
????????????...?
????????]}.
????? ? （2）因為安全的原因, 你可以在一個安全的連接上伺服Web管理, 在一個不同于HTTP輪詢接口的端口上, 并把它綁定到內部的局域網IP. 這個Web管理將只能被瀏覽器從https://192.168.1.1:5282/admin/?訪問:? ? ??
????{hosts,?["example.org"]}.??
????{listen,?
????????[?
????????????...?
????????????{5280, ejabberd_http,?[?
????????????????????????????????????http_poll?
??????????????????????????????????]},?
????????????{{5282,?"192.168.1.1"}, ejabberd_http,?[?
????????????????????????????????????????????????????????web_admin,? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ??
????????????????????????????????????????????????????????tls,?{certfile,?"/usr/local/etc/server.pem"}?
????????????????????????????????????????????????????]},? ? ? ??
????????????...?
????????]}.
????在ejabberd Web管理頁面中包含了一個到 ejabberd安裝和操作指南 相關章節的連接. 為了查看這些鏈接, 本指南的一個 HTML 格式的拷貝必須安裝在該系統上. 該文件缺省放在 "/share/doc/ejabberd/guide.html". 該文檔的目錄可以用環境變量 EJABBERD_DOC_PATH 來指定.?
?
?
四、特設命令
????如果你激活了 mod_configure 和 mod_adhoc, 你可以使用一個 XMPP 客戶端在 ejabberd 上執行很多管理任務. 該客戶端必須支持 Ad-Hoc Commands (XEP-0050), 而你必須以一個擁有適當權限的帳號登錄到該 XMPP 服務器.
?
五、修改計算機主機名
?
????ejabberd使用分布式的 Mnesia 數據庫. 作為分布式數據庫, Mnesia 強制它的文件一致性, 所以它在它里面存儲Erlang節點名. 一個Erlang節點的名字包含了該計算機的hostname. 所以, 如果你修改ejabberd運行的機器的名字，或當你移動ejabberd到一個不同的機器上時，那么Erlang節點名也修改了.
????你有兩個辦法在一個新節點名的 ejabberd 上使用舊的 Mnesia 數據庫: 把舊節點名寫入 ejabberdctl.cfg, 或轉換數據庫到為新節點名.
????那些例子步驟將備份, 轉換并裝載 Mnesia 數據庫. 你需要要么有舊的 Mnesia spool 目錄，要么有一個 Mnesia 的備份. 如果你已經有一個舊的數據庫的備份文件, 你可以直接去步驟5. 你也需要知道舊節點名和新節點名. 如果你不知道它們, 執行ejabberdctl或在ejabberd 日志文件里查找它們.
????在開始之前, 設置一些變量:
????OLDNODE=ejabberd@oldmachine?
????NEWNODE=ejabberd@newmachine
????OLDFILE=/tmp/old.backup?
????NEWFILE=/tmp/new.backup
?
????（1）強制以舊節點名啟動 ejabberd?:? ? ??
????????ejabberdctl?--node?$OLDNODE?start
? ? （2）生成一個備份文件:? ? ??
????????ejabberdctl?--node?$OLDNODE?backup?$OLDFILE
? ? （3）停止舊節點:? ? ??
????????ejabberdctl?--node?$OLDNODE?stop
????（4）確保在 Mnesia spool 目錄沒有文件 . 例如:? ? ??
????????mkdir?/var/lib/ejabberd/oldfiles?
????????mv?/var/lib/ejabberd/*.*?/var/lib/ejabberd/oldfiles/
????（5）啟動 ejabberd. 不需要再指定任何節點名:? ? ??
????????ejabberdctl start
????（6）轉換備份到新節點名:? ? ??
????????ejabberdctl mnesia_change_nodename?$OLDNODE?$NEWNODE?$OLDFILE?$NEWFILE
????（7）安裝備份文件作為一個fallback:? ? ??
????????ejabberdctl install_fallback?$NEWFILE
????（8）停止 ejabberd:? ? ??
????????ejabberdctl stop
????????你可能在日志文件看到一個錯誤信息, 這是正常的, 不要擔心:? ? ??
????????Mnesia(ejabberd@newmachine):? ? ??
????????** ERROR ** (ignoring core)? ? ??
????????** FATAL ** A fallback is installed and Mnesia must be restarted.? ? ? ??
????????Forcing shutdown after mnesia_down from ejabberd@newmachine...
????（9）現在你可以最后啟動 ejabberd:? ? ??
????????ejabberdctl start
????（10）檢查是否舊數據庫的信息可用: accounts, rosters... 完成之后, 記住從公共目錄刪除臨時備份文件.
總結
以上是生活随笔為你收集整理的Ejabberd源码解析前奏--管理的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： OAF_开发系列03_实现OAF如何在保
- 下一篇： 使用MySql保存session