README

   1 ================================================================================
   2  Ganeti Web Manager
   3 ================================================================================
   4
   5 Ganeti Web Manager is a Django-based web application that allows administrators
   6 and clients access to their ganeti clusters.
   7
   8 Ganeti compatibility:
   9     >=2.4.x - supported
  10     2.2.2 - mostly supported
  11     2.3.1 - mostly supported
  12     2.1.x - mostly supported
  13     2.0.x - unsupported but may work
  14     1.x   - unsupported
  15
  16 Browser compatibility:
  17     * Mozilla Firefox >= 3.x
  18     * Chrome / Chromium
  19
  20 The VNC console requires WebSockets or flash support and HTML5 support in the
  21 browser.
  22
  23 Project page: http://code.osuosl.org/projects/ganeti-webmgr
  24 Mailing List: http://groups.google.com/group/ganeti-webmgr
  25 IRC:          #ganeti-webmgr on freenode.net
  26 Twitter:      http://twitter.com/ganetiwebmgr
  27
  28
  29 ================================================================================
  30  Installation
  31 ================================================================================
  32
  33 *Note*: Installing from the tarball is the preferred method. After installing
  34 the dependencies, please download the tarball instead of cloning the repository.
  35
  36 Overview
  37
  38     1. Install dependencies: Python, Pip, Fabric, VirtualEnv
  39     2. Get the Ganeti Web Manager code: Clone from the repository or download
  40         a release tarball
  41     3. Deploy fabric environment: fab dev deploy or fab prod deploy
  42     4. Configure Settings: Copy settings.py.dist to settings.py and make any
  43         modifications
  44     5. Sync database, then run the server: ./manage.py syncdb --migrate, then
  45         ./manage.py runserver
  46
  47 This section explains how to automatically install Ganeti Web Manager using
  48 Fabric: http://docs.fabfile.org/en/1.0.1/index.html.  Fabric simplifies the
  49 installation process by automatically installing dependencies into a virtual
  50 environment.
  51
  52 Related Topics:
  53     * Read more about why Fabric is strongly recommended:
  54         https://code.osuosl.org/projects/ganeti-webmgr/wiki/Fabric_is_strongly_recommended
  55     * Troubleshoot an installation using Fabric:
  56         https://code.osuosl.org/projects/ganeti-webmgr/wiki/Fabric-troubleshooting
  57     * Manual installation:
  58         https://code.osuosl.org/projects/ganeti-webmgr/wiki/Manual-installation
  59
  60 Compatibility
  61
  62 Ganeti Web Manager is compatible with the following:
  63
  64   Ganeti (http://code.google.com/p/ganeti/)
  65        Ganeti >= v2.2.x is supported. v2.1.x and v2.0.x are unsupported and sometimes
  66        work but can cause problems (see #8973). Lower versions are **not**
  67        supported.
  68
  69   Browsers:
  70       Mozilla Firefox (http://mozilla.com/firefox) >= v3.x,
  71       Google Chrome: (http://www.google.com/chrome/)
  72         or Chromium: (http://code.google.com/chromium/)
  73
  74       Other contemporary browsers may also work, but are not supported. (The
  75       web-based VNC console requires browser support of WebSockets
  76       (http://en.wikipedia.org/wiki/WebSockets) and HTML5
  77       (http://en.wikipedia.org/wiki/Html5).
  78
  79   Databases:
  80       MySQL or SQLite. SQLite is not recommended in production environments.
  81
  82   Operating Systems:
  83       GWM has been tested on Debian 7, Ubuntu 11.10, 12.04 and CentOs 5 and 6.
  84       Debian 6 is supported, provided the Pip, Virtualenv and Fabric packages
  85       are updated to the versions listed below.
  86
  87 Dependencies
  88
  89     Python: >=2.5, python >=2.6 recommended
  90     Pip: http://www.pip-installer.org/en/latest/index.html >= 0.8.2
  91     Fabric: http://docs.fabfile.org/en/1.0.1/index.html >=1.0.1
  92     VirtualEnv: http://pypi.python.org/pypi/virtualenv >= 1.6.1
  93
  94 Pip is required for installing Fabric and a useful tool to install Virtualenv
  95
  96     * install pip
  97       $ sudo apt-get install python-pip
  98
  99     * devel libraries may be needed for some pip installs
 100       $ sudo apt-get install python-dev
 101
 102     * install fabric and virtualenv
 103       $ sudo apt-get install python-virtualenv
 104       $ sudo apt-get install fabric
 105
 106 Note: the use of pip to install system packages is not recommended, please use
 107 your system's package manager to install Virtualenv and Fabric.
 108
 109 Install with Fabric
 110
 111 Either download and unpack the "latest release" from
 112 http://code.osuosl.org/projects/ganeti-webmgr/files, or check it out from the
 113 repository:
 114
 115   $ git clone git://git.osuosl.org/gitolite/ganeti/ganeti_webmgr
 116
 117 Switch to project directory
 118 (Fabric commands only work from a directory containing a fabfile)
 119
 120   $ cd ganeti_webmgr/
 121
 122 Run Fabric to automatically create python virtual environment with required
 123 dependencies.  Choose either production or development environment
 124
 125   * production environment
 126
 127     $ fab prod deploy
 128
 129   * development environment
 130
 131     $ fab dev deploy</pre>
 132
 133   * activate virtual environment
 134
 135     $ source bin/activate
 136
 137 Configuration
 138
 139 In the project root, you'll find a default settings file called settings.py.dist
 140
 141 Copy it to settings.py:
 142
 143     $ cp settings.py.dist settings.py
 144
 145 If you want to use another database engine besides the default SQLite (not
 146 recommended for production), edit settings.py, and edit the following lines to
 147 reflect your wishes (*note that postgresql is not supported at this time and
 148 the install will fail*, see issue #3237):
 149
 150 DATABASE_ENGINE = ''   # <-- Change this to 'mysql', 'postgresql',
 151                               'postgresql_psycopg2' or 'sqlite3'
 152 DATABASE_NAME = ''     # <-- Change this to a database name, or a file for
 153                               SQLite
 154 DATABASE_USER = ''     # <-- Change this (not needed for SQLite)
 155 DATABASE_PASSWORD = '' # <-- Change this (not needed for SQLite)
 156 DATABASE_HOST = ''     # <-- Change this (not needed if database is localhost)
 157 DATABASE_PORT = ''     # <-- Change this (not needed if database is localhost)
 158
 159
 160 Initialize Database:
 161
 162     $ ./manage.py syncdb --migrate
 163
 164 Build the search indexes:
 165
 166     $ ./manage.py rebuild_index
 167
 168     Note: running ./manage.py update_index on a regular basis ensures that the
 169       search indexes stay up-to-date when models change in Ganeti Web Manager.
 170
 171 Everything should be all set up! Run the development server with:
 172
 173     $ ./manage.py runserver
 174
 175 Additional configuration for production servers:
 176
 177 Deploying a production server requires additional setup steps.
 178
 179     1. Change the ownership of the @whoosh_index@ directory to apache
 180
 181         $ chown apache:apache whoosh_index/
 182
 183     2. Change your *SECRET_KEY* and *WEB_MGR_API_KEY* to unique (and hopefully
 184         unguessable) strings in your settings.py.
 185
 186     3. Configure the Django Cache Framework
 187         (http://docs.djangoproject.com/en/dev/topics/cache/) to use a production
 188         capable backend in *settings.py*.  By default Ganeti Web Manager is
 189         configured to use the *LocMemCache* but it is not recommended for
 190         production.  Use Memcached or a similar backend.
 191
 192         CACHES = {
 193             'default': {
 194                 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
 195             }
 196         }
 197
 198     4. For versions >= 0.5 you may need to add the full filesystem path to your
 199         templates directory to TEMPLATE_DIRS and remove the relative
 200         reference to 'templates'. We've had issues using wsgi not working
 201         correctly unless this change has been made.
 202
 203     5. Ensure the server has the ability to send emails or you have access to
 204         an SMTP server. Set EMAIL_HOST, EMAIL_PORT, and DEFAULT_FROM_EMAIL in
 205         settings.py. For more complicated outgoing mail setups, please refer to
 206         the django email documentation
 207           (http://docs.djangoproject.com/en/1.2/topics/email/)
 208
 209     6. Follow the django guide to deploy with apache.
 210         (http://docs.djangoproject.com/en/dev/howto/deployment/modwsgi/)
 211         Here is an example mod_wsgi file:
 212
 213           import os
 214           import sys
 215
 216           path = '/var/lib/django/ganeti_webmgr'
 217
 218           # activate virtualenv
 219           activate_this = '%s/bin/activate_this.py' % path
 220           execfile(activate_this, dict(__file__=activate_this))
 221
 222           # add project to path
 223           if path not in sys.path:
 224               sys.path.append(path)
 225
 226           # configure django environment
 227           os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
 228
 229           import django.core.handlers.wsgi
 230           application = django.core.handlers.wsgi.WSGIHandler()
 231
 232
 233     7.  Enable the periodic cache updater.
 234         *NOTE*: Do not run the cache updater as root.
 235
 236         $ twistd --pidfile=/tmp/gwm_cache.pid gwm_cache
 237
 238     You may encounter an issue where twisted fails to start and gives you an
 239     error. This is usually caused by the environment variable PYTHONPATH not
 240     being exported correctly if you switch to superuser 'su -'. To fix it type:
 241
 242         $ export PYTHONPATH="."
 243
 244     Then exit out of root.
 245
 246     8. Set VNC_PROXY to the hostname of your VNC AuthProxy server in
 247         settings.py.  The VNC AuthProxy does not need to run on the same server
 248         as Ganeti Web Manager.
 249
 250           VNC_PROXY = 'my.server.org:8888'
 251
 252 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Install
 253
 254 ================================================================================
 255  Ganeti RAPI users and passwords
 256 ================================================================================
 257
 258 Before you can start using Ganeti Web Manager, you will need to create a user
 259 and password on the Ganeti cluster.
 260
 261 Here is an example with user "jack" and password "abc123":
 262
 263     $ echo -n 'jack:Ganeti Remote API:abc123' | openssl md5
 264
 265 Add the hash to the RAPI users file and restart ganeti-rapi. Depending on the
 266 version of Ganeti you are running, you will need to either use
 267 `/var/lib/ganeti/rapi_users` (Ganeti <=2.3.x ) or
 268 `/var/lib/ganeti/rapi/users` (Ganeti >=2.4.x ).
 269
 270 An example hash entry might look like the following:
 271
 272     # Hashed password for jack
 273     jack {HA1}54c12257ee9be413f2f3182435514aae write
 274
 275 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Ganeti-RAPI-users-and-passwords
 276
 277
 278 ================================================================================
 279  Importing a Cluster
 280 ================================================================================
 281
 282 1. Use the admin user created during syncdb to log in.
 283 2. Import a cluster:  Clusters -> Add Cluster
 284 3. Fill out properties and click save
 285
 286 When the cluster is created it will automatically synchronize the list of
 287 Virtual Machines with information from the Ganeti cluster.
 288
 289 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Importing_a_Cluster
 290
 291
 292 ================================================================================
 293  Users, Groups, and Permissions
 294 ================================================================================
 295
 296 Permissions may be granted to both clusters and virtual machines. The
 297 permissions system is intended to allow users to manage themselves. Any object
 298 that can have its permissions edited will have a Users tab.
 299
 300 Adding users to objects:
 301   1. Navigate to Group, Cluster, or Virtual Machine detail page
 302   2. Click Add New User
 303   3. Select user or group
 304   4. Select permissions
 305   5. Save
 306
 307 Updating permissions:
 308   1. Navigate to Group, Cluster, or Virtual Machine detail page
 309   2. Click Users tab
 310   3. Click permissions column
 311   4. Select permissions and save
 312
 313 Deleting permissions:
 314   1. Navigate to Group, Cluster, or Virtual Machine detail page
 315   2. Click Users tab
 316   3. Click the delete icon
 317
 318 Deleting a user will remove all permissions, and other properties associated
 319 with the user such as cluster quotas.
 320
 321 Users may belong to any number of user groups.  User groups can be assigned
 322 permissions and quotas just like users.  Users inherit permissions from groups
 323 and may act on their behalf to create virtual machines.
 324
 325 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions
 326
 327
 328 ================================================================================
 329  Assigning Quotas
 330 ================================================================================
 331
 332 Quotas restrict the usage of cluster resources by users and groups. Default
 333 quotas can be set by editing clusters, if no quota is set unlimited access is
 334 allowed. This will affect all users and groups.
 335
 336 The default quota can be overridden on the cluster users page:
 337
 338    1. Clusters -> Cluster -> Users
 339    2. Click on the quota
 340    3. Edit values
 341
 342 Leaving a value empty specifies unlimited access for that resource.
 343
 344 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions#Quotas
 345
 346
 347 ================================================================================
 348  Orphaned Virtual Machines
 349 ================================================================================
 350
 351 You can find Virtual Machines with no permissions via Admin -> Orphaned VMs.
 352 This will force a synchronization of all clusters and display Virtual Machines
 353 that do not have any permissions assigned.
 354
 355 You only need to grant permissions directly on virtual machines if you are
 356 granting access to non-admin users.
 357
 358 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Orphaned-Virtual-Machines
 359
 360
 361 ================================================================================
 362  Cache System
 363 ================================================================================
 364
 365 Ganeti Web Manager uses a cache system that stores information about Ganeti
 366 clusters in the database. This allows the following:
 367
 368       ---  Ganeti  ---
 369      /                \
 370     /                  \
 371  Cluster ->       <-   Bulk
 372   Model  <- cache <-  Updater
 373
 374     * Permissions are stored in the database and are associated to the cached
 375       objects
 376     * The cached data can be searched and or filtered
 377     * Limits the amount of traffic between the web server and Ganeti cluster.
 378
 379 The cache system is transparent and will load cached data automatically when
 380 the object is initialized.
 381
 382 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Cache_System
 383
 384 ================================================================================
 385  VNC
 386 ================================================================================
 387
 388 Ganeti Web Manager provides an in browser console using noVNC [1], an HTML5
 389 client.  noVNC requires WebSockets to function. Support for older browsers is
 390 provided through a flash applet that is used transparently in the absence of
 391 WebSockets.
 392
 393 [1] https://github.com/kanaka/noVNC
 394
 395 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC
 396
 397 ================================================================================
 398  VNC AuthProxy
 399 ================================================================================
 400
 401 VNC Auth proxy [1] is required for the console tab to function. VNC servers do
 402 not speak websockets and our proxy allows your ganeti cluster to sit behind a
 403 firewall, VPN, or NAT.
 404
 405 Enabling in settings.py
 406 -----------------------
 407
 408 Set the host and port that the proxy will be running at with the VNC_PROXY
 409 setting. For development this is typically "localhost:8888" but for production
 410 you would use the name of the server its running on. See the instructions in
 411 settings.py for more details.
 412
 413 Starting the Daemon
 414 -------------------
 415
 416 Twisted VNC Authproxy is started with twistd, the twisted daemon. Eventually we
 417 will include init.d scripts for better managing the daemon. You may want to open
 418 port 8888 in your firewall for production systems.
 419
 420     $ twistd --pidfile=/tmp/proxy.pid -n vncap
 421
 422 Starting Flash Policy Server
 423 ----------------------------
 424
 425 Browsers that do not support WebSockets natively are supported through the use
 426 of a flash applet. Flash applets that make use of sockets must retrieve a policy
 427 file from the server they are connecting to. Twisted VNCAuthProxy includes a
 428 policy server. It must be run separately since it requires a root port. You may
 429 want to open port 843 in your firewall for production systems.
 430
 431 Start the policy server with twistd
 432
 433     $ sudo twistd --pidfile=/tmp/policy.pid -n flashpolicy
 434
 435
 436 Possible issues
 437 ---------------
 438 You may encounter an issue where twisted fails to start and gives you an error.
 439 This is usually caused by the environment variable PYTHONPATH not being
 440 exported correctly if you sudo up to root. To fix it type:
 441
 442     $ export PYTHONPATH="."
 443
 444 Try executing twisted again and it should work.
 445
 446 [1] http://code.osuosl.org/projects/twisted-vncauthproxy
 447
 448 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC#VNC-Authproxy
 449
 450 ================================================================================
 451  SSH Keys
 452 ================================================================================
 453
 454 Ganeti Web Manager allows users to store SSH Keys. Each virtual machine has a
 455 view that will return SSH keys for users with access. This can be used as a
 456 Ganeti post-install hook to deploy user's keys on the VMs.
 457
 458 To allow VMs to copy keys, copy util/hooks/sshkeys.sh to the instance
 459 definition hooks directory on every node in the cluster and make the file
 460 executable. Next, add the required variables to the variant config file
 461 or main instance definition config file. The config file can be found in
 462 util/hooks/sshkeys.conf and includes documentation for each variable.
 463
 464 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/PermissionsSSHKeys