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.2.x - supported
  10     2.1.x - mostly supported
  11     2.0.x - unsupported but may work
  12     1.x   - unsupported
  13
  14 Browser compatibility:
  15     * Mozilla Firefox >= 3.x
  16     * Chrome / Chromium
  17
  18 The VNC console requires websockets or flash support and HTML5 support in the
  19 browser.
  20
  21 Project page: http://code.osuosl.org/projects/ganeti-webmgr
  22 Mailing List: http://groups.google.com/group/ganeti-webmgr
  23 IRC:          #ganeti-webmgr on freenode.net
  24 Twitter:      http://twitter.com/ganetiwebmgr
  25
  26
  27 ================================================================================
  28  Installation
  29 ================================================================================
  30
  31 1.  Install Dependencies
  32     * Python     >= 2.5 but < 3.x (Python 3.x is not supported due to
  33                                backward-compatibility issues)
  34     * Pip        >= 0.8.2
  35     * Fabric     >= 1.0.1 (installable from pip)
  36     * VirtualEnv >= 1.6.1 (installable from pip)
  37 2. Deploy this code somewhere (i.e. /var/lib/django/ganeti_webmgr)
  38 3. Install libaries needed for pip installs
  39
  40       sudo apt-get install python-dev
  41
  42 4. Run Fabric deployment
  43
  44       cd ./ganeti_webmgr
  45       fab dev deploy
  46
  47   or a production deployment:
  48
  49       fab prod deploy
  50
  51 5. Activate Virtual Environment
  52
  53     source bin/activate
  54
  55 6. Copy settings.py.dist to settings.py
  56
  57 7. Create a database and configure your settings:
  58
  59  DATABASE_ENGINE = ''   <-- Change This to 'mysql', 'postgresql',
  60                             'postgresql_psycopg2' or 'sqlite3'
  61  DATABASE_NAME = ''     <-- Change this to a database name, or a file for SQLite
  62  DATABASE_USER = ''     <-- Change this (not needed for SQLite)
  63  DATABASE_PASSWORD = '' <-- Change this (not needed for SQLite)
  64  DATABASE_HOST = ''     <-- Change this (not needed if database is localhost)
  65  DATABASE_PORT = ''     <-- Change this (not needed if database is localhost)
  66
  67 8. Set the id, name and domain of your site in settings.py and the site will
  68    automatically be created when syncdb is run.
  69
  70  # Unique site id used by many modules to distinguish site from others.
  71  SITE_ID = 1
  72
  73  # Site name and domain referenced by some modules to provide links back to the
  74  # site.
  75  SITE_NAME = 'Ganeti Web Manager'
  76  SITE_DOMAIN = 'localhost:8000'
  77
  78 9. Initialize the database
  79
  80     ./manage.py syncdb --migrate
  81
  82 10. Build the search indexes
  83
  84     ./manage.py rebuild_index
  85
  86 NOTE: running ./manage.py update_index on a regular basis ensures that the
  87 search indexes stay up-to-date when models change in Ganeti Web Manager.
  88
  89 11. Run the server
  90
  91     Development:
  92
  93     ./manage.py runserver
  94
  95     Production:
  96
  97     1. Change your SECRET_KEY and WEB_MGR_API_KEY to unique (and hopefully
  98        unguessable) strings in your settings.py.
  99
 100     2. For versions >= 0.5 you may need to add the full filesystem path to your
 101        templates directory to TEMPLATE_DIRS and remove the relative reference
 102        to 'templates'. We've had issues using wsgi not working correctly unless
 103        this change has been made.
 104
 105     3. Ensure the server has the ability to send emails or you have access to
 106        an SMTP server. Set EMAIL_HOST, EMAIL_PORT, and DEFAULT_FROM_EMAIL in
 107        settings.py. For more complicated outgoing mail setups, please refer to
 108        the django email documentation [1].
 109
 110     4. Follow the django guide to deploy [2] with apache. Here is an example
 111        mod_wsgi file:
 112
 113         import os
 114         import sys
 115
 116         path = '/var/lib/django/ganeti_webmgr'
 117         if path not in sys.path:
 118                 sys.path.append(path)
 119
 120                 os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
 121
 122                 import django.core.handlers.wsgi
 123                 application = django.core.handlers.wsgi.WSGIHandler()
 124
 125     5. Enable periodic cache updater [3].
 126
 127         twistd --pidfile=tmp/gwm_cache.pid gwm_cache
 128
 129  [1] http://docs.djangoproject.com/en/1.2/topics/email/
 130  [2] http://docs.djangoproject.com/en/1.2/howto/deployment/
 131  [3] http://code.osuosl.org/projects/ganeti-webmgr/wiki/Cache_System#Periodic-Cache-Refresh
 132
 133 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Install
 134
 135 ================================================================================
 136  Ganeti RAPI users and passwords
 137 ================================================================================
 138
 139 Before you can start using Ganeti Web Manager you will need to create a user
 140 and password on the Ganeti cluster.
 141
 142 Here is an example with a user jack and password abc123:
 143
 144     echo -n 'jack:Ganeti Remote API:abc123' | openssl md5
 145
 146 Add the hash to the RAPI users file and restart ganeti-rapi. Depending on the
 147 version of Ganeti you are running, you will need to either use
 148 `/var/lib/ganeti/rapi_users` (Ganeti <=2.3.x ) or
 149 `/var/lib/ganeti/rapi/users` (Ganeti >=2.4.x ).
 150
 151 An example hash entry might look like the following:
 152
 153     # Hashed password for jack
 154     jack {HA1}54c12257ee9be413f2f3182435514aae write
 155
 156 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Ganeti-RAPI-users-and-passwords
 157
 158
 159 ================================================================================
 160  Importing a Cluster
 161 ================================================================================
 162
 163 1. Use the admin user created during syncdb to log in.
 164 2. Import a cluster:  Clusters -> Add Cluster
 165 3. Fill out properties and click save
 166
 167 When the cluster is created it will automatically synchronize the list of
 168 Virtual Machines with information from the ganeti cluster.
 169
 170 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Importing_a_Cluster
 171
 172
 173 ================================================================================
 174  Users, Groups, and Permissions
 175 ================================================================================
 176
 177 Permissions may be granted to both clusters and virtual machines. The
 178 permissions system is intended to allow users to manage themselves. Any object
 179 that can have its permissions edited will have a Users tab.
 180
 181 Adding users to objects:
 182   1. Navigate to Group, Cluster, or VirtualMachine detail page
 183   2. Click Add New User
 184   3. Select user or group
 185   4. Select permissions
 186   5. Save
 187
 188 Updating permissions:
 189   1. Navigate to Group, Cluster, or VirtualMachine detail page
 190   2. Click Users tab
 191   3. Click permissions column
 192   4. Select permissions and save
 193
 194 Deleting permissions:
 195   1. Navigate to Group, Cluster, or VirtualMachine detail page
 196   2. Click Users tab
 197   3. Click the delete icon
 198
 199 Deleting a user will remove all permissions, and other properties associated
 200 with the user such as cluster quotas.
 201
 202 Users may belong to any number of user groups.  User groups can be assigned
 203 permissions and quotas just like users.  Users inherit permissions from groups
 204 and may act on their behalf to create virtual machines.
 205
 206 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions
 207
 208
 209 ================================================================================
 210  Assigning Quotas
 211 ================================================================================
 212
 213 Quotas restrict the usage of cluster resources by users and groups. Default
 214 quotas can be set by editing clusters, if no quota is set unlimited access is
 215 allowed. This will affect all users and groups.
 216
 217 The default quota can be overridden on the cluster users page:
 218
 219    1. Clusters -> Cluster -> Users
 220    2. Click on the quota
 221    3. Edit values
 222
 223 Leaving a value empty specifies unlimited access for that resource.
 224
 225 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions#Quotas
 226
 227
 228 ================================================================================
 229  Orphaned VirtualMachines
 230 ================================================================================
 231
 232 You can find VirtualMachines with no permissions via Admin -> Orphaned VMs.
 233 This will force a synchronization of all clusters and display VirtualMachines
 234 that do not have any permissions assigned.
 235
 236 You only need to grant permissions directly on virtual machines if you are
 237 granting access to non-admin users.
 238
 239 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Orphaned-Virtual-Machines
 240
 241
 242 ================================================================================
 243  Cache System
 244 ================================================================================
 245
 246 Ganeti Web Manager uses a cache system that stores information about ganeti
 247 clusters in the database. This allows the following:
 248
 249       ---  Ganeti  ---
 250      /                \
 251     /                  \
 252  Cluster ->       <-   Bulk
 253   Model  <- cache <-  Updater
 254
 255     * Permissions are stored in the database and are associated to the cached
 256       objects
 257     * The cached data can be searched and or filtered
 258     * Limits the amount of traffic between the webserver and ganeti cluster.
 259
 260 The cache system is transparent and will load cached data automatically when
 261 the object is initialized.
 262
 263 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Cache_System
 264
 265 ================================================================================
 266  VNC
 267 ================================================================================
 268
 269 Ganeti Web Manager provides an in browser console using noVNC [1], an HTML5
 270 client.  noVNC requires WebSockets to function. Support for older browsers is
 271 provided through a flash applet that is used transparently in the absence of
 272 WebSockets.
 273
 274 [1] https://github.com/kanaka/noVNC
 275
 276 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC
 277
 278 ================================================================================
 279  VNC AuthProxy
 280 ================================================================================
 281
 282 VNC Auth proxy [1] is required for the console tab to function. VNC servers do
 283 not speak websockets and our proxy allows your ganeti cluster to sit behind a
 284 firewall, VPN, or NAT.
 285
 286 Enabling in settings.py
 287 -----------------------
 288
 289 Set the host and port that the proxy will be running at with the VNC_PROXY
 290 setting. For development this is typically "localhost:8888" but for production
 291 you would use the name of the server its running on. See the instructions in
 292 settings.py for more details.
 293
 294 Starting the Daemon
 295 -------------------
 296
 297 Twisted VNC Authproxy is started with twistd, the twisted daemon. Eventually we
 298 will include init.d scripts for better managing the daemon. You may want to open
 299 port 8888 in your firewall for production systems.
 300
 301     twistd --pidfile=/tmp/proxy.pid -n vncap
 302
 303 Starting Flash Policy Server
 304 ----------------------------
 305
 306 Browsers that do not support WebSockets natively are supported through the use
 307 of a flash applet. Flash applets that make use of sockets must retrieve a policy
 308 file from the server they are connecting to. Twisted VNCAuthProxy includes a
 309 policy server. It must be run separately since it requires a root port. You may
 310 want to open port 843 in your firewall for production systems.
 311
 312 Start the policy server with twistd
 313
 314     sudo twistd --pidfile=/tmp/policy.pid -n flashpolicy
 315
 316
 317 Possible issues
 318 ---------------
 319
 320 You may encounter an issue where twisted fails to start and gives you an error.
 321 This is usually caused by the environment variable PYTHONPATH not being
 322 exported correctly if you sudo up to root. To fix it type:
 323
 324     export PYTHONPATH="."
 325
 326 Try executing twisted again and it should work.
 327
 328 [1] http://code.osuosl.org/projects/twisted-vncauthproxy
 329
 330 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC#VNC-Authproxy
 331
 332 ================================================================================
 333  SSH Keys
 334 ================================================================================
 335
 336 Ganeti Web Manager allows users to store SSH Keys. Each virtual machine has a
 337 view that will return SSH keys for users with access. This can be used as a
 338 Ganeti post-install hook to deploy user's keys on the VMs.
 339
 340 To allow VMs to copy keys, copy util/hooks/sshkeys.sh to the instance
 341 definition hooks directory on every node in the clsuter and make the file
 342 executable. Next, add the required variables to the variant config file
 343 or main instance definition config file. The config file can be found in
 344 util/hooks/sshkeys.conf and includes documentation for each variable.
 345
 346 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/PermissionsSSHKeys