NameDateSize

..16-Mar-201612 KiB

.gitignore01-Dec-2015505

__init__.py01-Dec-2015854

ABOUT-NLS12-May-201491.6 KiB

API.json09-Dec-201529.7 KiB

autogen.sh01-Dec-2015467

build-aux/01-Aug-20144 KiB

ChangeLog25-Sep-2015222.3 KiB

check_ui_code_errors.sh01-Dec-20151.2 KiB

config.py.in01-Dec-20155.1 KiB

config.rpath12-May-201418 KiB

configure.ac15-Dec-20153.6 KiB

contrib/01-Dec-20154 KiB

CONTRIBUTE.md12-May-2014653

control/09-Dec-20154 KiB

COPYING01-Dec-2015772

COPYING.ASL212-May-201411.1 KiB

COPYING.LGPL12-Oct-201525.9 KiB

disks.py01-Dec-20159.3 KiB

distroloader.py01-Dec-20152.2 KiB

distros.d/01-Dec-20154 KiB

docs/15-Dec-20154 KiB

i18n.py09-Dec-201523.4 KiB

imageinfo.py01-Dec-20152.2 KiB

INSTALL12-May-201415.4 KiB

iscsi.py01-Dec-20153 KiB

isoinfo.py01-Dec-201520.5 KiB

kimchi.conf15-Dec-2015749

kvmusertests.py01-Dec-20152.4 KiB

m4/12-May-20144 KiB

Makefile.am01-Dec-20155.2 KiB

mockmodel.py09-Dec-201521.5 KiB

model/15-Dec-20154 KiB

netinfo.py09-Dec-20157.1 KiB

network.py01-Dec-20152.2 KiB

osinfo.py11-Dec-20159.6 KiB

po/01-Dec-20154 KiB

README.md01-Dec-20157.8 KiB

root.py09-Dec-20153 KiB

scan.py01-Dec-20152.9 KiB

screenshot.py01-Dec-20155.6 KiB

template.conf09-Dec-2015966

tests/15-Dec-20154 KiB

ui/01-Dec-20154 KiB

utils.py09-Dec-20157.2 KiB

VERSION01-Dec-20156

vmtemplate.py15-Dec-201517.9 KiB

vnc.py01-Dec-20152.5 KiB

xmlutils/15-Dec-20154 KiB

README.md

1Kimchi Project
2==============
3
4Kimchi is an HTML5 based management tool for KVM. It is designed to make it as
5easy as possible to get started with KVM and create your first guest.
6
7Kimchi runs as a Wok plugin. Wok runs as a daemon on the hypervisor host.
8
9Kimchi manages KVM guests through libvirt. The management interface is accessed
10over the web using a browser that supports HTML5.
11
12Browser Support
13===============
14
15Wok and its plugin can run in any web browser that supports HTML5. The
16Kimchi community (responsible for Wok project) makes an effort to
17test it with the latest versions of Chrome and Firefox browsers, but the
18following list can be used as reference to browser support.
19
20Desktop Browser Support:
21-----------------------
22* **Internet Explorer:** Current version
23* **Chrome:** Current version
24* **Firefox:** Current version
25* **Safari:** Current version
26* **Opera:** Current version
27
28Mobile Browser Support:
29-----------------------
30* **Safari iOS:** Current version
31* **Android Browser** Current version
32
33
34Hypervisor Distro Support
35=========================
36
37Kimchi might run on any GNU/Linux distribution that meets the conditions
38described on the 'Getting Started' section below.
39
40The Kimchi community makes an effort to test it with the latest versions of
41Fedora, RHEL, OpenSuSe, and Ubuntu.
42
43Getting Started
44===============
45
46Install Dependencies
47--------------------
48
49**For fedora and RHEL:**
50
51     $ sudo yum install wok libvirt-python libvirt \
52                        libvirt-daemon-config-network python-imaging \
53                        qemu-kvm python-ethtool sos python-ipaddr \
54                        nfs-utils iscsi-initiator-utils pyparted \
55                        python-libguestfs libguestfs-tools \
56                        python-websockify novnc spice-html5 \
57                        python-configobj python-magic python-paramiko
58
59     # If using RHEL, install the following additional packages:
60     $ sudo yum install python-unittest2 python-ordereddict
61
62     # Restart libvirt to allow configuration changes to take effect
63     $ sudo service libvirtd restart
64
65    # These dependencies are only required if you want to run the tests:
66    $ sudo yum install pyflakes python-pep8 python-requests python-mock
67
68
69*Note for RHEL users*: Some of the above packages are located in the Red Hat
70EPEL repositories.  See
71[this FAQ](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F)
72for more information on how to configure your system to access this repository.
73
74And for RHEL7 systems, you also need to subscribe to the "RHEL Server Optional"
75channel at RHN Classic or Red Hat Satellite.
76
77**For Ubuntu (Debian-based):**
78
79    $ sudo apt-get install wok python-imaging python-configobj websockify \
80                           novnc python-libvirt libvirt-bin nfs-common \
81                           qemu-kvm python-parted python-ethtool sosreport \
82                           xsltproc python-ipaddr python-lxml open-iscsi \
83                           python-guestfs libguestfs-tools spice-html5 \
84                           python-magic python-paramiko \
85
86    # These dependencies are only required if you want to run the tests:
87    $ sudo apt-get install pep8 pyflakes python-requests python-mock
88
89**For openSUSE:**
90
91    $ sudo zypper install wok libvirt-python libvirt \
92                          libvirt-daemon-config-network python-imaging \
93                          kvm python-ethtool python-ipaddr nfs-client \
94                          open-iscsi python-parted python-libguestfs \
95                          python-configobj guestfs-tools python-websockify \
96                          novnc python-magic
97
98    # These dependencies are only required if you want to run the tests:
99    $ sudo zypper install python-pyflakes python-pep8 python-requests python-mock
100
101*Note for openSUSE users*: Some of the above packages are located in different
102openSUSE repositories. See
103[this FAQ](http://download.opensuse.org/repositories/home:GRNET:synnefo/) for
104python-parted, [this FAQ](http://download.opensuse.org/repositories/systemsmanagement:/spacewalk/)
105for python-ethtool, and [this FAQ](http://download.opensuse.org/repositories/home:/Simmphonie:/python/) for python-magic to get the correct repository based on your openSUSE version. And
106[this FAQ](http://en.opensuse.org/SDB:Add_package_repositories) for more
107information on how configure your system to access this repository.
108
109Build and Install
110-----------------
111
112    Wok:
113    $ ./autogen.sh --system
114
115    $ make
116    $ sudo make install   # Optional if running from the source tree
117
118
119    Kimchi:
120    $ cd plugins/kimchi
121
122    For openSUSE 13.1:
123    $ ./autogen.sh --with-spice-html5
124
125    Otherwise:
126    $ ./autogen.sh --system
127
128    $ make
129    $ sudo make install   # Optional if running from the source tree
130
131Run
132---
133
134    $ sudo wokd --host=0.0.0.0
135
136If you cannot access Wok, take a look at these 2 points:
137
1381. Firewall
139Wok uses by default the ports 8000, 8001 and 64667. To allow incoming connections:
140
141    For system using firewalld, do:
142    sudo firewall-cmd --add-port=8000/tcp --permanent
143    sudo firewall-cmd --add-port=8001/tcp --permanent
144    sudo firewall-cmd --add-port=64667/tcp --permanent
145    sudo firewall-cmd --reload
146
147    For openSUSE systems, do:
148    sudo /sbin/SuSEfirewall2 open EXT TCP 8000
149    sudo /sbin/SuSEfirewall2 open EXT TCP 8001
150    sudo /sbin/SuSEfirewall2 open EXT TCP 64667
151
152    For system using iptables, do:
153    sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
154    sudo iptables -A INPUT -p tcp --dport 8001 -j ACCEPT
155    sudo iptables -A INPUT -p tcp --dport 64667 -j ACCEPT
156
157    Don't forget to correctly save the rules.
158
159
1602. SELinux
161Allow httpd_t context for Wok web server:
162
163    semanage permissive -a httpd_t
164
165
166Test
167----
168
169    $ cd plugins/kimchi
170    $ make check-local # check for i18n and formatting errors
171    $ sudo make check
172
173After all tests are executed, a summary will be displayed containing any
174errors/failures which might have occurred.
175
176Usage
177-----
178
179Connect your browser to https://localhost:8001.  You should see a screen like:
180
181![Wok Login Screen](/docs/kimchi-login.png)
182
183Wok uses PAM to authenticate users so you can log in with the same username
184and password that you would use to log in to the machine itself.  Once logged in
185you will see a screen like:
186
187![Kimchi Guest View](/docs/kimchi-guest.png)
188
189This shows you the list of running guests including a live screenshot of
190the guest session.  You can use the action buttons to shutdown the guests
191or connect to the display in a new window.
192
193To create a new guest, click on the "+" button in the upper right corner.
194In Kimchi, all guest creation is done through templates.
195
196You can view or modify templates by clicking on the Templates link in the
197top navigation bar.
198
199The template screen looks like:
200
201![Kimchi Template View](/docs/kimchi-templates.png)
202
203From this view, you can change the parameters of a template or create a
204new template using the "+" button in the upper right corner.
205
206To create a template, you need an ISO on your host or using remote one.
207If you are willing to use your own ISO, please copy it to out of box storage
208pool (default path is: /var/lib/kimchi/isos).
209
210Known Issues
211------------
212
2131. When you are using NFS as storage pool, check the nfs export path permission
214is configured as:
215    (1) export path need to be squashed as kvm gid and libvirt uid:
216        /my_export_path *(all_squash,anongid=<kvm-gid>, anonuid=<libvirt-uid>,rw,sync)
217        So that root user can create volume with right user/group.
218    (2) Chown of export path as libvirt user, group as kvm group,
219        In order to make sure all mapped user can get into the mount point.
220
221Participating
222-------------
223
224All patches are sent through our mailing list hosted by oVirt.  More
225information can be found at:
226
227https://github.com/kimchi-project/kimchi/wiki/Communications
228
229Patches should be sent using git-send-email to kimchi-devel@ovirt.org.
230