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