models: Rewrite check_job_status().

[ganeti_webmgr.git] / README

================================================================================
 Ganeti Web Manager
================================================================================

Ganeti Web Manager is a Django-based web application that allows administrators
and clients access to their ganeti clusters.  

Ganeti compatibility:
    >=2.2.x - supported
    2.1.x - mostly supported
    2.0.x - unsupported but may work
    1.x   - unsupported

Browser compatibility:
    * Mozilla Firefox >= 3.x
    * Chrome / Chromium

The VNC console requires WebSockets or flash support and HTML5 support in the
browser.

Project page: http://code.osuosl.org/projects/ganeti-webmgr
Mailing List: http://groups.google.com/group/ganeti-webmgr
IRC:          #ganeti-webmgr on freenode.net
Twitter:      http://twitter.com/ganetiwebmgr


================================================================================
 Installation
================================================================================

1.  Install Dependencies
    * Python     >= 2.5 but < 3.x (Python 3.x is not supported due to
                               backward-compatibility issues)
    * Pip        >= 0.8.2
    * Fabric     >= 1.0.1 (installable from pip)
    * virtualenv >= 1.6.1 (installable from pip)
2. Deploy this code somewhere (i.e. /var/lib/django/ganeti_webmgr)
3. Install libaries needed for pip installs

    $ sudo apt-get install python-dev

4. Run Fabric

    $ cd ./ganeti_webmgr

    a. Development Environment

        $ fab dev deploy

    b. Production Environment:

        $ fab prod deploy

5. Activate Virtual Environment

    $ source bin/activate

6. Copy settings.py.dist to settings.py

7. Create a database and configure the DATABASE dictionary in
   settings.py
     If your setup is more complex than what is described by
     your settings.py, please refer to the Django documentation
     on DATABASES [1].

8. Set the id, name and domain of your site in settings.py and the site will
   automatically be created when syncdb is run.

    # Unique site id used by many modules to distinguish site from others.
    SITE_ID = 1

    # Site name and domain referenced by some modules to provide links back to the
    # site.
    SITE_NAME = 'Ganeti Web Manager'
    SITE_DOMAIN = 'localhost:8000'

9. Initialize the database and run migrations

    $ ./manage.py syncdb --migrate

10. Build the search indexes

    $ ./manage.py rebuild_index

    NOTE: Running ./manage.py update_index on a regular basis ensures that the
    search indexes stay up-to-date when models change in Ganeti Web Manager.

NOTE: If running a production server, please skip to #12.
11. Run the server (Development):

    $ ./manage.py runserver

12. Run the server (Production):
    1. Change the ownership of the whoosh_index directory to apache.

         $ chown apache:apache whoosh_index/

    2. Change your SECRET_KEY and WEB_MGR_API_KEY to unique (and hopefully
       unguessable) strings in your settings.py.

    3. Configure Configure the Django Cache Framework to use a production 
       capable backend in settings.py. By default Ganeti Web Manager is 
       configured to use the LocMemCache but it is not recommended for 
       production. Use Memcached or a similar backend.

         CACHES = {
             'default': {
                 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
             }
         }

    4. For versions >= 0.5 you may need to add the full filesystem path to your
       templates directory to TEMPLATE_DIRS and remove the relative reference
       to 'templates'. We've had issues using WSGI not working correctly unless
       this change has been made.

    5. Ensure the server has the ability to send emails or you have access to
       an SMTP server. Set EMAIL_HOST, EMAIL_PORT, and DEFAULT_FROM_EMAIL in
       settings.py. For more complicated outgoing mail setups, please refer to
       the Django email documentation [2].

    6. Follow the Django guide to deploy [3] with apache. Here is an example
       mod_wsgi file:

        import os
        import sys

        path = '/var/lib/django/ganeti_webmgr'

        # activate virtualenv
        activate_this = '%s/bin/activate_this.py' % path
        execfile(activate_this, dict(__file__=activate_this))

        # add project to path
        if path not in sys.path:
            sys.path.append(path)

        # configure django environment
        os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
        
        import django.core.handlers.wsgi
        application = django.core.handlers.wsgi.WSGIHandler()

    7. Enable periodic cache updater [4].

        $ twistd --pidfile=tmp/gwm_cache.pid gwm_cache


[1] http://docs.djangoproject.com/en/1.2/topics/email/
[2] https://docs.djangoproject.com/en/dev/ref/settings/#databases
[3] http://docs.djangoproject.com/en/1.2/howto/deployment/
[4] http://code.osuosl.org/projects/ganeti-webmgr/wiki/Cache_System#Periodic-Cache-Refresh

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Install

================================================================================
 Ganeti RAPI users and passwords
================================================================================

Before you can start using Ganeti Web Manager, you will need to create a user
and password on the Ganeti cluster.

Here is an example with user "jack" and password "abc123":

    $ echo -n 'jack:Ganeti Remote API:abc123' | openssl md5

Add the hash to the RAPI users file and restart ganeti-rapi. Depending on the
version of Ganeti you are running, you will need to either use
`/var/lib/ganeti/rapi_users` (Ganeti <=2.3.x ) or
`/var/lib/ganeti/rapi/users` (Ganeti >=2.4.x ).

An example hash entry might look like the following:

    # Hashed password for jack
    jack {HA1}54c12257ee9be413f2f3182435514aae write

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Ganeti-RAPI-users-and-passwords


================================================================================
 Importing a Cluster
================================================================================

1. Use the admin user created during syncdb to log in.
2. Import a cluster:  Clusters -> Add Cluster
3. Fill out properties and click save

When the cluster is created it will automatically synchronize the list of
Virtual Machines with information from the Ganeti cluster.

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Importing_a_Cluster


================================================================================
 Users, Groups, and Permissions
================================================================================

Permissions may be granted to both clusters and virtual machines. The
permissions system is intended to allow users to manage themselves. Any object
that can have its permissions edited will have a Users tab.

Adding users to objects:
  1. Navigate to Group, Cluster, or Virtual Machine detail page
  2. Click Add New User
  3. Select user or group
  4. Select permissions
  5. Save

Updating permissions:
  1. Navigate to Group, Cluster, or Virtual Machine detail page
  2. Click Users tab
  3. Click permissions column
  4. Select permissions and save

Deleting permissions:
  1. Navigate to Group, Cluster, or Virtual Machine detail page
  2. Click Users tab
  3. Click the delete icon

Deleting a user will remove all permissions, and other properties associated
with the user such as cluster quotas.

Users may belong to any number of user groups.  User groups can be assigned
permissions and quotas just like users.  Users inherit permissions from groups
and may act on their behalf to create virtual machines.

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions


================================================================================
 Assigning Quotas
================================================================================

Quotas restrict the usage of cluster resources by users and groups. Default
quotas can be set by editing clusters, if no quota is set unlimited access is
allowed. This will affect all users and groups.

The default quota can be overridden on the cluster users page:

   1. Clusters -> Cluster -> Users
   2. Click on the quota
   3. Edit values

Leaving a value empty specifies unlimited access for that resource.

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions#Quotas


================================================================================
 Orphaned Virtual Machines
================================================================================

You can find Virtual Machines with no permissions via Admin -> Orphaned VMs.
This will force a synchronization of all clusters and display Virtual Machines
that do not have any permissions assigned.

You only need to grant permissions directly on virtual machines if you are
granting access to non-admin users.

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Orphaned-Virtual-Machines


================================================================================
 Cache System
================================================================================

Ganeti Web Manager uses a cache system that stores information about Ganeti
clusters in the database. This allows the following:

      ---  Ganeti  ---
     /                \
    /                  \
 Cluster ->       <-   Bulk
  Model  <- cache <-  Updater

    * Permissions are stored in the database and are associated to the cached
      objects
    * The cached data can be searched and or filtered
    * Limits the amount of traffic between the web server and Ganeti cluster.

The cache system is transparent and will load cached data automatically when
the object is initialized.

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Cache_System

================================================================================
 VNC 
================================================================================

Ganeti Web Manager provides an in browser console using noVNC [1], an HTML5
client.  noVNC requires WebSockets to function. Support for older browsers is
provided through a flash applet that is used transparently in the absence of
WebSockets.

[1] https://github.com/kanaka/noVNC

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC

================================================================================
 VNC AuthProxy
================================================================================

VNC Auth proxy [1] is required for the console tab to function. VNC servers do
not speak websockets and our proxy allows your ganeti cluster to sit behind a
firewall, VPN, or NAT.

Enabling in settings.py
-----------------------

Set the host and port that the proxy will be running at with the VNC_PROXY
setting. For development this is typically "localhost:8888" but for production
you would use the name of the server its running on. See the instructions in
settings.py for more details.

Starting the Daemon
-------------------

Twisted VNC Authproxy is started with twistd, the twisted daemon. Eventually we
will include init.d scripts for better managing the daemon. You may want to open
port 8888 in your firewall for production systems.

    $ twistd --pidfile=/tmp/proxy.pid -n vncap

Starting Flash Policy Server
----------------------------

Browsers that do not support WebSockets natively are supported through the use
of a flash applet. Flash applets that make use of sockets must retrieve a policy
file from the server they are connecting to. Twisted VNCAuthProxy includes a
policy server. It must be run separately since it requires a root port. You may
want to open port 843 in your firewall for production systems.

Start the policy server with twistd

    $ sudo twistd --pidfile=/tmp/policy.pid -n flashpolicy


Possible issues
---------------
You may encounter an issue where twisted fails to start and gives you an error.
This is usually caused by the environment variable PYTHONPATH not being
exported correctly if you sudo up to root. To fix it type:

    $ export PYTHONPATH="."

Try executing twisted again and it should work.

[1] http://code.osuosl.org/projects/twisted-vncauthproxy

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC#VNC-Authproxy

================================================================================
 SSH Keys
================================================================================

Ganeti Web Manager allows users to store SSH Keys. Each virtual machine has a
view that will return SSH keys for users with access. This can be used as a
Ganeti post-install hook to deploy user's keys on the VMs.

To allow VMs to copy keys, copy util/hooks/sshkeys.sh to the instance
definition hooks directory on every node in the cluster and make the file
executable. Next, add the required variables to the variant config file
or main instance definition config file. The config file can be found in
util/hooks/sshkeys.conf and includes documentation for each variable.

Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/PermissionsSSHKeys