• En faq
• En howto multi host
• En howtos
• En license
• En pysilhouette
• En reference
• En tutorial
• En update
• En wiki policy
• Ja En tutorial
• Ja faq
• Ja howto error
• Ja howto image
• Ja howto init setting
• Ja howto install images
• Ja howto log cutem
• Ja howto multi host
• Ja howtos
• Ja license
• Ja pysilhouette
• Ja reference
• Ja tutorial
• Ja update
• Ja wiki policy
• V2 En dev top
• V2 En faq
• V2 En howto error
• V2 En howto image
• V2 En howto init setting
• V2 En howto log customize
• V2 En howto multi host
• V2 En howtos
• V2 En install
• V2 En license
• V2 En pysilhouette
• V2 En reference
• V2 En tutorial
• V2 En update
• V2 Ja dev build package
• V2 Ja dev top
• V2 Ja faq
• V2 Ja howto create db
• V2 Ja howto error
• V2 Ja howto image
• V2 Ja howto init setting
• V2 Ja howto install images
• V2 Ja howto log customize
• V2 Ja howto multi host
• V2 Ja howtos
• V2 Ja license
• V2 Ja pysilhouette
• V2 Ja reference
• V2 Ja reference DownloadSource
• V2 Ja reference ER
• V2 Ja reference Function
• V2 Ja reference Import Export
• V2 Ja reference Requirements
• V2 Ja reference ScreenStructure
• V2 Ja reference SettingFiles
• V2 Ja reference StoragePool
• V2 Ja reference TroubleShooting
• V2 Ja reference Watch
• V2 Ja tutorial
• V2 Ja update
• V2 ja dev make dev env
• V2 ja dev make new page
• V2 ja dev make system
• V2 ja dev provide the framework controller
• V2 ja dev provide the framework model access
• V2 ja dev provide the framework model modell
• V2 ja dev provide the framework view
• V2 ja dev repository description

FAQ
(based on Ja_faq#21)¶

Table of Contents¶

• FAQ
  (based on Ja_faq#21)
• Table of Contents
• General
• Q. Is it free?
• Q. What kind of the license is Karesansui under?
• Q. Does Karesansui support full-virtualization?
• Q. Does Karesansui only support Xen?
• Q. I'm not used to Linux. Is the installation easy?
• Q. There are already many virtulization management consoles around there. What are the pros of Karesansui?
• Q. I'd like to introduce Karesansui to others.
• Q. I'd like to use Karesansui in our company's network. Is there any license problems?
• Application
• Q. What happens when the database, which Karesansui refers, stops? Does the guest stop?
• Q. I'll get "You need Java installed" errors when I try to access the guest console.
• Q. Guest console doesn't show up. What can I do?
• Q. Guest console keymap is garbled.
• Q. It doesn't work.
• Logging
• Q. How can I change the maximum size of log files, its file path or the number of rotated files?
• Q. An error message is displayed on the screen but it seems that these trace messages are not properly written to the log file.
• Q. I'd like to change the format of log files.
• Q. Where is the log file found?
• Q. I found three log files. What does the each log file contain?

General¶

Q. Is it free?¶

Yes, it is. You may use Karesansui for business or personal use for free.

Q. What kind of the license is Karesansui under?¶

Karesansui is mainly under GPL and LGPL. See here for details.

Q. Does Karesansui support full-virtualization?¶

Karesansui is aimed to support virtual servers so it does not support full-virtualization now. We are planning to support it in future. While it is not supported by Karesansui, you may setup full-virtualized guests using command line.

Q. Does Karesansui only support Xen?¶

Yes, it only supports Xen now. But we are planning to support KVM in near future.

Q. I'm not used to Linux. Is the installation easy?¶

We prepared and install pack so you should be able to install Karesansui easily. Please follow our Tutorial.

Q. There are already many virtulization management consoles around there. What are the pros of Karesansui?¶

We are working hard. Please take a look at our Karesansui's full ajax web control panel.

Q. I'd like to introduce Karesansui to others.¶

Yes! Thank you! Take the Get Karesansui Badge if you like it.

Q. I'd like to use Karesansui in our company's network. Is there any license problems?¶

No. Nothing. It's GPL/LGPL so there's no problem.

Application¶

Q. What happens when the database, which Karesansui refers, stops? Does the guest stop?¶

No. Karesansui uses the database to keep information for its user interface. Guests don't stop if when the database stops, but you will have problems to access Karesansui control panel.

Q. I'll get "You need Java installed" errors when I try to access the guest console.¶

We use TightVNC Java applet for guest console. So you need Java installed for your browser.

Q. Guest console doesn't show up. What can I do?¶

First, Check if you can access your host. From your client's console, type

> ping {Karesansui server IP address or name}

Next, Check if the VNC port is open on your Karesansui host.

# netstat -nalt

If all above are OK, then try to connect the guest from the client, using standard VNC viewer applications.

Q. Guest console keymap is garbled.¶

Select 'Display' from guest device tab, and set 'VNC Keymap'. Choose appropriate keymap.

Q. It doesn't work.¶

Go and ask your question in the Karesansui Forum . Somebody may answer you.

Logging¶

Q. How can I change the maximum size of log files, its file path or the number of rotated files?¶

You need to change "args" parameter in "[handler_*" catetories of log.conf. The following example shows how you can change those settings.

In case that you want to change the maximum size of log file from 5 Mbytes to 10 Mbytes:

(before) args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
(after) args=('/var/log/karesansui/application.log', 'a', (10 *1024 *1024), 5)

In case that you want to change the name of log file from application.log to server.log:

(before) args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
(after) args=('/var/log/karesansui/server.log', 'a', (5 *1024 *1024), 5)

In case that you want to change the maximum number of rotated log files from 5 to 10:

(before) args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
(after) args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 10)

Q. An error message is displayed on the screen but it seems that these trace messages are not properly written to the log file.¶

It is possible that logging is limited by specific log level. Please check the level in category of "[logger_*".

Avaliable Log Levels (* The former level includes the latter.)
 - DEBUG : All messages.  debug-level message.
 - INFO : Informational message.
 - WARNING : Warning conditions. This is recommended during operation.
 - ERROR : Error conditions.
 - CRITICAL : Critical and fatal conditions.
 - EXCEPTION : Application error message.

Notice: You must restart the Web service, or lighttpd, for the changes to take effect.

Q. I'd like to change the format of log files.¶

Karesansui supports all the format that is avaliable in Python logging. So please check Python official site for details.

Q. Where is the log file found?¶

The path of the log file is set as a value of "args" parameter in "[handler_*" categories of log.conf.

Q. I found three log files. What does the each log file contain?¶

Karesansui outputs the following multiple log files:

How can I set up multiple hosts?¶

Required Conditions¶

1. You should be using databases which allows network connection from multiple hosts, like MySQL or PostgreSQL.
2. SQLite can't be used for multiple host configuration.

How to add a new host¶

Definitions¶

1. Host A = Existing host (Karesansui installed)
2. Host B = A new host to be added

Step 1. Check the version of exisiting Karesansui¶

Access Karesansui on host A, click "Options" which are in the header, and display "About Karesansui" screen. Take a memo of the version information.

Step 2. Install Karesansui in host B¶

Download the same version of the Karesansui you checked in Step 1, and install it into host B.

warning: While the install process, you will be asked about the database location. Specify the same location of host A, and DO NOT CHECK the "Initilize database" checkbox.

ref. Tutorial

Step 3. Check the Karesansui unique key of host B¶

Look in /etc/opt/karesansui/application.conf of the host B, and find "application.uniqkey". The value is the unique key of host B. We use this in Step4, so take a memo of the unique key. example) application.uniqkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Step 4. Add host B to host A Karesansui¶

Access host A, and click "Add" at the top page to add a host. Input required fields and press "Add".

Some explaination:
- Host Name (required): The host name to display on Karesansui control panel. There are no restrictions for this name so choose the name you like.
           Example）Host B

- FQDN (required): FQDN of host B to access from the client. Input a FQDN or an IP address.
           Example）hostb.karesansui-project.info / 192.168.0.1

- UUID (required) : Input the Karesansui unique key of Host B you checked in Step 3.
- Note : Space for a memo.
- Tags : Tags to put on this host.

Step 5. Testing¶

Access host A Karesansui control panel, and click host B icon (usually the N/A icon are displayed) to display details. Find "Link to host" in "Other Information" and click to see the host B control panel. Basic authorization may be required at this step. 

If you see host B name in the control panel header, host was successfully added. *A

*A : Host name should appear in the right of this image.

P.S.: Host B icon can be changed on host B control panel.

Index of HOWTOs¶

• How can I set up multiple hosts?
• ログをカスタマイズするには？
• エラーが発生した場合には？
• 初期値を変更したい場合には？
• カーネルイメージ・initrdイメージってなに？
• インストールしたゲストのイメージファイルはどこにあるの？

License¶

Some parts of Karesansui are GPL, and some are LGPL, but the core architecture is LGPL, to reduce problems for re-using. All source code has license notice, so you should clearly know what license to follow.

For exception, some Karesansui files some don't have license notice for technical problems. The files under template/default/include coming with the source tree are LGPL. Other files under template/default are GPL. This DOES NOT mean that your original files you put in template/default should be GPL, or template/default/include should be LGPL. This DOES NOT mean that files somebody put in template/default or template/default/include without any notice will become GPL or LGPL. We can only mention about files we distribute, so consult the original author for such files.

The Karesansui source tree includes other open source projects work, which may come with its own distribution rule. Please consult each license notice for these projects.

pysilhouette¶

coming soon...

(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".

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

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

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

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

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.4 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

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-1.1.0-1-install-pack.tar.gz
# cd Karesansui
# ./karesansui-install

Here is the detailed instructions.

'Welcome' screen

Push 'OK' button to display the next page.

'Administrator setting' screen

Setting up Karesansui administrator account.

'TLS certificates setting' screen

Setting up TLS certificates for libvirt remote SSL connection.

'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.

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

'Confirm' screen

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

'Progress' screen

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

'Finish' screen

When the installation process has finished successfully, the following screen will be displayed.

An error occurred and installation failed, then the error message will be displayed.
See log file for error details and resolve the error, then please install again.

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

# /etc/init.d/network restart

Logging in to the Management Console¶

Try the URL displayed on the "Finish" screen (like "https://{hostname}/karesansui/v1/").
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.4(i386) to guest.
We describe two ways to do that.

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

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)

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

# 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

# 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.

# dd if=/dev/cdrom of=/iso/centos54-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)

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)

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.4 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.

Update Instructions¶

1. Contents¶

• Update Instructions
• 1. Contents
• 2. Users who are using SQLite with Karesansui 1.0.0 and Karesansui 1.0.1.
• 3. Users who want to upgrade from Karesansui 1.0.x to 1.1.x.

2. Users who are using SQLite with Karesansui 1.0.0 and Karesansui 1.0.1.¶

Target users for this document

Users who are using SQLite with 1.0.0 and 1.0.1.

Affected area

The job manager (Pysilhouette)

Issue which was fixed in 1.0.2

Installer was causing the job manager (Pysilhouette) to lookup SQLite database path, even the user specified other database path (like MySQL or PostgreSQL), so multi-host configuration was not supported.

1.0.2 fixes these problems, but some manual configuration are needed for updates.

1. Database Creation

Create database for the job manager (Pysilhouette).

For PostgreSQL
    # createdb -U username -W pysilhouette --encoding=utf8

For MySQL
    # mysql -u username -p -e 'CREATE DATABASE pysilhouette DEFAULT CHARACTER SET utf8;'

Important)
Create database with UTF-8 charsets.

2. Download the new package and deploy.

Download URL

# rm -rf Karesansui
# tar zxvf karesansui-<version>-install-pack.tar.gz
# cd Karesansui

3. Check current database path

Get current Pysilhouette database path.

• Get from the configuration file
  Look at the key "database.url" in /etc/opt/pysilhouette/silhouette.conf

sqlite:////var/opt/pysilhouette/pysilhouette.db

4. Update Karesansui

Update Karesansui and change Pysilhouette database path.
Update Karesansui as the steps in the tutorial

# ./karesansui-install

• In "Administrator Settings" screen
  Set "Password", and press "OK".

• In "Database Settings" screen
  Uncheck "Initialize database", and input the new database path in "Pysilhouette database path", and press "OK".

Uncheck "Initialize database", or you will lose your current database settings.

• On "Confirmation" screen
  Press "OK".

5. Installation Environment Check
Execute ./karesansui-checkenv to check if there are any errors.
Check if the output message "Checking whether we are able to connect to database for XXXXX... " describes your new database path.

# ./karesansui-checkenv

6. Migrate Database
Copy SQLite database to MySQL or PostgreSQL database.

# cd /opt/pysilhouette/share/doc/pysilhouette-0.6.2/tool/
# export PYTHONPATH=/opt/hde/lib/python:/opt/karesansui/lib/python:/opt/pysilhouette/lib/python:$PYTHONPATH
# ./sqlite2other.py --input=<old database path> --output=<new database path>

• Put the path we got checked in the above section
  "3. Check current database path" into <old database path>.

• <new database path> is available through some ways.
  • Get from 'karesansui-checkenv' output: Check the output message
    "Checking whether we are able to connect to database for XXXXX... of karesansui-checkenv.
  • Get from the configuration file
    Check the key "database.url" of /etc/opt/pysilhouette/silhouette.conf.

• Database path format

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

Take a memo of the outputted "copy num" number. We use it later.
(copy num - xxx)
sqlite2other.py only supports SQLite -> MySQL or  SQLite -> PostgreSQL migration.

# ./sqlite2other.py --input=sqlite:////var/opt/pysilhouette/pysilhouette.db --output=mysql://username:password@localhost/pysilhouette?charset=utf8
Cleanup Database [OK]
copy num - 3

Information)
For details about database path format, consult the reference

7. Change Auto Increment Counter Value
Change the auto increment counter value of Pysilhouette.
Access Pysilhouette database an execute the SQL below.

Put the "copy-num" value we got above into <copy num value>.

For PostgreSQL:
    select setval('jobgroup_id_seq', <copy num value>);
    select setval('job_id_seq', <copy num value>);

    Example)
    # psql pysilhouette  -U username -h localhost -c "select setval('jobgroup_id_seq', 3);" 
    # psql pysilhouette -U username -h localhost -c "select setval('job_id_seq' 3);" 

For MySQL:
    ALTER TABLE jobgroup AUTO_INCREMENT = <copy num value>;
    ALTER TABLE job AUTO_INCREMENT = <copy num value>;

    Example)
    # mysql pysilhouette -u username -h localhost -p -e "ALTER TABLE jobgroup AUTO_INCREMENT = 3;" 
    # mysql pysilhouette -u username -h localhost -p -e "ALTER TABLE job AUTO_INCREMENT = 3;" 

# ./sqlite2other.py --input=<old database path> --output=<new database path>
Cleanup Database [OK]
copy num - 3 <-- "copy-num" value

# /etc/init.d/hde-lighttpd stop
# /etc/init.d/silhouetted restart
# /etc/init.d/hde-lighttpd start

3. Users who want to upgrade from Karesansui 1.0.x to 1.1.x.¶

• Description

In version 1.1, the path of some configuration files and disk image files has changed.
This document describes how to migrate these files and settings.

_*We recommend to back up the important data to other physical machine in advance.*_

1. Stop Daemon

# /etc/init.d/silhouetted stop
# /etc/init.d/hde-lighttpd stop
# /etc/init.d/hde-libvirtd stop
# /etc/init.d/xend stop

2. Download the new package and deploy.

Download URL

# rm -rf Karesansui
# tar zxvf karesansui-<version>-install-pack.tar.gz
# cd Karesansui

3. Update Karesansui

# ./karesansui-install

_*You must not choise the database initialization.*_

4. Installation Environment Check
Execute ./karesansui-checkenv to check if there are any errors.

# ./karesansui-checkenv

Wiki editing policy¶

Page Names¶

• All page name should start with underscore after 2-lettered short codes for language names (defined in ISO 639). The first letter should be capitalized (by redmine wiki specification).
  • ex) En_wiki_policy, Ja_wiki_policy
• When translating one page to other language, all letters other than the first three letters should not be changed.
  • ex) En_wiki_policy, Ja_wiki_policy

Translation¶

• Translating are welcomed!
• When translating one page, translator may express the original version url in the top of the page. You can get the original version url (and number) in the 'history' page of the wiki page.

チュートリアル¶

1. 目次¶

• チュートリアル
• 1. 目次
• 2. はじめに
• 3. 概念図
• 4. CentOS 5.5 64bitの場合
• 4.1. 事前に
• 4.2. Karesansuiのインストール
• 4.3. ゲストの作成
• 4.4. 最後に
• 5. Red Hat Enterprise Linux 5.5 64bitの場合
• 5.1. 事前に
• 5.2. Karesansuiのインストール
• 5.3. ゲストの作成
• 5.4. 最後に
• 6. CentOS 5.5 64bitの場合
• 6.1. 事前に
• 6.2. Karesansuiのインストール
• 6.3. ゲストの作成
• 6.4. 最後に
• 7. CentOS 5.5 32bitの場合
• 7.1. 事前に
• 7.2. Karesansuiのインストール
• 7.3. ゲストの作成
• 7.4. 最後に

2. はじめに¶

このチュートリアルでは、パッケージング済みのKaresansuiを利用したインストールから、実際にゲスト上にOSインストールし動作させるまでを紹介します。

3. 概念図¶

4. CentOS 5.5 64bitの場合¶

ホスト、ゲストともにCentOS 5.5 64bitを用いたときのチュートリアルです。

4.1. 事前に¶

4.1.1. ホストOSのインストール

CentOS 5.5以降のISOイメージを利用しホストOSを作成します。

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

(必須) ソフトウェアのセットアップで「仮想化」「KVM」にチェックを入れてください。
(必須ではありません) ストレージ拡張を容易に行えるため、LVMを利用することを推奨しています。
注）デフォルトパーティションを利用するとデフォルトでLVMになります。

4.2. Karesansuiのインストール¶

4.2.1. インストール前準備

Karesansuiは、これらのインストールパッケージと依存関係があります。別途インストールする必要があります。

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

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

4.2.2. ダウンロード

ダウンロードページ から最新のkaresansui-2.0.0-x-install-pack.tar.gzをダウンロードします。

sourceforge.jpのダウンロードページ

4.2.3. インストール

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

インストールスクリプト実行後の画面の流れは下記の通りです。

4.2.4. 「ようこそ」画面

「OK」ボタンを押して、そのまま次の画面へ進みます。

4.2.5. 「管理者の設定」画面

Karesansuiの管理画面にログインする管理者の設定を行います。各項目の説明は下記の通りです。

4.2.6. 「鍵と証明書の設定」画面

Karesansuiで使用する仮想マシン制御の抽象化サービス(libvirt)にSSL接続するための鍵と証明書の設定を行います。
各項目の説明は下記の通りです。

4.2.7. 「データベース設定」画面

Karesansuiが利用するデータベースに関する設定を行います。

MySQLやPostgreSQLを利用する場合は、あらかじめデータベースを作成し、ホストOSから接続可能なことを確認してください。作成方法はリファレンスのMySQL, PostgreSQLを使用する場合の手順 を参照してください。

データベースパスの指定方法は、下記の通りです。

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

4.2.8. 「プロキシ設定」画面

インターネットへアクセスするためのHTTPプロキシ設定を行います。

4.2.9. 「メールの設定」画面

通知メールなどのメールの送信に利用するSMTPサーバーに関する設定を行います。

4.2.10. 「確認」画面

インストールを続行したい場合は、「OK」を押し、ソフトウェアのインストールを始めます。
これまでの入力に誤りがある場合やインストールを中断したい場合は、「戻る」、「取り消し」を押してください。

4.2.11. 「進捗」画面

ソフトウェアのインストールの進捗状況が表示されます。
ソフトウェアのインストール、鍵・証明書の生成、設定ファイルの書き込み、データベースの初期化、サービスの有効化 の順に進捗します。

4.2.12. 「完了」画面

インストールが正常に完了すると、下記画面のようにメッセージが表示されます。
インストールの途中でエラーになると、エラー原因のメッセージが表示されます。エラーメッセージはインストールログにも出力されますので、ログを確認した後、エラー原因を解消し再度インストールを行ってください。

終了しました。
下記サイトにアクセスしログインしてください。ログインIDは'taizo@karesansui-project.info'です。
 https://karesansui.example.com/karesansui/v2/
 http://karesansui.example.com/karesansui/v2/
詳細は、/root/karesansui-install.log を参照してください。

# /etc/init.d/network restart

4.2.13. 管理画面の確認

インストール完了後に表示された 'https://{ホスト名}/karesansui/v2/' に接続すると、認証ダイアログが表示されますので、インストール時に指定した管理者のメールアドレスとパスワードを入力します。

認証をパスして、以下のような画面が表示されればインストールは成功です。

4.3. ゲストの作成¶

4.3.1. ゲストのOSインストール準備

以降は、ゲストに CentOS 5.5(i386) をインストールする場合を例に、２通りの方法を説明します。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

ホストOSが既にインターネットに繋がっている場合は、外部サーバー上にある、カーネルイメージ、および、OSイメージを取得してインストールを行います。プロキシサーバー経由でのインストールはできませんので、その場合はFTPサーバーを利用してください。

http://<OSイメージ配布サイトのFQDN>/Linux/centos/5/os/i386/
ftp://<OSイメージ配布サイトのFQDN>/Linux/centos/5/os/i386/

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

ホストOSがインターネットに繋がっていない場合は、CentOS 5.5(i386)のDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

KVMを仮想化ハイパーバイザーに利用している場合は、OSインストールDVDのISOイメージからインストールすることも可能です。

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

4.3.2 ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法を、前述のインストールのタイプごとに示します。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のCentOS 5.5 のOSインストールと同じようにゲスト上にOSをインストールすることができます。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

OSインストール時の「Installation Method」の選択では前述のカーネルイメージで指定したプロトコル（「HTTP」または「FTP」）を選択し、「HTTP」の場合は「HTTP Setup」、「FTP」の場合は「FTP Setup」で接続先を設定してください。

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

「Installation Method」の選択の必要はありません。

4.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

5. Red Hat Enterprise Linux 5.5 64bitの場合¶

ホスト、ゲストともにRed Hat Enterprise Linux 5.5 64bit( 以下、RHEL 5.5(64bit) )を用いたときのチュートリアルです。

5.1. 事前に¶

ホストOSのインストール

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

# yum install kvm

5.2. Karesansuiのインストール¶

Karesansuiのインストールは、CentOS 5.5の場合と同じです。
CentOS 5.5のチュートリアル を参照してください。

5.3. ゲストの作成¶

5.3.1. ゲストのOSインストール準備

RHEL 5.5(64bit)のDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

5.3.2. ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法は、以下の通りです。

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のRHEL 5.5(64bit)のOSインストールと同じようにゲスト上にOSをインストールすることができます。

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

5.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

6. CentOS 5.5 64bitの場合¶

ホスト、ゲストともにCentOS 5.5 64bitを用いたときのチュートリアルです。

6.1. 事前に¶

ホストOSのインストール

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

(必須) ソフトウェアのセットアップで「仮想化」「KVM」にチェックを入れてください。
(必須ではありません) ストレージ拡張を容易に行えるため、LVMを利用することを推奨しています。
注）デフォルトパーティションを利用するとデフォルトでLVMになります。

6.2. Karesansuiのインストール¶

Karesansuiのインストールは、CentOS 5.5の場合と同じです。
CentOS 5.5のチュートリアル を参照してください。

6.3. ゲストの作成¶

6.3.1. ゲストのOSインストール準備

CentOS 5.5 64bitのDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

6.3.2. ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法は、以下の通りです。

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のRHEL 5.5(64bit)のOSインストールと同じようにゲスト上にOSをインストールすることができます。

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

6.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

7. CentOS 5.5 32bitの場合¶

ホスト、ゲストともにCentOS 5.5 32bitを用いたときのチュートリアルです。

7.1. 事前に¶

ホストOSのインストール

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

(必須) ソフトウェアのセットアップで「仮想化」「KVM」にチェックを入れてください。
(必須ではありません) ストレージ拡張を容易に行えるため、LVMを利用することを推奨しています。
注）デフォルトパーティションを利用するとデフォルトでLVMになります。

7.2. Karesansuiのインストール¶

Karesansuiのインストールは、CentOS 5.5の場合と同じです。
CentOS 5.5のチュートリアル を参照してください。

7.3. ゲストの作成¶

7.3.1. ゲストのOSインストール準備

CentOS 5.5 32bitのDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

7.3.2. ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法は、以下の通りです。

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のRHEL 5.5(32bit)のOSインストールと同じようにゲスト上にOSをインストールすることができます。

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

7.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

FAQ¶

目次¶

• FAQ
• 目次
• 一般
• Q. 無料で利用できるの？
• Q. Karesansuiはどんなライセンスなの？
• Q. 完全仮想化には対応してないの？
• Q. 対応するハイパーバイザーはXenだけなの？
• Q. Linuxに詳しくないんだけどインストールって簡単？
• Q. 他にもいろんな仮想化ソフトがあるけどKaresansuiだとなにかメリットがあるの？
• Q. Karesansuiをいろんなところで紹介したいんだけど。
• Q. 会社で利用したんだけど、ライセンスで問題とかある？
• アプリケーションについて
• Q. RHEL5には対応してないの？
• Q. Athlonには対応してないの？
• Q. 64bit(x86_64)には対応してないの？
• Q. Karesansuiが参照するデータベースが異常停止したらゲストは停止する？
• Q. ゲストのコンソールを表示するとJavaが必要ってでるんだけど。
• Q. コンソールが表示されないんだけど、どうしたらいい？
• Q. コンソールからキーボード入力すると、別のキーボード配列になってるんだけど。
• Q. うまく動かないんだけど、どうしたらいい？
• ログ関連
• Q. ログファイルのサイズ・ファイルパス・ローテート数を変更したいんだけどどうすればいい？
• Q. 画面でエラーが発生したがうまくログ出力されていないみたい。
• Q. ログの出力形式を変更したいんだけど。
• Q. ログファイルってどこに出力されるの？
• Q. ログファイルが3つあるんだけど
• Q. アップデート画面が表示されない。(エラーが画面に表示される。)

一般¶

Q. 無料で利用できるの？¶

Karesansuiは商用、非商用を問わずだれでも無料で利用することができます。

Q. Karesansuiはどんなライセンスなの？¶

GPLとLGPLで構成するライセンスになっています。詳細はこちらを参照してください。

Q. 完全仮想化には対応してないの？¶

現時点では対応していませんが、コミュニティで検討されています。
Karesansui(Xen)としては対応してませんが、直接コマンドを実行することで動作させることができます。
Karesansui(Xen)で完全仮想化をできないよう制限していることはありません。

Q. 対応するハイパーバイザーはXenだけなの？¶

現在サポートしているのはXenだけですが、近い将来 KVM にも対応する予定です。
Version 1.1でKVMに対応し、現在KVMとXenに対応しています。

Q. Linuxに詳しくないんだけどインストールって簡単？¶

インストールパックを用意していますので、簡単にインストールが可能です。初めての方はチュートリアルをご覧ください。

Q. 他にもいろんな仮想化ソフトがあるけどKaresansuiだとなにかメリットがあるの？¶

Karesansuiを使えば複雑な操作から解放されるはずです。Karesansuiは誰でも簡単に仮想化ができるアプリケーションを目指して日々開発しています。

Q. Karesansuiをいろんなところで紹介したいんだけど。¶

是非、是非じゃんじゃんご紹介ください。バナーも提供中 です！

Q. 会社で利用したんだけど、ライセンスで問題とかある？¶

まったく問題ありません。KaresansuiはGPL・LGPLで配布されていますので、利用することによる制限はありません。

アプリケーションについて¶

Q. RHEL5には対応してないの？¶

対応を予定しています。今しばらくお待ちください。
version 1.0.1で対応しました。

Q. Athlonには対応してないの？¶

現在リリースされている 1.0.0では不具合によりエラーが発生します。
メーリングリストに回避方法があります。
[karesansui-users-jp:13]
次期マイナーバージョンアップで修正予定です。
Version 1.0.1で対応しました。

Q. 64bit(x86_64)には対応してないの？¶

対応を予定しています。今しばらくお待ちください。
Version 1.0.1で対応しました。

Q. Karesansuiが参照するデータベースが異常停止したらゲストは停止する？¶

データベースが停止していてもゲストやホストに影響が出ることはありません。ただしブラウザからの操作はできなくなります。

Q. ゲストのコンソールを表示するとJavaが必要ってでるんだけど。¶

コンソールの表示には、オープンソースのTightVNC のJava appletを利用していますので、Javaが必要となります。

Q. コンソールが表示されないんだけど、どうしたらいい？¶

以下を試してみてください。通信ができるかどうかを確認します。クライアントのコンソールから以下のコマンドを発行します。

＞ ping {Karesansuiサーバー名}

次にKaresansuiサーバーでVNCポート番号が開いているか確認します。

# netstat -nalt

上記が正常な場合にはクライアントにVNCビューアを入れて接続してみてください。

Q. コンソールからキーボード入力すると、別のキーボード配列になってるんだけど。¶

「ゲスト」のデバイスタブから「Display」を選択し、「VNCキーマップ」を選択してください。日本語106/109キーボードは「ja」を選択してください。

Q. うまく動かないんだけど、どうしたらいい？¶

フォーラム にて聞いてみてください。有志の方や開発者が答えてくれるはずです。

ログ関連¶

Q. ログファイルのサイズ・ファイルパス・ローテート数を変更したいんだけどどうすればいい？¶

log.conf内の "[handler_*"カテゴリにある "args" を変更します。以下に変更例を記載します。

ログファイルサイズ 5M を 10Mにする場合

args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/application.log', 'a', (10 *1024 *1024), 5)

ログファイル名をapplication.log を server.log にする場合
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/server.log', 'a', (5 *1024 *1024), 5)

ログローテートを5から10にする場合
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 10)

Q. 画面でエラーが発生したがうまくログ出力されていないみたい。¶

ログレベルによってログの出力を制限している可能性があります。 "[logger_*"カテゴリのlevelを確認してください。

ログレベル一覧(※上は下を包括します。)
 - DEBUG : 全て出力
 - INFO : 一般情報のみ出力
 - WARNING : 警告のみ出力(運用時の推奨設定)
 - ERROR : エラーのみ出力
 - CRITICAL : 深刻なエラーのみ出力
 - EXCEPTION : システム的なエラーのみ出力

補足 : ログ設定の変更時はウェブサーバーの再起動が必要です。

Q. ログの出力形式を変更したいんだけど。¶

Python loggingで利用できるすべての形式に対応していますので詳しくはそちらを参照ください。

Q. ログファイルってどこに出力されるの？¶

log.conf内の "[handler_*"カテゴリにある "args" に定義されています。

Q. ログファイルが3つあるんだけど¶

Karesansuiのログは複数のファイルで構成されています。

Karesansui全体のログ : /var/log/karesansui/application.log
Karesansuiで発生したエラーのプログラムトレースログ : /var/log/karesansui/error.log
Karesansuiが発行したSQL関連のログ : /var/log/karesansui/sql.log

Q. アップデート画面が表示されない。(エラーが画面に表示される。)¶

A. プロキシサーバーの設定が正しく行われていない可能性があります。「トップ画面」「設定タブ」からプロシキサーバーの設定を確認してみてください。

例)(Bad Request) [400] ('Cannot retrieve repository metadata (repomd.xml) for repository: karesansui-base. Please verify its path and try again',) 

エラーが発生した場合には？¶

アプリケーションエラーについて¶

KaresansuiはRESTfulアーキテクチャ(オーバーライドPOST対応)を採用しているため、管理画面のエラーはすべてHTTPレスポンスコードで判断されます。

以下に使用しているレスポンスコードの一部を記載します。

 - 2xx : 正常に処理が終了した際に使用されるHTTPレスポンスコードです。
   - Karesansuiでは、正常な動作になります。

 - 3xx : リクエストの転送に使用されるHTTPレスポンスコードです。
   - Karesansuiでは、正常な動作になります。

 - 4xx : クライアント(主にブラウザ)からのリクエストに問題があった場合に使用されるHTTPレスポンスコードです。
   - Karesansuiでは、主に不正なリクエストや存在しないURLアクセス時に使用されます。

 - 5xx : サーバーエラー時に使用されるHTTPレスポンスコードです。
   - Karesansuiでのエラーになりますので、エラーを解決する必要があります。

カーネルイメージ・initrdイメージってなに？¶

概要¶

ゲストの作成画面で入力をするカーネルイメージ・initrdイメージですが、よくわからないという方も多いと思います。
以下に簡単な説明とインストール検証済みディストリビューションの入力例を記載しておきます。

カーネルイメージ¶

カーネルイメージとはその名の通りLinuxカーネル本体です。
今回入力で利用するカーネルイメージは初期インストール時のブート(テキストベースのインストール前作業)に利用されます。

initrdイメージ¶

initrdとは、Linuxがブートする際に、一時利用されるファイルシステムのイメージを指します。
今回入力で利用するカーネルイメージは「カーネルイメージ」でブートした際に利用されます。

入力例¶

CentOS5.3¶

カーネルイメージ
http://<ミラーサーバー>/Linux/centos/5.3/os/i386/images/xen/initrd.img

initrdイメージ
http://<ミラーサーバー>/Linux/centos/5.3/os/i386/images/xen/vmlinuz

ヒント
ゲストインストール時に必要なインストールイメージパス例
http://<ミラーサーバー>/Linux/centos/5.3/os/i386/

Fedora10¶

カーネルイメージ
http://<ミラーサーバー>/Linux/fedora/releases/10/Fedora/i386/os/images/pxeboot/initrd-PAE.img

initrdイメージ
http://<ミラーサーバー>/Linux/fedora/releases/10/Fedora/i386/os/images/pxeboot/vmlinuz-PAE

ヒント
ゲストインストール時に必要なインストールイメージパス例
「http://<ミラーサーバー>/Linux/fedora/releases/10/Fedora/i386/os/」　です。

補足
Fedora 11 previewもインストール可能なことを確認しています。

初期値を変更したい場合には？¶

Karesansuiは、設定ファイルと定数ファイルで初期値等を決めています。

設定ファイルについて¶

設定ファイルの説明はこちらです

定数ファイルについて¶

パッケージでインストールした場合は、「/opt/karesansui/lib/python/karesansui/lib/const.py」に配置されています。
さまざまな設定がありますが、よく使う設定を１つ紹介します。

1. ゲストOS追加時に設定される、コンソール(VNC)のキーボード配列を変更したい場合は、DEFAULT_KEYMAPを変更します。

注）設定後はウェブサーバーを再起動してください。

インストールしたゲストのイメージファイルはどこにあるの？¶

概要¶

Karesansuiを利用してゲストを作成した場合、特定のディレクトリに保存・管理されています。

前提条件¶

パッケージインストールを行っている場合

配置パス¶

ヒント¶

ゲストのバックアップが必要な場合は、上記をバックアップすることで最低限のバックアップが可能です。
注)Karesansuiのバックアップは含みません。

ログをカスタマイズするには？¶

■ログの設定
パッケージからのインストールの場合、「/etc/opt/karesansui/log.conf(以後log.conf)」ファイルにログの設定がされています。

設定方法はPython logging 　を参照ください。

ログ関連のFAQは こちらから

複数ホスト構成にするには？¶

前提条件¶

1. MySQLやPostgreSQLといったネットワーク接続に対応したデータベースで運用されていること。
2. 注）SQLiteでは複数のホストを管理することができません。

新たに物理マシンを追加する手順¶

説明で利用する単語¶

1. ホストA = 既存のホスト(Karesansuiは導入済み)
2. ホストB = 新たに追加したいホスト

Step 1. 追加したいKaresansuiアプリケーションのバージョン情報を調べる¶

ホストAのKaresansuiにアクセスし、ヘッダーの「オプション」「Karesansui について」画面を表示し、バージョン情報を取得します。

Step 2. ホストBにKaresansuiをインストールする¶

Step 1で調べたバージョンと同じKaresansuiをダウンロードし、インストールを行います。

注）ホストBのデータベースは、ホストAと同じデータベースを指定し、「データーベースを初期化する」のチェックボックスを外します。

チュートリアル参照

Step 3. ホストBのKaresansuiユニークキーを調べる¶

/etc/opt/karesansui/application.conf ファイルの application.uniqkey がホストBのユニークキーになります。 Step4で使用しますのでメモしておいてください。 設定されている値 例) application.uniqkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Step 4. ホストAの既存KaresansuiにホストBを追加する¶

ホストAの管理画面にアクセスし、トップ画面にある「追加」アクションを押下します。 ホストの追加画面で、入力項目を入力し「追加」を押下します。

入力項目の補足 : 
- ホスト名(必須) : 管理画面に表示するホスト名です。特に指定はありませんので、わかりやすい名前を入力してください。
            例）ホストB

- FQDN(必須) : ホストBにアクセスできるFQDN・ドメイン名またはIPアドレスを入力します。
           例）hostb.karesansui-project.info or 192.168.0.1

- UUID(必須) : Step 3で調べたユニークキーを入力します。
- ノート(任意) : メモ書きです。
- タグ(任意) : カンマ区切りでタグを入力します。

Step 5. テスト¶

ホストAの管理画面にアクセスし、Step 4で追加したホストBのアイコン(通常は N/Aアイコンが表示されています。)を選択し、詳細を表示させます。

「その他の情報」「ホストのトップページへのリンク」のリンクをクリックし、ホストの移動を行います。

注）この際、再度Basic認証ダイアログが表示されることがあります。

移動後、ヘッダーのホスト名がホストBのものになっていればホストの追加は完了です。※A

※A : 画像の右がホスト名になります。

補足　: ホストBアイコンについては、ホストBへ移動後、「編集」アクションから変更することができます

HOWTO一覧¶

• 複数ホスト構成にするには？
• ログをカスタマイズするには？
• エラーが発生した場合には？
• 初期値を変更したい場合には？
• カーネルイメージ・initrdイメージってなに？
• インストールしたゲストのイメージファイルはどこにあるの？

ライセンスについて¶

Karesansuiの一部はLGPL、一部はGPLです。 コア部分のソースコードは利用制約の少ないLGPLライセンスを採用していますので、 再利用時のライセンスによる問題を軽減します。
すべてのソースコードにライセンスが明記されていますので、迷うことなく利用することができるはずです。

ただし、例外としていくつかのファイルには技術的な問題でライセンス表記をしていません。

ソースツリーに含まれるtemplate/default/include以下のファイルはLGPLです。その他のtemplate/default以下のファイルはGPLです。

これは、あなたがあなたの書いたオリジナルのファイルをtemplate/defaultにファイルを置く場合GPLを付さないといけないということは意味しません。また、template/default/includeにファイルを置く場合はLGPLを付さないといけないということは意味しません。

また、template/defaultやtemplate/default/includeに誰かがファイルを置き、それがライセンス表記されていなかったら、GPLやLGPLが付されたということにはなりません。

私たちは私たちが配布しているファイルについてのみ言及することができますので、それ以外のファイルについては著作者に問い合わせてください。

ソースツリーはKaresansui以外のオープンソースプロジェクトの成果物を含んでいます。それらはKaresansuiとは異なるライセンスポリシーで配布されていることがあるので、それぞれのライセンス表記をご確認下さい。

ジョブマネージャー (pysilhouette)¶

概要¶

Karesansuiで実行される更新系処理のほとんどはジョブマネジャーを経由して実行されます。
Karesansuiは、 Pysilhouette を採用しています。

Pysilhouetteとは¶

逐次的に登録されたジョブ(コマンド)を実行する機能を有するジョブマネジャーです。
主にウェブアプリケーションのバックグラウンド処理を実現するために開発されています。

Pysilhouetteの特徴¶

• 100% Pure Pythonで開発されているアプリケーションです。
• シンプルな監視機能を有し、信頼性を向上させています。
• ジョブグループ単位で実行されそのなかで複数のジョブを実行することができます。
• 各ジョブ単位でロールバック処理を追加することができます。
• 複数のデータベースをサポートしています。

※ PysilhouetteはKaresansui Projectによって運営/管理されています。

説明の前に¶

Karesanuiパッケージに含まれるPysilhouetteを想定して説明します。

各種設定について¶

Comming soon.

サービスの起動停止方法¶

こちらを参照してください。

ログ出力¶

Pysilhouetteのログは5つで構成されています。

pysilhouette全体のログ : /var/log/pysilhouette/application.log

pysilhouetteで発生したエラーのプログラムトレースログ : /var/log/pysilhouette/error.log

pysilhouetteが発行したSQL関連のログ : /var/log/pysilhouette/sql.log

pysilhouetteサービスが出力する標準エラー出力ログ : /var/log/pysilhouette/stderr.log

pysilhouetteサービスが出力する標準出力ログ : /var/log/pysilhouette/stdout.log

直接更新系処理を行わない理由¶

ウェブサービスに必要以上の権限を付加することによるセキュリティリスクを考慮したためです。

リファレンス¶

必要な環境¶

対応ホストOS¶

1. CentOS 5.3以降 32bit/64bit
2. RHEL 5.3以降 32bit/64bit

対応ゲストOS¶

1. Xenの準仮想化に対応しているOSすべて（仮想化ハイパーバイザーがXenの場合）
2. Linux、FreeBSD、OpenSolaris、Windows（仮想化ハイパーバイザーがKVMの場合）

推奨スペック¶

1. CPU : Intel Core 2 Duo以上
2. メモリ : 2GB以上
3. HDD : 100GB以上

データベース¶

1. SQLite3(※マルチホスト非対応)
2. MySQL
3. PostgreSQL
4. その他
   http://www.sqlalchemy.org/docs/05/dbengine.html?highlight=db2#supported-databases

ブラウザ¶

1. Firefox 3以降
2. Safari 3(Mac)以降
3. Opera 9以降
4. Google Chrome

機能一覧¶

※Karesansuiでは仮想マシンを立ち上げるサーバーのことを「ホスト」、ホスト上で動作する仮想マシンのことを「ゲスト」と呼びます。

ソースのダウンロード方法¶

Karesansuiのソースコードを取得するには、いくつかの方法があります。

sourceforge.jpからダウンロード

ソースコードは、Karesansuiのインストールパック(tarball)の中に、RPMパッケージとしても提供されています。
Karesansuiのインストールパックは、ダウンロードページ から最新のKaresansui-1.x.tar.gz を選択してダウンロードできます。

gitリポジトリからダウンロード

最新のソースコードは、sourceforge.jpのgitリポジトリから取り寄せることもできます。
gitがインストールされていない場合は、あらかじめgitをインストールした後、以下のコマンドでダウンロードすることができます。

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

設定ファイル(log.conf)の説明¶

FAQを参照

application.confの説明¶

application.search.path¶

Pythonの追加サーチパスを設定します。
※複数指定する場合はカンマ(,)で区切ります

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

application.log.config¶

ログ出力設定ファイルパスを設定します。
ログ出力設定ファイルついてはこちらを参照してください。

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

application.url.prefix¶

URIのプレフィックスを設定します。
以下の{}内を設定します。
http://example.com{/karesansui/v1}/
※v1はKaresansuiのメジャーバージョンを指定しておくことを推奨します。

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

application.default.locale¶

Karesansuiが使用するデフォルトのロケールを設定します。
※現在、ja_JPとen_USに対応しています。
※ログインしている場合は、ログインユーザのロケールが優先されます。

例) application.default.locale=ja_JP

application.template.theme¶

Karesansuiのテーマを設定します。
※初期インストール時はdefaultに設定されています。

例) application.template.theme=default

application.tmp.dir¶

Karesansuiが一時的に作成するファイル等々をおくディレクトリパスを設定します。

例) application.tmp.dir=/tmp

application.bin.dir¶

Karesansuiが使用するジョブコマンドのディレクトリパスを設定します。
※Karesansuiの実行ユーザ権限で書き込みができる必要があります。

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

application.generate.dir¶

各種設定ファイルのテンプレートディレクトリを設定します。

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

application.mail.email¶

Karesansuiで利用するメールアドレスを設定します。

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

application.mail.port¶

Karesansuiで利用するメールサーバのポート番号を設定します。

例) application.mail.port=25

application.mail.server¶

Karesansuiで利用するメールサーバ名を設定します。

例) application.mail.server=localhost

application.proxy.status¶

Karesansuiでプロキシサーバを利用するかを設定します。
1=有効
0=無効

例)application.proxy.status=0

application.proxy.server¶

Karesansuiで利用するプロキシサーバ名を設定します。

例) application.proxy.server=localhost

application.proxy.port¶

Karesansuiで利用するプロキシサーバのポート番号を設定します。

例) application.proxy.port=9080

application.proxy.user¶

Karesansuiで利用するプロキシサーバにログインするユーザ名を設定します。

例) application.proxy.user=bar

application.proxy.password¶

Karesansuiで利用するプロキシサーバにログインするパスワードを設定します。

例)application.proxy.password=foo

lighttpd.etc.dir¶

KaresansuiをLighttpdで動作させる場合に利用する設定ファイルを置くディレクトリを設定します。

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

database.bind¶

Karesansuiで利用するデータベースのバインドを設定します。
RFC-1738で定義されているスタイルで設定してください。
さらに詳しい設定についてはSQLAlchemyのサポートデータベース を参照してください。

MySQL
mysql://localhost/<データベース名>
mysql://<ユーザ名>:<パスワード>@<ホスト名>/<データベース名>
mysql://<ユーザ名>:<パスワード>@<ホスト名>:<ポート番号>/<データベース名>
PostgreSQL
postgres://<ユーザ名>:<パスワード>@<ホスト名>:<ポート番号>/<データベース名>
SQLite※Karesansuiの実行権限で読み取り・書き込み可能である必要があります。
sqlite:////<絶対パス>/<ファイル名>-絶対パスで定義
sqlite:///<相対パス>/<ファイル名>-相対パスで定義
例) database.bind=sqlite:////var/opt/karesansui/karesansui.db

database.pool.status¶

コネクションプールの利用可否を設定します。
0=利用しない
1=利用する

例)database.pool.status=0

database.pool.size¶

通常時のコネクションプール数を設定します。
※SQLiteでは利用できません。設定は無視されます。

例)database.pool.size=1

database.pool.max.overflow¶

コネクションプールの最大数を設定します。

例)database.pool.max.overflow=10

pysilhouette.conf.path¶

Karesansuiで使用するPysilhouetteソフトウェアの設定ファイルパスを設定します。
※Karesansuiの実行ユーザ権限で読み取り可能である必要があります。(書き込み・実行権限は必要ありません。)

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

application.updater.yum.cachedir¶

Karesansuiが利用するyumのキャッシュディレクトリを設定します。
注)wwwhde(hde-lighttpdサービス)ユーザの書き込み権限が必要です。

例)application.updater.yum.cachedir=/var/opt/karesansui/cache/yum

application.updater.yum.log.file¶

Karesansui経由で実行されたyumのログファイルを設定します。

例)application.updater.yum.log.file=/var/log/karesansui/yum.log

application.updater.yum.target.repos¶

Karesansui用のyumリポジトリ名を設定します。

例)application.updater.yum.target.repos=karesansui-base

起動停止方法、自動起動設定方法¶

Karesansuiには主に5つのサービスを利用しています。
注）インストーラーでインストールしている場合はインストール時に自動起動設定が行われていますので再度行う必要はありません。

• hde-libvirtd

仮想化制御を抽象化したライブラリ(libvirtd) デーモンです。
注）ディストリビューションのlibvirtdが起動していると正常に起動することができません。
必ずlibvirtdは停止させた上でhde-libvirtdを起動してください。

起動、停止方法の例
起動 : /etc/init.d/hde-libvirtd start
停止 : /etc/init.d/hde-libvirtd stop

自動起動設定の例
設定 : chkconfig hde-libvirtd on
設定確認 : chkconfig --list hde-libvirtd

• hde-lighttpd

Webインターフェース用のWebサーバー（Lighttpd)

起動、停止方法の例
起動 : /etc/init.d/hde-lighttpd start
停止 : /etc/init.d/hde-lighttpd stop

自動起動設定の例
設定 : chkconfig hde-lighttpd on
設定確認 : chkconfig --list hde-lighttpd

• silhouetted

ジョブ管理サービス

起動、停止方法の例
起動 : /etc/init.d/silhouetted start
停止 : /etc/init.d/silhouetted stop

自動起動設定の例
設定 : chkconfig silhouetted on
設定確認 : chkconfig --list silhouetted

依存関係での問題¶

以下のソフトウェアが不足する可能性がありますので事前にインストールしておく必要があります。

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

# yum install iscsi-initiator-utils
# yum install cyrus-sasl-md5
# yum install qemu
# yum install gnutls-utils
# yum install PyXML

# rpm -ivh iscsi-initiator-utils
# rpm -ivh cyrus-sasl-md5
# rpm -ivh qemu
# rpm -ivh gnutls-utils
# rpm -ivh PyXML

インストール後の問題¶

正常にインストールしたにも関わらず、正常に動作しない場合は、インストールしたディレクトリ内にある karesansui-checkenv を実行してください。現在のシステム環境情報が表示され問題を解決に導きます。

実行結果例

# ./karesansui-checkenv
@==========================================@
@   Karesansui Environment Check Program   @
@==========================================@
KaresansuiのRPMパッケージが正常にインストールされているかをチェック...  OK
Karesansuiの設定パラメータをチェック...  OK
Karesansuiのpythonモジュールをインポートできるかチェック...  OK
Karesansuiのグループが存在するかをチェック...  OK
Karesansuiの設定ファイルがロードできるかをチェック...  OK
sqlalchemyモジュールをインポートできるかチェック...  OK
pysilhouetteモジュールをインポートできるかチェック...  OK
pysilhouetteの設定パラメータをチェック...  OK
pysilhouetteの設定ファイルがロードできるかをチェック...  OK
KaresansuiのデータベースAPIモジュールをインポートできるかチェック...  sqlite
データベース Karesansui に接続できるかをチェック...  sqlite:////var/opt/karesansui/karesansui.db
KaresansuiのSQLiteデータベースのパーミッションをチェック...  OK
pysilhouetteのデータベースAPIモジュールをインポートできるかチェック...  sqlite
データベース pysilhouette に接続できるかをチェック...  sqlite:////var/opt/pysilhouette/pysilhouette.db
pysilhouetteのSQLiteデータベースのパーミッションをチェック...  OK
Karesansuiのファイル/ディレクトリのパーミッションをチェック...  OK
Karesansuiのpythonモジュールをインポートできるかチェック...  OK
全てのチェックをクリアしました。
下記サイトにアクセスしログインしてください。
 https://karesansui-project.info/karesansui/v1/
 http://karesansui-project.info/karesansui/v1/

画面構成¶

Karesansuiの画面は4つのパーツで構成されています。

A： ヘッダー
B：メイン
C：ドメインツリー
D：ログメッセージ

ヘッダー
¶

A：ロゴ
クリックするとトップページへ移動します。

B：パンくず
KaresansuiはTOP, ホスト、ゲストの3つの画面を遷移して操作します。
この部分には現在どの画面にいるか表示されます。
また、リンクをクリックすることでその画面へ遷移します。

C：ログインユーザ名表示
ログインしているサーバーのホスト名や、ログインしているユーザーのメールアドレスが表示されます。

D：メニュー
ログインしているユーザーの情報を編集したり、Karesansuiからログアウトすることができます。

E：通知アイコン
実行中のジョブがあることや、サーバーとAJAX通信中であることを点滅して示すアイコンです。

メイン
¶

A：タブ

クリックすると、その内容にメイン画面が遷移します。

B：ボタン

クリックすると、追加や変更などを行うことができます。
暗い色になっているボタンは押しても実行することができません。

C：タグ

ホスト一覧やゲスト一覧の画面に表示されます。ホストやゲストに登録されたタグを使って
アイコンの表示を絞り込むことができます。

D：ホスト（ゲスト）アイコン

一度目のクリックで下の詳細表示画面に詳細が表示されます。
その際、背景に緑色の枠が表示されます。
二度目のクリックで選択したホスト（ゲスト）の画面に遷移します。
ホスト（ゲスト）の編集で、表示するアイコンを変更することができます。

E：詳細表示

ジョブの登録者や登録時間、ホストのメモリ総量やディスク使用量など、細かい情報を表示します。

F：更新アイコン

クリックすると、メイン画面の内容を更新します。

ドメインツリー
¶

A：ツリー
ホストと、その上に作られているゲストをツリー状に表示します。
各リンクをクリックすることでそのホストやゲストの画面に遷移します。
また、ホストの横にある▼のアイコンを押すことで開閉することができます。

B：更新アイコン
クリックするとツリーの内容を更新します。

ログメッセージ
¶

A：ログメッセージ
直近5件のジョブの進捗や結果などの情報を表示します。

B：更新アイコン
クリックするとログメッセージの内容を更新します。

チュートリアル¶

1. 目次¶

• チュートリアル
• 1. 目次
• 2. はじめに
• 3. 概念図
• 4. CentOS 5.4 32bitの場合
• 4.1. 事前に
• 4.2. Karesansuiのインストール
• 4.3. ゲストの作成
• 4.4. 最後に
• 5. Red Hat Enterprise Linux 5.4 64bitの場合
• 5.1. 事前に
• 5.2. Karesansuiのインストール
• 5.3. ゲストの作成
• 5.4. 最後に
• 6. CentOS 5.4 64bitの場合
• 6.1. 事前に
• 6.2. Karesansuiのインストール
• 6.3. ゲストの作成
• 6.4. 最後に
• 7. CentOS 5.4 32bitの場合
• 7.1. 事前に
• 7.2. Karesansuiのインストール
• 7.3. ゲストの作成
• 7.4. 最後に

2. はじめに¶

このチュートリアルでは、パッケージング済みのKaresansuiを利用したインストールから、実際にゲスト上にOSインストールし動作させるまでを紹介します。

3. 概念図¶

4. CentOS 5.4 32bitの場合¶

ホスト、ゲストともにCentOS 5.4 32bitを用いたときのチュートリアルです。

4.1. 事前に¶

4.1.1. ホストOSのインストール

CentOS 5.4以降のISOイメージを利用しホストOSを作成します。

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

(必須) ソフトウェアのセットアップで「仮想化」「KVM」にチェックを入れてください。
(必須ではありません) ストレージ拡張を容易に行えるため、LVMを利用することを推奨しています。
注）デフォルトパーティションを利用するとデフォルトでLVMになります。

4.2. Karesansuiのインストール¶

4.2.1. インストール前準備

Karesansuiは、これらのインストールパッケージと依存関係があります。別途インストールする必要があります。

• iscsi-initiator-utils
• cyrus-sasl-md5
• gnutls-utils
• PyXML
• SDL
• curl

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

4.2.2. ダウンロード

ダウンロードページ から最新のkaresansui-1.1.0-x-install-pack.tar.gzをダウンロードします。

sourceforge.jpのダウンロードページ

4.2.3. インストール

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

インストールスクリプト実行後の画面の流れは下記の通りです。

4.2.4. 「ようこそ」画面

「OK」ボタンを押して、そのまま次の画面へ進みます。

4.2.5. 「管理者の設定」画面

Karesansuiの管理画面にログインする管理者の設定を行います。各項目の説明は下記の通りです。

4.2.6. 「鍵と証明書の設定」画面

Karesansuiで使用する仮想マシン制御の抽象化サービス(libvirt)にSSL接続するための鍵と証明書の設定を行います。
各項目の説明は下記の通りです。

4.2.7. 「データベース設定」画面

Karesansuiが利用するデータベースに関する設定を行います。

MySQLやPostgreSQLを利用する場合は、あらかじめデータベースを作成し、ホストOSから接続可能なことを確認してください。作成方法はリファレンスのMySQL, PostgreSQLを使用する場合の手順 を参照してください。

データベースパスの指定方法は、下記の通りです。

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

4.2.8. 「確認」画面

インストールを続行したい場合は、「OK」を押し、ソフトウェアのインストールを始めます。
これまでの入力に誤りがある場合やインストールを中断したい場合は、「戻る」、「取り消し」を押してください。

4.2.9. 「進捗」画面

ソフトウェアのインストールの進捗状況が表示されます。
ソフトウェアのインストール、鍵・証明書の生成、設定ファイルの書き込み、データベースの初期化、サービスの有効化 の順に進捗します。

4.2.10. 「完了」画面

インストールが正常に完了すると、下記画面のようにメッセージが表示されます。
インストールの途中でエラーになると、エラー原因のメッセージが表示されます。エラーメッセージはインストールログにも出力されますので、ログを確認した後、エラー原因を解消し再度インストールを行ってください。

終了しました。
下記サイトにアクセスしログインしてください。ログインIDは'taizo@karesansui-project.info'です。
 https://karesansui.example.com/karesansui/v1/
 http://karesansui.example.com/karesansui/v1/
詳細は、/root/karesansui-install.log を参照してください。

# /etc/init.d/network restart

4.2.10. 管理画面の確認

インストール完了後に表示された 'https://{ホスト名}/karesansui/v1/' に接続すると、認証ダイアログが表示されますので、インストール時に指定した管理者のメールアドレスとパスワードを入力します。

認証をパスして、以下のような画面が表示されればインストールは成功です。

4.3. ゲストの作成¶

4.3.1. ゲストのOSインストール準備

以降は、ゲストに CentOS 5.4(i386) をインストールする場合を例に、２通りの方法を説明します。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

ホストOSが既にインターネットに繋がっている場合は、外部サーバー上にある、カーネルイメージ、および、OSイメージを取得してインストールを行います。プロキシサーバー経由でのインストールはできませんので、その場合はFTPサーバーを利用してください。

http://<OSイメージ配布サイトのFQDN>/Linux/centos/5/os/i386/
ftp://<OSイメージ配布サイトのFQDN>/Linux/centos/5/os/i386/

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

ホストOSがインターネットに繋がっていない場合は、CentOS 5.4(i386)のDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

KVMを仮想化ハイパーバイザーに利用している場合は、OSインストールDVDのISOイメージからインストールすることも可能です。

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

4.3.2 ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法を、前述のインストールのタイプごとに示します。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のCentOS 5.4 のOSインストールと同じようにゲスト上にOSをインストールすることができます。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

OSインストール時の「Installation Method」の選択では前述のカーネルイメージで指定したプロトコル（「HTTP」または「FTP」）を選択し、「HTTP」の場合は「HTTP Setup」、「FTP」の場合は「FTP Setup」で接続先を設定してください。

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

「Installation Method」の選択の必要はありません。

4.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

5. Red Hat Enterprise Linux 5.4 64bitの場合¶

ホスト、ゲストともにRed Hat Enterprise Linux 5.4 64bit( 以下、RHEL 5.4(64bit) )を用いたときのチュートリアルです。

5.1. 事前に¶

ホストOSのインストール

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

# yum install kvm

5.2. Karesansuiのインストール¶

Karesansuiのインストールは、CentOS 5.4の場合と同じです。
CentOS 5.4のチュートリアル を参照してください。

5.3. ゲストの作成¶

5.3.1. ゲストのOSインストール準備

RHEL 5.4(64bit)のDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

5.3.2. ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法は、以下の通りです。

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のRHEL 5.4(64bit)のOSインストールと同じようにゲスト上にOSをインストールすることができます。

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

5.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

6. CentOS 5.4 64bitの場合¶

ホスト、ゲストともにCentOS 5.4 64bitを用いたときのチュートリアルです。

6.1. 事前に¶

ホストOSのインストール

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

(必須) ソフトウェアのセットアップで「仮想化」「KVM」にチェックを入れてください。
(必須ではありません) ストレージ拡張を容易に行えるため、LVMを利用することを推奨しています。
注）デフォルトパーティションを利用するとデフォルトでLVMになります。

6.2. Karesansuiのインストール¶

Karesansuiのインストールは、CentOS 5.4の場合と同じです。
CentOS 5.4のチュートリアル を参照してください。

6.3. ゲストの作成¶

6.3.1. ゲストのOSインストール準備

CentOS 5.4 64bitのDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

6.3.2. ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法は、以下の通りです。

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のRHEL 5.4(64bit)のOSインストールと同じようにゲスト上にOSをインストールすることができます。

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

6.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

7. CentOS 5.4 32bitの場合¶

ホスト、ゲストともにCentOS 5.4 32bitを用いたときのチュートリアルです。

7.1. 事前に¶

ホストOSのインストール

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

(必須) ソフトウェアのセットアップで「仮想化」「KVM」にチェックを入れてください。
(必須ではありません) ストレージ拡張を容易に行えるため、LVMを利用することを推奨しています。
注）デフォルトパーティションを利用するとデフォルトでLVMになります。

7.2. Karesansuiのインストール¶

Karesansuiのインストールは、CentOS 5.4の場合と同じです。
CentOS 5.4のチュートリアル を参照してください。

7.3. ゲストの作成¶

7.3.1. ゲストのOSインストール準備

CentOS 5.4 32bitのDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

7.3.2. ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法は、以下の通りです。

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のRHEL 5.4(32bit)のOSインストールと同じようにゲスト上にOSをインストールすることができます。

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

7.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

アップデート¶

1. 目次¶

• アップデート
• 1. 目次
• 2. Karesansui 1.0.1 からKaresansui 1.0.2へアップデートする場合
• 3. Karesansui 1.0.x からKaresansui 1.1.xへアップデートする手順

2. Karesansui 1.0.1 からKaresansui 1.0.2へアップデートする場合¶

対象者

利用しているデータベースが、SQLite以外の方が対象です。

影響範囲

ジョブマネージャー(Pysilhouette)全体

今回の不具合について

インストーラーに不具合があり、どのデータベースパスを入力しても、ジョブマネージャー(Pysilhoutte)がSQLiteを選択してしまいます。

その結果、ネットワーク接続に対応していないSQLiteですと、マルチホストに対応することができなくなります。

この不具合の修正版を1.0.2でリリースしましたが、手動で行わなければならない作業がいくつかあります。

以下の手順でアップデートしてください。

1. データベースの作成
移行先のPysilhouetteデーターベースを作成してください。

PostgreSQLの場合
    # createdb -U username -W pysilhouette --encoding=utf8

MySQLの場合
    # mysql -u username -p -e 'CREATE DATABASE pysilhouette DEFAULT CHARACTER SET utf8;'

注意)
UTF-8でデータベースを作成してください。

2. 新パッケージをダウンロードし、伸長する

ダウンロードURL

# rm -rf Karesansui
# tar zxvf karesansui-<バージョン>-install-pack.tar.gz
# cd Karesansui

3. 現在のデータベースパスの確認

現在のPysilhouetteのデータベースパスを取得しておきます。

• 設定ファイルから取得する方法
  /etc/opt/pysilhouette/silhouette.confファイル内の「database.url」の値を取得する。

sqlite:////var/opt/pysilhouette/pysilhouette.db

4. Karesansuiをアップデートする

Karesansuiをアップデートし、Pysilhouetteのデータベースを変更します。
チュートリアル を参考にKaresansuiをアップデートしてください。

# ./karesansui-install

• 「管理者の設定」画面
  「パスワード」を設定し、「OK」を押下します。

• 「データベースの設定」画面
  「データベースを初期化する」のチェックを外し、「pysilhouette データベースパス」に新しく作成したデータベースのパスを設定し、「OK」を押下します。

「データベースを初期化する」のチェックを外してください！
Karesansuiのデータベースが初期化されてしまいます！

• 「確認」画面
  「OK」を押下します。

5. インストールチェック
./karesansui-checkenvを実行しエラーがないか確認します。
また、「データベース pysilhouette に接続できるかをチェック... 」が指定したデータベースパスになっているか確認してください。

# ./karesansui-checkenv

6. データベースの移行
データベースをSQLiteからMySQLまたはPostgreSQLへコピーをします。

# cd /opt/pysilhouette/share/doc/pysilhouette-0.6.2/tool/
# export PYTHONPATH=/opt/hde/lib/python:/opt/karesansui/lib/python:/opt/pysilhouette/lib/python:$PYTHONPATH
# ./sqlite2other.py --input=<移行元データベースパス> --output=<移行先データベースパス>

• --inputに入力するパス取得方法
  「3. 現在のデータベースパスの確認」の手順で確認したパスです。

• --outputに入力するパス取得方法
  • karesansui-checkenvから取得する方法
    karesansui-checkenvで出力された「データベース pysilhouette に接続できるかをチェック... 」に書かれてあるパスを入力します。
  • 設定ファイルから取得する方法
    /etc/opt/pysilhouette/silhouette.confファイル内の「database.url」の値を入力します。

• データベースパスの書式

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

コマンドの実行結果で画面に出力される「copy num」の数値はあとで使用しますので、保管してください。
(copy num - xxx) のxxxの部分
sqlite2other.py は SQLite -> MySQL or PostgreSQLの移行のみサポートしています。

# ./sqlite2other.py --input=sqlite:////var/opt/pysilhouette/pysilhouette.db --output=mysql://username:password@localhost/pysilhouette?charset=utf8
Cleanup Database [OK]
copy num - 3

参考)
データベースパスの書式の詳細な説明は、リファレンス を参考にしてください。

7. 自動インクリメントの変更
Pysilhouetteデータベースの自動インクリメントの値を変更します。
Pysilhouetteデータベースにアクセスして、下記のSQLを実行してください。

SQLの<copy numの数字>の部分は、「4. データベースの移行」の手順で実行した
./sqlite2other.pyで出力されるcopy numの数字に置き換えて実行してください。

PostgreSQLの場合
    select setval('jobgroup_id_seq', <copy numの数字>);
    select setval('job_id_seq', <copy numの数字>);

    例)
    # psql pysilhouette  -U username -h localhost -c "select setval('jobgroup_id_seq', 3);" 
    # psql pysilhouette -U username -h localhost -c "select setval('job_id_seq' 3);" 

MySQLの場合
    ALTER TABLE jobgroup AUTO_INCREMENT = <copy numの数字>;
    ALTER TABLE job AUTO_INCREMENT = <copy numの数字>;

    例)
    # mysql pysilhouette -u username -h localhost -p -e "ALTER TABLE jobgroup AUTO_INCREMENT = 3;" 
    # mysql pysilhouette -u username -h localhost -p -e "ALTER TABLE job AUTO_INCREMENT = 3;" 

# ./sqlite2other.py --input=<移行元データベースパス> --output=<移行先データベースパス>
Cleanup Database [OK]
copy num - 3 <-- 置き換える数字

# /etc/init.d/hde-lighttpd stop
# /etc/init.d/silhouetted restart
# /etc/init.d/hde-lighttpd start

3. Karesansui 1.0.x からKaresansui 1.1.xへアップデートする手順¶

概要
1.1では、ゲストOSの各種データのファイル・ディレクトリ構成が変更されました。下記手順でアップグレードを行うことで、各種ソフトウェアの更新を行うとともに、ファイル・ディレクトリ配置の変換も行います。

なお、アップグレードを行う場合は、重要なデータは別のサーバーへバックアップしてから行うことをお薦めします。

以降では、CentOS 5.3 (i386) を例に説明します。

# /etc/init.d/silhouetted stop
# /etc/init.d/hde-lighttpd stop
# /etc/init.d/hde-libvirtd stop
# /etc/init.d/xend stop

1. ダウンロードした1.1のインストールパックを任意のディレクトリに展開します。

      # tar zxvf karesansui-1.1.0-xxx-install-pack.tar.gz

2. 展開されたインストールパックに含まれるインストーラを実行します。

      # cd Karesansui
      # ./karesansui-install

3. インストーラの案内にしたがって、項目を入力します。

このとき、データベース設定の画面でデーターベース初期化を選択しますと、それまでのデータが消去されてしまいますのでアップグレードを行いたい場合は、選択しないようご注意下さい。

4.インストーラの実行が終了後

各種ソフトウェア更新と既存データの移行は完了です。以下のコマンドで、Karesansuiの実行環境に問題ないか確認してください。

      # ./karesansui-checkenv

Wiki編集方針¶

（http://karesansui-project.info/wiki/karesansui/En_wiki_policy?version=3 に基づく翻訳）

ページ名¶

• ページ名は2文字の言語略号（ISO 639で定義）＋アンダースコアではじまらなければいけません。最初の文字は大文字にしなければいけません（redmineの仕様）。
  • ex) En_wiki_policy, Ja_wiki_policy
• あるページを別の言語に翻訳する場合、はじめの3文字以外は変えてはいけません。
  • ex) En_wiki_policy, Ja_wiki_policy

翻訳¶

• 翻訳は歓迎します。
• あるページを翻訳する場合には、翻訳者はオリジナルの文書のURLを冒頭に入れても良いでしょう。
  オリジナルバージョンのURLとバージョン番号は'履歴'リンクからたどれます。

Development document¶

comming soon.

FAQ¶

Table of Contents¶

• FAQ
• Table of Contents
• General
• Q. Is it free?
• Q. What kind of the license is Karesansui under?
• Q. Does Karesansui support full-virtualization?
• Q. Does Karesansui only support Xen?
• Q. I'm not used to Linux. Is the installation easy?
• Q. There are already many virtulization management consoles around there. What are the pros of Karesansui?
• Q. I'd like to introduce Karesansui to others.
• Q. I'd like to use Karesansui in our company's network. Is there any license problems?
• Application
• Q. What happens when the database, which Karesansui refers, stops? Does the guest stop?
• Q. I'll get "You need Java installed" errors when I try to access the guest console.
• Q. Guest console doesn't show up. What can I do?
• Q. Guest console keymap is garbled.
• Q. I can't shutdown/stop guests.
• Q. It doesn't work.
• Logging
• Q. I want to change the log file rotation cycle, size, path, etc..
• Q. I found an error on the Karesansui control panel, but can't find corresponding message in the error log.
• Q. Can I change the log output style?
• Q. Where are the log files stored?
• Q. I have several log files. What are these?
• Q. "Update" panel is not displayed. (Error is displayed)
• Development/OSS
• Q. Binary package and source package seems to be all bundled in the installer package. Do you offer single package downloads?

General¶

Q. Is it free?¶

Yes, it is. You may use Karesansui for business or personal use for free.

Q. What kind of the license is Karesansui under?¶

Karesansui is mainly under GPL and LGPL. See here for details.

Q. Does Karesansui support full-virtualization?¶

Karesansui is aimed to support virtual servers so it does not support full-virtualization now. We are planning to support it in future. While it is not supported by Karesansui, you may setup full-virtualized guests using command line.

Q. Does Karesansui only support Xen?¶

Yes, it only supports Xen now. But we are planning to support KVM in near future.

Q. I'm not used to Linux. Is the installation easy?¶

We prepared and install pack so you should be able to install Karesansui easily. Please follow our Tutorial.

Q. There are already many virtulization management consoles around there. What are the pros of Karesansui?¶

We are working hard. Please take a look at our Karesansui's full ajax web control panel.

Q. I'd like to introduce Karesansui to others.¶

Yes! Thank you! Take the Get Karesansui Badge if you like it.

Q. I'd like to use Karesansui in our company's network. Is there any license problems?¶

No. Nothing. It's GPL/LGPL so there's no problem.

Application¶

Q. What happens when the database, which Karesansui refers, stops? Does the guest stop?¶

No. Karesansui uses the database to keep information for its user interface. Guests don't stop if when the database stops, but you will have problems to access Karesansui control panel.

Q. I'll get "You need Java installed" errors when I try to access the guest console.¶

We use TightVNC Java applet for guest console. So you need Java installed for your browser.

Q. Guest console doesn't show up. What can I do?¶

> ping {Karesansui server IP address or name}

# netstat -nalt

If all above are OK, then try to connect the guest from the client, using standard VNC viewer applications.

Q. Guest console keymap is garbled.¶

Select 'Display' from guest device tab, and set 'VNC Keymap'. Choose appropriate keymap.

Q. I can't shutdown/stop guests.¶

Try the following instructions. First check if acpid is running. On the guest console, do as shown below.

# ps auxww | grep acpid
root        34  0.0  0.0      0     0 ?        S<   10:50   0:00 [kacpid]
68        2420  0.0  0.0  12320   876 ?        S    10:51   0:00 hald-addon-acpi: listening on acpi kernel interface /proc/acpi/event
root      4082  0.0  0.0  65372   868 pts/0    S+   12:15   0:00 grep acpid

If /usr/sbin/acpid is not installed, install it. If /usr/sbin/acpid is not running, start it.

# rpm -q acpid 2>/dev/null || yum -y install acpid
# /etc/init.d/acpid start
# chkconfig acpid on

if acpid fails with error like "acpid: can't open /proc/acpi/event: Device or resource busy", try as following.

# /etc/init.d/haldaemon stop
# /etc/init.d/acpid start
# /etc/init.d/haldaemon start
# chkconfig acpid on

Check if acpid is running on guest again.

# ps auxww | grep acpi
root        34  0.0  0.0      0     0 ?        S<   10:50   0:00 [kacpid]
root      4107  0.0  0.0   3800   576 ?        Ss   12:18   0:00 /usr/sbin/acpid
68        4122  0.0  0.0  12320   880 ?        S    12:18   0:00 hald-addon-acpi: listening on acpid socket /var/run/acpid.socket
root      4142  0.0  0.0  65372   876 pts/0    S+   12:20   0:00 grep acpi

After acpid is started, try to shutdown/stop the guest.

Q. It doesn't work.¶

Go and ask your question in the Karesansui Forum . Somebody may answer you.

Logging¶

Q. I want to change the log file rotation cycle, size, path, etc..¶

Change "args" in the "[handler_*" category of log.conf

ex) Change log file size from 5M -> 10M

args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/application.log', 'a', (10 *1024 *1024), 5)

ex) Change log file name from application.log -> server.log
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/server.log', 'a', (5 *1024 *1024), 5)

Change log rotate files from 5 -> 10
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 10)

Q. I found an error on the Karesansui control panel, but can't find corresponding message in the error log.¶

May be the message is filtered by the log level. Check the level in "[logger_*" category of log.conf.

Log levels (From high to low. Higher level include lower level.)
 - DEBUG : Log all
 - INFO : General information
 - WARNING : Log warnings (recommended)
 - ERROR : Log errors
 - CRITICAL : Log severe errors
 - EXCEPTION : Log system errors

After changing log.conf, restart the web server.

Q. Can I change the log output style?¶

We use python logging. Check python logging instructions.

Q. Where are the log files stored?¶

Where defined in "args" of "[handler_*" category of log.conf.

Q. I have several log files. What are these?¶

Karesansui writes log in several files.

General log of Karesansui: /var/log/karesansui/application.log
Program trace for errors: /var/log/karesansui/error.log
SQL committed by Karesansui: /var/log/karesansui/sql.log

Q. "Update" panel is not displayed. (Error is displayed)¶

A. May be the proxy server is not properly set. Check the proxy settings in "Top" - "Settings".

ex) (Bad Request) [400] ('Cannot retrieve repository metadata (repomd.xml) for repository: karesansui-base. Please verify its path and try again',) 

Development/OSS¶

Q. Binary package and source package seems to be all bundled in the installer package. Do you offer single package downloads?¶

A. We offer Karesansui package downloads via HTTP.
Karesansui software update (using yum) also accesses the URL below.

URL : http://updates.karesansui-project.info/
id : karesansui
password : karesansui

How to consult errors¶

Application Errors¶

Karesansui uses RESTful architecture (supporting override POST), so errors in Karesansui control panel has an HTTP response code.
Below are examples of the response code.

 - 2xx : HTTP result code standing for normal execution.
   - On Karesansui, these normal response codes.

 - 3xx : HTTP result code used for redirections.
   - On Karesansui these are also normal response codes.

 - 4xx : HTTP result code for client request errors.
   - On Karesansui, this is returned on "Bad request" or "URL not found".

 - 5xx : HTTP result code standing for server errors.
   - This is probably Karesansui's error. If you get 5xx please report it in the forum or mailing list.

What is kernel image? What is initrd image?¶

Abstract¶

On creating guest, you are asked to input the kernel image an initrd image.
We will introduce some examples below.

Kernel image¶

Kernel image is the image of Linux kernel, as you may guess.
On guest creation, kernel image will be used only for the first installation of the guest.

initrd image¶

initrd is the ram file sysmte which Linux temporally uses on boot.
On guest creation, initrd image will be used only when booted using the kernel image above.

Example¶

CentOS5.3¶

kernel image
http://<mirror server name>/Linux/centos/5.3/os/i386/images/xen/initrd.img

initrd image
http://<mirror server name>/Linux/centos/5.3/os/i386/images/xen/vmlinuz

Hints
Install image path used on guest installation:
http://<mirror server name>/Linux/centos/5.3/os/i386/

Fedora10¶

kernel image
http://<mirror server name>/Linux/fedora/releases/10/Fedora/i386/os/images/pxeboot/initrd-PAE.img

initrd image
http://<mirror server name>/Linux/fedora/releases/10/Fedora/i386/os/images/pxeboot/vmlinuz-PAE

Hints
Install image path used on guest installation:
http://<mirror server name>/Linux/fedora/releases/10/Fedora/i386/os/

How to change configuration settings¶

Karesansui uses configuration file and const.py file for configuration.

Configuration file¶

Coming soon.

How to customize logs¶

If you installed Karesansui from install package, you have log configurations in /etc/opt/karesansui/log.conf.

For details, consult Python logging

*FAQ about logging are here.

How can I set up multiple hosts?¶

Required Conditions¶

1. You should be using databases which allows network connection from multiple hosts, like MySQL or PostgreSQL.
2. SQLite can't be used for multiple host configuration.

How to add a new host¶

Definitions¶

1. Host A = Existing host (Karesansui installed)
2. Host B = A new host to be added

Step 1. Check the version of exisiting Karesansui¶

Access Karesansui on host A, click "Options" which are in the header, and display "About Karesansui" screen. Take a memo of the version information.

Step 2. Install Karesansui in host B¶

Download the same version of the Karesansui you checked in Step 1, and install it into host B.

warning: While the install process, you will be asked about the database location. Specify the same location of host A, and DO NOT CHECK the "Initilize database" checkbox.

Step 3. Check the Karesansui unique key of host B¶

Look in /etc/opt/karesansui/application.conf of the host B, and find "application.uniqkey". The value is the unique key of host B. We use this in Step4, so take a memo of the unique key. example) application.uniqkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Step 4. Add host B to host A Karesansui¶

Access host A, and click "Add" at the top page to add a host. Input required fields and press "Add".

Some explaination:
- Host Name (required): The host name to display on Karesansui control panel. There are no restrictions for this name so choose the name you like.
           Example）Host B

- FQDN (required): FQDN of host B to access from the client. Input a FQDN or an IP address.
           Example）hostb.karesansui-project.info / 192.168.0.1

- UUID (required) : Input the Karesansui unique key of Host B you checked in Step 3.
- Note : Space for a memo.
- Tags : Tags to put on this host.

Step 5. Testing¶

Access host A Karesansui control panel, and click host B icon (usually the N/A icon are displayed) to display details. Find "Link to host" in "Other Information" and click to see the host B control panel. Basic authorization may be required at this step. 

If you see host B name in the control panel header, host was successfully added. *A

*A : Host name should appear in the right of this image.

P.S.: Host B icon can be changed on host B control panel.

HOWTO¶

• How to setup multiple hosts
• How to customize logs
• How to consult errors
• How to change initial configuration values
• What is kernel images? What is initrd images?
• Where are the image file of the guests I created?

Where are the guest images which I installed using Karesansui?¶

Paths¶

(This only applies if you have installed karesansui using the install package)

Hints¶

To backup guests, you may use above paths.

License¶

Some parts of Karesansui are GPL, and some are LGPL, but the core architecture is LGPL, to reduce problems for re-using. All source code has license notice, so you should clearly know what license to follow.

For exception, some Karesansui files some don't have license notice for technical problems. The files under template/default/include coming with the source tree are LGPL. Other files under template/default are GPL. This DOES NOT mean that your original files you put in template/default should be GPL, or template/default/include should be LGPL. This DOES NOT mean that files somebody put in template/default or template/default/include without any notice will become GPL or LGPL. We can only mention about files we distribute, so consult the original author for such files.

The Karesansui source tree includes other open source projects work, which may come with its own distribution rule. Please consult each license notice for these projects.

Job Manager (pysilhouette)¶

Abstract¶

Many of the system update actions performed by Karesansui are executed using the job manager.
Karesansui uses Pysilhouette for the job manager.

Pysilhouette¶

Pysilhouette is a job manager which executes jobs(commands) which are registered in queue.
Support parallel job executions since 0.7.0.
Aimed to be used to execute web application background jobs.

About Pysilhouette¶

• Developed in 100% Pure Python.
• Armed with simple self audit feature, to achieve high availabilty.
• Jobs can be batch executed using job group feature.
• Each job can perform rollbacks.
• Supports several RDBMS for backend.

Pysilhouette is developed by Karesansui Project.

Premise¶

This document explains about Pysilhouette included in Karesansui package.

Settings¶

Coming soon.

References
Requirements
Functions
Screen Structure
How To Download Source
Setting Files
Trouble Shooting
Guest Import/Export
Watch
Storage Pool
ER¶

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

 # 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.

'TLS certificates setting' screen

Setting up TLS certificates for libvirt remote SSL connection.

'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.

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.

'Mail setting' screen

Setting up SMTP connection to send e-mail.

'Confirm' screen

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

'Progress' screen

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.

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.

# /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)

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)

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

# 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

# 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.

# 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)

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)

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

# 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

Update Instructions¶

1. Contents¶

• Update Instructions
• 1. Contents
• 2. Users who are using SQLite with Karesansui 1.0.0/1.0.1 and planning to upgrade to 1.0.2.
• 3. Users who are planning to upgrade from Karesansui 1.0.x to 1.1.x.
• 4. Users who are planning to upgrade from Karesansui 1.1.x to 2.0.x.
• 5. Users who are planning to upgrade from Karesansui 2.0.0 to 2.0.x.

2. Users who are using SQLite with Karesansui 1.0.0/1.0.1 and planning to upgrade to 1.0.2.¶

Target users for this document

Users who are using SQLite with 1.0.0 and 1.0.1.

Affected area

The job manager (Pysilhouette)

Issue which was fixed in 1.0.2

Installer was causing the job manager (Pysilhouette) to lookup SQLite database path, even the user specified other database path (like MySQL or PostgreSQL), so multi-host configuration was not supported.

1.0.2 fixes these problems, but some manual configuration are needed for updates.

1. Database Creation

Create database for the job manager (Pysilhouette).

For PostgreSQL
    # createdb -U username -W pysilhouette --encoding=utf8

For MySQL
    # mysql -u username -p -e 'CREATE DATABASE pysilhouette DEFAULT CHARACTER SET utf8;'

Important)
Create database with UTF-8 charsets.

2. Download the new package and deploy.

Download URL

# rm -rf Karesansui
# tar zxvf karesansui-<version>-install-pack.tar.gz
# cd Karesansui

3. Check current database path

Get current Pysilhouette database path.

• Get from the configuration file
  Look at the key "database.url" in /etc/opt/pysilhouette/silhouette.conf

sqlite:////var/opt/pysilhouette/pysilhouette.db

4. Update Karesansui

Update Karesansui and change Pysilhouette database path.
Update Karesansui as the steps in the tutorial

# ./karesansui-install

• In "Administrator Settings" screen
  Set "Password", and press "OK".

• In "Database Settings" screen
  Uncheck "Initialize database", and input the new database path in "Pysilhouette database path", and press "OK".

Uncheck "Initialize database", or you will lose your current database settings.

• On "Confirmation" screen
  Press "OK".

5. Installation Environment Check
Execute ./karesansui-checkenv to check if there are any errors.
Check if the output message "Checking whether we are able to connect to database for XXXXX... " describes your new database path.

# ./karesansui-checkenv

6. Migrate Database
Copy SQLite database to MySQL or PostgreSQL database.

# cd /opt/pysilhouette/share/doc/pysilhouette-0.6.2/tool/
# export PYTHONPATH=/opt/hde/lib/python:/opt/karesansui/lib/python:/opt/pysilhouette/lib/python:$PYTHONPATH
# ./sqlite2other.py --input=<old database path> --output=<new database path>

• Put the path we got checked in the above section
  "3. Check current database path" into <old database path>.

• <new database path> is available through some ways.
  • Get from 'karesansui-checkenv' output: Check the output message
    "Checking whether we are able to connect to database for XXXXX... of karesansui-checkenv.
  • Get from the configuration file
    Check the key "database.url" of /etc/opt/pysilhouette/silhouette.conf.

• Database path format

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

Take a memo of the outputted "copy num" number. We use it later.
(copy num - xxx)
sqlite2other.py only supports SQLite -> MySQL or  SQLite -> PostgreSQL migration.

# ./sqlite2other.py --input=sqlite:////var/opt/pysilhouette/pysilhouette.db --output=mysql://username:password@localhost/pysilhouette?charset=utf8
Cleanup Database [OK]
copy num - 3

Information)
For details about database path format, consult the reference

7. Change Auto Increment Counter Value
Change the auto increment counter value of Pysilhouette.
Access Pysilhouette database an execute the SQL below.

Put the "copy-num" value we got above into <copy num value>.

For PostgreSQL:
    select setval('jobgroup_id_seq', <copy num value>);
    select setval('job_id_seq', <copy num value>);

    Example)
    # psql pysilhouette  -U username -h localhost -c "select setval('jobgroup_id_seq', 3);" 
    # psql pysilhouette -U username -h localhost -c "select setval('job_id_seq' 3);" 

For MySQL:
    ALTER TABLE jobgroup AUTO_INCREMENT = <copy num value>;
    ALTER TABLE job AUTO_INCREMENT = <copy num value>;

    Example)
    # mysql pysilhouette -u username -h localhost -p -e "ALTER TABLE jobgroup AUTO_INCREMENT = 3;" 
    # mysql pysilhouette -u username -h localhost -p -e "ALTER TABLE job AUTO_INCREMENT = 3;" 

# ./sqlite2other.py --input=<old database path> --output=<new database path>
Cleanup Database [OK]
copy num - 3 <-- "copy-num" value

# /etc/init.d/hde-lighttpd stop
# /etc/init.d/silhouetted restart
# /etc/init.d/hde-lighttpd start

3. Users who are planning to upgrade from Karesansui 1.0.x to 1.1.x.¶

• Description

In version 1.1, the path of some configuration files and disk image files has changed.
This document describes how to migrate these files and settings.

_*We recommend to back up the important data to other physical machine in advance.*_

1. Stop Daemon

# /etc/init.d/silhouetted stop
# /etc/init.d/hde-lighttpd stop
# /etc/init.d/hde-libvirtd stop
# /etc/init.d/xend stop

2. Download the new package and deploy.

Download URL

# rm -rf Karesansui
# tar zxvf karesansui-<version>-install-pack.tar.gz
# cd Karesansui

3. Update Karesansui

# ./karesansui-install

_*You must not choose the database initialization.*_

4. Installation Environment Check
Execute ./karesansui-checkenv to check if there are any errors.

# ./karesansui-checkenv

4. Users who are planning to upgrade from Karesansui 1.1.x to 2.0.x.¶

• Description

In version 2.0, the disk image files are stored on the disk volumes in storage pool.
This document describes how to migrate these files and settings.

_*We recommend to back up the important data to other physical machine in advance.*_

1. Shutdown all the domains gracefully

You need to stop domains by Karesansui's management console or executing command below.

# /opt/hde/bin/virsh shutdown <domain>

2. Stop Daemon

# /etc/init.d/silhouetted stop
# /etc/init.d/hde-lighttpd stop
# /etc/init.d/hde-libvirtd stop
# /etc/init.d/xend stop (on system using xen-kernel)

3. Download the new package and deploy.

Download URL

# rm -rf Karesansui
# tar zxvf karesansui-<version>-install-pack.tar.gz
# cd Karesansui

4. Update Karesansui

# ./karesansui-install

_*You must not choose the database initialization.*_
_*Whatever you choose, the database of pysilhouette will be initialized. If necessary, please back up the database.*_

5. Installation Environment Check
Execute ./karesansui-checkenv to check if there are any errors.

# ./karesansui-checkenv

6. Reboot Host

# shutdown -r now

Differences about paths between the previous version and this version

In version 2.0, each disk image file used by guest is stored on the disk volumes in storage pool.

1. Disk image file used by guest

1.1 path of version 1.1.x
/var/opt/hde/libvirt/domains/<domain_name>/images/<domain_name>.img

1.1 path of version 2.0.x
The disk volume file in libvirt's storage pool.

By default, the storage pool named 'default' will be created in ''/var/opt/hde/libvirt/domains''.
So after finishing upgrade from 1.1.x, volume files are created as an symbolik link to existant image files used by the previous version and named uuid.

# ls -ltr /var/opt/hde/libvirt/domains/[0-9]*
lrwxrwxrwx 1 root kss  57  Jun  9 HH:MM /var/opt/hde/libvirt/domains/55236ff8-88bb-023f-1499-2f34c4f1b133 -> /var/opt/hde/libvirt/domains/foo/images/foo.img

5. Users who are planning to upgrade from Karesansui 2.0.0 to 2.0.x.¶

• Description

This document describes how to migrate these files and settings.

_*We recommend to back up the important data to other physical machine in advance.*_

1. Shutdown all the domains gracefully

You need to stop domains by Karesansui's management console or executing command below.

# /opt/hde/bin/virsh shutdown <domain>

2. Stop Daemon

# /etc/init.d/silhouetted stop
# /etc/init.d/hde-lighttpd stop
# /etc/init.d/hde-libvirtd stop
# /etc/init.d/xend stop (on system using xen-kernel)

3. Download the new package and deploy.

Download URL

# rm -rf Karesansui
# tar zxvf karesansui-<version>-install-pack.tar.gz
# cd Karesansui

4. Update Karesansui

# ./karesansui-install

_*You must not choose the database initialization.*_
_*Whatever you choose, the database of pysilhouette will be initialized. If necessary, please back up the database.*_

5. Installation Environment Check
Execute ./karesansui-checkenv to check if there are any errors.

# ./karesansui-checkenv

6. Reboot Host

# shutdown -r now

パッケージのビルド¶

パッケージの取得¶

karesansui-projectはインストーラパックに含まれているRPMや開発に便利なRPM、全てのパッケージのSRPMなどをアップデートサーバにて公開しています。

http://updates.karesansui-project.info/

※ベーシック認証がかけられています。
id : karesansui
password : karesansui

ここからSRPMを取得することで、karesansuiで利用している各種OSSのビルドを行うことが出来ます。

パッケージのビルド¶

RPMのビルドを行うにあたり、以下のパッケージが必要となるので、あらかじめyumなどでインストールしてください。

• rpm-build
• gcc

依存関係で足りないパッケージは、CentOSやrpmforgeなどのリポジトリからyumでインストールしてください。

開発ドキュメント¶

概要¶

Karesansuiは大きくWebアプリケーション(以後Webフレームワーク)と仮想化操作(仮想化ライブラリ)に分かれています。
WebフレームワークはMVC,RESTfulをweb.py、テンプレートエンジンをMako、O/RマッピングをSQLAlchemyを採用しています。
Karesansuiはそれらを結合した薄いフレーワークを独自に提供するスタイルをとっています。

開発ドキュメントの他に、リファレンスもありますので、あわせてみてください。

その他¶

Webサーバー : lighttpd(FCGI)を採用
国際化 : mako+gettext
データベース : SQLALchemyを採用することで複数のデータベースをサポート
監視 : collectd
グラフレポート : rrdtool
パッケージ管理 : yum, rpm
Javascript : jQuery

などさまざまなオープンソースが使われています。

ソースコード¶

ソースコードの取得

パッケージのビルド¶

パッケージのビルド

カスタマイズについて¶

様々なオープンソースを組み合わせ仮想化管理を行うのは大変なことです。
Karesansuiをカスタマイズすることで簡単にあなたにあった管理ツールを手にすることができます。

• 内部のシステム構成
• 開発環境を作ってみる
• 新しいページを作ってみる
• フレームワークの提供する関数/変数リファレンス
  • コントローラー(gadget)
  • データベースへのアクセス(db.access)
  • データベーステーブル(db.model)
  • ビュー(templates/theme)

• リポジトリ構成
• v2 ja dev make i18n|国際化してみる
• v2 ja dev make cookbook|クックブック
• v2 ja dev make auth plugin|認証プラグインを作ってみる
• v2 ja dev make watch|新たに監視対象を増やす
• v2 ja dev use virt|karesansui.lib.virtを使って仮想マシンを操作してみる

• Karesansui E-R Diagram

FAQ¶

目次¶

• FAQ
• 目次
• 一般
• Q. 無料で利用できるの？
• Q. Karesansuiはどんなライセンスなの？
• Q. 対応するハイパーバイザーはXenだけなの？
• Q. Linuxに詳しくないんだけどインストールって簡単？
• Q. 他にもいろんな仮想化ソフトがあるけどKaresansuiだとなにかメリットがあるの？
• Q. Karesansuiをいろんなところで紹介したいんだけど。
• Q. 会社で利用したんだけど、ライセンスで問題とかある？
• アプリケーションについて
• Q. Karesansuiが参照するデータベースが異常停止したらゲストは停止する？
• Q. ゲストのコンソールを表示するとJavaが必要ってでるんだけど。
• Q. コンソールが表示されないんだけど、どうしたらいい？
• Q. コンソールからキーボード入力すると、別のキーボード配列になってるんだけど。
• Q. ゲストのシャットダウン・再起動ができない。
• Q. アップデート画面が表示されない。(エラーが画面に表示される。)
• Q. ネットワークストレージ画面が表示されない。(タイムアウトが画面に表示される。)
• Q. うまく動かないんだけど、どうしたらいい？
• ログ関連
• Q. ログファイルのサイズ・ファイルパス・ローテート数を変更したいんだけどどうすればいい？
• Q. 画面でエラーが発生したがうまくログ出力されていないみたい。
• Q. ログの出力形式を変更したいんだけど。
• Q. ログファイルってどこに出力されるの？
• Q. ログファイルが3つあるんだけど
• 開発・オープンソース関連
• Q. バイナリパッケージとソースパッケージがインストーラーパッケージに含まれて提供されているけど、HTTP経由での提供はしていないの？
• Q. SQLite以外のデータベースを利用したいのですが。

一般¶

Q. 無料で利用できるの？¶

Karesansuiは商用、非商用を問わずだれでも無料で利用することができます。

Q. Karesansuiはどんなライセンスなの？¶

GPLとLGPLで構成するライセンスになっています。詳細はこちらを参照してください。

Q. 対応するハイパーバイザーはXenだけなの？¶

現在サポートしているのはXenだけですが、近い将来 KVM にも対応する予定です。
Version 1.1でKVMに対応し、現在KVMとXen両方に対応しています。

Q. Linuxに詳しくないんだけどインストールって簡単？¶

インストールパックを用意していますので、簡単にインストールが可能です。初めての方はチュートリアルをご覧ください。

Q. 他にもいろんな仮想化ソフトがあるけどKaresansuiだとなにかメリットがあるの？¶

Karesansuiを使えば複雑な操作から解放されるはずです。Karesansuiは誰でも簡単に仮想化ができるアプリケーションを目指して日々開発しています。

Q. Karesansuiをいろんなところで紹介したいんだけど。¶

是非、是非じゃんじゃんご紹介ください。バナーも提供中 です！

Q. 会社で利用したんだけど、ライセンスで問題とかある？¶

まったく問題ありません。KaresansuiはGPL・LGPLで配布されていますので、利用することによる制限はありません。

アプリケーションについて¶

Q. Karesansuiが参照するデータベースが異常停止したらゲストは停止する？¶

データベースが停止していてもゲストやホストに影響が出ることはありません。ただしブラウザからの操作はできなくなります。

Q. ゲストのコンソールを表示するとJavaが必要ってでるんだけど。¶

コンソールの表示には、オープンソースのTightVNC のJava appletを利用していますので、Javaが必要となります。

Q. コンソールが表示されないんだけど、どうしたらいい？¶

以下を試してみてください。通信ができるかどうかを確認します。クライアントのコンソールから以下のコマンドを発行します。

＞ ping {Karesansuiサーバー名}

次にKaresansuiサーバーでVNCポート番号が開いているか確認します。

# netstat -nalt

上記が正常な場合にはクライアントにVNCビューアを入れて接続してみてください。

Q. コンソールからキーボード入力すると、別のキーボード配列になってるんだけど。¶

「ゲスト」のデバイスタブから「Display」を選択し、「VNCキーマップ」を選択してください。日本語106/109キーボードは「ja」を選択してください。

Q. ゲストのシャットダウン・再起動ができない。¶

以下を試してください。ゲストに acpid が起動しているかを確認します。ゲストのコンソールから以下のコマンドを発行します。

# ps auxww | grep acpid
root        34  0.0  0.0      0     0 ?        S<   10:50   0:00 [kacpid]
68        2420  0.0  0.0  12320   876 ?        S    10:51   0:00 hald-addon-acpi: listening on acpi kernel interface /proc/acpi/event
root      4082  0.0  0.0  65372   868 pts/0    S+   12:15   0:00 grep acpi

/usr/sbin/acpid が起動していない場合には acpid を起動してください。

# rpm -q acpid 2>/dev/null || yum -y install acpid
# /etc/init.d/acpid start
# chkconfig acpid on

もし acpid: can't open /proc/acpi/event: Device or resource busy エラーで acpid の起動に失敗する場合には以下を試してください。

# /etc/init.d/haldaemon stop
# /etc/init.d/acpid start
# /etc/init.d/haldaemon start
# chkconfig acpid on

ゲストに acpid が起動しているかを再確認します。

# ps auxww | grep acpi
root        34  0.0  0.0      0     0 ?        S<   10:50   0:00 [kacpid]
root      4107  0.0  0.0   3800   576 ?        Ss   12:18   0:00 /usr/sbin/acpid
68        4122  0.0  0.0  12320   880 ?        S    12:18   0:00 hald-addon-acpi: listening on acpid socket /var/run/acpid.socket
root      4142  0.0  0.0  65372   876 pts/0    S+   12:20   0:00 grep acpi

ゲストで acpid を起動後に、ゲストのシャットダウン・再起動を試してみてください。

Q. アップデート画面が表示されない。(エラーが画面に表示される。)¶

A. プロキシサーバーの設定が正しく行われていない可能性があります。「トップ画面」「設定タブ」からプロキシサーバーの設定を確認してみてください。

例)(Bad Request) [400] ('Cannot retrieve repository metadata (repomd.xml) for repository: karesansui-base. Please verify its path and try again',) 

Q. ネットワークストレージ画面が表示されない。(タイムアウトが画面に表示される。)¶

A. iSCSI接続に時間が掛かり、Webサーバーがタイムアウトしている可能性があります。Webサーバーの設定を変更することでタイムアウトまでの時間を伸ばすことができます。
設定ファイルは　/etc/opt/hde/lighttpd/conf.d/karesansui.conf　です。

"idle-timeout"    => 120
↓↓↓↓↓
"idle-timeout"    => 300

Q. うまく動かないんだけど、どうしたらいい？¶

フォーラム にて聞いてみてください。有志の方や開発者が答えてくれるはずです。

ログ関連¶

Q. ログファイルのサイズ・ファイルパス・ローテート数を変更したいんだけどどうすればいい？¶

log.conf内の "[handler_*"カテゴリにある "args" を変更します。以下に変更例を記載します。

ログファイルサイズ 5M を 10Mにする場合

args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/application.log', 'a', (10 *1024 *1024), 5)

ログファイル名をapplication.log を server.log にする場合
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/server.log', 'a', (5 *1024 *1024), 5)

ログローテートを5から10にする場合
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 5)
↓↓↓↓↓
args=('/var/log/karesansui/application.log', 'a', (5 *1024 *1024), 10)

Q. 画面でエラーが発生したがうまくログ出力されていないみたい。¶

ログレベルによってログの出力を制限している可能性があります。 "[logger_*"カテゴリのlevelを確認してください。

ログレベル一覧(※上は下を包括します。)
 - DEBUG : 全て出力
 - INFO : 一般情報のみ出力
 - WARNING : 警告のみ出力(運用時の推奨設定)
 - ERROR : エラーのみ出力
 - CRITICAL : 深刻なエラーのみ出力
 - EXCEPTION : システム的なエラーのみ出力

補足 : ログ設定の変更時はウェブサーバーの再起動が必要です。

Q. ログの出力形式を変更したいんだけど。¶

Python loggingで利用できるすべての形式に対応していますので詳しくはそちらを参照ください。

Q. ログファイルってどこに出力されるの？¶

log.conf内の "[handler_*"カテゴリにある "args" に定義されています。

Q. ログファイルが3つあるんだけど¶

Karesansuiのログは複数のファイルで構成されています。

Karesansui全体のログ : /var/log/karesansui/application.log
Karesansuiで発生したエラーのプログラムトレースログ : /var/log/karesansui/error.log
Karesansuiが発行したSQL関連のログ : /var/log/karesansui/sql.log

開発・オープンソース関連¶

Q. バイナリパッケージとソースパッケージがインストーラーパッケージに含まれて提供されているけど、HTTP経由での提供はしていないの？¶

A. KaresansuiのパッケージはすべてHTTP経由で取得することができます。
※Karesansuiのソフトウェアアップデート(yum)もここから取得しています。

URL : http://updates.karesansui-project.info/
id : karesansui
password : karesansui

Q. SQLite以外のデータベースを利用したいのですが。¶

A. インストーラーにはSQLite以外のデータベースを利用する場合、別途Python用のデータベースドライバをインストールする必要があります。
Karesansuiでは、MySQLとPostgreSQLのドライバをextraパッケージにて提供しています。
詳しくは、チュートリアルの　4.2.1. 「インストール前準備」の項目を御覧ください。

手動でデータベースを作るには？¶

Karesansuiでは、KaresansuiとPysilhouetteの二つのデータベースを使用します。
何らかの原因でインストーラで正常にデータベースが構築されない場合は、手動でKaresansuiデータベースを構築することが出来ます。
なお、KaresansuiデータベースのE-R図がこちらにあるので、参考にしてください。
http://karesansui-project.info/2.0.0/er/karesansui/

テーブルの作成¶

Karesansuiデータベースは以下のSQL文で構築することが出来ます。¶

CREATE TABLE tag (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    name VARCHAR(24) NOT NULL, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id)
)

CREATE TABLE user (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    email VARCHAR(256) NOT NULL, 
    password VARCHAR(40) NOT NULL, 
    salt VARCHAR(16) NOT NULL, 
    nickname VARCHAR(16) NOT NULL, 
    languages VARCHAR(6), 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id), 
     UNIQUE (email)
)

CREATE TABLE `option` (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    created_user_id INTEGER, 
    modified_user_id INTEGER, 
    `key` VARCHAR(12) NOT NULL, 
    value TEXT, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id), 
     FOREIGN KEY(created_user_id) REFERENCES user (id), 
     FOREIGN KEY(modified_user_id) REFERENCES user (id), 
     UNIQUE (`key`)
)

CREATE TABLE notebook (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    title VARCHAR(64) NOT NULL, 
    value TEXT NOT NULL, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id)
)

CREATE TABLE machine (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    parent_id INTEGER, 
    notebook_id INTEGER, 
    created_user_id INTEGER, 
    modified_user_id INTEGER, 
    uniq_key VARCHAR(36) NOT NULL, 
    name VARCHAR(256) NOT NULL, 
    attribute SMALLINT NOT NULL, 
    hypervisor SMALLINT NOT NULL, 
    hostname VARCHAR(256), 
    icon VARCHAR(256), 
    is_deleted BOOL, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id), 
     FOREIGN KEY(parent_id) REFERENCES machine (id), 
     FOREIGN KEY(created_user_id) REFERENCES user (id), 
     FOREIGN KEY(modified_user_id) REFERENCES user (id), 
     UNIQUE (hostname), 
     UNIQUE (uniq_key), 
     FOREIGN KEY(notebook_id) REFERENCES notebook (id)
)

CREATE TABLE machine2tag (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    tag_id INTEGER, 
    machine_id INTEGER, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id), 
     FOREIGN KEY(tag_id) REFERENCES tag (id), 
     FOREIGN KEY(machine_id) REFERENCES machine (id)
)

CREATE TABLE snapshot (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    parent_id INTEGER, 
    machine_id INTEGER, 
    notebook_id INTEGER, 
    created_user_id INTEGER, 
    modified_user_id INTEGER, 
    name VARCHAR(256), 
    is_deleted BOOL, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id), 
     FOREIGN KEY(notebook_id) REFERENCES notebook (id), 
     FOREIGN KEY(parent_id) REFERENCES snapshot (id), 
     FOREIGN KEY(created_user_id) REFERENCES user (id), 
     FOREIGN KEY(modified_user_id) REFERENCES user (id), 
     FOREIGN KEY(machine_id) REFERENCES machine (id)
)

CREATE TABLE watch (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    machine_id INTEGER NOT NULL, 
    created_user_id INTEGER, 
    modified_user_id INTEGER, 
    name VARCHAR(256) NOT NULL, 
    plugin VARCHAR(256) NOT NULL, 
    plugin_selector TEXT NOT NULL, 
    continuation_count INTEGER, 
    prohibition_period INTEGER, 
    warning_value TEXT, 
    is_warning_percentage BOOL, 
    is_warning_script BOOL, 
    warning_script TEXT, 
    is_warning_mail BOOL, 
    warning_mail_body TEXT, 
    failure_value TEXT, 
    is_failure_percentage BOOL, 
    is_failure_script BOOL, 
    failure_script TEXT, 
    is_failure_mail BOOL, 
    failure_mail_body TEXT, 
    is_okay_script BOOL, 
    okay_script TEXT, 
    is_okay_mail BOOL, 
    okay_mail_body TEXT, 
    notify_mail_to TEXT, 
    notify_mail_from TEXT, 
    karesansui_version VARCHAR(12) NOT NULL, 
    collectd_version VARCHAR(12) NOT NULL, 
    is_deleted BOOL, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id), 
     FOREIGN KEY(machine_id) REFERENCES machine (id), 
     FOREIGN KEY(created_user_id) REFERENCES user (id), 
     FOREIGN KEY(modified_user_id) REFERENCES user (id)
)

CREATE TABLE machine2jobgroup (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    machine_id INTEGER, 
    jobgroup_id INTEGER NOT NULL, 
    uniq_key VARCHAR(36) NOT NULL, 
    created_user_id INTEGER, 
    modified_user_id INTEGER, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id), 
     FOREIGN KEY(machine_id) REFERENCES machine (id), 
     FOREIGN KEY(created_user_id) REFERENCES user (id), 
     FOREIGN KEY(modified_user_id) REFERENCES user (id)
)

Pysilhouetteデータベースは以下のSQL文で構築することが出来ます。¶

CREATE TABLE jobgroup (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    name VARCHAR(512) NOT NULL, 
    uniq_key VARCHAR(36) NOT NULL, 
    finish_command VARCHAR(1024), 
    type INTEGER NOT NULL, 
    status VARCHAR(3) NOT NULL, 
    register VARCHAR(32), 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id)
)

CREATE TABLE job (
    id INTEGER NOT NULL AUTO_INCREMENT, 
    jobgroup_id INTEGER NOT NULL, 
    name VARCHAR(32) NOT NULL, 
    `order` INTEGER NOT NULL, 
    action_command VARCHAR(1024) NOT NULL, 
    rollback_command VARCHAR(1024), 
    status VARCHAR(3) NOT NULL, 
    action_exit_code INTEGER, 
    action_stdout TEXT, 
    action_stderr TEXT, 
    rollback_exit_code INTEGER, 
    rollback_stdout TEXT, 
    rollback_stderr TEXT, 
    progress INTEGER NOT NULL, 
    created DATETIME, 
    modified DATETIME, 
    PRIMARY KEY (id), 
     FOREIGN KEY(jobgroup_id) REFERENCES jobgroup (id)
)

初期値の入力¶

デーブルの作成ができたらKaresansuiデータベースに初期値を入力します。
Pysilhouetteデータベースは空のままで構いません。

user¶

INSERT INTO user (email, password, salt, nickname, languages, created, modified) VALUES ([ログイン用メールアドレス], [パスワード], [salt], [表示名], [言語], [現在時刻], [現在時刻])

ログイン用メールアドレス：Basic認証でのログインID（例：hoge@example.com）
パスワード：パスワードとslatを足した文字列をSHA1でハッシュ化した文字列（sha1(pass+salt)）（例：4132395efd6b67d5cad0ea0f514a664ae8a2a82c）
salt：パスワードハッシュを作る際に加える文字列（例：vRsiQo7PaprZAro9）
表示名：画面に表示されるユーザ名（例：Administrator）
言語：ja_JPもしくはen_US
現在時刻の例：2010-1-2 03:04:05.678901

tag¶

INSERT INTO tag (name, created, modified) VALUES (default, [現在時刻], [現在時刻])

現在時刻の例：2010-1-2 03:04:05.678901

notebook¶

INSERT INTO notebook (title, value, created, modified) VALUES ("", "", [現在時刻], [現在時刻])

現在時刻の例：2010-1-2 03:04:05.678901

machine¶

INSERT INTO machine (parent_id, notebook_id, created_user_id, modified_user_id, uniq_key, name, attribute, hypervisor, hostname, icon, is_deleted, created, modified) VALUES ("", 1, 1, 1, [UUID], [ホスト名], 0, 0, [ホスト名], icon-guest1.png, 0, [現在時刻], [現在時刻])

UUID：ユニークなUUID（例：d6886345-62b6-4fa5-b445-d5891f734e3c）
ホスト名：ホストOSのホスト名

machine2tag¶

INSERT INTO machine2tag (tag_id, machine_id, created, modified) VALUES (1, 1, [現在時刻], [現在時刻])

現在時刻の例：2010-1-2 03:04:05.678901

エラーが発生した場合には？¶

アプリケーションエラーについて¶

KaresansuiはRESTfulアーキテクチャ(オーバーライドPOST対応)を採用しているため、管理画面のエラーはすべてHTTPレスポンスコードで判断されます。

以下に使用しているレスポンスコードの一部を記載します。

 - 2xx : 正常に処理が終了した際に使用されるHTTPレスポンスコードです。
   - Karesansuiでは、正常な動作になります。

 - 3xx : リクエストの転送に使用されるHTTPレスポンスコードです。
   - Karesansuiでは、正常な動作になります。

 - 4xx : クライアント(主にブラウザ)からのリクエストに問題があった場合に使用されるHTTPレスポンスコードです。
   - Karesansuiでは、主に不正なリクエストや存在しないURLアクセス時に使用されます。

 - 5xx : サーバーエラー時に使用されるHTTPレスポンスコードです。
   - Karesansuiでのエラーになりますので、エラーを解決する必要があります。

カーネルイメージ・initrdイメージってなに？¶

概要¶

ゲストの作成画面で入力をするカーネルイメージ・initrdイメージですが、よくわからないという方も多いと思います。
以下に簡単な説明とインストール検証済みディストリビューションの入力例を記載しておきます。

カーネルイメージ¶

カーネルイメージとはその名の通りLinuxカーネル本体です。
今回入力で利用するカーネルイメージは初期インストール時のブート(テキストベースのインストール前作業)に利用されます。

initrdイメージ¶

initrdとは、Linuxがブートする際に、一時利用されるファイルシステムのイメージを指します。
今回入力で利用するカーネルイメージは「カーネルイメージ」でブートした際に利用されます。

入力例¶

CentOS5.3¶

カーネルイメージ
http://<ミラーサーバー>/Linux/centos/5.3/os/i386/images/xen/initrd.img

initrdイメージ
http://<ミラーサーバー>/Linux/centos/5.3/os/i386/images/xen/vmlinuz

ヒント
ゲストインストール時に必要なインストールイメージパス例
http://<ミラーサーバー>/Linux/centos/5.3/os/i386/

Fedora10¶

カーネルイメージ
http://<ミラーサーバー>/Linux/fedora/releases/10/Fedora/i386/os/images/pxeboot/initrd-PAE.img

initrdイメージ
http://<ミラーサーバー>/Linux/fedora/releases/10/Fedora/i386/os/images/pxeboot/vmlinuz-PAE

ヒント
ゲストインストール時に必要なインストールイメージパス例
「http://<ミラーサーバー>/Linux/fedora/releases/10/Fedora/i386/os/」　です。

補足
Fedora 11 previewもインストール可能なことを確認しています。

初期値を変更したい場合には？¶

Karesansuiは、設定ファイルと定数ファイルで初期値等を決めています。

設定ファイルについて¶

設定ファイルの説明はこちらです

定数ファイルについて¶

パッケージでインストールした場合は、「/opt/karesansui/lib/python/karesansui/lib/const.py」に配置されています。
さまざまな設定がありますが、よく使う設定を１つ紹介します。

1. ゲストOS追加時に設定される、コンソール(VNC)のキーボード配列を変更したい場合は、DEFAULT_KEYMAPを変更します。

注）設定後はウェブサーバーを再起動してください。

インストールしたゲストのイメージファイルはどこにあるの？¶

概要¶

Karesansuiを利用してゲストを作成した場合、特定のディレクトリに保存・管理されています。

前提条件¶

パッケージインストールを行っている場合

配置パス¶

ヒント¶

ゲストのバックアップが必要な場合は、上記をバックアップすることで最低限のバックアップが可能です。
注)Karesansuiのバックアップは含みません。

ログをカスタマイズするには？¶

■ログの設定
インストールパッケージを使ってインストールをした場合、「/etc/opt/karesansui/log.conf(以後log.conf)」ファイルにログの設定がされています。

設定方法はPython logging 　を参照ください。

ログ関連のFAQは こちらから

複数ホスト構成にするには？¶

前提条件¶

1. MySQLやPostgreSQLといったネットワーク接続に対応したデータベースで運用されていること。
2. 注）SQLiteでは複数のホストを管理することができません。

新たに物理マシンを追加する手順¶

説明で利用する単語¶

1. ホストA = 既存のホスト(Karesansuiは導入済み)
2. ホストB = 新たに追加したいホスト

Step 1. 追加したいKaresansuiアプリケーションのバージョン情報を調べる¶

ホストAのKaresansuiにアクセスし、ヘッダーの「オプション」「Karesansui について」画面を表示し、バージョン情報を取得します。

Step 2. ホストBにKaresansuiをインストールする¶

Step 1で調べたバージョンと同じKaresansuiをダウンロードし、インストールを行います。

注）ホストBのデータベースは、ホストAと同じデータベースを指定し、「データーベースを初期化する」のチェックボックスを外します。

Step 3. ホストBのKaresansuiユニークキーを調べる¶

/etc/opt/karesansui/application.conf ファイルの application.uniqkey がホストBのユニークキーになります。 Step4で使用しますのでメモしておいてください。 設定されている値 例) application.uniqkey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Step 4. ホストAの既存KaresansuiにホストBを追加する¶

ホストAの管理画面にアクセスし、トップ画面にある「追加」アクションを押下します。 ホストの追加画面で、入力項目を入力し「追加」を押下します。

入力項目の補足 : 
- ホスト名(必須) : 管理画面に表示するホスト名です。特に指定はありませんので、わかりやすい名前を入力してください。
            例）ホストB

- FQDN(必須) : ホストBにアクセスできるFQDN・ドメイン名またはIPアドレスを入力します。
           例）hostb.karesansui-project.info or 192.168.0.1

- UUID(必須) : Step 3で調べたユニークキーを入力します。
- ノート(任意) : メモ書きです。
- タグ(任意) : カンマ区切りでタグを入力します。

Step 5. テスト¶

ホストAの管理画面にアクセスし、Step 4で追加したホストBのアイコン(通常は N/Aアイコンが表示されています。)を選択し、詳細を表示させます。

「その他の情報」「ホストのトップページへのリンク」のリンクをクリックし、ホストの移動を行います。

注）この際、再度Basic認証ダイアログが表示されることがあります。

移動後、ヘッダーのホスト名がホストBのものになっていればホストの追加は完了です。※A

※A : 画像の右がホスト名になります。

補足　: ホストBアイコンについては、ホストBへ移動後、「編集」アクションから変更することができます

HOWTO一覧¶

• 複数ホスト構成にするには？
• ログをカスタマイズするには？
• エラーが発生した場合には？
• 初期値を変更したい場合には？
• カーネルイメージ・initrdイメージってなに？
• インストールしたゲストのイメージファイルはどこにあるの？
• 手動でデータベースを作るには？

ライセンスについて¶

Karesansuiの一部はLGPL、一部はGPLです。 コア部分のソースコードは利用制約の少ないLGPLライセンスを採用していますので、 再利用時のライセンスによる問題を軽減します。
すべてのソースコードにライセンスが明記されていますので、迷うことなく利用することができるはずです。

ただし、例外としていくつかのファイルには技術的な問題でライセンス表記をしていません。

ソースツリーに含まれるtemplate/default/include以下のファイルはLGPLです。その他のtemplate/default以下のファイルはGPLです。

これは、あなたがあなたの書いたオリジナルのファイルをtemplate/defaultにファイルを置く場合GPLを付さないといけないということは意味しません。また、template/default/includeにファイルを置く場合はLGPLを付さないといけないということは意味しません。

また、template/defaultやtemplate/default/includeに誰かがファイルを置き、それがライセンス表記されていなかったら、GPLやLGPLが付されたということにはなりません。

私たちは私たちが配布しているファイルについてのみ言及することができますので、それ以外のファイルについては著作者に問い合わせてください。

ソースツリーはKaresansui以外のオープンソースプロジェクトの成果物を含んでいます。それらはKaresansuiとは異なるライセンスポリシーで配布されていることがあるので、それぞれのライセンス表記をご確認下さい。

ジョブマネージャー (pysilhouette)¶

概要¶

Karesansuiで実行される更新系処理のほとんどはジョブマネジャーを経由して実行されます。
Karesansuiは、 Pysilhouette を採用しています。

Pysilhouetteとは¶

逐次的に登録されたジョブ(コマンド)を実行する機能を有するジョブマネジャーです。
並列処理にも対応しました。(Since 0.7.0)
主にウェブアプリケーションのバックグラウンド処理を実現するために開発されています。

Pysilhouetteの特徴¶

• 100% Pure Pythonで開発されているアプリケーションです。
• シンプルな監視機能を有し、信頼性を向上させています。
• ジョブグループ単位で実行されそのなかで複数のジョブを実行することができます。
• 各ジョブ単位でロールバック処理を追加することができます。
• 複数のデータベースをサポートしています。

※ PysilhouetteはKaresansui Projectによって運営/管理されています。

説明の前に¶

Karesanuiパッケージに含まれるPysilhouetteを想定して説明します。

各種設定について¶

Comming soon.

サービスの起動停止方法¶

こちらを参照してください。

ログ出力¶

Pysilhouetteのログは5つで構成されています。

pysilhouette全体のログ : /var/log/pysilhouette/application.log

pysilhouetteで発生したエラーのプログラムトレースログ : /var/log/pysilhouette/error.log

pysilhouetteが発行したSQL関連のログ : /var/log/pysilhouette/sql.log

pysilhouetteサービスが出力する標準エラー出力ログ : /var/log/pysilhouette/stderr.log

pysilhouetteサービスが出力する標準出力ログ : /var/log/pysilhouette/stdout.log

直接更新系処理を行わない理由¶

ウェブサービスに必要以上の権限を付加することによるセキュリティリスクを考慮したためです。

リファレンス
必要な環境
機能一覧
画面構成
ソースのダウンロード方法
設定ファイルについて
トラブルシューティング
ゲストOSのインポート・エクスポート
監視
ストレージプール
E-R図¶

ソースのダウンロード方法¶

Karesansuiのソースコードを取得するには、いくつかの方法があります。

sourceforge.jpからダウンロード¶

ソースコードは、Karesansuiのインストールパック(tarball)の中に、RPMパッケージとしても提供されています。
Karesansuiのインストールパックは、ダウンロードページ から最新のKaresansui-x.x.tar.gz を選択してダウンロードできます。

gitリポジトリからダウンロード¶

最新のソースコードは、sourceforge.jpのgitリポジトリから取り寄せることもできます。
gitがインストールされていない場合は、あらかじめgitをインストールした後、以下のコマンドでダウンロードすることができます。

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

E-R図¶

Karesansui¶

Karesansui E-R Diagram : http://karesansui-project.info/2.0.0/er/karesansui/

機能一覧¶

※Karesansuiでは仮想マシンを立ち上げるサーバーのことを「ホスト」、ホスト上で動作する仮想マシンのことを「ゲスト」と呼びます。

※１ : ゲートウェイ、FQDN、DNS、各イーサネットのIPアドレス等の編集が行えます。
※２ : 以下の利用方法をご利用できます。
・ 任意のディレクトリをストレージプールにすることが可能です。
・ iSCSIを任意のディレクトリにマウントした先をストレージプールにすることも可能です。
・ iSCSIをBlockデバイスとして利用することも可能です。
※３ : CHAP認証に対応しています。
※４ : 一部サービスについては、閲覧のみに制限されています。
※５ : 詳細はこちらへTODO
※６ : 詳細はこちらへTODO

戻る

ゲストOSのインポート・エクスポート¶

概要¶

ある時点のゲストOSをバックアップすることができます。
※データベース情報、設定ファイル、OSイメージ、ディスクイメージなどのすべてを含みます。
※ストレージに、エクスポート元のデータサイズと同一の空き容量が必要です。

コピーとの違い¶

別サーバーへの移動手順¶

エクスポートされた情報は、他のKaresansui サーバーでインポートさせることが可能です。
エクスポートデータは、エクスポート時に選択したディレクトリにまとまって置かれています。

下記の例を参考に説明します。

ゲストOS情報

1. ゲストOS名 : hoge
2. OSイメージが置かれているPool名 : default
3. OSイメージが置かれているPoolパス : /var/opt/hde/libvirt/domains
4. exportされたPool名 : export
5. Poolディレクトリパス : /var/opt/hde/libvirt/export

エクスポートしたディレクトリ構成

[root@kss25 export]# tree /var/opt/hde/libvirt/export/
.
|-- 23896700-2abc-13dd-7ae5-2772bd28537a # Export UUIDになります。※エクスポートを一意に識別するキーになります。
|   |-- disk # ゲストOSで追加ディスクされたディスクが置かれるディレクトリです。
|   |   `-- disk # ゲストOSで追加ディスクされたディスクのストレージプール名です。
|   |       `-- hoge # ゲストOSのドメイン名です。
|   |           `-- disk
|   |               `-- 359be9c7-7cea-166f-c926-5ff6acb29875.img # ディスクイメージ
|   |-- domain # ゲストOSのディスクイメージが置かれるディレクトリです。
|   |   `-- hoge # ゲストOSのドメイン名です。
|   |       `-- images
|   |           `-- hoge.img # OSイメージ
|   |-- hoge.conf # xenで利用する設定ファイルです。
|   |-- hoge.xml # Karesansuiで利用する設定ファイルです。
|   `-- info.dat # エクスポートデータです。
`-- 23896700-2abc-13dd-7ae5-2772bd28537a-hoge.img -> /var/opt/hde/libvirt/export/23896700-2abc-13dd-7ae5-2772bd28537a/domain/hoge/images/hoge.img # エクスポートデータのシンボリックリンクです。※ストレージプールの自動認識に利用します。

上記のexportディレクトリにある「23896700-2abc-13dd-7ae5-2772bd28537a-hoge.img(シンボリックリンク)」と「23896700-2abc-13dd-7ae5-2772bd28537a(ディレクトリごと)」を移動したいサーバーへコピー※１します。

移動後、管理画面(ゲスト一覧画面)に移動したエクスポートが表示されますので、通常通りインポートします。

※1 移動先では、ゲストOS情報の2, 3,4, 5 すべてが完全に一致している必要がありますので、移動先でストレージプール等を作成している必要があります。上記の場合ですと、default、export、diskの３つのストレージプールが移動先に存在している必要があります。

必要な環境¶

対応ホストOS¶

1. CentOS 5.3以降 32bit/64bit
2. RHEL 5.3以降 32bit/64bit

対応ゲストOS¶

1. Xenの準仮想化に対応しているOSすべて（仮想化ハイパーバイザーがXenの場合）
2. Linux、FreeBSD、OpenSolaris、Windows（仮想化ハイパーバイザーがKVMの場合）

推奨スペック¶

1. CPU : Intel Core 2 Duo以上
2. メモリ : 2GB以上
3. HDD : 100GB以上

データベース¶

1. SQLite3(※マルチホスト非対応)
2. MySQL
3. PostgreSQL
4. その他
   http://www.sqlalchemy.org/docs/05/dbengine.html?highlight=db2#supported-databases

ブラウザ¶

1. Firefox 3以降
2. Safari 3(Mac)以降
3. Opera 9以降
4. Google Chrome

依存関係¶

以下のソフトウェアが不足する可能性がありますので事前にインストールしておく必要があります。

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

# yum install iscsi-initiator-utils
# yum install cyrus-sasl-md5
# yum install qemu
# yum install gnutls-utils
# yum install PyXML
# yum install SDL
# yum install curl
# yum install perl-URI
# yum install perl-HTML-Parser
# yum install gettext

# rpm -ivh iscsi-initiator-utils
# rpm -ivh cyrus-sasl-md5
# rpm -ivh qemu
# rpm -ivh gnutls-utils
# rpm -ivh PyXML
# rpm -ivh SDL
# rpm -ivh curl
# rpm -ivh perl-URI
# rpm -ivh perl-HTML-Parser
# rpm -ivh gettext

画面構成¶

Karesansuiの画面は4つのパーツで構成されています。

A： ヘッダー
B：メイン
C：ドメインツリー
D：ログメッセージ

ヘッダー
¶

A：ロゴ
クリックするとトップページへ移動します。

B：パンくず
KaresansuiはTOP, ホスト、ゲストの3つの画面を遷移して操作します。
この部分には現在どの画面にいるか表示されます。
また、リンクをクリックすることでその画面へ遷移します。

C：ログインユーザ名表示
ログインしているサーバーのホスト名や、ログインしているユーザーのメールアドレスが表示されます。

D：メニュー
ログインしているユーザーの情報を編集したり、Karesansuiからログアウトすることができます。

E：通知アイコン
実行中のジョブがあることや、サーバーとAJAX通信中であることを点滅して示すアイコンです。

メイン
¶

A：タブ

クリックすると、その内容にメイン画面が遷移します。

B：ボタン

クリックすると、追加や変更などを行うことができます。
暗い色になっているボタンは押しても実行することができません。

C：タグ

ホスト一覧やゲスト一覧の画面に表示されます。ホストやゲストに登録されたタグを使って
アイコンの表示を絞り込むことができます。

D：ホスト（ゲスト）アイコン

一度目のクリックで下の詳細表示画面に詳細が表示されます。
その際、背景に緑色の枠が表示されます。
二度目のクリックで選択したホスト（ゲスト）の画面に遷移します。
ホスト（ゲスト）の編集で、表示するアイコンを変更することができます。

E：詳細表示

ジョブの登録者や登録時間、ホストのメモリ総量やディスク使用量など、細かい情報を表示します。

F：更新アイコン

クリックすると、メイン画面の内容を更新します。

ドメインツリー
¶

A：ツリー
ホストと、その上に作られているゲストをツリー状に表示します。
各リンクをクリックすることでそのホストやゲストの画面に遷移します。
また、ホストの横にある▼のアイコンを押すことで開閉することができます。

B：更新アイコン
クリックするとツリーの内容を更新します。

ログメッセージ
¶

A：ログメッセージ
直近5件のジョブの進捗や結果などの情報を表示します。
各ログメッセージをクリックすることでそのホストやゲストの詳細ジョブ画面に遷移します。

B：更新アイコン
クリックするとログメッセージの内容を更新します。

設定ファイル(log.conf)の説明¶

FAQを参照

application.confの説明¶

application.search.path¶

Pythonの追加サーチパスを設定します。
※複数指定する場合はカンマ(,)で区切ります

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

application.log.config¶

ログ出力設定ファイルパスを設定します。
ログ出力設定ファイルついてはこちらを参照してください。

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

application.url.prefix¶

URIのプレフィックスを設定します。
以下の{}内を設定します。
http://example.com{/karesansui/v1}/
※v1はKaresansuiのメジャーバージョンを指定しておくことを推奨します。
※Karesansui 2.0.0で"karesansui/v2/"に変更になりました。(Since 2.0.0)

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

application.default.locale¶

Karesansuiが使用するデフォルトのロケールを設定します。
※現在、ja_JPとen_USに対応しています。
※ログインしている場合は、ログインユーザのロケールが優先されます。

例) application.default.locale=ja_JP

application.template.theme¶

Karesansuiのテーマを設定します。
※初期インストール時はdefaultに設定されています。

例) application.template.theme=default

application.tmp.dir¶

Karesansuiが一時的に作成するファイル等々をおくディレクトリパスを設定します。

例) application.tmp.dir=/tmp

application.bin.dir¶

Karesansuiが使用するジョブコマンドのディレクトリパスを設定します。
※Karesansuiの実行ユーザ権限で書き込みができる必要があります。

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

application.generate.dir¶

各種設定ファイルのテンプレートディレクトリを設定します。

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

application.mail.email¶

Karesansuiで利用するメールアドレスを設定します。

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

application.mail.port¶

Karesansuiで利用するメールサーバのポート番号を設定します。

例) application.mail.port=25

application.mail.server¶

Karesansuiで利用するメールサーバ名を設定します。

例) application.mail.server=localhost

application.proxy.status¶

Karesansuiでプロキシサーバを利用するかを設定します。
1=有効
0=無効

例)application.proxy.status=0

application.proxy.server¶

Karesansuiで利用するプロキシサーバ名を設定します。

例) application.proxy.server=localhost

application.proxy.port¶

Karesansuiで利用するプロキシサーバのポート番号を設定します。

例) application.proxy.port=9080

application.proxy.user¶

Karesansuiで利用するプロキシサーバにログインするユーザ名を設定します。

例) application.proxy.user=bar

application.proxy.password¶

Karesansuiで利用するプロキシサーバにログインするパスワードを設定します。

例)application.proxy.password=foo

lighttpd.etc.dir¶

KaresansuiをLighttpdで動作させる場合に利用する設定ファイルを置くディレクトリを設定します。

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

database.bind¶

Karesansuiで利用するデータベースのバインドを設定します。
RFC-1738で定義されているスタイルで設定してください。
さらに詳しい設定についてはSQLAlchemyのサポートデータベース を参照してください。

MySQL
mysql://localhost/<データベース名>
mysql://<ユーザ名>:<パスワード>@<ホスト名>/<データベース名>
mysql://<ユーザ名>:<パスワード>@<ホスト名>:<ポート番号>/<データベース名>
PostgreSQL
postgres://<ユーザ名>:<パスワード>@<ホスト名>:<ポート番号>/<データベース名>
SQLite※Karesansuiの実行権限で読み取り・書き込み可能である必要があります。
sqlite:////<絶対パス>/<ファイル名>-絶対パスで定義
sqlite:///<相対パス>/<ファイル名>-相対パスで定義
例) database.bind=sqlite:////var/opt/karesansui/karesansui.db

database.pool.status¶

コネクションプールの利用可否を設定します。
0=利用しない
1=利用する

例)database.pool.status=0

database.pool.size¶

通常時のコネクションプール数を設定します。
※SQLiteでは利用できません。設定は無視されます。

例)database.pool.size=1

database.pool.max.overflow¶

コネクションプールの最大数を設定します。

例)database.pool.max.overflow=10

pysilhouette.conf.path¶

Karesansuiで使用するPysilhouetteソフトウェアの設定ファイルパスを設定します。
※Karesansuiの実行ユーザ権限で読み取り可能である必要があります。(書き込み・実行権限は必要ありません。)

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

application.updater.yum.cachedir¶

Karesansuiが利用するyumのキャッシュディレクトリを設定します。
注)wwwhde(hde-lighttpdサービス)ユーザの書き込み権限が必要です。

例)application.updater.yum.cachedir=/var/opt/karesansui/cache/yum

application.updater.yum.log.file¶

Karesansui経由で実行されたyumのログファイルを設定します。

例)application.updater.yum.log.file=/var/log/karesansui/yum.log

application.updater.yum.target.repos¶

Karesansui用のyumリポジトリ名を設定します。

例)application.updater.yum.target.repos=karesansui-base

ストレージプールについて¶

ストレージプールとは¶

ストレージを利用する際に、ディレクトリ、ファイルシステム、NFS、i-SCSIといった様々なアクセス手段で利用しますが、ストレージプールはそのアクセス手段を抽象化、隠蔽化する概念です。

抽象化、隠蔽化するメリット¶

アクセス手段を、すべてストレージプールで隠蔽することで、利用はその内部を知ることなく利用することが可能になります。

ストレージボリュームとは¶

利用者が利用出来るストレージの最小単位で、利用者はボリューム単位でゲストOSなどにストレージを割り当てる事ができます。

※実際は、イメージファイル/ブロックデバイス等になります。

Karesansui がサポートするストレージタイプについて¶

タイプ : ディレクトリ(dir)¶

タイプ : iSCSI(iscsi)¶

タイプ : ファイルシステム(fs)¶

※iSCSI連携のみ対応

Coming soon.¶

仮想化サーバー監視とは¶

• 仮想化サーバー監視とは
• システム構成
• collectdの特徴
• 監視で使われる設定ファイルについて
• 設定変更不可データ
• 設定変更可能データ
• デフォルトで有効可能になっているプラグイン一覧
• しきい値を超えた時の挙動について
• アクションコマンドについて
• 通知メールのカスタマイズについて

Karesansuiでは、collected( http://collectd.org/ )を利用しホストOSのシステムリソース監視とゲストOSの監視に重点をおいたサーバー監視を行ないます。

システム構成¶

collectdの特徴¶

collectdはシステムの様々な状態を収集する非常に小さなデーモンプログラムです。
UNIX上で動作し、ライセンスはGPLv2となっています。
本体がC言語で書かれた小さなデーモンプログラムのみで構成されており、システムに掛かる負荷が非常に少ないのが特徴です。
また、各種のデータの収集、記録などは、全てプラグインで追加していく形になっています。

各機能を使うためのプラグインも充実しており、あらかじめ90種類以上用意されています。

※Karesansui UIからは追加できませんが、任意のプラグイン設置も可能です。

CPUやネットワークトラフィックなど基本的なものから、Apacheの情報やSNMPなど、様々な情報を取得することができます。
さらに、自前でプラグインを作成するための言語バインディングも用意されているので、自分で好きな情報を集めるプラグインを作ることができます。

収集したデータの出力はRRD形式やCSV形式などがあります。KaresansuiではRRD形式を採用し収集データを行ないます。
また、収集したデータを別のサーバに送信する機能を持ったプラグインもあり、複数のサーバの情報を一箇所に集めることもできます。

※Karesansuiへの取り込みが検討されています。

その他に、collectdには値の収集/保存のほかにも、しきい値を利用したアラート機能があります。

Karesansui ではそれら機能を利用し、予めしきい値などの条件を設定しておき、条件に当てはまった場合に任意のスクリプトを実行したり、通知メールを送信する機能が実装されています。
この機能を利用することで、サーバの状態監視を自動化することができ、運用コストを劇的に軽減させることができます。

最後に、collectdはあくまでも値の収集や監視が目的なので、収集した値を見るためのインタフェースは提供されていません。
そこで、Karesansuiではシンプルで美しいレポート機能を実現しました。

監視で使われる設定ファイルについて¶

collectd本体の設定ファイル : /etc/opt/hde/collectd.conf
各種プラグインの設定ファイル : /etc/opt/hde/collectd.d/*

RRD形式のデータ保存について
 - rrdchachedサービス(デーモン)経由で、/var/opt/hde/collectd/配下に保存されます。

設定変更不可データ¶

本体設定

収集間隔：10秒

設定変更可能データ¶

本体設定

読み込みスレッド数：5

デフォルトで有効可能になっているプラグイン一覧¶

 - 収集データ：CPUのアイドル時間など
 - 収集対象　：搭載されている全てのCPU(論理CPU数ごとに収集)

 - 収集データ：メモリの使用量など
 - 収集対象　：搭載されているメモリ

 - 収集データ：ファイルシステムの使用量と空き容量(dfコマンドの結果と同等)
 - 収集対象　：全て(dfコマンドで表示されるファイルシステム)

 - 収集データ：時間当たりの読み込み/書き込みデータ量など
 - 収集対象　："/^(([hs]|xv)d[a-f][0-9]?|([a-z]+\/)?c[0-9]d[0-9](p[0-9])?)$/" 

 - 収集データ：時間当たりの送信/受信パケット数など
 - 収集対象　：全てのNIC

 - 収集データ：ロードアベレージ
 - 収集対象　：collectdが動作しているマシン

 - 収集データ：起動時間
 - 収集対象　：collectdが動作しているマシン

 - 収集データ：ユーザ数
 - 収集対象　：collectdが動作しているマシン

 - 収集データ：仮想マシンのCPU、ディスク、ネットワークに関するデータ
 - 収集対象　：全てのゲストOS

syslogにcollectdのログを出力します。

 - ログレベル：info
 - ログの出力先：/var/log/hde-collectd/collectd.log

pythonで書かれたプラグインを動作させます。

RRD形式で収集したデータをrrdchachedサービス(デーモン)経由で保存します。
 - RRDファイルの保存先：/var/opt/hde/collectd

しきい値を超えた時の挙動について¶

アクションには３つの場合があります。

1. 警告のしきい値を超えた場合
　- 警告しきい値を超えた場合に、任意のスクリプトの実行及び通知メールの送信が可能です。

2. 危険のしきい値を超えた場合
　- 危険しきい値を超えた場合に、任意のスクリプトの実行及び通知メールの送信が可能です。

3. 正常値へしきい値を戻った場合
　- 正常値へしきい値が戻った場合、任意のスクリプトの実行及び通知メールの送信が可能です。

アクションコマンドについて¶

karesansuiはcollectdから呼ばれるコマンドだけ提供してます。
collectdから見ると、karesansuiは閾値を超えたときに呼ぶpythonプログラムのみを提供します。

このpythonプログラムがcollectdから渡されるデータから状況を判断し、任意のスクリプト実行や通知メールを送信します。
※Karesansui データベースと連携していますので、データベースが必須になります。

テーブル名 : watch

通知メールのカスタマイズについて¶

通知メールには、Karesansui固有の変数を利用して、データの差し込みをすることができます。
※メールヘッダと本文の間には空行を一つ以上入れてください。
※変数とは : 送信されるメール内で文字列の置き換えが行われます

チュートリアル¶

1. 目次¶

• チュートリアル
• 1. 目次
• 2. はじめに
• 3. 概念図
• 4. CentOS 5.5 64bitの場合
• 4.1. 事前に
• 4.2. Karesansuiのインストール
• 4.3. ゲストの作成
• 4.4. 最後に
• 5. Red Hat Enterprise Linux 5.5 64bitの場合
• 5.1. 事前に
• 5.2. Karesansuiのインストール
• 5.3. ゲストの作成
• 5.4. 最後に

2. はじめに¶

このチュートリアルでは、パッケージング済みのKaresansuiを利用したインストールから、実際にゲスト上にOSインストールし動作させるまでを紹介します。

3. 概念図¶

4. CentOS 5.5 64bitの場合¶

ホスト、ゲストともにCentOS 5.5 64bitを用いたときのチュートリアルです。

4.1. 事前に¶

4.1.1. ホストOSのインストール

CentOS 5.5以降のISOイメージを利用しホストOSを作成します。

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

(必須) ソフトウェアのセットアップで「仮想化」「KVM」にチェックを入れてください。
(必須ではありません) ストレージ拡張を容易に行えるため、LVMを利用することを推奨しています。
注）デフォルトパーティションを利用するとデフォルトでLVMになります。

4.2. Karesansuiのインストール¶

4.2.1. インストール前準備

Karesansuiは、これらのインストールパッケージと依存関係があります。別途インストールする必要があります。

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

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

SQLite以外のデータベースを利用する場合、Pythonのデータベースドライバが必要です。

その他のデータベース
http://www.sqlalchemy.org/docs/05/dbengine.html?highlight=db2#supported-databases

インストーラーには現在含まれていないので、yumやeasy_installなどで事前にインストールしてください。
karesansui-projectが用意したrpmが以下から取得可能ですので、こちらを使ってインストールも可能です。
※ベーシック認証がかけられています。
id : karesansui
pass : karesansui

4.2.2. ダウンロード

ダウンロードページ から最新のkaresansui-2.0.x-install-pack.tar.gzをダウンロードします。

sourceforge.jpのダウンロードページ

4.2.3. インストール

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

インストールスクリプト実行後の画面の流れは下記の通りです。

4.2.4. 「ようこそ」画面

「OK」ボタンを押して、そのまま次の画面へ進みます。

4.2.5. 「管理者の設定」画面

Karesansuiの管理画面にログインする管理者の設定を行います。各項目の説明は下記の通りです。

4.2.6. 「鍵と証明書の設定」画面

Karesansuiで使用する仮想マシン制御の抽象化サービス(libvirt)にSSL接続するための鍵と証明書の設定を行います。
各項目の説明は下記の通りです。

4.2.7. 「データベース設定」画面

Karesansuiが利用するデータベースに関する設定を行います。

MySQLやPostgreSQLを利用する場合は、あらかじめデータベースを作成し、ホストOSから接続可能なことを確認してください。

データベースパスの指定方法は、下記の通りです。

4.2.8. 「プロキシ設定」画面

インターネットへアクセスするためのHTTPプロキシ設定を行います。

4.2.9. 「メールの設定」画面

通知メールなどのメールの送信に利用するSMTPサーバーに関する設定を行います。

4.2.10. 「確認」画面

インストールを続行したい場合は、「OK」を押し、ソフトウェアのインストールを始めます。
これまでの入力に誤りがある場合やインストールを中断したい場合は、「戻る」、「取り消し」を押してください。

4.2.11. 「進捗」画面

ソフトウェアのインストールの進捗状況が表示されます。
ソフトウェアのインストール、鍵・証明書の生成、設定ファイルの書き込み、データベースの初期化、サービスの有効化 の順に進捗します。

4.2.12. 「完了」画面

インストールが正常に完了すると、下記画面のようにメッセージが表示されます。
インストールの途中でエラーになると、エラー原因のメッセージが表示されます。エラーメッセージはインストールログにも出力されますので、ログを確認した後、エラー原因を解消し再度インストールを行ってください。

終了しました。
下記サイトにアクセスしログインしてください。ログインIDは'taizo@karesansui-project.info'です。
 https://karesansui.example.com/karesansui/v2/
 http://karesansui.example.com/karesansui/v2/
詳細は、/root/karesansui-install.log を参照してください。

# /etc/init.d/network restart

4.2.13. 管理画面の確認

インストール完了後に表示された 'https://{ホスト名}/karesansui/v2/' に接続すると、認証ダイアログが表示されますので、インストール時に指定した管理者のメールアドレスとパスワードを入力します。

認証をパスして、以下のような画面が表示されればインストールは成功です。

4.3. ゲストの作成¶

4.3.1. ゲストのOSインストール準備

以降は、ゲストに CentOS 5.5(i386) をインストールする場合を例に、２通りの方法を説明します。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

ホストOSが既にインターネットに繋がっている場合は、外部サーバー上にある、カーネルイメージ、および、OSイメージを取得してインストールを行います。プロキシサーバー経由でのインストールはできませんので、その場合はFTPサーバーを利用してください。

http://<OSイメージ配布サイトのFQDN>/Linux/centos/5/os/i386/
ftp://<OSイメージ配布サイトのFQDN>/Linux/centos/5/os/i386/

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

ホストOSがインターネットに繋がっていない場合は、CentOS 5.5(i386)のDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

KVMを仮想化ハイパーバイザーに利用している場合は、OSインストールDVDのISOイメージからインストールすることも可能です。

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

4.3.2 ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法を、前述のインストールのタイプごとに示します。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のCentOS 5.5 のOSインストールと同じようにゲスト上にOSをインストールすることができます。

1. 既にインターネットに繋がる環境の場合（ネットワークインストール）

OSインストール時の「Installation Method」の選択では前述のカーネルイメージで指定したプロトコル（「HTTP」または「FTP」）を選択し、「HTTP」の場合は「HTTP Setup」、「FTP」の場合は「FTP Setup」で接続先を設定してください。

2. インターネットに繋がらない環境の場合（ローカルインストール/CD-ROM）

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

3. インターネットに繋がらない環境の場合（ローカルインストール/ISOイメージ）

「Installation Method」の選択の必要はありません。

4.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

その他の注意点

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

5. Red Hat Enterprise Linux 5.5 64bitの場合¶

ホスト、ゲストともにRed Hat Enterprise Linux 5.5 64bit( 以下、RHEL 5.5(64bit) )を用いたときのチュートリアルです。

5.1. 事前に¶

ホストOSのインストール

通常のインストール手順で問題ありませんが、以下の点に気をつけてインストールしてください。

# yum install kvm

5.2. Karesansuiのインストール¶

Karesansuiのインストールは、CentOS 5.5の場合と同じです。
CentOS 5.5のチュートリアル を参照してください。

5.3. ゲストの作成¶

5.3.1. ゲストのOSインストール準備

RHEL 5.5(64bit)のDVDを利用してインストールを行います。その際、一時的にホストOS上にFTPサーバーを稼働させる必要がありますので、vsftpd等のFTPサーバーソフトウェアをあらかじめインストールしておきます。

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

# 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

# echo 0 >/selinux/enforce

5.3.2. ゲストへのOSインストール

まず、Karesansuiのトップ画面のホストアイコンをクリックします。
その後、表示される「ゲスト一覧」タブ内の「作成」ボタンをクリックすると以下のような「ゲスト作成」画面が表示されます。

入力方法は、以下の通りです。

その他、各項目の入力方法に関しては、項目名の右に表示される「？」をクリックして確認してください。

全ての入力が完了したら、「ゲスト作成」画面の最下部にある「作成」ボタンをクリックしてください。
クリック後、ゲスト作成のジョブを受理した旨のメッセージが表示されますので、「閉じる」ボタンで「ゲスト作成」画面を閉じます。

その後表示されるゲスト一覧画面に、今作成したゲストのアイコンが追加されます。

作成されたゲストのアイコンをクリックし、その後表示されるゲスト画面の「コンソール」タブをクリックします。
ゲストのコンソール画面が表示され、コンソール画面において通常のRHEL 5.5(64bit)のOSインストールと同じようにゲスト上にOSをインストールすることができます。

OSインストール時の「Installation Method」の選択では「FTP」を選択し、「FTP Setup」で下記のようにFTPの接続先を設定してください。

5.4. 最後に¶

以上で、ゲストにOSをインストールするまでの作業は終了です。
ゲストへのOSインストールが終了したら、ゲスト画面の「サマリ」タブに表示される「開始」「停止」「再起動」ボタンでゲストの起動、シャットダウン、再起動を行うことができます。

その他の注意点

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

アップデート¶

1. 目次¶

• アップデート
• 1. 目次
• 2. Karesansui 1.0.1 からKaresansui 1.0.2へアップデートする場合
• 3. Karesansui 1.0.x からKaresansui 1.1.xへアップデートする手順
• 4. Karesansui 1.1.x からKaresansui 2.0.xへアップデートする手順
• 5. Karesansui 2.0.0 からKaresansui 2.0.xへアップデートする手順

2. Karesansui 1.0.1 からKaresansui 1.0.2へアップデートする場合¶

対象者

利用しているデータベースが、SQLite以外の方が対象です。

影響範囲

ジョブマネージャー(Pysilhouette)全体

今回の不具合について

インストーラーに不具合があり、どのデータベースパスを入力しても、ジョブマネージャー(Pysilhoutte)がSQLiteを選択してしまいます。

その結果、ネットワーク接続に対応していないSQLiteですと、マルチホストに対応することができなくなります。

この不具合の修正版を1.0.2でリリースしましたが、手動で行わなければならない作業がいくつかあります。

以下の手順でアップデートしてください。

1. データベースの作成
移行先のPysilhouetteデーターベースを作成してください。

PostgreSQLの場合
    # createdb -U username -W pysilhouette --encoding=utf8

MySQLの場合
    # mysql -u username -p -e 'CREATE DATABASE pysilhouette DEFAULT CHARACTER SET utf8;'

注意)
UTF-8でデータベースを作成してください。

2. 新パッケージをダウンロードし、伸長する

ダウンロードURL

# rm -rf Karesansui
# tar zxvf karesansui-<バージョン>-install-pack.tar.gz
# cd Karesansui

3. 現在のデータベースパスの確認

現在のPysilhouetteのデータベースパスを取得しておきます。

• 設定ファイルから取得する方法
  /etc/opt/pysilhouette/silhouette.confファイル内の「database.url」の値を取得する。

sqlite:////var/opt/pysilhouette/pysilhouette.db

4. Karesansuiをアップデートする

Karesansuiをアップデートし、Pysilhouetteのデータベースを変更します。
チュートリアル を参考にKaresansuiをアップデートしてください。

# ./karesansui-install

• 「管理者の設定」画面
  「パスワード」を設定し、「OK」を押下します。

• 「データベースの設定」画面
  「データベースを初期化する」のチェックを外し、「pysilhouette データベースパス」に新しく作成したデータベースのパスを設定し、「OK」を押下します。

「データベースを初期化する」のチェックを外してください！
Karesansuiのデータベースが初期化されてしまいます！

• 「確認」画面
  「OK」を押下します。

5. インストールチェック
./karesansui-checkenvを実行しエラーがないか確認します。
また、「データベース pysilhouette に接続できるかをチェック... 」が指定したデータベースパスになっているか確認してください。

# ./karesansui-checkenv

6. データベースの移行
データベースをSQLiteからMySQLまたはPostgreSQLへコピーをします。

# cd /opt/pysilhouette/share/doc/pysilhouette-0.6.2/tool/
# export PYTHONPATH=/opt/hde/lib/python:/opt/karesansui/lib/python:/opt/pysilhouette/lib/python:$PYTHONPATH
# ./sqlite2other.py --input=<移行元データベースパス> --output=<移行先データベースパス>

• --inputに入力するパス取得方法
  「3. 現在のデータベースパスの確認」の手順で確認したパスです。

• --outputに入力するパス取得方法
  • karesansui-checkenvから取得する方法
    karesansui-checkenvで出力された「データベース pysilhouette に接続できるかをチェック... 」に書かれてあるパスを入力します。
  • 設定ファイルから取得する方法
    /etc/opt/pysilhouette/silhouette.confファイル内の「database.url」の値を入力します。

• データベースパスの書式

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

コマンドの実行結果で画面に出力される「copy num」の数値はあとで使用しますので、保管してください。
(copy num - xxx) のxxxの部分
sqlite2other.py は SQLite -> MySQL or PostgreSQLの移行のみサポートしています。

# ./sqlite2other.py --input=sqlite:////var/opt/pysilhouette/pysilhouette.db --output=mysql://username:password@localhost/pysilhouette?charset=utf8
Cleanup Database [OK]
copy num - 3

参考)
データベースパスの書式の詳細な説明は、リファレンス を参考にしてください。

7. 自動インクリメントの変更
Pysilhouetteデータベースの自動インクリメントの値を変更します。
Pysilhouetteデータベースにアクセスして、下記のSQLを実行してください。

SQLの<copy numの数字>の部分は、「4. データベースの移行」の手順で実行した
./sqlite2other.pyで出力されるcopy numの数字に置き換えて実行してください。

PostgreSQLの場合
    select setval('jobgroup_id_seq', <copy numの数字>);
    select setval('job_id_seq', <copy numの数字>);

    例)
    # psql pysilhouette  -U username -h localhost -c "select setval('jobgroup_id_seq', 3);" 
    # psql pysilhouette -U username -h localhost -c "select setval('job_id_seq' 3);" 

MySQLの場合
    ALTER TABLE jobgroup AUTO_INCREMENT = <copy numの数字>;
    ALTER TABLE job AUTO_INCREMENT = <copy numの数字>;

    例)
    # mysql pysilhouette -u username -h localhost -p -e "ALTER TABLE jobgroup AUTO_INCREMENT = 3;" 
    # mysql pysilhouette -u username -h localhost -p -e "ALTER TABLE job AUTO_INCREMENT = 3;" 

# ./sqlite2other.py --input=<移行元データベースパス> --output=<移行先データベースパス>
Cleanup Database [OK]
copy num - 3 <-- 置き換える数字

# /etc/init.d/hde-lighttpd stop
# /etc/init.d/silhouetted restart
# /etc/init.d/hde-lighttpd start

3. Karesansui 1.0.x からKaresansui 1.1.xへアップデートする手順¶

概要
1.1では、ゲストOSの各種データのファイル・ディレクトリ構成が変更されました。下記手順でアップグレードを行うことで、各種ソフトウェアの更新を行うとともに、ファイル・ディレクトリ配置の変換も行います。

なお、アップグレードを行う場合は、重要なデータは別のサーバーへバックアップしてから行うことをお薦めします。

以降では、CentOS 5.3 (i386) を例に説明します。

# /etc/init.d/silhouetted stop
# /etc/init.d/hde-lighttpd stop
# /etc/init.d/hde-libvirtd stop
# /etc/init.d/xend stop

1. ダウンロードした1.1のインストールパックを任意のディレクトリに展開します。

      # tar zxvf karesansui-1.1.0-xxx-install-pack.tar.gz

2. 展開されたインストールパックに含まれるインストーラを実行します。

      # cd Karesansui
      # ./karesansui-install

3. インストーラの案内にしたがって、項目を入力します。

このとき、データベース設定の画面でデーターベース初期化を選択しますと、それまでのデータが消去されてしまいますのでアップグレードを行いたい場合は、選択しないようご注意下さい。

4.インストーラの実行が終了後

各種ソフトウェア更新と既存データの移行は完了です。以下のコマンドで、Karesansuiの実行環境に問題ないか確認してください。

      # ./karesansui-checkenv

4. Karesansui 1.1.x からKaresansui 2.0.xへアップデートする手順¶

概要
2.0では、ゲストOSのイメージデータファイルはlibvirtの機能であるストレージプールへ配置されるように変更されました。下記手順でアップグレードを行うことで、各種ソフトウェアの更新を行うとともに、ファイル・ディレクトリ配置の変換も行います。

なお、アップグレードを行う場合は、重要なデータは別のサーバーへバックアップしてから行うことをお薦めします。

以降では、CentOS 5.4 (x86_64) を例に説明します。

# /opt/hde/bin/virsh shutdown <ゲストOSのドメイン>

# /etc/init.d/silhouetted stop
# /etc/init.d/hde-lighttpd stop
# /etc/init.d/hde-libvirtd stop
# /etc/init.d/xend stop (Xenを利用しているときのみ)

3. ダウンロードした2.0のインストールパックを任意のディレクトリに展開します。

      # tar zxvf karesansui-2.0.0-xxx-install-pack.tar.gz

4. 展開されたインストールパックに含まれるインストーラを実行します。

      # cd Karesansui
      # ./karesansui-install

5. インストーラの案内にしたがって、項目を入力します。

このとき、データベース設定の画面でデーターベース初期化を選択しますと、それまでのデータが消去されてしまいますのでアップグレードを行いたい場合は、選択しないようご注意下さい。
ただし、pysilhouetteの使用するデータベースは、アップグレード時に初期化されますので、必要であればデータベースのバックアップも行ってください。

6.インストーラの実行が終了後

各種ソフトウェア更新と既存データの移行は完了です。以下のコマンドで、Karesansuiの実行環境に問題ないか確認してください。

      # ./karesansui-checkenv

# shutdown -r now

バージョン1.1.xとのファイル・ディレクトリ構成の差分

2.0からゲストOSに使用されるイメージファイルは、ストレージプール上のストレージボリュームとして配置されます。

1. ゲストOSのイメージファイル

1.1 バージョン1.1.xのファイルパス
/var/opt/hde/libvirt/domains/<ドメイン名>/images/<ドメイン名>.img

1.2 バージョン2.0.xのファイルパス
ストレージプール上のストレージボリュームファイル

デフォルトでは、defaultという名前のストレージプールが、/var/opt/hde/libvirt/domainsディレクトリに対して作成されますので、
1.1からのアップグレードでは、1.1のイメージファイルパス(/var/opt/hde/libvirt/domains/<ドメイン名>/images/<ドメイン名>.img)へ
のシンボリックリンクが、/var/opt/hde/libvirt/domainsディレクトリの配下にUUID形式のファイル名で作成されます。

# ls -ltr /var/opt/hde/libvirt/domains/[0-9]*
lrwxrwxrwx 1 root kss  57  6月 15 12:46 /var/opt/hde/libvirt/domains/55236ff8-88bb-023f-1499-2f34c4f1b133 -> /var/opt/hde/libvirt/domains/foo/images/foo.img

5. Karesansui 2.0.0 からKaresansui 2.0.xへアップデートする手順¶

概要
2.0.0から2.0.xへのアップデートは、インストーラの使用し、下記手順でアップグレードを行うことで、各種ソフトウェアの更新を行うことができます。
なお、アップデートを行う場合は、重要なデータは別のサーバーへバックアップしてから行うことをお薦めします。

以降では、CentOS 5.4 (x86_64) を例に説明します。

# /opt/hde/bin/virsh shutdown <ゲストOSのドメイン>

# /etc/init.d/silhouetted stop
# /etc/init.d/hde-lighttpd stop
# /etc/init.d/hde-libvirtd stop
# /etc/init.d/xend stop (Xenを利用しているときのみ)

3. ダウンロードした2.0.xのインストールパックを任意のディレクトリに展開します。

# tar zxvf karesansui-2.0.x-xxx-install-pack.tar.gz

4. 展開されたインストールパックに含まれるインストーラを実行します。

# cd Karesansui
# ./karesansui-install

5. インストーラの案内にしたがって、項目を入力します。

このとき、データベース設定の画面でデーターベース初期化を選択しますと、それまでのデータが消去されてしまいますのでアップグレードを行いたい場合は、選択しないようご注意下さい。
ただし、pysilhouetteの使用するデータベースは、アップグレード時に初期化されますので、必要であればデータベースのバックアップも行ってください。

6.インストーラの実行が終了後

各種ソフトウェア更新と既存データの移行は完了です。以下のコマンドで、Karesansuiの実行環境に問題ないか確認してください。

# ./karesansui-checkenv

# shutdown -r now

開発環境を作ってみる¶

Karesansuiをインストール¶

チュートリアルのKaresansuiのインストールを参照し、インストールを行います。

開発環境構築コマンド¶

Karesansuiには開発者向けの構築コマンドがあります。これを実行する事で簡単に構築することができます。

手順¶

# cd /opt/karesansui/share/doc/karesansui-2.0.1/tool
# ./mk_opendev.sh

構築コマンド内部説明¶

• 事前準備
• ネットワーク環境にproxyが存在する場合は、41行目の proxy_host を設定してください。

• ディストリビューションに入っている重複パッケージを除去します。
• Karesansuiに必要なパッケージをインストールします。
• 開発用フォルダを設定します。>作業したいフォルダを指定します。※推奨は「/git」フォルダです。
• wget, lftp, ntpが入っていないときはインストールを行います。
• Karesansui Projectが提供するyumリポジトリからgitをインストールします。
• ntpサービスを起動します。
• 開発用フォルダを作成します。
• sourceforge.jpにあるリポジトリ(git)からチェックアウト(clone)します。
  ※Karesansuiリポジトリは開発用フォルダ配下に「karesansui.git」配置されます。
• Karesansuiリポジトリの開発版は、devブランチで行われていますので自動でそちらにSwitch(git)します。
• インストールされたKaresansuiのプログラム「/opt/karesansui/lib/python/karesansuiを「/opt/karesansui/lib/python/karesansui」にリネームします。
• チェックアウトしたリポジトリ(git)にある必要なファイルを各々シンボリックリンクで/opt/karesansui配下に配置します。※権限設定も合わせて行います。
  ※Karesansuiの権限は基本的にkssユーザを使用します。lighttpdはwwwhdeユーザで動作します。

mk_opendev.shの実行結果(example)¶

[root@localhost tool]# ./mk_opendev.sh 
Loaded plugins: fastestmirror
Loading mirror speeds from cached hostfile
 * addons: www.ftp.ne.jp
 * base: www.ftp.ne.jp
 * extras: www.ftp.ne.jp
 * updates: www.ftp.ne.jp
addons                                                                                                                                                      |  951 B     00:00     
base                                                                                                                                                        | 2.1 kB     00:00     
extras                                                                                                                                                      | 2.1 kB     00:00     
updates                                                                                                                                                     | 1.9 kB     00:00     
Setting up Install Process
Package gnutls-utils-1.4.1-3.el5_4.8.x86_64 already installed and latest version
Package PyXML-0.8.4-4.el5_4.2.x86_64 already installed and latest version
Package perl-HTML-Parser-3.55-1.fc6.x86_64 already installed and latest version
Package perl-URI-1.35-3.noarch already installed and latest version
Nothing to do
Working Directory[default:/root]                       :/git

Proceed to build development environment, then press enter.
Loaded plugins: fastestmirror
Loading mirror speeds from cached hostfile
 * addons: www.ftp.ne.jp
 * base: www.ftp.ne.jp
 * extras: www.ftp.ne.jp
 * updates: www.ftp.ne.jp
karesansui-devel                                                                                                                                            |  951 B     00:00     
karesansui-devel/primary                                                                                                                                    |  13 kB     00:00     
karesansui-devel                                                                                                                                                             41/41
Setting up Install Process
Resolving Dependencies
--> Running transaction check
---> Package git.x86_64 0:1.7.1-1 set to be updated
--> Processing Dependency: perl-Git = 1.7.1-1 for package: git
--> Processing Dependency: perl(DBI) for package: git
--> Processing Dependency: perl(Git) for package: git
--> Running transaction check
---> Package perl-DBI.x86_64 0:1.52-2.el5 set to be updated
---> Package perl-Git.x86_64 0:1.7.1-1 set to be updated
--> Finished Dependency Resolution

Dependencies Resolved

===================================================================================================================================================================================
 Package                                  Arch                                   Version                                    Repository                                        Size
===================================================================================================================================================================================
Installing:
 git                                      x86_64                                 1.7.1-1                                    karesansui-devel                                 6.2 M
Installing for dependencies:
 perl-DBI                                 x86_64                                 1.52-2.el5                                 base                                             600 k
 perl-Git                                 x86_64                                 1.7.1-1                                    karesansui-devel                                  17 k

Transaction Summary
===================================================================================================================================================================================
Install       3 Package(s)
Upgrade       0 Package(s)

Total download size: 6.8 M
Downloading Packages:
(1/3): perl-Git-1.7.1-1.x86_64.rpm                                                                                                                          |  17 kB     00:00     
(2/3): perl-DBI-1.52-2.el5.x86_64.rpm                                                                                                                       | 600 kB     00:00     
(3/3): git-1.7.1-1.x86_64.rpm                                                                                                                               | 6.2 MB     00:05     
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Total                                                                                                                                              570 kB/s | 6.8 MB     00:12     
警告: rpmts_HdrFromFdno: ヘッダ V3 DSA signature: NOKEY, key ID 8c0505ed
karesansui-devel/gpgkey                                                                                                                                     | 1.7 kB     00:00     
Importing GPG key 0x8C0505ED "Karesansui Project Key (Karesansui Project Official Signing Key) <karesansui-key@karesansui-project.info>" from /etc/pki/rpm-gpg/RPM-GPG-KEY-Karesansui
Running rpm_check_debug
Running Transaction Test
Finished Transaction Test
Transaction Test Succeeded
Running Transaction
  Installing     : perl-DBI                                                                                                                                                    1/3 
  Installing     : git                                                                                                                                                         2/3 
  Installing     : perl-Git                                                                                                                                                    3/3 

Installed:
  git.x86_64 0:1.7.1-1                                                                                                                                                             

Dependency Installed:
  perl-DBI.x86_64 0:1.52-2.el5                                                              perl-Git.x86_64 0:1.7.1-1                                                             

Complete!

ntpd を停止中:
11 Nov 22:28:33 ntpdate[5980]: step time server 210.171.226.40 offset 280.294142 sec
ntpd を起動中:                                             [  OK  ]

Proceed to build development environment, then press enter.        
/git /opt/karesansui/share/doc/karesansui-2.0.1/tool
Initialized empty Git repository in /git/karesansui/.git/
remote: Counting objects: 14433, done.
remote: Compressing objects: 100% (3193/3193), done.
remote: Total 14433 (delta 10153), reused 14409 (delta 10137)
Receiving objects: 100% (14433/14433), 4.94 MiB | 3.55 MiB/s, done.
Resolving deltas: 100% (10153/10153), done.
/git/karesansui.git /git /opt/karesansui/share/doc/karesansui-2.0.1/tool
Branch dev set up to track remote branch dev from origin.
Switched to a new branch 'dev'
/git /opt/karesansui/share/doc/karesansui-2.0.1/tool
# su -s /bin/bash wwwhde -c "KARESANSUI_CONF=/etc/opt/karesansui/application.conf SEARCH_PATH=/opt/karesansui/lib/python:/opt/hde/lib/python:/opt/pysilhouette/lib/python /opt/karesansui/bin/karesansui.fcgi" 

• 末尾にあるコマンドを実行する事でKaresansui内部にある開発用Webサーバー(web.py内蔵)をフォアグランドで実行することができます。
  ※内部サーバーを利用することで、一般的なpdbデバッガの利用等行えるようになります。

開発Webサーバーの実行例¶

[root@localhost tool]# su -s /bin/bash wwwhde -c "KARESANSUI_CONF=/etc/opt/karesansui/application.conf SEARCH_PATH=/opt/karesansui/lib/python:/opt/hde/lib/python:/opt/pysilhouette/lib/python /opt/karesansui/bin/karesansui.fcgi" 
http://0.0.0.0:8080/

開発Webサーバーにアクセスしてみる。¶

ブラウザで、http://localhost:8080/karesansui/v2/ にアクセスしてください。
※開発WebサーバーはSSLをサポートしていません。httpでアクセスしてください。

アクセス出来ない場合¶

-A INPUT -p tcp -m tcp --dport 8080 -j ACCEPT

# git checkout master

最後に¶

以上で開発の準備は終了です。
コマンドをひとつ実行するだけで開発準備が整ったと思います。
あとは、開発用フォルダにあるkaresansui.gitを編集するだけで開発が行えるはずです。

Karesansui Projectから¶

Karesansuiは開発準備にコストをかけることを望んでいません。
我々はあなたにとってシンプルで直感的な開発環境を提供します。

注) だからといってエディタ、IDEを強制するものではありませんのであしからず。

新しいページを作ってみる¶

Karesansui に Hello World ページを新しく追加する手順です。

開発環境¶

開発ドキュメントの開発環境を作ってみるを参照し、開発環境を構築します。

新規ページ¶

以下の流れで新規ページを作成します。

• タブの追加
• URL マッピングの追加
• gadget の作成
• テンプレート (part, input) の作成
• スタイルシートの作成
• 権限設定
• 開発 Web サーバーの起動
  
  

タブの追加¶

templates/default/host/host.html ファイルを次のように編集します。
これにより Karesansui のホスト画面に、Hello タブが追加されます。

# cat templates/default/host/host.html | grep -e "<li class" -e "tab-left" -e "</li>" 
                        <li class="top-tab">
                            <a class="tab-left" href="#" id="${ctx.homepath}/host.part"><span class="tab-right">${_('Summary')}</span></a>
                        </li>
                        <li class="top-tab">
                            <a class="tab-left" href="#" id="${ctx.homepath}/user.part"><span class="tab-right">${_('User')}</span></a>
                        </li>
                        <li class="top-tab">
                            <a class="tab-left" href="#" id="${ctx.homepath}/job.part"><span class="tab-right">${_('Job')}</span></a>
                        </li>
                        <li class="top-tab">
                            <a class="tab-left" href="#" id="${ctx.homepath}/tag.part"><span class="tab-right">${_('Tag')}</span></a>
                        </li>
                        <li class="top-tab">
                            <a class="tab-left" href="#" id="${ctx.homepath}/hello.part"><span class="tab-right">${_('Hello')}</span></a>
                        </li>

URL マッピングの追加¶

urls.py ファイルを次のように編集します。これにより、URL マッピングが行われるようになります。

# grep hello /git/karesansui.git/karesansui/urls.py
import karesansui.gadget.hello
       + karesansui.gadget.hello.urls \

gadget の作成¶

gadget/hello.py ファイルを次のように作成します。
Notice: gadget ファイルを変更・作成した場合は、Web サーバーの再起動が必要となります。

# cat << 'EOS' > /git/karesansui.git/karesansui/gadget/hello.py
# -*- coding: utf-8 -*-

from karesansui.lib.rest import Rest, auth

class Hello(Rest):
    @auth
    def _GET(self, *param, **params):
        return True

    @auth
    def _POST(self, *param, **params):
        return True

urls = (
    '/hello/?(\.part)$', Hello,
    )
EOS

テンプレートの作成¶

templates/default/hello/hello.part ファイルを次のように作成します。

# rm -rf /git/karesansui.git/karesansui/templates/default/hello
# mkdir /git/karesansui.git/karesansui/templates/default/hello
# cat << 'EOS' > /git/karesansui.git/karesansui/templates/default/hello/hello.part
<%inherit file="../include/common.part" />
<script type="text/javascript">
<!--
$(document).ready(function(){
    $("#tool_renew").click(function(){
        renew_msg(true);
    });
});
-->
</script>
                    <div id="hello">
                        <div classs="alert"></div>
                        <div id="action" >
                            <div class="left"></div>
                            <div class="right">
                                <a href="#" class="tool-link" >
                                    <div class="tool-mid">
                                        <img src="${ctx.homepath}/static/images/reload.gif" alt="renew" id="tool_renew"/>
                                    </div>
                                </a>
                            </div>
                        </div>
                        <br style="clear: both;"/>
                        <div class="space"/>
                        <div id="view">
                            <div class="hello-contents">
                                <br>
                                <div align="center">Hello World</div>
                                <br>
                            </div>
                        </div>
                        <br style="clear: both;"/>
                    </div>
EOS

スタイルシートの作成¶

static/css/style.css を次のように編集し、static/css/hello.css ファイルを作成します。

# grep hello /git/karesansui.git/karesansui/static/css/style.css
@import url('./hello.css');

# cat << 'EOS' > /git/karesansui.git/karesansui/static/css/hello.css
.hello-contents{
    background-color:#FFFFFF;
    border-color:#BCBCBC;
    border-style:solid;
    border-width:1px 1px 1px;
    color:#000000;
    font-size:12px;
    margin-bottom:15px;
    padding-bottom:5px;
    padding-top:6px;
    width:99.8%;
}
EOS

権限設定¶

今回作成したファイルを、kss グループから読み込みできるように設定します。

# chown root:kss /git/karesansui.git/karesansui/gadget/hello.py
# chown root:kss /git/karesansui.git/karesansui/static/css/hello.css
# chown -R root:kss /git/karesansui.git/karesansui/templates/default/hello

開発 Web サーバーの起動¶

次のコマンドで開発 Web サーバーを起動します。
既に起動している場合は、再起動を行ってください。

# su -s /bin/bash wwwhde -c "KARESANSUI_CONF=/etc/opt/karesansui/application.conf SEARCH_PATH=/opt/karesansui/lib/python:/opt/hde/lib/python:/opt/pysilhouette/lib/python /opt/karesansui/bin/karesansui.fcgi" 

確認¶

開発 Web サーバーに接続し、今回作成した Hello World ページが正常に表示されるかを確認してください。
最後に新しいページを作るにあたって、注意する点としては以下があります。

開発サーバーが ImportError で起動しない¶

今回新しく作成した gadget ファイルを読み込めない場合に発生します。
ファイル属性の確認を行ってください。

新しく作成したページにアクセスできない (500エラーが発生する)¶

今回新しく作成した template ファイルを読み込めない場合に発生します。
ファイル属性の確認を行ってください。

内部のシステム構成¶

app.py¶

起動処理が行われます。初期化処理の追加時に利用してください。

詳細¶

• コネクションプール
• コマンドオプション(prep.py)
• ログ
• URLマッピング初期化(urls.py)
• 内部サーバー(開発用)
• readline(ipython)
• pysilhouette初期化

rest.py¶

Karesansuiが独自に作成した、薄いWebフレームワークの基盤です。Webフレームワークで一般的に存在する処理がすべて記述されています。

詳細¶

• URL別のgadget振り分け
• テンプレートファイルの振り分けと出力
• HTTPレスポンスのメディアタイプ振り分け
• GET/POST/DELETE/PUT の振り分け
• 国際化
• オーバーライドPOST
• 認証基盤

※ karesansui/lib/rest.py

gadget¶

MVCのControllerにあたるクラスです。gadgetのファイル名は、テンプレート名(View)で命名規則利用されます。

詳細¶

• GET/POST/DELETE/PUTの各処理
• 認証判断

※ karesansui/gadget

static¶

静的ファイルを配置します。

lighttpd経由の場合はWebフレームワークを経由しません。
内部サーバー(開発)の場合はWebフレームワークを経由します。

詳細¶

• js, css, 画像データが配置されています。
• js, cssを動的に出力させたい場合は、templages/{テーマ名}/data/xxx に配置します。

※ karesansui/static

templates¶

動的に出力される、テンプレートが配置されています。

※テーマ機能を備えており、設定ファイルを利用することで簡単にテーマ変更をすることができます。
/etc/opt/karesansui/application.conf -> application.template.theme
デフォルトは「default」になっています。

※ karesansui/templates/テーマ名/テンプレートフォルダ名/テンプレート名.拡張子

詳細¶

• テンプレートフォルダ名は、gadgetで作成したファイル名と同じものにしてください。
• テンプレート名は、gadgetで作成したファイル名と同じものにしてください。
• URLの拡張子は現在html, part, json, inputを自動判別します。 * html : htmlファイル形式を記述します。 * part : html形式で記述します。主に部分的な更新Ajaxを行う場合に利用します。 * json : jsonフォーマットを記述します。gadgetでsimplejsonという外部ライブラリを利用することで簡単に実装することができます。 * input : htmlやpartで更新ページを出力する場合に利用されます。GETパラメータにmode=inputを指定することで自動判別されます。

テンプレートフォルダ名、テンプレート名、拡張子のカスタマイズ方法¶

gadgetで以下の設定を行います。

self.__template__.dir = "テンプレートフォルダ名を指定します" 

self.__template__.file = "テンプレート名を指定します" 

self.__template__.media = "拡張子を指定します"

db¶

データベース制御、操作を行います。

※Pysilhouetteについては外部ライブラリとして透過利用しています。

※ karesansui/db

詳細¶

• modelフォルダ : O/Rマッピング用のモデルクラスを定義します。※SQLAlchemyを直接利用しています。
• accessフォルダ : データアクセス操作用の処理を行います。

pysilhouette¶

高い権限が必要な処理はすべてジョブマネージャ(Pysilhouette)で処理されます。操作はすべてデータベース経由になります。

lib¶

仮想化ライブラリ、各種ロジック、ファイル操作などライブラリとして切り出せるすべてが配置されています。

※ karesansui/lib

詳細¶

• 仮想化操作ライブラリは、karesansui/lib/virtにまとめられています。
• KaresansuiVirtConnection(uri)を利用することで簡単にlibvirt(オープンソースの仮想化ライブラリ)にアクセスできます。

utils¶

一般的なものから、仮想化特有、環境特有のユーティリティなど様々提供します

※ karesansui/lib/utils
※ こまったらまずこのファイルを参照してください。たいていのものがあるはずです。

checker¶

Webフレームワークにアクセスする入力チェックライブラリです。
static配下のchecker.js(Javascript)と完全に同じ記述で入力チェックを実装することができます。これにより、言語差による学習コストを低減しています。

※ karesansui/lib/checker.py
※ こまったらまずこのファイルを参照してください。たいていのものがあるはずです。

最後に¶

KaresansuiのWebフレームワークは薄いラッパーです。各OSSのライブラリへの直接アクセスを妨げません。ですがより簡単にシンプルに操作するためのライブラリは積極的に実装されています。

ライブラリへのリンク
web.py docs
mako docs
SQLAlchemy docs

Karesansuiフレームワークの提供する関数/変数リファレンス - コントローラー(gadget)¶

※MVC別に分類します。

このページではMVCのController部分のリファレンスを紹介します。

gadget(Controller)¶

gadgetは各ファイルが一つのリソース(URL:RESTful)になります。
作成手順は 新しいページを作ってみる を参照してください。

利用可能なメソッド, 変数¶

gadgetクラスにはHTTP Methodに合わせて _GET, _POST, _PUT, _DELETE がありますがその中で利用可能なメソッド, 変数に以下のようなものがあります。

• param : gadgetファイル内に定義した、urls変数で指定したURLの正規表現部分が設定されています。
• params : GET, POSTパラメタが設定されています。
• self.DELETE : スーパクラスのDELETEメソッド(lib/rest.pyを参照してください)
• self.GET : スーパクラスのDELETEメソッド(lib/rest.pyを参照してください)
• self.POST : スーパクラスのDELETEメソッド(lib/rest.pyを参照してください)
• self.PUT : スーパクラスのDELETEメソッド(lib/rest.pyを参照してください)
• self._ : _("hoge")と利用するだけで、国際化(gettext)が利用できます。詳しくは 国際化してみるを参照ください。
• self.__method__ : リクエストされたHTTP Methodが設定されています。example) "GET"
• self.__module__ : gedgetクラスのモジュールパスが設定されています。example) "karesansui.gadget.hoge"
• self.__template__ : メディアタイプ、テンプレートのファイル名(MVCのview名※拡張子は除く)、テンプレートのディレクトリ名がdict(辞書)で設定されています。

example) <Storage {'media': 'html', 'file': 'host', 'dir': 'host'}>

• self.chk_guestby1 : URLに含まれるパスを利用してゲストOSが存在しているかチェックする。引数にはparamを利用します。
• self.chk_hostby1 : URLに含まれるパスを利用してホストOSが存在しているかチェックする。引数にはparamを利用します。
• self.download : クライアントへファイルをダウンロードする際に利用します。 ※1
• self.input : クライアントからのGET、POSTパラメタが辞書(dict)で設定されています。
• self.is_html : リクエストURLの拡張子が、.htmlか
  テンプレートファイルの拡張子(.html)が選ばれます。
• self.is_json : リクエストURLの拡張子が、.jsonか
  テンプレートファイルの拡張子(.json)が選ばれます。
• self.is_mode_input : リクエストパラメータに、mode=inputがある場合にTrueが設定されます。
  テンプレートファイルの拡張子(.input)が選ばれます。
• self.is_part : リクエストURLの拡張子が、.partか
  テンプレートファイルの拡張子(.part)が選ばれます。
• self.is_standalone : リクエストパラメータに、standalone=1がある場合にTrueが設定されます。
  .partのようなHTMLの一部を出力する場合のテストに使用します。.partファイルの前後にHTMLタグを自動で付加します。
• self.is_xml : リクエストURLの拡張子が、.xmlか
  テンプレートファイルの拡張子(.xml)が選ばれます。
• self.languages : ログインしているユーザの言語(現在はenとjaがサポートされています)のリストが設定されています。
• self.logger : ログ出力オブジェクトです。

example)
self.logger.debug("hoge") # /var/log/karesansui/application.logに出力されます。

• self.logger_trace : プログラムエラーログ出力オブジェクトです。

example)
self.logger.debug("hoge") # /var/log/karesansui/error.logに出力されます。

• self.me : ログインしているユーザのUser情報が設定されています。
• self.orm : Karesansuiデータベースへのセッションが設定されています。これを利用しデータベースアクセスを行います。
• self.pysilhouette : pysilhouette(ジョブマネージャー)データベースへのセッションが設定されています。これを利用しデータベースアクセスを行います。
• self.view : テンプレートへデータを渡したい際に利用します。

example)
self.view.hoge = "hogehoge" # テンプレートでは ${hoge} を記述するだけで hogehoge が取得できます。
 

※1

ダウンロードを行う方法は3種類あります。

• 通常使用されるHTMLやXML、JSONをクライアントに返却します。一般的なWebアプリケーションで利用される形式です。
• すでに存在するファイルを出力します。※一般的なファイルダウンロード時に利用します。

example) 
self.download.file = "ファイルパス" 
self.download.type = OUTPUT_TYPE_FILE (lib.restをインポートします)

example)
self.download.stream = IOオブジェクト
self.download.type = OUTPUT_TYPE_STREAM

※以下をTrueにすることで出力したあとに元のファイルを削除します。

self.download.once = False

_GET, _POST, _PUT, _DELETEメソッドのreturnについて¶

return True : HTTP Responseコード200で処理されます。
return False : HTTP Responseコード500で処理されます。

その他のHTT Responseコードで処理するには

return web.xxxx()

example) return web.notfound()

# 200, 201, 202
"ok", "created", "accepted",

# 301, 302, 303, 304, 407, 408
"redirect", "found", "seeother", "notmodified", "tempredirect", "requesttimeout" 

# 400, 401, 403, 404, 405, 406, 409, 410, 412
"badrequest", "unauthorized", "forbidden", "nomethod", "notfound", "notacceptable", "conflict", "gone", "preconditionfailed",

# 500
"internalerror",

Karesansuiフレームワークの提供する関数/変数リファレンス - データベースへのアクセス(db.access)¶

※MVC別に分類します。

このページではMVCのModelを利用してのアクセス部分のリファレンスを紹介します。

※例文のコードは、karesansui/db/access/user.pyのプログラムを利用しています。

データベースアクセス(model.access)¶

Karesansuiでは、様々なデータをデータベースに保存しています。ここでは、データベースにアクセスする方法を紹介します。

データベースにアクセスするプログラムは、karesansui/db/accessフォルダ になります。
※テーブル別にファイルを分類しています。

O/Rマッパー(SQLAlchemy)について¶

Karesansuiでは、オープンソースのSQLAlchemyを利用しています。
SQLAlchemyはPythonで書かれたO/RマッパーでPostgreSQL、MySQL、SQLite、Firebirdなど複数のデータベースをサポート(KaresansuiのサポートデータベースはSQLAlchemyに準拠しています)しています。

詳しくはSQLAlchemyのドキュメントを参照ください

SQLAlchemyドキュメント

基本的なSELECTについて¶

KaresansuiではfindbyXXという命名規則を利用してます。
これもSQLAlchemyを直接利用することで簡単に実装可能です。

# idを利用して一件レコードを取得します。
def findby1(session, id):
    return session.query({Modelオブジェクト}).filter({Modelオブジェクト}.id == id).first()

# モデルで定義したテーブルをすべて取得します。
def findbyall(session):
    return session.query({Modelオブジェクト}).all()

基本的なINSERT、UPDATE、DELETEについて¶

karesansui.db.accessにKaresansuiが拡張したデコレータがあります。
このデコレータでは、Karesansui用の処理エラー、ログ出力、戻り値の成功可否を自動処理します。

利用方法は簡単で、karesansui.db.access配下にデータベースアクセスファイルを作成し内部で定義するだけです。

@dbsave
def save(session, user):
    session.save(user)

@dbupdate
def update(session, user):
    session.update(user)

@dbdelete
def delete(session, user):
    session.delete(user)

Modelオブジェクトをnewする推奨方法¶

Modelオブジェクトは直接 karesansui.db.model.xxxを利用することでnewすることができますが、それでは依存関係が複雑になります。
そこでKaresansuiでは、karesansui.db.access.xxxにnewメソッドを記述することで、gadgetなどでmodelを直接インポートしない形をとっています。

def new(email, password, salt, nickname, languages=None):
    return User(email, password, salt, nickname, languages)

最後に¶

データベースアクセスについては、説明より既存のコードを読むほうが分かりやすいと思います。

Karesansui Projectでは、karesansui/db/access/user.py が一番分かりやすいと考えます。

また、SQLAlchemyのドキュメントにすべて書かれていますので合わせて読むのを推奨します。

データベーステーブル(model.model)¶

※MVC別に分類します。

このページではMVCのデータベースに紐づくModelのリファレンスを紹介します。

※例文のコードは、karesansui/db/model/user.pyのプログラムを利用しています。

データベースモデル(model)¶

Karesansuiでは、様々なデータをデータベースに保存しています。ここでは、データベースをModel定義する方法を紹介します。

データベースモデル定義プログラムは、karesansui/db/modelフォルダ になります。
※テーブル別にファイルを分類しています。

O/Rマッパー(SQLAlchemy)について¶

Karesansuiでは、オープンソースのSQLAlchemyを利用しています。
SQLAlchemyはPythonで書かれたO/RマッパーでPostgreSQL、MySQL、SQLite、Firebirdなど複数のデータベースをサポート(KaresansuiのサポートデータベースはSQLAlchemyに準拠しています)しています。

詳しくはSQLAlchemyのドキュメントを参照ください

SQLAlchemyドキュメント

モデルを用意する¶

Karesansui からSQLAlchemyを使う場合、以下の３つを用意する必要があります。

• モデル定義 : sqlalchemy.Tableクラスを利用し定義します。コンストラクタにデータベースのテーブルに合うカラム定義を行います。
  ※SQLAlchemyには、一般的なデータベースにある機能が相当数存在します。Karesansuiはそれらを制限しませんので、自由に利用することが可能です。
• モデルクラス : アプリケーションで利用するモデルクラスを定義します。通常このクラスを利用しテーブルを操作します。
  ※Karesansuiではこの中に、get_json関数を用意し簡単にJSON形式でモデル出力する方法を提供しています。
  ※このクラスは、karesansui/db/model/__init__#Modelを継承してください。Karesansuiが用意した便利な関数を提供しています。
• モデル定義とモデルクラスをマッピング : 上記のモデル定義とモデルクラスをマッピングします。
  ※マッピングを利用することで、複雑なリレーションや遅延ロードなどを設定することができます。

モデル作成手順¶

def get_user_table(metadata, now):
    return sqlalchemy.Table('user', metadata,
                            sqlalchemy.Column('id', sqlalchemy.Integer,
                                              primary_key=True,
                                              autoincrement=True,
                                              ),
                            sqlalchemy.Column('email', sqlalchemy.String(256),
                                              unique=True,
                                              nullable=False,
                                              ),
                            sqlalchemy.Column('password', sqlalchemy.String(40),
                                              nullable=False,
                                              ),
                            sqlalchemy.Column('salt', sqlalchemy.Unicode(16),
                                              nullable=False,
                                              ),
                            sqlalchemy.Column('nickname', sqlalchemy.Unicode(16),
                                              nullable=False,
                                              ),
                            sqlalchemy.Column('languages', sqlalchemy.Unicode(6),
                                              default=u'ja_JP',
                                              ),
                            sqlalchemy.Column('created', sqlalchemy.DateTime,
                                              default=now,
                                              ),
                            sqlalchemy.Column('modified', sqlalchemy.DateTime,
                                              default=now,
                                              onupdate=now,
                                              ),
                            )

class User(karesansui.db.model.Model):
    def __init__(self, email, password, salt, nickname, languages=None):
        self.password = password
        self.salt = salt
        self.email = email
        self.nickname = nickname
        self.languages = languages

    def get_json(self, languages):
        ret = {}
        ret["id"] = self.id
        ret["email"] = self.email
        #ret["password"] = self.password                                                                                                                                  
        #ret["salt"] = self.salt                                                                                                                                          
        ret["nickname"] = self.nickname
        ret["languages"] = self.languages
        ret["created"] = self.created.strftime(
            DEFAULT_LANGS[languages]['DATE_FORMAT'][1])
        ret["modified"] = self.modified.strftime(
            DEFAULT_LANGS[languages]['DATE_FORMAT'][1])

        return ret

    def __repr__(self):
        return "User<'%s, %s'>" % (
            self.email, self.languages)

def reload_mapper(metadata, now):
    t_user = get_user_table(metadata, now)
    mapper(User, t_user)

+    import karesansui.db.model.user
+    karesansui.db.model.user.reload_mapper(metadata, _now)

ビュー(view)¶

※MVC別に分類します。

このページではMVCのビュー(templates/theme)のリファレンスを紹介します。

※例文のコードは、karesansui/templates/{テーマ}のプログラムを利用しています。

テンプレートエンジン(Mako)について¶

Karesansuiでは、オープンソースのMakoを利用しています。
MakoはPythonで書かれたテンプレートエンジンで、Pythonコードを埋め込む機能やキャッシュ機能を有しています。

詳しくはMakoのドキュメントを参照ください

Makoドキュメント

ビュー(templates/theme)¶

Karesansuiでは、ビューのテンプレートエンジンにMakoを採用しています。ここでは、テンプレート(View)を記述する方法を紹介します。

テンプレートファイルフォルダは、karesansui/templates/{テーマ名}/ になります。
※gadgetの名前とURL拡張子別にファイルを分類しています。

gadgetの名前 : gadgetのファイル名をテンプレートパスに自動定義します。
URL拡張子 : .html | .part | .input | .json をテンプレートパスに自動定義します。

gadgetファイル名 : hoge.py

テンプレートパス : karesansui/{テーマ}/hoge/hoge.[.html|.part|.input|.json]

テーマについて¶

Karesansuiではテンプレートをテーマとして切り替えることができます。

切り替える方法 : /etc/opt/karesansui/application.confの「application.template.theme=default」を変更しテーマフォルダにテーマフォルダを作成します。

設定ファイルを変更 : application.template.theme=hoge

テンプレートフォルダを作成 : karesansui/templates/hoge

拡張子の意味¶

拡張子をうまく利用することで、さまざなメディアタイプに対応することができます。

Karesansuiでは標準で以下の拡張子に対応しています。
※もちろん対応を増やすことも容易です。

'html' : 通常のHTMLファイルです。
'json' : JSON形式ファイルです。
'part' : HTMLの一部ファイルです。
'input' : partの一部ファイルを編集可能な形式にしたファイルです。(<label>を<input>にするなど...)
'xml' : XML形式ファイルです。

gadgetからview(templates)へ値を引き渡す方法¶

gadgetの_GET ... 内で、self.viewに値をセットします。

example)

gadget/hoge.py

def _GET ...
    self.view.foo = "Foo" 
    self.view.bar = "Bar" 

--
templates/theme/hoge/hoge.html

${foo}
${bar}

view(templates)で利用可能な変数¶

_ : 国際化された文字を出力します。利用方法 : ${_("hoge")}
context : mako定義
ctx : HTTP情報

リポジトリ - ファイル構成¶

.
|-- AUTHORS 開発者リスト
|-- COPYING コピーライト(GPL)
|-- COPYING.LIB ライブラリ部分のコピーライト(LGPL)
|-- INSTALL インストール方法
|-- INSTALL.ja インストール方法(日本語)
|-- MANIFEST.in # Python マニフェストファイル
|-- README READMEファイル
|-- README.ja READMEファイル(日本語)
|-- bin # Karesansuiが利用するコマンド(単体での利用も可能です。)
|   |-- __cmd__.py # サーバー起動時に動的に作成されるファイルです。※変更しないでください。
|   |-- add_bonding.py
|   |-- add_disk.py
|   |-- add_iscsi.py
|   |-- add_nic.py
|   |-- append_disk.py
|   |-- apply_lighttpdconf.py
|   |-- apply_snapshot.py
|   |-- autostart_guest.py
|   |-- autostart_network.py
|   |-- autostart_service.py
|   |-- autostart_storage_pool.py
|   |-- connect_virt.py
|   |-- control_iptables.py
|   |-- cputop.py
|   |-- create_guest.py
|   |-- create_network.py
|   |-- create_storage_pool.py
|   |-- create_storage_volume.py
|   |-- delete_bonding.py
|   |-- delete_disk.py
|   |-- delete_export_data.py
|   |-- delete_guest.py
|   |-- delete_iscsi.py
|   |-- delete_network.py
|   |-- delete_nic.py
|   |-- delete_snapshot.py
|   |-- delete_storage_pool.py
|   |-- delete_storage_volume.py
|   |-- destroy_guest.py
|   |-- destroy_storage_pool.py
|   |-- export_guest.py
|   |-- get_cpu_usage.py
|   |-- get_iscsi.py
|   |-- get_memory_usage.py
|   |-- import_guest.py
|   |-- initialize_collectd_conf.py
|   |-- karesansui.fcgi
|   |-- karesansui_sysinfo.py
|   |-- ksscommand.py
|   |-- read_conf.py
|   |-- ready_mount.py
|   |-- reboot_guest.py
|   |-- replicate_guest.py
|   |-- replicate_storage_volume.py
|   |-- restart_network.py
|   |-- restart_network_interface.py
|   |-- restart_service.py
|   |-- restore_firewall.py
|   |-- resume_guest.py
|   |-- save_firewall.py
|   |-- set_mac_address.py
|   |-- set_memory.py
|   |-- set_vcpus.py
|   |-- set_vnc.py
|   |-- shutdown_guest.py
|   |-- start_guest.py
|   |-- start_iscsi.py
|   |-- start_network.py
|   |-- start_service.py
|   |-- start_storage_pool.py
|   |-- stop_iscsi.py
|   |-- stop_network.py
|   |-- stop_service.py
|   |-- suspend_guest.py
|   |-- take_snapshot.py
|   |-- update_iscsi.py
|   |-- update_network.py
|   |-- update_software.py
|   `-- write_conf.py
|-- doc 各種設定ファイル
|   |-- application.conf.example # Karesansuiの設定ファイル例
|   |-- babel.map # 国際化マッピングファイル(Babelを使用しています。)
|   |-- centos5-x86.ks # centos5のキックスタートファイル例
|   |-- cron_cleantmp.example # Karesansuiの設定ファイル例
|   |-- epydoc.cfg # epydocの設定ファイル
|   |-- lighttpd # Karesansuiの設定ファイル例
|   |-- log.conf.example # Karesansuiの設定ファイル例
|   |-- logview.xml.example # Karesansuiの設定ファイル例
|   |-- messages.pot # 国際化メッセージファイル
|   |-- redhat.spec # SPECファイル(KaresansuiをRPMパッケージする場合はこちらを利用してください)
|   |-- service.xml.example # Karesansuiの設定ファイル例
|   |-- tables # Karesansuiの設定ファイル例
|   |-- template # Karesansuiの設定ファイル例
|   `-- whitelist.conf.example # Karesansuiの設定ファイル例
|-- example
|   `-- rrd
|-- installer # インストーラー関連
|   |-- doc
|   |-- installer
|   |-- karesansui-checkenv # Karesansuiの状態をチェックします。
|   |-- karesansui-initdb # Karesansuiが利用するデータベースを初期化します。
|   |-- karesansui-install # Karesanuiインストールコマンド
|   |-- karesansui-uninstall # Karesansuiアンインストールコマンド
|   `-- tool
|-- karesansui # Karesansui 本体
|   |-- __init__.py
|   |-- app.py # サーバー起動ファイル
|   |-- auth # ユーザ認証
|   |-- db # データベース
|   |-- gadget # Controller 
|   |-- lib # ライブラリ
|   |-- locale # 国際化
|   |-- plus # Karesansuiとは別のライセンスで定義されたプログラム
|   |-- prep.py # サーバ起動前処理
|   |-- static # 静的ファイル
|   |-- templates # テンプレート
|   |-- tests # test
|   |-- urls.py # URLマッピング
|-- scripts # FastCGI用のスクリプト
|   `-- karesansui.fcgi
|-- setup.cfg
|-- setup.py
`-- tool # Karesansuiで利用出来るツールコマンド群
    |-- cleanlydb.py # データベースをクリーンすることができます。
    |-- coverage.sh # カバレッジをHTMLで出力します。
    |-- db_dump.sh # データベースダンプコマンド
    |-- db_restore.sh # データベースリストアコマンド
    |-- delbr.sh # ネットワークブリッジを削除するコマンド
    |-- epydoc.sh # Javadoc形式のドキュメントを生成します。
    |-- install.sh # 現在使われていません。
    |-- make_locale.sh # gettextを利用した国際化ファイルを作成します。
    |-- makefirewall.sh # Karesansui用のiptablesを作成します。
    |-- mk_opendev.sh # ※Karesansuiの開発環境を自動で構築します。
    |-- rpm_2_git.sh # 現在利用されていません。
    `-- uninstall.sh # 現在利用されていません。