This whole project is intended to build up a VMware-like tool, which is based on Eve to provide a set of RESTful interfaces, and making full use of libvirt to manage underlying VMs and corresponding peripherals including virtual interface cards, virtual disks and the like.

1. libvirt-java-api is kind of deprecated refactored version of the client interfaces and corresponding test cases;

2. pool_management is where all the pool manamgement related files exist including some automatic assistant scripts;

3. RESTful-java-api is the bran-new version which we are trying to make use of Eve to replace former out-dated xmlrpc to achieve RPC and data storing features.

4. Folder Server is the server-side of the project using Eve as the basic underlying framework and trying to provide a RESTful web service for the java clients and web pages.

By LHearen E-mail: LHearen@126.com

This Guide is used to lead developers to work on clients based-on this server provided by us, which will including Configure Eve, Configure Mongodb 3.2, Starting our service and the last but also the most important part, APIs supplied both in client demo and server side.

We currently are adopting Eve as our basic framework to build our server side, which is coded in python and can be easily installed via pip to achieve global installation. So there are three steps then we need to complete:

• install pip - there is a get-pip.py, get it and just run 'python get-pip.py' then everything will be handled automatically if there is something wrong in this process check this site for some reference.

• install eve globally - 'pip install eve'.

• replace some files under '/usr/lib64/python2.7/site-packages/eve/' replace 'endpoints.py' and 'methods/post.py' with the same files under 'Server/Eve'; these files are modified to fit in our requirements.

Due to the requirement of our service, we have to provide a database for data storing, meantime the underlying database chosen by Eve is also mongodb, so we have to configure it for further development. There are also two simple steps we need to follow:

• configure repository under /etc/yum.repos.d/ - run 'vim /etc/yum.repos.d/mongodb.repo' and then copy the following profile to it

[mongodb-org-3.2]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/3.2/x86_64/
gpgcheck=0
enabled=1

save it and exit.

• 'yum clean all' and make sure the network connection is alright and then execute this command 'yum install -y mongodb-org' to install mongodb of version 3.2, the latest stable version.

Before you truly start to develope on this framework, there are two major parts you've got to understand first.

Rule 1 - parameters

• For creation methods, there will always be a config object for you to adopt to store essential values and optional ones while the essential will be used to construct the config object and the optional will be set by 'set' methods; after all these, you can then pass this config to the creation methods to create corresponding objects (VM, StoragePool, Volume or VIF for example); to make this process more clear, an simple example will be quite essential here - if you try to just create a VM with the essential values, then the UUID of the VM will be automatically generated by the server and at the same time considering the name is also optional then the name will be set to UUID too; if in this case, you want to set the UUID of the VM, then after constructing the config, you have to call setUUID to set it and likewise you can use setName to set its name to use a customized name instead of a UUID which might be quite confusing sometimes.
• For all other methods, the uuid will be needed to execute related operations (VM.start(uuidString) for example); of course some other essential values might also be necessary at times, but it will be clarified clearly by its testing demo and this kind of case is quite rare by the way.

Rule 2 - return value

• As for creation, if the operation succeed, server will return the UUID of the newly created object, if failed for duplicate UUID the corresponding message '_id already exists!' will be delivered but when it failed for some unexpected errors, 'User function failed' will be returned as a error message.
• When it comes to other methods, if it finished successfully, 'true' will be returned but if it encounters some unexpected failures, it will also return 'User function failed!'; there some exceptions in these methods which are inquiring 'true' or 'false' or other result from the server themselves ('isTemplate' and 'listPool' for example) then they will return 'true' or 'false' or other information it enquired when succeed but still will return 'User function failed' when encountering some unexpected errors.

• create - the parameter accepted is a customized object which will cover the basic and essential elements which creating process will require, besides there are some default values which means that they can be ignored and specified according to the situation. For example, the UUID of the VM can be ignored and then the server will automatically generate one for it, at the same time the client can set it by an exposed interface - setUUID method to set it before creating and then the server will use the provided UUID to create the VM.
• start, shutdown, reboot, delete - all these four methods will require a UUID of the VM to proceed corresponding operation(start, shut off, reboot or delete).
• isTemplate - is a method to check whether the VM is a template.
• setTemplate, unsetTemplate - to set a VM template or otherwise.

• createPool - a customized object will be passed as the parameter, for more details, you check Rule 1.
• deletePool - the UUID should be provided to specify the pool.
• listPools - this method will return a string composed of pools' names separated by comma in the host.
• createVolume - a customized object will be passed as the parameter, for more details, you check Rule 1.
• deleteVolume - only the UUID of the volume will be needed.
• listVolumes - the UUID of pool is needed here and the result will a string composed of names separated by comma.
• attach - using the UUID of VM and volume and target of VM to complete attaching a certain volume to a VM.
• detach - the opposite operation of attach.

• create - just like VM, a customized object will be used to specify the factors creating operation requires and also some values can be ignored for more details, check Rule 1.
• delete - only UUID required to accomplished this operation.
• attach - to attach a VIF to an existed VM while both are specified by UUID.
• detach - to detach a VIF from an VM while both are specified by UUID.

This documentation is used to specify the details of the APIs in server side which can be used to understand the underlying realization details and helpful to clients development.

• The client side (a java or web client) would invoke an encapsulated POST method to transfer method information and the parameters the method needs to the server;

• the server side will automatically dispatch the called method before the data transferred to the normal eve handling process in which process the data will be handled in RESTful way and the data will meantime validated according to the configuration defined in settings.py.

• due to some extra data being enclosed in the request, the eve module will prompt failure in data validation and data insertion, so we have to remove the data undefined in settings.py before the checking process in post.py of eve which is always located in /usr/lib64/python2.7/site-packages/eve/*.

• another thing should not be ignored is that the uuidString used in creation process (VM, StoragePool, Volumes and VIF and the like) can be ignored in client side which will use a default one to replace to keep the data part complete but before the mongodb inserting process, the uuidString must be replaced with the actual one which can be generated by either libvirt or UUIDGenerator.py.

• all the create* methods will be handled first by invoking related methods manipulating the libvirt interfaces and then pass through the 'eve' while all the related data will be further process before mongodb insertion in 'DBEventHander.py'; as for the returning value, it will be cut out the formal redundant profile and just return the UUID of the newly created object.

• all the other methods will be handled separately and the response will also be handled in customized way.

• create -- using some parameters to create a VM and return the uuidString to the client if failed return 'User function failed';
• start -- start a VM specified by uuidString and return True if failed return False;
• shutdown -- shut down a VM specified by uuidString and the return value will be just like create;
• delete -- delete a VM specified by uuidString and the return value will be just like create;
• reboot -- reboot a VM specified by uuidString and the return value will be just like create;
• isTemplate -- check a whether a VM is template or not and return True if it is otherwise return False;
• setTemplate -- set a VM to VM template if this operation done as expected return True otherwise False;
• unsetTemplate - unset a VM to VM template if this operation done as expected return True otherwise False.

• createPool -- create a storage pool and return the uuidString to the client if failed return 'User function failed';
• deletePool -- delete a storage pool and return True if done successfully otherwise return False;
• listPools -- return a string composed by names of pools created and separated by comma but return 'User function failed' if something unexpected happened;
• createVolume -- create a volume and return the uuidString to the client if failed return 'User function failed';
• deleteVolume -- delete a volume and return True if done successfully otherwise return 'User function failed';
• listVolumes -- list all volumes in a pool specified by a pool uuidString and return a string composed of names of volumes which is separated by comma but return 'User function failed' if something unexpected occurred;
• attach -- used to attach a existed volume to a specified VM both of them are specified by uuidString and return True if succeed otherwise return 'User function failed';
• detach -- the opposite operation of attach;

• create -- create a VIF according to the provided parameters return uuidString if created successfully, otherwise return 'User function failed';
• delete -- delete a VIF by its uuidString and return True if it is done successfully, otherwise return 'User function failed';
• attach -- attaching a created VIF to an existed vm via uuidString ob them and return True if succeed otherwise return 'User function failed';
• detach -- the opposite operation of attach.

###Team members Now this project is supported by only four major members while LHearen and Frank are working on underlying server part.

• LHearen: LHearen@126.com, luosonglei14@otcaix.iscas.ac.cn
• Frank: wuyuewen11@otcaix.iscas.ac.cn