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