README

Ginger
======

Ginger is an open source host management plugin to Wok, Web Server Originated
from Kimchi, that provides an intuitive web panel with common tools for
configuring and operating Linux systems.

Wok is a cherrypy-based web framework with HTML5 support that is extended by
plugins which expose functionality through REST APIs.

The current features of Host Management of Linux system include:
 + retrieve system health (sensors) stats
 + user login account management,
 + network interface configuration,
 + configuration backup,
 + Power (ppc) firmware update,
 + Power policy management.

Browser Support
===============

Wok and its plugin can run in any web browser that supports HTML5. The
Kimchi community (responsible for Wok project) makes an effort to
test it with the latest versions of Chrome and Firefox browsers, but the
following list can be used as reference to browser support.

Desktop Browser Support:
-----------------------
* **Internet Explorer:** Current version
* **Chrome:** Current version
* **Firefox:** Current version
* **Safari:** Current version
* **Opera:** Current version

Mobile Browser Support:
-----------------------
* **Safari iOS:** Current version
* **Android Browser** Current version


Hypervisor Distro Support
=========================

Kimchi might run on any GNU/Linux distribution that meets the conditions
described on the 'Getting Started' section below.

The Kimchi community makes an effort to test it with the latest versions of
Fedora, RHEL, IBM KVM and Ubuntu.

Getting Started
===============

Install Dependencies
--------------------

**For fedora, RHEL and IBM KVM :**

     $ sudo yum install ginger-base libvirt-python libvirt hddtemp \
                        libuser-python python-augeas python-netaddr\
                        python-ethtool python-ipaddr python-magic \

    # For fedora, RHEL and Power ppc
    $ sudo yum install tuned lm_sensors

    # Power ppc install the following packages
    $ sudo yum install powerpc-utils serviceable.event.provider

    # These dependencies are only required if you want to run the tests:
    $ sudo yum install pyflakes python-pep8 python-mock

**For Ubuntu (Debian-based):**

    $ sudo apt-get install ginger-base libvirt-bin python-libvirt hddtemp \
                        python-libuser python-ethtool python-augeas \
                        python-ipaddr python-magic python-netaddr

    # These dependencies are only required if you want to run the tests:
    $ sudo apt-get install pep8 pyflakes python-requests python-mock

At the moment of this writing (11-30-2015), libuser has a bug that
prevents it to work properly in Ubuntu 15.10 and older
(https://bugs.launchpad.net/ubuntu/+source/libuser/+bug/1387274).
A workaround is needed to fix this bug:

$ sudo touch /etc/libuser.conf

This workaround is for Debian/Ubuntu only.

Build and Install
-----------------

    Wok Framework Installation:
    $ ./autogen.sh --system

    $ make
    $ sudo make install   # Optional if running from the source tree

    Ginger Base:
    $ cd src/wok/plugins/gingerbase
    $ ./autogen.sh --system

    $ make
    $ sudo make install   # Optional if running from the source tree

    Ginger:
    $ cd ginger
    $ ./autogen.sh --system

    $ make
    $ sudo make install   # Optional if running from the source tree

Run
---
    $ sudo /usr/bin/wok --host=0.0.0.0

    OR

    $ sudo systemctl start wokd

*** Notes on Power policy management feature ***

The power policy management feature uses the 'tuned' service to control the
power policies of the host. Problems have been reported with this package,
depending on the host configuration, such as SELinux denials and trouble
to communicate using DBUS with the 'tuned' service started from systemd.

If you find any problems with the power policy management feature, we
recommend following these steps (all steps requires 'sudo' privileges):

- put SELinux in permissive mode for 'tuned' (required if the version of the
package 'selinux-policy' is < 3.11):

$ semanage permissive -a tuned_t

- disable the 'tuned' service from systemd and restart it by hand:

$ systemctl stop tuned.service
$ tuned -l -P -d

Remember to restart wokd service after these changes:

$ systemctl restart wokd.service

If these steps do not solve the problem, try to update all 'tuned' related
packages and the packages'selinux-policy' and 'selinux-policy-targeted'.

Test
----

    $ cd ginger
    $ make check-local # check for i18n and formatting errors
    $ sudo make check

After all tests are executed, a summary will be displayed containing any
errors/failures which might have occurred.

Participating
-------------

All patches are sent through our mailing list.  More information can be found at:

https://github.com/kimchi-project/ginger/wiki/Communications

Patches should be sent using git-send-email to ginger-dev-list@googlegroups.com

** Copyright notice ***

All the .gif and .png files in 'ui/css/base/images/' directory are licensed
as follows:

----------------------------
Copyright IBM Corp, 2015

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA