(Translation based on http://karesansui-project.info/wiki/karesansui/Ja_install?version=48)

Installation¶

Required Spec.¶

Features¶

On Karesansui, we call the machine which hosts virtual machines "host", and the virtual machine instance which runs in the host "guest".

Catogory	Feature	Detail	Check
Common	Login	Login based on basic authentication.	x
Common	Logout	Logout.	x
Common	"My Account" Settings	Edit account information which are logged in now.	x
Common	Tags	Group guests using tags. Future support for other resources are planned.	x
Security	SSL settings	Enable/disable SSL for the Karesansui web interface server.	x
Security	Access policies	Access policy settings for Karesansui web interface	x
Security	VNC password settings	Sets/changes passwords for VNC connection to each individual guest	x
Security	Whitelist	Set whitelist of commands allowed to execute.(no web interface for this function)	x
Other	Karesansui	Display Karesansui version	x
General	Display hosts	Display hosts. Version 1 doesn't fully support multiple hosts.	x
General	Karesansui settings (web server)	Set Karesansui parameters.	x
General	Karesansui settings (mail server)	Set Karesansui parameters.	x
General	Tree navigation view for hosts and guests	Tree navigation view for hosts and guests.	x
Host	List of guests	Display list of guests.	x
Host	Host information	Display information about the host.	x
Host	Create guests	Create a guest.	x
Host	Copy guests	Copy a guest under management.	x
Host	Delete guests	Delete a guest under management.	x
Host	Edit	Edit host information.	x
Host	Jobs	Search and view jobs which are executed on the host.	x
Host	Add/edit/delete networks	Manage virtual network.	x
Host	Add/edit/delete firewall rules	Manage host firewall settings.	x
Host	Start/stop firewalls	Start/stop host firewall	x
User management	Create/edit/delete user	Manage users.	x
Edit tags	Create/edit/delete tags	Manage tags.	x
Guest	Information	Display information about guest.	x
Guest	Start	Start (boot up) guests.	x
Guest	Pause/resume guests.	Pause/resume a guest.	x
Guest	Force shutdown	Force guest to shutdown.	x
Guest	Shutdown	Standard guest shutdown.	x
Guest	Create/edit/delete snapshot	Manage snapshots.	x
Guest	Apply snapshost	Apply snapshots to a managed guest.	x
Guest	Add/edit/delete storage (HDD)	Manage storage (Virtual HDD.)	x
Guest	Add/edit/delete network interfaces	Manage network interfaces (NIC).	x
Guest	Add/edit/delete displays (VNC)	Manage virtual display (VNC).	x
Guest	Change CPU numbers	Change the number of CPUs for a guest.	x
Guest	Change RAM size	Change RAM size for a guest.	x
Guest	Jobs	Search/view jobs which are executed on a specified guest.	x
Guest	Console	Access guest consoles through the web interface.	x

How to Get the Source¶

There are several ways to get the source.

download from sourceforge.jp

The source code is provided as RPM package included in Karesansui install-pack(tarball).
You can download the install-pack from here.

download from git repository

The latest code can be download from git repository in "sourceforge.jp".

$ git clone git://git.sourceforge.jp/gitroot/karesansui/karesansui.git

Configuration File Format¶

log.conf

TODO

application.conf

application.search.path¶

Additional library search path for Python. Separate by commas (,) to specify two or more.

ex.) application.search.path=/opt/hde/lib/python,/opt/pysilhouette/lib/python,/opt/karesansui/lib/python

application.log.config¶

Location of the log config files to write.
More information about log config files are [[|here]].

ex.) application.log.config=/etc/opt/karesansui/log.conf

application.url.prefix¶

Prefix of the URI for Karesansui web interface
Prefix is a string between the curly braces below.
http://example.com{/karesansui/v1}/
We encourage to set "/v1" at the end.

ex.) application.url.prefix=/karesansui/v1

application.default.locale¶

Default locale for Karesansui web interface.
ja_JP and en_US are available now.
For user logged in, user's locale setting have priority over this.

ex.) application.default.locale=en_US

application.template.theme¶

Set Karesansui theme.
"default" is provided by the default installation.

ex.) application.template.theme=default

application.tmp.dir¶

Directory where Karesansui stores temporary files.

ex.) application.tmp.dir=/tmp

application.bin.dir¶

Directory where Karesansui stores job commands.
Karesansui process owner user must be able to write to this directory.

ex.) application.bin.dir=/opt/karesansui/bin

application.generate.dir¶

Template directory for various setting files.

ex.) application.generate.dir=/opt/karesansui/karesansui/templates/default/_generate

application.mail.email¶

Mail address which Karesansui uses for notification, etc..

ex.) application.mail.email=karesansui@example.com

application.mail.port¶

Mail server port which Karesansui uses for notification, etc..

ex.) application.mail.port=25

application.mail.server¶

Name of the mail server which Karesansui uses.

ex.) application.mail.server=localhost

application.proxy.status¶

Whether Karesansui use web proxy for outer connection or not.
1=Enable
0=Diable

ex.) application.proxy.status=0

application.proxy.server¶

Proxy server which Karesansui uses.

ex.) application.proxy.server=localhost

application.proxy.port¶

Proxy server port which Karesansui uses.

ex.) application.proxy.port=9080

application.proxy.user¶

Proxy user which Karesansui uses.

ex.) application.proxy.user=bar

application.proxy.password¶

Proxy password which Karesansui uses.

ex.) application.proxy.password=foo

lighttpd.etc.dir¶

Where to put Lighttpd config file which will be used when you access Karesansui web inteface through Lighttpd.

ex.) lighttpd.etc.dir=/etc/opt/hde/lighttpd/conf.d/karesansui

database.bind¶

Database bind for Karesansui. Specify in the style defined in RFC-1738.
For detail information, consult SQLAlchemy documentation Database Engines

Some examples:

MySQL
mysql://localhost/{{databasename}}
mysql://{{username}}:{{password}}@{{hostname}}/{{databasename}}
mysql://{{username}}:{{password}}@{{hostname}}:{{port}}/{{databasename}}

PostgreSQL
postgres://{{username}}:{{password}}@{{hostname}}:{{port}}/{{databasename}}
SQLite (Must be able to read/write by Karesansui process)
sqlite:////{{Absolute path}}/{{filename}}
sqlite:///{{Relative path}}/{{filename}}
ex.) database.bind=sqlite:////var/opt/karesansui/karesansui.db

database.pool.size¶

Connection pool size. Ignored on SQLite.

ex.) database.pool.size=1

h3. database.pool.max.overflow

Connection pool max size.

ex.) database.pool.max.overflow=10

pysilhouette.conf.path
bq. Pysilhouette configuration path. Must be readable by Karesansui process owner (not required to be writeable).¶

ex.) pysilhouette.conf.path=/etc/opt/pysilhouette/silhouette.conf

How to Start/Stop, Automatic Startup on Bootup¶

Karesansui works with 5 processes.
If you have installed Karesansui using the installer, start up configuration is automatically done.

• hde-libvirtd

Daemon from libvirtd, the abstract layer for virtualization.
Caution) If the original libvirtd which comes with the Linux distribution is running, hde-libvirtd fails to start up correctly. You must disable libvirtd first (possibly using "/sbin/chkconfig libvirtd off" command) before starting hde-libvirtd.

ex.)
Starting: /etc/init.d/hde-libvirtd start
Stopping: /etc/init.d/hde-libvirtd stop

ex.)
Automatic startup settings: chkconfig hde-libvirtd on
Check startup settings: chkconfig --list hde-libvirtd

• hde-lighttpd

Web server to be used to access Karesansui web interface. (Lighttpd)

ex.) 
Starting: /etc/init.d/hde-lighttpd start
Stopping: /etc/init.d/hde-lighttpd stop

ex.)
Automatic startup settings: chkconfig hde-lighttpd on
Check startup settings: chkconfig --list hde-lighttpd

• silhouetted

Job management service (Pysilhouette).

ex.) 
Starting: /etc/init.d/silhouetted start
Stopping: /etc/init.d/silhouetted stop

ex.)
Automatic startup settings: chkconfig silhouetted on
Check startup settings: chkconfig --list silhouetted

Solving Dependency Problems¶

iscsi-initiator-utils
cyrus-sasl-md5
gnutls-utils
PyXML

Problems after Installation¶

Use karesansui-checkenv which are placed in the installation folder to get diagonistics output for solving troubles.

ex.) 
# ./karesansui-checkenv
@==========================================@
@   Karesansui Environment Check Program   @
@==========================================@
Checking if Karesansui RPM packages are installed completely... OK
Checking if Karesansui config parameters are enough...  OK
Checking if Karesansui modules can be imported...  OK
Checking whether Karesansui group exists or not...  OK
Checking if Karesansui configuration file can be loaded...  OK
Checking if sqlalchemy modules can be imported...  OK
Checking if pysilhouette modules can be imported...  OK
Checking if pysilhouette config parameters are enough...  OK
Checking if pysilhouette configuration file can be loaded...  OK
Checking if Database API modules for Karesansui can be imported...  sqlite
Checking whether we are able to connect to database for Karesansui...  sqlite:////var/opt/karesansui/karesansui.db
Checking permission of SQLite database for Karesansui...  OK
Checking if Database API modules for pysilhouette can be imported...  sqlite
Checking whether we are able to connect to database for pysilhouette...  sqlite:////var/opt/pysilhouette/pysilhouette.db
Checking permission of SQLite database for pysilhouette...  OK
Checking permission of Karesansui files/directories...  OK
Checking if Karesansui services are running...  OK

Everything is gonna be alright!!

You can now login through following url.
 https://karesansui-project.info/karesansui/v1/
 http://karesansui-project.info/karesansui/v1/

A TODO