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