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