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