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 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 deploy
 128
 129   * development environment
 130
 131     $ fab dev deploy</pre>
 132
 133   * activate virtual environment
 134
 135     $ source venv/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/venv/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     7. Set VNC_PROXY to the hostname of your VNC AuthProxy server in
 233         settings.py.  The VNC AuthProxy does not need to run on the same server
 234         as Ganeti Web Manager.
 235
 236           VNC_PROXY = 'my.server.org:8888'
 237
 238 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Install
 239
 240 ================================================================================
 241  Ganeti RAPI users and passwords
 242 ================================================================================
 243
 244 Before you can start using Ganeti Web Manager, you will need to create a user
 245 and password on the Ganeti cluster.
 246
 247 Here is an example with user "jack" and password "abc123":
 248
 249     $ echo -n 'jack:Ganeti Remote API:abc123' | openssl md5
 250
 251 Add the hash to the RAPI users file and restart ganeti-rapi. Depending on the
 252 version of Ganeti you are running, you will need to either use
 253 `/var/lib/ganeti/rapi_users` (Ganeti <=2.3.x ) or
 254 `/var/lib/ganeti/rapi/users` (Ganeti >=2.4.x ).
 255
 256 An example hash entry might look like the following:
 257
 258     # Hashed password for jack
 259     jack {HA1}54c12257ee9be413f2f3182435514aae write
 260
 261 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Ganeti-RAPI-users-and-passwords
 262
 263
 264 ================================================================================
 265  Importing a Cluster
 266 ================================================================================
 267
 268 1. Use the admin user created during syncdb to log in.
 269 2. Import a cluster:  Clusters -> Add Cluster
 270 3. Fill out properties and click save
 271
 272 When the cluster is created it will automatically synchronize the list of
 273 Virtual Machines with information from the Ganeti cluster.
 274
 275 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Importing_a_Cluster
 276
 277
 278 ================================================================================
 279  Users, Groups, and Permissions
 280 ================================================================================
 281
 282 Permissions may be granted to both clusters and virtual machines. The
 283 permissions system is intended to allow users to manage themselves. Any object
 284 that can have its permissions edited will have a Users tab.
 285
 286 Adding users to objects:
 287   1. Navigate to Group, Cluster, or Virtual Machine detail page
 288   2. Click Add New User
 289   3. Select user or group
 290   4. Select permissions
 291   5. Save
 292
 293 Updating permissions:
 294   1. Navigate to Group, Cluster, or Virtual Machine detail page
 295   2. Click Users tab
 296   3. Click permissions column
 297   4. Select permissions and save
 298
 299 Deleting permissions:
 300   1. Navigate to Group, Cluster, or Virtual Machine detail page
 301   2. Click Users tab
 302   3. Click the delete icon
 303
 304 Deleting a user will remove all permissions, and other properties associated
 305 with the user such as cluster quotas.
 306
 307 Users may belong to any number of user groups.  User groups can be assigned
 308 permissions and quotas just like users.  Users inherit permissions from groups
 309 and may act on their behalf to create virtual machines.
 310
 311 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions
 312
 313
 314 ================================================================================
 315  Assigning Quotas
 316 ================================================================================
 317
 318 Quotas restrict the usage of cluster resources by users and groups. Default
 319 quotas can be set by editing clusters, if no quota is set unlimited access is
 320 allowed. This will affect all users and groups.
 321
 322 The default quota can be overridden on the cluster users page:
 323
 324    1. Clusters -> Cluster -> Users
 325    2. Click on the quota
 326    3. Edit values
 327
 328 Leaving a value empty specifies unlimited access for that resource.
 329
 330 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions#Quotas
 331
 332
 333 ================================================================================
 334  Orphaned Virtual Machines
 335 ================================================================================
 336
 337 You can find Virtual Machines with no permissions via Admin -> Orphaned VMs.
 338 This will force a synchronization of all clusters and display Virtual Machines
 339 that do not have any permissions assigned.
 340
 341 You only need to grant permissions directly on virtual machines if you are
 342 granting access to non-admin users.
 343
 344 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Orphaned-Virtual-Machines
 345
 346
 347 ================================================================================
 348  Cache System
 349 ================================================================================
 350
 351 Ganeti Web Manager uses a cache system that stores information about Ganeti
 352 clusters in the database. This allows the following:
 353
 354       ---  Ganeti  ---
 355      /                \
 356     /                  \
 357  Cluster ->       <-   Bulk
 358   Model  <- cache <-  Updater
 359
 360     * Permissions are stored in the database and are associated to the cached
 361       objects
 362     * The cached data can be searched and or filtered
 363     * Limits the amount of traffic between the web server and Ganeti cluster.
 364
 365 The cache system is transparent and will load cached data automatically when
 366 the object is initialized.
 367
 368 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Cache_System
 369
 370 ================================================================================
 371  VNC
 372 ================================================================================
 373
 374 Ganeti Web Manager provides an in browser console using noVNC [1], an HTML5
 375 client.  noVNC requires WebSockets to function. Support for older browsers is
 376 provided through a flash applet that is used transparently in the absence of
 377 WebSockets.
 378
 379 [1] https://github.com/kanaka/noVNC
 380
 381 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC
 382
 383 ================================================================================
 384  VNC AuthProxy
 385 ================================================================================
 386
 387 VNC Auth proxy [1] is required for the console tab to function. VNC servers do
 388 not speak websockets and our proxy allows your ganeti cluster to sit behind a
 389 firewall, VPN, or NAT.
 390
 391 Enabling in settings.py
 392 -----------------------
 393
 394 Set the host and port that the proxy will be running at with the VNC_PROXY
 395 setting. For development this is typically "localhost:8888" but for production
 396 you would use the name of the server its running on. See the instructions in
 397 settings.py for more details.
 398
 399 Starting the Daemon
 400 -------------------
 401
 402 Twisted VNC Authproxy is started with twistd, the twisted daemon. Eventually we
 403 will include init.d scripts for better managing the daemon. You may want to open
 404 port 8888 in your firewall for production systems.
 405
 406     $ twistd --pidfile=/tmp/proxy.pid -n vncap
 407
 408 Starting Flash Policy Server
 409 ----------------------------
 410
 411 Browsers that do not support WebSockets natively are supported through the use
 412 of a flash applet. Flash applets that make use of sockets must retrieve a policy
 413 file from the server they are connecting to. Twisted VNCAuthProxy includes a
 414 policy server. It must be run separately since it requires a root port. You may
 415 want to open port 843 in your firewall for production systems.
 416
 417 Start the policy server with twistd
 418
 419     $ sudo twistd --pidfile=/tmp/policy.pid -n flashpolicy
 420
 421
 422 Possible issues
 423 ---------------
 424 You may encounter an issue where twisted fails to start and gives you an error.
 425 This is usually caused by the environment variable PYTHONPATH not being
 426 exported correctly if you sudo up to root. To fix it type:
 427
 428     $ export PYTHONPATH="."
 429
 430 Try executing twisted again and it should work.
 431
 432 [1] http://code.osuosl.org/projects/twisted-vncauthproxy
 433
 434 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC#VNC-Authproxy
 435
 436 ================================================================================
 437  SSH Keys
 438 ================================================================================
 439
 440 Ganeti Web Manager allows users to store SSH Keys. Each virtual machine has a
 441 view that will return SSH keys for users with access. This can be used as a
 442 Ganeti post-install hook to deploy user's keys on the VMs.
 443
 444 To allow VMs to copy keys, copy util/hooks/sshkeys.sh to the instance
 445 definition hooks directory on every node in the cluster and make the file
 446 executable. Next, add the required variables to the variant config file
 447 or main instance definition config file. The config file can be found in
 448 util/hooks/sshkeys.conf and includes documentation for each variable.
 449
 450 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/PermissionsSSHKeys