README

   1 handler_virt
   2 ------------
   3
   4 This code implements a webserver interface for the libvirt[1] project, a helper
   5 daemon joins a complete network of physical hardware running libvirtd to one
   6 point of access. For this project we followed the libvirt API in their function
   7 naming.
   8
   9
  10 LICENSE
  11 -------
  12
  13 The code is primary based on handler_server_info, and was written for Cherokee
  14 by Alvaro Lopez Ortega. Since that code is GPLv2, all the attached code is
  15 compatible with that license. In my opinion GPLv2 or in your opinion ANY later
  16 version.
  17
  18
  19 AUTHORS
  20 -------
  21
  22 Stefan de Konink <stefan@konink.de>
  23 Alvaro Lopez Ortega <alvaro@alobbs.com>
  24
  25
  26 SECURITY
  27 --------
  28
  29 With security in mind we developed several modi:
  30  - an insecure mode that allows anyone that has access to the server to issue
  31    all possible commands
  32  - a bit more secure mode that allows anyone to see all commands, but are only
  33    allowed to issue 'read only' libvirt commands.
  34  - a secure mode that allows specific vm owners to see only their vms
  35  - a secure mode that allows specific vm owners to see and modify their vms
  36
  37
  38 DESIGN
  39 ------
  40
  41 The project consists of several parts:
  42  - a service announcement daemon (domumdns)
  43  - an mdns client (handler_avahi)
  44  - interface code with libvirt on request (handler_virt)
  45
  46
  47 domumdns, implements a daemon that should be run on every physical machine on
  48 your cluster. This daemon can be integrated with libvirt, please bug Red Hat
  49 to do so! In its current form it will only export the names of domu's to the
  50 world using mDNS. Specifically we use the Avahi[2] libraries for this. If you
  51 see memory leaks in libvirt or avahi, please contact their developers!
  52
  53 handler_avahi, implements in cherokee handler style a way to set up a client
  54 and communicate with it using a private thread. It was split first developed
  55 to show of the powers of Avahi-as-Client within a webserver.
  56
  57 handler_virt, implements the 'phone home' glue code around http_get and
  58 http_post, libvirt and avahi. The basic structure of a request looks like:
  59
  60 /virt/client1/vm1/virCommand
  61
  62
  63 In insecure mode /virt will produce XML output having all vms on the network.
  64 When going secure /virt/client1 will be only available that will show the vms
  65 owned by a specific user. /virt/client1/vm1 will show the default command
  66 virDomainGetXMLDesc, basically an XML representation of a domain.
  67
  68
  69 CONFIGURATION
  70 -------------
  71
  72 Using cherokee-admin you are asked to set some parameters to get the handler
  73 running.
  74
  75 mDNS Service Type;
  76 the server type currently non-configurable by domumdns is _domu._tcp
  77
  78 Authenticate;
  79 Should users authenticate (http_auth) before having access to any facility of
  80 the module. Don't forget; you should specify the security settings in the
  81 security tab! If authentication is disabled, everyone can access anything.
  82
  83 Read Only;
  84 A Read Only connection is made with libvirt to the hypervisor, that means that
  85 you cannot modify domains. This option is created for security reasons,
  86 if you want to modify (not only show) domains on the web, disable it.
  87
  88 XSL Stylesheet;
  89 An XSL stylesheet can be created to make the XML output look pretty. If you
  90 would like to implement oVirt competitor, something in the handler should
  91 be changed (or some javascript is required) to process the non XML output
  92 of some functions.
  93
  94
  95 WHAT IS IMPLEMENTED
  96 -------------------
  97
  98 domainAttachDevice,
  99 domainDetachDevice,
 100 domainGetID,
 101 domainGetMaxMemory,
 102 domainGetMaxVcpus,
 103 domainGetName,
 104 domainGetOSType,
 105 domainGetSchedulerParameters,
 106 domainGetSchedulerType,
 107 domainGetUUID, (unsure if this is the correct output!)
 108 domainGetUUIDString,
 109 domainGetVcpus,
 110 domainReboot,
 111 domainShutdown,
 112 domainInterfaceStats,
 113 domainGetXMLDesc
 114
 115
 116 QUESTIONS
 117 ---------
 118
 119 If you have additional questions or inquiries you can email them to:
 120
 121 handlervirt@kinkrsoftware.nl
 122
 123
 124 [1] http://www.libvirt.org/
 125 [2] http://www.avahi.org/