1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc/json-rpc.txt Wed Oct 28 19:20:44 2009 -0700
1.3 @@ -0,0 +1,130 @@
1.4 +Qemudo implements JSON-RPC over HTTP as defined in the standard
1.5 +http://groups.google.com/group/json-rpc/web/json-rpc-over-http
1.6 +JSON requests have to be posted to http://hostname</QEMUDO-ROOT>/json-rpc
1.7 +where </QEMUDO-ROOT> is the root URL configured for Qemudo. For
1.8 +example assuming the root is "/", the following "qemucmd" call starts
1.9 +the VM with the given UUID:
1.10 +
1.11 + POST /json-rpc HTTP/1.1
1.12 + Host: xxx
1.13 + Content-length: xxx
1.14 +
1.15 + {
1.16 + "method":"qemucmd",
1.17 + "params":{
1.18 + "act":"start",
1.19 + "uuid":"dea6681e-68fd-4dc6-b430-23db4ce24b29"
1.20 + },
1.21 + "id":0
1.22 + }
1.23 +
1.24 +
1.25 +createimg: Create a VM
1.26 +======================
1.27 +
1.28 +The "createimg" call creates a VM. It takes one of the 2 following parameters:
1.29 +- "disksize" (integer): creates a VM from scratch, the parameter gives
1.30 + the size of the disk in GB
1.31 +- "tmpluuid" (string): creates a VM from a template, the parameter references
1.32 + the template UUID
1.33 +If both params are specified, "tmpluuid" is ignored, and a VM is
1.34 +created from scratch.
1.35 +
1.36 +Example:
1.37 +
1.38 + {
1.39 + "method":"createimg",
1.40 + "params":{
1.41 + "tmpluuid":"adccf517-26e5-4a23-9db6-dd8a81c9aed8"
1.42 + },
1.43 + "id":0
1.44 + }
1.45 +
1.46 +getimg: Get VM attributes
1.47 +=========================
1.48 +
1.49 +The "getimg" call searches for VMs (by UUID, complex search query) and returns
1.50 +their attributes. It takes the following parameters:
1.51 +- "uuid" (string): if this param is specified, attributes of this VM and only
1.52 + this one are returned
1.53 +- "search" (string): this param specifies a complex search query which supports
1.54 + the same syntax as the syntax exposed through the Web UI (see the help link
1.55 + next to the search box for a completed documentation of the syntax)
1.56 +- "nr" (integer): this parameter limits the number of matches returned to
1.57 + the caller
1.58 +- "off" (integer): this parameter returns matches starting at the specified
1.59 + offset
1.60 +- "fields" (hash of strings): if unspecified all attributes are returned
1.61 + to the caller, if specified only the given attributes are returned
1.62 +
1.63 +Example #1:
1.64 +
1.65 +This request:
1.66 +
1.67 + {"method":"getimg","params":{"search":"mrb-appl"},"id":0}
1.68 +
1.69 +Might return 1 match (indicated by the "total" value) and will return all
1.70 +the VM attributes because the "fields" param was not specified:
1.71 +
1.72 + { "error":null,
1.73 + "id":0,
1.74 + "result": {
1.75 + "total":1,
1.76 + "imgs": {
1.77 + "9cd4d0aa-af18-49ab-9664-7e945c14e62f": {
1.78 + "creator":"mrb",
1.79 + "status":"stopped",
1.80 + "vncpass":"",
1.81 + "qemucmd":"",
1.82 + "desc":"NeXpose appliance ...",
1.83 + "mac":"52:37:00:34:30:bd",
1.84 + "nicmodel":"",
1.85 + "cpu":"",
1.86 + "vncserver":"",
1.87 + "template":"d56f6aa2-39c1-4746-a07f-fe1998d28fbe",
1.88 + "cdrom":"",
1.89 + "name":"mrb-appl",
1.90 + "tags":{},
1.91 + "usetablet":"",
1.92 + "type":"vm",
1.93 + "nodes":{"mrsq.tor.rapid7.com":1},
1.94 + "mem":768,
1.95 + "snapshots":{},
1.96 + "perms":"private"
1.97 + }
1.98 + }
1.99 + }
1.100 + }
1.101 +
1.102 +Example #2:
1.103 +
1.104 + {"method":"getimg","params":{"search":"mrb-appl","fields":{}},"id":0}
1.105 +
1.106 +Would return only the UUIDs because the "fields" param has been explicitely
1.107 +set to an empty hash.
1.108 +
1.109 + {
1.110 + "error":null,
1.111 + "id":0,"result": {
1.112 + "total":1,
1.113 + "imgs": {
1.114 + "9cd4d0aa-af18-49ab-9664-7e945c14e62f": {}
1.115 + }
1.116 + }
1.117 + }
1.118 +
1.119 +
1.120 +setimg: Set VM attributes
1.121 +=========================
1.122 +
1.123 +The "setimg" call sets the attributes (eg. name, description, etc) of 1 or more VMs.
1.124 +It takes 1 param:
1.125 +- "imgs" (hash): similar to the "imgs" result of the "getimg" call
1.126 +
1.127 +
1.128 +qemucmd: Act on a VM
1.129 +====================
1.130 +
1.131 +The "qemucmd" call starts or stops a VM. It takes 2 params:
1.132 +- "uuid" (string): the UUID of the VM to be started or stopped
1.133 +- "act" (string): action name, "start" or "stop"