Tutorial¶

Abstract¶

On this tutorial, we will go through brief instruction from Karesansui installation (using packages), to boot guest.

Goal¶

Preparing¶

Install Host OS

Use CentOS 5.5 or later to create host environment.

Just do usual installation, but be careful of the points below.

(Required) On software setup, check "Virtualization", "KVM".
(Not required but encouraged) Use LVM. It's easy to add storage in future. (It will be LVM-ready if you use the default partition offered by the installer)

Additional Requirements

Karesansui requires the following packages. Please make sure that these packages are installed.

• iscsi-initiator-utils
• cyrus-sasl-md5
• gnutls-utils
• PyXML
• SDL
• curl
• perl-URI
• perl-HTML-Parser
• gettext
• gnutls-utils

Other Preparations

If kvm-qemu-img package have already been installed in your system, you need to uninstall it before the installation.
Otherwise, as qemu package provided by the install-pack and kvm-qemu-img package would be conflicted, you might not install Karesansui completely.
To remove kvm-qemu-img package, please run the command below.

 # rpm -e --nodeps kvm-qemu-img

Download¶

Download the newest release from the Download Page.

Installation¶

Installing Karesansui is very easy.
The installation steps will be as follow:

# tar xzvf karesansui-2.0.1-install-pack.tar.gz
# cd Karesansui
# ./karesansui-install

Here is the detailed instructions.

'Welcome' screen

Press 'OK' button to display the next page.

'Administrator setting' screen

Setting up Karesansui administrator account.

Hostname	Specify FQDN of this Host OS
Mail address	Specify administrator's e-mail address. Requires this password at login.
Password	Specify administrator's password. Requires this password at login.
Password (again)	Specify the same password as 'Password' for confirmation
Language	Select the display languages of Karesansui.

'TLS certificates setting' screen

Setting up TLS certificates for libvirt remote SSL connection.

Country	Specify country ISO 2 letter code
State or Province Name	Specify your state or province name
Locality Name	Specify your location (e.g. town)
Origanization Name	Specify your organization (e.g. company name)
Common Name	Specify FQDN of this Host OS
Initialize SSL certificates settings?	If you want to initialize SSL keys and certificates, check the checkbox.

'Database setting' screen

Setting up Karesansui database.

In case of using MySQL or PostgreSQL as database, you need to create a database for Karesansui in advance and make sure to connect the database.

Database path	Specify the path of database for Karesansui
Database pysilhouette path	Specify the path database for pysilhouette job management daemon
Initialize database	If you want to initialize database, check the checkbox.

Please specify a database in using the following pattern:

MySQL	mysql://username:password@hostname/database?charset=utf8
PostgreSQL	pgsql://username:password@hostname/database
SQLite	sqlite:////var/opt/karesansui/karesansui.db

'Proxy setting' screen

Setting up a proxy connection to the Internet.

Use Proxy	If you want to use proxy at all, check the checkbox.
Hostname	Specify the hostname of proxy server
Port Number	Specify the port number of proxy server
Username	Specify the username for authentication on a proxy server
Password	Specify the password for authentication on a proxy server
Password (again)	Input the same password as 'Password' for confirmation

'Mail setting' screen

Setting up SMTP connection to send e-mail.

Hostname	Specify the hostname of SMTP server
Port Number	Specify the port number of SMTP server

'Confirm' screen

Press 'OK' button to proceed installation, then the software installation will start.
Press 'Back' or 'Cancel' to abort installation.

'Progress' screen

The current progress state of software installation is displayed.
Installation process goes on like this:

1. Installing the RPM packages.
2. Generating SSL certificates.
3. Writing the configuration files.
4. Initializing Karesansui database.
5. Enabling services that Karesansui uses.

'Finish' screen

When the installation process has finished successfully, messages will be displayed as follow.

If an error occurred and installation failed, error messages will be displayed.
See log file for further details to resolve errors. Then please install again.

Console output goes like this:

Done.
You can now login through following url. Your login credential is 'taizo@karesansui-project.info'.
 https://karesansui.example.com/karesansui/v2/
 http://karesansui.example.com/karesansui/v2/
See '/root/karesansui-install.log' for detail.

In the case that the KVM hypervisor is running on your machine, network device configuration files will be modified by installer. So you need to reload network.

# /etc/init.d/network restart

Logging in to the Management Console¶

Try the URL displayed on the "Finish" screen (like "https://{hostname}/karesansui/v2/").
Please input e-mail address and password in user authentication dialog, then login to the Management Console.

If you see the screen like this, then the installation had all succeeded.

Preparing for Guest OS Installation¶

Here is an example of installing CentOS 5.5(i386) to guest.
We describe two ways to do that.

1. if the host is able to connect to the internet. (Network Install)

Using kernel image and OS image on an external server, you can install guest OS.
You cannot retrieve the images via proxy server at installation, so you should use an external FTP server.
Be sure that the host is able to connect to the URL of CentOS 5.5's OS image.
Examples of URL:

http://<Web site name>/centos/5/os/i386/
ftp://<FTP site name>/Linux/centos/5/os/i386/

2. if the host is NOT able to connect to the internet. (Local Install/CD-ROM)

Using CentOS 5.5(i386) DVD, you can intall guest OS.
You'll need to setup your own FTP server temporarily, so you have to install FTP server software like vsftpd in advance.
Please insert CentOS 5.5(i386) DVD to drive, and mount OS image on AnonymousFTP area.

# rpm -q vsftpd 2>/dev/null || yum -y install vsftpd
# /etc/init.d/vsftpd restart
# mount /dev/cdrom /var/ftp/pub

Check to be sure that you can login to localhost as AnonymousFTP user.

# ftp localhost
Connected to localhost (127.0.0.1).
220 (vsFTPd 2.0.5)
Name (localhost:root): ftp
331 Please specify the password.
Password:
230 Login successful.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> quit

If you fail to login, SELinux may work.
Please set SELinux disabled temporarily by executing the following command.

# echo 0 >/selinux/enforce

3. if the host is NOT able to connect to the internet. (Local Install/ISO image)

In the case that the KVM hypervisor is running on your machine, you can install from CD-ROM ISO image.

If you doesn't have CD-ROM ISO image but DVD-ROM, 'dd' command can create CD-ROM ISO image.

# dd if=/dev/cdrom of=/iso/centos55-i386.iso
dd: reading `/dev/cdrom': Input/output error
269860+0 records in
269860+0 records out

Installing Guest OS¶

First, please click the host icon image on top window.
And click the 'Create' in 'Guests' tab, then 'Create guest' window as follow will be displayed.

Here we describe the ways to specify values for each item.

1. if the host is able to connect to the internet. (Network Install)

Kernel image	the URL of CentOS 5.5's kernel image path (ex: case of Xen=>'ftp://ftp.example.com/Linux/centos/5/os/i386/images/xen/vmlinuz', case of KVM=>'ftp://ftp.example.com/Linux/centos/5/os/i386/isolinux/vmlinuz')
initrd image	the URL of CentOS 5.5's initrd image path (ex: case of Xen=>'ftp://ftp.example.com/Linux/centos/5/os/i386/images/xen/initrd.img', case of KVM=>'ftp://ftp.example.com/Linux/centos/5/os/i386/isolinux/initrd.img')

As for other items, you can see the details clicking "?" displayed at the right of each item.

2. if the host is NOT able to connect to the internet. (Local Install)

Kernel image	case of Xen=>'/var/ftp/pub/images/xen/vmlinuz', case of KVM=>'/var/ftp/pub/isolinux/vmlinuz'
initrd image	case of Xen=>'/var/ftp/pub/images/xen/initrd.img', case of KVM=>'/var/ftp/pub/isolinux/initrd.img'

As for other items, you can see the details clicking "?" displayed at the right of each item.

Fill up all items, please click the "Create" button at the bottom of "Create guest" window.
Then, the message that the creation job is accepted will be displayed.

So the icon image that stands for new guest will appear in "Guests" window.

Please click the new guest icon, and then click the "Console" tab.
The console window of guest will be displayed. In this window, you can install CentOS 5.5 into guest as into real machine.

1. if the host is able to connect to the internet. (Network Install)

In the guest installation,

• 1. Selecting an Installation Method*
  You need to select the "HTTP" or "FTP".

• 2 - 1. Installing via HTTP

  Web site name	Web site name that provides OS image
  CentOS directory	image path on this site(ex: /Linux/centos/5/os/i386)

• 2 - 2. Installing via FTP

  FTP site name	FTP site name that provides OS image
  CentOS directory	image path on this site(ex: /Linux/centos/5/os/i386)

2. if the host is NOT able to connect to the internet. (Local Install)

In the guest installation,

• 1. Selecting an Installation Method*
  You need to select the "FTP".

• 2. Installing via FTP

  FTP site name	IP address of host (NOT loopback address)
  CentOS directory	/pub/

End¶

This is the end of the tutorial. You can now do basic operation about virtualization.

Hints

To allow a user to shut down a guest properly by Karesansui management console, ACPI event daemon must be installed and running in each guests.
Under CentOS, Red Hat Enterprise Linux or Fedora Linux, 'acpid' package should be installed, and the ACPI event daemon must start automatically at each system boot.

# rpm -q acpid 2>/dev/null || yum -y install acpid
# /sbin/service haldaemon stop
# /sbin/service apcid restart
# /sbin/chkconfig apcid on
# /sbin/service haldaemon start