[Kimchi-devel] [RFC PATCH V2 06/31] Update kimchi plugin docs

Update kimchi plugin documentation to reflect new plugin structure. Signed-off-by: Lucio Correia <luciojhc(a)linux.vnet.ibm.com&gt; Signed-off-by: Gustavo Y. Ribeiro <gyr(a)linux.vnet.ibm.com&gt; --- plugins/kimchi/docs/API.md | 112 ++++++++++++++---------------- plugins/kimchi/docs/README-federation.md | 18 +++--- plugins/kimchi/docs/README.md | 37 +++++++--- 3 files changed, 86 insertions(+), 81 deletions(-) diff --git a/plugins/kimchi/docs/API.md b/plugins/kimchi/docs/API.md index e022c9e..bfefeab 100644 --- a/plugins/kimchi/docs/API.md +++ b/plugins/kimchi/docs/API.md @@ -31,13 +31,13 @@ the following general conventions: URI. Available *actions* are described within the *actions* property of a Resource representation. The request body *must* contain a JSON object which specifies parameters. -* URIs begin with a '/' to indicate the root of the API. +* URIs begin with '/plugins/kimchi' to indicate the root of Kimchi plugin. * Variable segments in the URI begin with a ':' and should replaced with the appropriate resource identifier. ### Collection: Virtual Machines -**URI:** /vms +**URI:** /plugins/kimchi/vms **Methods:** @@ -61,7 +61,7 @@ the following general conventions: ### Resource: Virtual Machine -**URI:** /vms/*:name* +**URI:** /plugins/kimchi/vms/*:name* **Methods:** @@ -149,7 +149,7 @@ the following general conventions: ### Sub-resource: Virtual Machine Screenshot -**URI:** /vms/*:name*/screenshot +**URI:** /plugins/kimchi/vms/*:name*/screenshot Represents a snapshot of the Virtual Machine's primary monitor. @@ -159,7 +159,7 @@ Represents a snapshot of the Virtual Machine's primary monitor. ### Sub-collection: Virtual Machine storages -**URI:** /vms/*:name*/storages +**URI:** /plugins/kimchi/vms/*:name*/storages * **GET**: Retrieve a summarized list of all storages of specified guest * **POST**: Attach a new storage or virtual drive to specified virtual machine. * type: The type of the storage (currently support 'cdrom' and 'disk'). @@ -168,7 +168,7 @@ Represents a snapshot of the Virtual Machine's primary monitor. * vol: Storage volume name of disk image. ### Sub-resource: storage -**URI:** /vms/*:name*/storages/*:dev* +**URI:** /plugins/kimchi/vms/*:name*/storages/*:dev* * **GET**: Retrieve storage information * dev: The name of the storage in the vm. * type: The type of the storage (currently support 'cdrom' and 'disk'). @@ -182,28 +182,28 @@ Represents a snapshot of the Virtual Machine's primary monitor. ### Sub-collection: Virtual Machine Passthrough Devices -**URI:** /vms/*:name*/hostdevs +**URI:** /plugins/kimchi/vms/*:name*/hostdevs * **GET**: Retrieve a summarized list of all directly assigned host device of specified guest. * **POST**: Directly assign a host device to guest. * name: The name of the host device to be assigned to vm. ### Sub-resource: Device -**URI:** /vms/*:name*/hostdevs/*:dev* +**URI:** /plugins/kimchi/vms/*:name*/hostdevs/*:dev* * **GET**: Retrieve assigned device information * name: The name of the assigned device. * type: The type of the assigned device. * **DELETE**: Detach the host device from VM. ### Sub-collection: Virtual Machine Snapshots -**URI:** /vms/*:name*/snapshots +**URI:** /plugins/kimchi/vms/*:name*/snapshots * **POST**: Create a new snapshot on a VM. * name: The snapshot name (optional, defaults to a value based on the current time). * **GET**: Retrieve a list of snapshots on a VM. ### Sub-resource: Snapshot -**URI:** /vms/*:name*/snapshots/*:snapshot* +**URI:** /plugins/kimchi/vms/*:name*/snapshots/*:snapshot* * **GET**: Retrieve snapshot information. * created: The time when the snapshot was created (in seconds, since the epoch). @@ -220,12 +220,12 @@ Represents a snapshot of the Virtual Machine's primary monitor. * revert: Revert the domain to the given snapshot. ### Sub-resource: Current snapshot -**URI:** /vms/*:name*/snapshots/current +**URI:** /plugins/kimchi/vms/*:name*/snapshots/current * **GET**: Retrieve current snapshot information for the virtual machine. ### Collection: Templates -**URI:** /templates +**URI:** /plugins/kimchi/templates **Methods:** @@ -270,7 +270,7 @@ Represents a snapshot of the Virtual Machine's primary monitor. ### Sub-Collection: Virtual Machine Network Interfaces -**URI:** /vms/*:name*/ifaces +**URI:** /plugins/kimchi/vms/*:name*/ifaces Represents all network interfaces attached to a Virtual Machine. @@ -289,7 +289,7 @@ Represents all network interfaces attached to a Virtual Machine. ### Sub-Resource: Virtual Machine Network Interface -**URI:** /vms/*:name*/ifaces/*:mac* +**URI:** /plugins/kimchi/vms/*:name*/ifaces/*:mac* A interface represents available network interface on VM. @@ -324,7 +324,7 @@ A interface represents available network interface on VM. ### Resource: Template -**URI:** /templates/*:name* +**URI:** /plugins/kimchi/templates/*:name* **Methods:** @@ -397,7 +397,7 @@ A interface represents available network interface on VM. ### Collection: Storage Pools -**URI:** /storagepools +**URI:** /plugins/kimchi/storagepools **Methods:** @@ -428,7 +428,7 @@ A interface represents available network interface on VM. ### Resource: Storage Pool -**URI:** /storagepools/*:name* +**URI:** /plugins/kimchi/storagepools/*:name* **Methods:** @@ -473,7 +473,7 @@ A interface represents available network interface on VM. ### Collection: Storage Volumes -**URI:** /storagepools/*:poolname*/storagevolumes +**URI:** /plugins/kimchi/storagepools/*:poolname*/storagevolumes **Methods:** @@ -493,7 +493,7 @@ A interface represents available network interface on VM. ### Resource: Storage Volume -**URI:** /storagepools/*:poolname*/storagevolumes/*:name* +**URI:** /plugins/kimchi/storagepools/*:poolname*/storagevolumes/*:name* **Methods:** @@ -531,7 +531,7 @@ A interface represents available network interface on VM. ### Collection: Interfaces -**URI:** /interfaces +**URI:** /plugins/kimchi/interfaces **Methods:** @@ -539,7 +539,7 @@ A interface represents available network interface on VM. ### Resource: Interface -**URI:** /interfaces/*:name* +**URI:** /plugins/kimchi/interfaces/*:name* A interface represents available interface on host. @@ -570,7 +570,7 @@ A interface represents available interface on host. ### Collection: Networks -**URI:** /networks +**URI:** /plugins/kimchi/networks **Methods:** @@ -592,7 +592,7 @@ A interface represents available interface on host. ### Resource: Network -**URI:** /networks/*:name* +**URI:** /plugins/kimchi/networks/*:name* **Methods:** @@ -637,7 +637,7 @@ A interface represents available interface on host. ### Collection: Tasks -**URI:** /tasks +**URI:** /plugins/kimchi/tasks **Methods:** @@ -645,7 +645,7 @@ A interface represents available interface on host. ### Resource: Task -**URI:** /tasks/*:id* +**URI:** /plugins/kimchi/tasks/*:id* A task represents an asynchronous operation that is being performed by the server. @@ -668,7 +668,7 @@ server. ### Resource: Configuration -**URI:** /config +**URI:** /plugins/kimchi/config Contains information about the application environment and configuration. @@ -685,7 +685,7 @@ Contains information about the application environment and configuration. ### Resource: Capabilities -**URI:** /config/capabilities +**URI:** /plugins/kimchi/config/capabilities Contains information about the host capabilities: iso streaming, screenshot creation. @@ -716,7 +716,7 @@ creation. ### Collection: Storage Servers -**URI:** /storageservers +**URI:** /plugins/kimchi/storageservers **Methods:** @@ -727,7 +727,7 @@ creation. ### Resource: Storage Server -**URI:** /storageservers/*:host* +**URI:** /plugins/kimchi/storageservers/*:host* **Methods:** @@ -737,7 +737,7 @@ creation. ### Collection: Storage Targets -**URI:** /storageservers/*:name*/storagetargets +**URI:** /plugins/kimchi/storageservers/*:name*/storagetargets **Methods:** @@ -754,7 +754,7 @@ creation. ### Collection: Distros -**URI:** /config/distros +**URI:** /plugins/kimchi/config/distros **Methods:** @@ -762,7 +762,7 @@ creation. ### Resource: Distro -**URI:** /config/distros/*:name* +**URI:** /plugins/kimchi/config/distros/*:name* Contains information about the OS distribution. @@ -780,7 +780,7 @@ Contains information about the OS distribution. #### Collection: Debug Reports -**URI:** /debugreports +**URI:** /plugins/kimchi/debugreports **Methods:** @@ -792,7 +792,7 @@ Contains information about the OS distribution. ### Resource: Debug Report -**URI:** /debugreports/*:name* +**URI:** /plugins/kimchi/debugreports/*:name* A Debug Report is an archive of logs and other information about the host that is used to diagnose and debug problems. The exact format and contents are @@ -819,7 +819,7 @@ specific to the low level collection tool being used. ### Sub-resource: Debug Report content -**URI:** /debugreports/*:name*/content +**URI:** /plugins/kimchi/debugreports/*:name*/content It is the sub-resource of Debug Report and the client use it to get the real content of the Debug Report file from the server @@ -832,7 +832,7 @@ of the Debug Report file from the server ### Resource: Host -**URI:** /host +**URI:** /plugins/kimchi/host Contains information of host. **Methods:** @@ -859,7 +859,7 @@ Contains information of host. ### Resource: Users -**URI:** /users +**URI:** /plugins/kimchi/users List of available users. **Methods:** @@ -871,7 +871,7 @@ List of available users. ### Resource: Groups -**URI:** /groups +**URI:** /plugins/kimchi/groups List of available groups. **Methods:** @@ -880,7 +880,7 @@ List of available groups. ### Resource: HostStats -**URI:** /host/stats +**URI:** /plugins/kimchi/host/stats Contains the host sample data. @@ -912,7 +912,7 @@ Contains the host sample data. ### Resource: HostStats -**URI:** /host/cpuinfo +**URI:** /plugins/kimchi/host/cpuinfo The cores and sockets of a hosts's CPU. Useful when sizing VMs to take advantages of the perforamance benefits of SMT (Power) or Hyper-Threading (Intel). @@ -936,7 +936,7 @@ advantages of the perforamance benefits of SMT (Power) or Hyper-Threading (Intel ### Resource: HostStatsHistory -**URI:** /host/stats/history +**URI:** /plugins/kimchi/host/stats/history It is the sub-resource of Host Stats and the client uses it to get the host stats history @@ -962,17 +962,9 @@ stats history *No actions defined* -### Collection: Plugins - -**URI:** /plugins - -**Methods:** - -* **GET**: Retrieve a summarized list names of all UI Plugins - ### Collection: Partitions -**URI:** /host/partitions +**URI:** /plugins/kimchi/host/partitions **Methods:** @@ -980,7 +972,7 @@ stats history ### Resource: Partition -**URI:** /host/partitions/*:name* +**URI:** /plugins/kimchi/host/partitions/*:name* **Methods:** @@ -998,7 +990,7 @@ stats history ### Collection: Devices -**URI:** /host/devices +**URI:** /plugins/kimchi/host/devices **Methods:** @@ -1016,7 +1008,7 @@ stats history ### Resource: Device -**URI:** /host/devices/*:name* +**URI:** /plugins/kimchi/host/devices/*:name* **Methods:** @@ -1045,11 +1037,11 @@ stats history ### Sub-collection: VMs with the device assigned. -**URI:** /host/devices/*:name*/vmholders +**URI:** /plugins/kimchi/host/devices/*:name*/vmholders * **GET**: Retrieve a summarized list of all VMs holding the device. ### Sub-resource: VM holder -**URI:** /host/devices/*:name*/vmholders/*:vm* +**URI:** /plugins/kimchi/host/devices/*:name*/vmholders/*:vm* * **GET**: Retrieve information of the VM which is holding the device * name: The name of the VM. * state: The power state of the VM. Could be "running" and "shutdown". @@ -1057,7 +1049,7 @@ stats history ### Collection: Host Packages Update -**URI:** /host/packagesupdate +**URI:** /plugins/kimchi/host/packagesupdate Contains the information and action of packages update in the host. @@ -1067,7 +1059,7 @@ Contains the information and action of packages update in the host. ### Resource: Host Package Update -**URI:** /host/packagesupdate/*:name* +**URI:** /plugins/kimchi/host/packagesupdate/*:name* Contains the information for a specific package to be updated. @@ -1081,7 +1073,7 @@ Contains the information for a specific package to be updated. ### Collection: Host Repositories -**URI:** /host/repositories +**URI:** /plugins/kimchi/host/repositories **Methods:** @@ -1101,7 +1093,7 @@ http://, ftp:// or file:// URL. ### Resource: Repository -**URI:** /host/repositories/*:repo-id* +**URI:** /plugins/kimchi/host/repositories/*:repo-id* **Methods:** @@ -1147,7 +1139,7 @@ http://, ftp:// or file:// URL. ### Collection: Peers -**URI:** /peers +**URI:** /plugins/kimchi/peers **Methods:** diff --git a/plugins/kimchi/docs/README-federation.md b/plugins/kimchi/docs/README-federation.md index b71a172..c184f4f 100644 --- a/plugins/kimchi/docs/README-federation.md +++ b/plugins/kimchi/docs/README-federation.md @@ -1,11 +1,11 @@ Kimchi Project - Federation Feature =================================== -Federation feature is a mechanism to discover Kimchi peers in the same network. -It uses openSLP tool (http://www.openslp.org/) to register and find the Kimchi +Federation feature is a Kimchi mechanism to discover Wok peers in the same +network. It uses openSLP tool (http://www.openslp.org/) to register and find Wok servers. -By default this feature is disabled on Kimchi as it is not critical for KVM +By default this feature is disabled on Wok as it is not critical for KVM virtualization and requires additional software installation. To enable it, do the following: @@ -43,18 +43,18 @@ To enable it, do the following: For system using iptables, do: sudo iptables -A INPUT -s <subnet> -j ACCEPT -4. Start slpd service and make sure it is up while running Kimchi +4. Start slpd service and make sure it is up while running Wok sudo service slpd start -5. Enable federation on Kimchi by editing the /etc/kimchi/kimchi.conf file: +5. Enable federation on Wok by editing the /etc/wok/wok.conf file: federation = on -6. Then start Kimchi service - sudo service kimchid start +6. Then start Wok service + sudo service wokd start -The Kimchi server will be registered on openSLP on server starting up and will -be found by other Kimchi peers (with federation feature enabled) in the same +The Wok server will be registered on openSLP on server starting up and will +be found by other Wok peers (with federation feature enabled) in the same network. Enjoy! diff --git a/plugins/kimchi/docs/README.md b/plugins/kimchi/docs/README.md index 034a591..f400333 100644 --- a/plugins/kimchi/docs/README.md +++ b/plugins/kimchi/docs/README.md @@ -4,9 +4,10 @@ Kimchi Project Kimchi is an HTML5 based management tool for KVM. It is designed to make it as easy as possible to get started with KVM and create your first guest. -Kimchi runs as a daemon on the hypervisor host. It manages KVM guests through -libvirt. The management interface is accessed over the web using a browser that -supports HTML5. +Kimchi runs as a Wok plugin. Wok runs as a daemon on the hypervisor host. + +Kimchi manages KVM guests through libvirt. The management interface is accessed +over the web using a browser that supports HTML5. Browser Support =============== @@ -33,11 +34,11 @@ find. Hypervisor Distro Support ========================= -Kimchi daemon might run on any GNU/Linux distribution that meets the conditions +Kimchi and Wok might run on any GNU/Linux distribution that meets the conditions described on the 'Getting Started' section below. -The Kimchi community makes an effort to test with the latest versions of Fedora, -RHEL, OpenSuSe, and Ubuntu. +The Kimchi community makes an effort to test it with the latest versions of +Fedora, RHEL, OpenSuSe, and Ubuntu. Getting Started =============== @@ -125,6 +126,17 @@ information on how configure your system to access this repository. Build and Install ----------------- + + Wok: + $ ./autogen.sh --system + + $ make + $ sudo make install # Optional if running from the source tree + + + Kimchi: + $ cd plugins/kimchi + For openSUSE 13.1: $ ./autogen.sh --with-spice-html5 @@ -137,12 +149,12 @@ Build and Install Run --- - $ sudo kimchid --host=0.0.0.0 + $ sudo wokd --host=0.0.0.0 -If you cannot access Kimchi, take a look at these 2 points: +If you cannot access Wok, take a look at these 2 points: 1. Firewall -Kimchi uses by default the ports 8000, 8001 and 64667. To allow incoming connections: +Wok uses by default the ports 8000, 8001 and 64667. To allow incoming connections: For system using firewalld, do: sudo firewall-cmd --add-port=8000/tcp --permanent @@ -164,7 +176,7 @@ Kimchi uses by default the ports 8000, 8001 and 64667. To allow incoming connect 2. SELinux -Allow httpd_t context for Kimchi web server: +Allow httpd_t context for Wok web server: semanage permissive -a httpd_t @@ -172,6 +184,7 @@ Allow httpd_t context for Kimchi web server: Test ---- + $ cd plugins/kimchi $ make check-local # check for i18n and formatting errors $ sudo make check @@ -183,9 +196,9 @@ Usage Connect your browser to https://localhost:8001. You should see a screen like: - + -Kimchi uses PAM to authenticate users so you can log in with the same username +Wok uses PAM to authenticate users so you can log in with the same username and password that you would use to log in to the machine itself. Once logged in you will see a screen like: -- 1.7.1