mod_xmlrpc - XML-RPC server Homepage: http://www.ejabberd.im/mod_xmlrpc Author: Badlop Note: this module will only receive bugfixes. If you are using ejabberd trunk SVN 1635 or newer, you will probably prefer to install ejabberd_xmlrpc. DESCRIPTION ----------- mod_xmlrpc is a module for ejabberd, a XMPP/Jabber server written in Erlang. It starts a XML-RPC server and waits for external requests. Implemented calls include statistics and user administration. This allows external programs written in any language like websites or administrative tools to communicate with ejabberd to get information or to make changes without the need to know ejabberd internals. One example usage is a corporate site in PHP that creates a Jabber user every time a new user is created on the website. Some benefits of interfacing with the Jabber server by XML-RPC instead of modifying directly the database are: - external programs are more simple and easy to develop and debug - can communicate with a server in a different machine, and even on Internet REQUIREMENTS ------------ ejabberd 1.1.2 or newer XMLRPC-Erlang 1.13 with IP, Ruby and Xmerl 1.x patches Optional: mod_muc_admin for MUC-related calls Optional: ejabberd SVN trunk r1329 or newer is required for muc_room_set_affiliation - Install XMLRPC-Erlang wget http://ejabberd.jabber.ru/files/contributions/xmlrpc-1.13-ipr2.tgz tar -xzvf xmlrpc-1.13-ipr2.tgz cd xmlrpc-1.13/src make cd ../../ CONFIGURE EJABBERD ------------------ 1. Add an option like this to the ejabberd start script: $ erl -pa '/home/jabber/xmlrpc-1.13/ebin' ... 2. Configure ejabberd to start this module at startup: edit ejabberd.cfg and add on 'modules' section: {mod_xmlrpc, []}, 3. Now start ejabberd. If everything went ok, no mention to mod_xmlrpc will be shown on the error log. CONFIGURE --------- Configuration is done in 'modules' section in ejabberd.cfg. Available options: port: port where the XML-RPC server will listen. Default: 4560 ip: IP address to listen, in Erlang format. Set to 'all' to listen on all IP address. Default: all maxsessions: Number of concurrent connections allowed. Default: 10 timeout: Timeout of the connections, expressed in milliseconds. Default: 5000 Example configurations: {mod_xmlrpc, [{port, 4560}]} {mod_xmlrpc, [{port, 4560}, {ip, all}, {maxsessions, 10}, {timeout, 5000}]} {mod_xmlrpc, [{port, 4560}, {ip, {81, 202, 202, 79}}]} USAGE ----- You can send calls to http://host:4560/ Call: Arguments: Returns: -- debug echothis String String multhis struct[{a, Integer}, {b, Integer}] Integer -- statistics tellme_title String String tellme_value String String tellme String struct[{title, String}, {value. String}] -- user administration create_account struct[{user, String}, {host, String}, {password, String}] Integer delete_account struct[{user, String}, {host, String}, {password, String}] Integer check_account struct[{user, String}, {host, String}] Integer check_password struct[{user, String}, {host, String}, {password, String}] Integer change_password struct[{user, String}, {host, String}, {newpass, String}] Integer num_resources struct[{user, String}, {host, String}] Integer resource_num struct[{user, String}, {host, String}, {num, Integer}] String set_nickname struct[{user, String}, {host, String}, {nickname, String}] Integer add_rosteritem struct[{localuser, String}, {localserver, String}, {user, String}, {server, String}, {nick, String}, {group, String}, {subs, String}] String delete_rosteritem struct[{localuser, String}, {localserver, String}, {user, String}, {server, String}] String get_roster struct[{user, String}, {server, String}] array[struct[{jid, String}, {nick, String}, {Group, String}]] send_message struct[{from, String}, {to, String}, {subject, String}, {body, String}] Integer -- MUC administration create_muc_room struct[{name, String}, {service, String}, {server, String}] Integer delete_muc_room struct[{name, String}, {service, String}, {server, String}] Integer muc_room_change_option struct[{name, String}, {service, String}, {option, String}, {value, String}] Integer muc_room_set_affiliation struct[{name, String}, {service, String}, {jid, String}, {affiliation, Affiliation}] Integer TEST ---- - You can easily try the XML-RPC server starting a new Erlang Virtual Machine and making calls to ejabberd's XML-RPC: 1. Start Erlang with this option: $ erl -pa '/home/jabber/xmlrpc-1.13/ebin' 2. Now on the Erlang console, write commands and check the results: 1> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, echothis, [800]}). {ok,{response,[800]}} 2> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, echothis, ["blot cloc 557.889 kg"]}). {ok,{response,["blot cloc 557.889 kg"]}} 3> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, multhis, [{struct,[{a, 83}, {b, 689}]}]}). {ok,{response,[57187]}} 4> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, create_account, [{struct, [{user, "ggeo"}, {host, "example.com"}, {password, "gogo11"}]}]}). {ok,{response,[0]}} 5> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, create_account, [{struct, [{user, "ggeo"}, {host, "example.com"}, {password, "gogo11"}]}]}). {ok,{response,[409]}} 6> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, muc_room_change_option, [{struct, [{name, "test"}, {service, "conference.localhost"}, {option, "title"}, {value, "Test Room"}]}]}). 7> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, muc_room_set_affiliation, [{struct, [{name, "test"}, {service, "conference.example.com"}, {jid, "ex@example.com"}, {affiliation, "member"}]}]}). 8> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, muc_room_set_affiliation, [{struct, [{name, "test"}, {service, "conference.example.com"}, {jid, "ex@example.com"}, {affiliation, "none"}]}]}). - Some possible XML-RPC error messages: + Client: connection refused: wrong IP, wrong port, the server is not started... 2> xmlrpc:call({127, 0, 0, 1}, 44444, "/", {call, echothis, [800]}). {error,econnrefused} + Client: bad value: a800 is a string, so it must be put into "" 7> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, echothis, [a800]}). {error,{bad_value,a800}} + Server: unknown call: you sent a call that the server does not implement 3> xmlrpc:call({127, 0, 0, 1}, 4560, "/", {call, bububu, [800]}). {ok,{response,{fault,-1,"Unknown call: {call,bububu,[800]}"}}} EXAMPLE IN PYTHON ----------------- This is an example XML-RPC client in Python, thanks to Diddek: ------- import xmlrpclib server_url = 'http://127.0.0.1:4560'; server = xmlrpclib.Server(server_url); params = {} params["user"] = "ggeo" params["host"] = "localhost" params["password"] = "gogo11" result = server.create_account(params) print result ------- EXAMPLE IN RUBY --------------- This is an example XML-RPC client in Ruby, thanks to Diddek: ------- require 'xmlrpc/client' host = "172.16.29.6:4560" timeout = 3000000 client = XMLRPC::Client.new2("http://#{host}", "#{host}", timeout) result = client.call("echothis", "800") puts result ------- EXAMPLE IN PHP -------------- This is an XML-RPC client in PHP, thanks to Zbyszek Żółkiewski and Calder. It requires "allow_url_fopen = On" in your php.ini. ------- "test_user","host"=>"example.com","password"=>"some_password"); $request = xmlrpc_encode_request('check_password', $param, (array('encoding' => 'utf-8'))); $context = stream_context_create(array('http' => array( 'method' => "POST", 'header' => "User-Agent: XMLRPC::Client mod_xmlrpc\r\n" . "Content-Type: text/xml\r\n" . "Content-Length: ".strlen($request), 'content' => $request ))); $file = file_get_contents("http://127.0.0.1:4560/RPC2", false, $context); $response = xmlrpc_decode($file); if (xmlrpc_is_fault($response)) { trigger_error("xmlrpc: $response[faultString] ($response[faultCode])"); } else { print_r($response); } ?> ------- EXAMPLE IN JAVA --------------- This is an XML-RPC client in Java, thanks to Calder. It requires Apache XML-RPC available at http://ws.apache.org/xmlrpc/ ------- import java.net.URL; import java.util.HashMap; import java.util.Map; import org.apache.xmlrpc.client.XmlRpcClient; import org.apache.xmlrpc.client.XmlRpcClientConfigImpl; public class Test { public static void main(String[] args) { try { XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl(); config.setServerURL(new URL("http://127.0.0.1:4560/RPC2")); XmlRpcClient client = new XmlRpcClient(); client.setConfig(config); /* Command string */ String command = "check_password"; /* Parameters as struct */ Map struct = new HashMap(); struct.put("user", "test1"); struct.put("host", "localhost"); struct.put("password", "test"); Object[] params = new Object[]{struct}; Integer result = (Integer) client.execute(command, params); System.out.println(result); } catch (Exception e) { System.out.println(e); } } } -------