Move variables in check_job_status to prevent undeclared error
[ganeti_webmgr.git] / README.rst
blob4d4a6a883d54415c123634dac64d3bb31219be34
1 ==================
2 Ganeti Web Manager
3 ==================
5 Ganeti Web Manager is a Django-based web application that allows administrators
6 and clients access to their ganeti clusters.
8 Ganeti compatibility:
9     :>=2.4.x: supported
10     :2.2.2: mostly supported
11     :2.3.1: mostly supported
12     :2.1.x: mostly supported
13     :2.0.x: unsupported but may work
14     :1.x:   unsupported
16 Browser compatibility:
17     * Mozilla Firefox >= 3.x
18     * Chrome / Chromium
20 The VNC console requires WebSockets or flash support and HTML5 support in the
21 browser.
23 :Project page: http://code.osuosl.org/projects/ganeti-webmgr
24 :Mailing List: http://groups.google.com/group/ganeti-webmgr
25 :IRC:          #ganeti-webmgr on freenode.net
26 :Twitter:      http://twitter.com/ganetiwebmgr
29 ============
30 Installation
31 ============
33 *Note*: Installing from the tarball is the preferred method. After installing
34 the dependencies, please download the tarball instead of cloning the repository.
36 Overview:
38 1. Install dependencies: Python, Pip, Fabric, VirtualEnv
39 2. Get the Ganeti Web Manager code: Clone from the repository or
40    download a release tarball
41 3. Deploy fabric environment: fab dev deploy or fab deploy
42 4. Configure Settings: Copy settings.py.dist to settings.py and make
43    any modifications
44 5. Sync database, then run the server: ./manage.py syncdb --migrate,
45    then ./manage.py runserver
47 This section explains how to automatically install Ganeti Web Manager
48 using Fabric_. Fabric simplifies the installation process by
49 automatically installing dependencies into a virtual environment.
51 Related Topics:
53 * Read more about why Fabric is strongly recommended [1]_
54 * Troubleshoot an installation using Fabric [2]_
55 * Manual installation [3]_
57 .. [1] https://code.osuosl.org/projects/ganeti-webmgr/wiki/Fabric_is_strongly_recommended
58 .. [2] https://code.osuosl.org/projects/ganeti-webmgr/wiki/Fabric-troubleshooting
59 .. [3] https://code.osuosl.org/projects/ganeti-webmgr/wiki/Manual-installation
62 Compatibility
63 -------------
65 Ganeti Web Manager is compatible with the following:
67 Ganeti_
68      Ganeti >= v2.2.x is supported. v2.1.x and v2.0.x are unsupported
69      and sometimes work but can cause problems (see #8973). Lower
70      versions are **not** supported.
72 Browsers:
73     `Mozilla Firefox`_ >= v3.x
74     `Google Chrome`_ or Chromium_
76     Other contemporary browsers may also work, but are not supported.
77     The web-based VNC console requires browser support of WebSockets_
78     and HTML5_.
80 Databases:
81     MySQL or SQLite. SQLite is not recommended in production
82     environments.
84 Operating Systems:
85     GWM has been tested on Debian 7, Ubuntu 11.10, 12.04 and CentOs 5
86     and 6.  Debian 6 is supported, provided the Pip, Virtualenv and
87     Fabric packages are updated to the versions listed below.
89 .. _Ganeti: http://code.google.com/p/ganeti/
90 .. _Mozilla Firefox: http://mozilla.com/firefox
91 .. _Google Chrome: http://www.google.com/chrome/
92 .. _Chromium: http://code.google.com/chromium/
93 .. _WebSockets: http://en.wikipedia.org/wiki/WebSockets
94 .. _HTML5: http://en.wikipedia.org/wiki/Html5
97 Dependencies
98 ------------
100 :Python: >=2.5, python >=2.6 recommended
101 :Pip_: >= 0.8.2
102 :Fabric_: >=1.0.1
103 :VirtualEnv_: >= 1.6.1
105 Pip is required for installing Fabric and a useful tool to install Virtualenv
107 * install pip::
109   $ sudo apt-get install python-pip
111 * devel libraries may be needed for some pip installs::
113   $ sudo apt-get install python-dev
115 * install fabric and virtualenv::
117   $ sudo apt-get install python-virtualenv
118   $ sudo apt-get install fabric
120 .. note:: the use of pip to install system packages is not recommended,
121           please use your system's package manager to install Virtualenv
122           and Fabric.
124 .. _Pip: http://www.pip-installer.org/en/latest/index.html
125 .. _Fabric: http://docs.fabfile.org/en/1.0.1/index.html
126 .. _Virtualenv: http://pypi.python.org/pypi/virtualenv
129 Install with Fabric
130 -------------------
132 Either download and unpack the `latest release`_, or check it out from
133 the repository::
135   $ git clone git://git.osuosl.org/gitolite/ganeti/ganeti_webmgr
137 Switch to project directory
138 (Fabric commands only work from a directory containing a fabfile)::
140   $ cd ganeti_webmgr/
142 Run Fabric to automatically create python virtual environment with
143 required dependencies. Choose either production or development
144 environment
146 * production environment::
148   $ fab deploy
150 * development environment::
152   $ fab dev deploy
154 * activate virtual environment::
156   $ source venv/bin/activate
159 .. _latest release: http://code.osuosl.org/projects/ganeti-webmgr/files
162 Configuration
163 -------------
165 In the project root, you'll find a default settings file called
166 settings.py.dist
168 Copy it to settings.py::
170     $ cp settings.py.dist settings.py
172 If you want to use another database engine besides the default SQLite
173 (not recommended for production), edit settings.py, and edit the
174 following lines to reflect your wishes (*note that postgresql is not
175 supported at this time and the install will fail*, see issue #3237)::
177     DATABASE_ENGINE = ''   # <-- Change this to 'mysql', 'postgresql',
178                                   'postgresql_psycopg2' or 'sqlite3'
179     DATABASE_NAME = ''     # <-- Change this to a database name, or a file for
180                                   SQLite
181     DATABASE_USER = ''     # <-- Change this (not needed for SQLite)
182     DATABASE_PASSWORD = '' # <-- Change this (not needed for SQLite)
183     DATABASE_HOST = ''     # <-- Change this (not needed if database is localhost)
184     DATABASE_PORT = ''     # <-- Change this (not needed if database is localhost)
187 Initialize Database::
189     $ ./manage.py syncdb --migrate
191 Build the search indexes::
193     $ ./manage.py rebuild_index
195     .. note: Running `./manage.py update_index` on a regular basis ensures
196              that the search indexes stay up-to-date when models change
197              in Ganeti Web Manager.
199 Everything should be all set up! Run the development server with::
201     $ ./manage.py runserver
204 Additional configuration for production servers
205 -----------------------------------------------
207 Deploying a production server requires additional setup steps.
209 1. Change the ownership of the *whoosh_index* directory to apache::
211     $ chown apache:apache whoosh_index/
213 2. Change your *SECRET_KEY* and *WEB_MGR_API_KEY* to unique (and
214    hopefully unguessable) strings in your settings.py.
216 3. Configure the `Django Cache Framework`_ to use a production
217    capable backend in *settings.py*.  By default Ganeti Web Manager is
218    configured to use the *LocMemCache* but it is not recommended for
219    production.  Use Memcached or a similar backend.::
221      CACHES = {
222          'default': {
223              'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
224          }
225      }
229 4. For versions >= 0.5 you may need to add the full filesystem path
230    to your templates directory to TEMPLATE_DIRS and remove the relative
231    reference to 'templates'. We've had issues using wsgi not working
232    correctly unless this change has been made.
234 5. Ensure the server has the ability to send emails or you have
235    access to an SMTP server. Set EMAIL_HOST, EMAIL_PORT, and
236    DEFAULT_FROM_EMAIL in settings.py. For more complicated outgoing
237    mail setups, please refer to the django email documentation
238    (http://docs.djangoproject.com/en/1.2/topics/email/)
240 6. Follow the django guide to deploy with apache.
241    (http://docs.djangoproject.com/en/dev/howto/deployment/modwsgi/)
243    Here is an example mod_wsgi file::
245        import os
246        import sys
248        path = '/var/lib/django/ganeti_webmgr'
250        # activate virtualenv
251        activate_this = '%s/venv/bin/activate_this.py' % path
252        execfile(activate_this, dict(__file__=activate_this))
254        # add project to path
255        if path not in sys.path:
256            sys.path.append(path)
258        # configure django environment
259        os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
261        import django.core.handlers.wsgi
262        application = django.core.handlers.wsgi.WSGIHandler()
264 7. Set VNC_PROXY to the hostname of your VNC AuthProxy server in
265    settings.py.  The VNC AuthProxy does not need to run on the same
266    server as Ganeti Web Manager::
268      VNC_PROXY = 'my.server.org:8888'
270 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Install
272 .. _Django Cache Framework: http://docs.djangoproject.com/en/dev/topics/cache/
275 ===============================
276 Ganeti RAPI users and passwords
277 ===============================
279 Before you can start using Ganeti Web Manager, you will need to create a
280 user and password on the Ganeti cluster.
282 Here is an example with user "jack" and password "abc123"::
284     $ echo -n 'jack:Ganeti Remote API:abc123' | openssl md5
286 Add the hash to the RAPI users file and restart ganeti-rapi. Depending
287 on the version of Ganeti you are running, you will need to either use
288 `/var/lib/ganeti/rapi_users` (Ganeti <=2.3.x ) or
289 `/var/lib/ganeti/rapi/users` (Ganeti >=2.4.x ).
291 An example hash entry might look like the following::
293     # Hashed password for jack
294     jack {HA1}54c12257ee9be413f2f3182435514aae write
296 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Ganeti-RAPI-users-and-passwords
299 ===================
300 Importing a Cluster
301 ===================
303 1. Use the admin user created during syncdb to log in.
304 2. Import a cluster:  Clusters -> Add Cluster
305 3. Fill out properties and click save
307 When the cluster is created it will automatically synchronize the list
308 of Virtual Machines with information from the Ganeti cluster.
310 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Importing_a_Cluster
313 ==============================
314 Users, Groups, and Permissions
315 ==============================
317 Permissions may be granted to both clusters and virtual machines. The
318 permissions system is intended to allow users to manage themselves. Any
319 object that can have its permissions edited will have a Users tab.
321 Adding users to objects:
322   1. Navigate to Group, Cluster, or Virtual Machine detail page
323   2. Click Add New User
324   3. Select user or group
325   4. Select permissions
326   5. Save
328 Updating permissions:
329   1. Navigate to Group, Cluster, or Virtual Machine detail page
330   2. Click Users tab
331   3. Click permissions column
332   4. Select permissions and save
334 Deleting permissions:
335   1. Navigate to Group, Cluster, or Virtual Machine detail page
336   2. Click Users tab
337   3. Click the delete icon
339 Deleting a user will remove all permissions, and other properties
340 associated with the user such as cluster quotas.
342 Users may belong to any number of user groups.  User groups can be
343 assigned permissions and quotas just like users.  Users inherit
344 permissions from groups and may act on their behalf to create virtual
345 machines.
347 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions
350 ================
351 Assigning Quotas
352 ================
354 Quotas restrict the usage of cluster resources by users and groups.
355 Default quotas can be set by editing clusters, if no quota is set
356 unlimited access is allowed. This will affect all users and groups.
358 The default quota can be overridden on the cluster users page:
360 1. Clusters -> Cluster -> Users
361 2. Click on the quota
362 3. Edit values
364 Leaving a value empty specifies unlimited access for that resource.
366 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Permissions#Quotas
369 =========================
370 Orphaned Virtual Machines
371 =========================
373 You can find Virtual Machines with no permissions via Admin -> Orphaned VMs.
374 This will force a synchronization of all clusters and display Virtual Machines
375 that do not have any permissions assigned.
377 You only need to grant permissions directly on virtual machines if you are
378 granting access to non-admin users.
380 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Managing_Clusters#Orphaned-Virtual-Machines
383 ============
384 Cache System
385 ============
387 Ganeti Web Manager uses a cache system that stores information about Ganeti
388 clusters in the database. This allows the following::
390       ---  Ganeti  ---
391      /                \
392     /                  \
393  Cluster ->       <-   Bulk
394   Model  <- cache <-  Updater
397 * Permissions are stored in the database and are associated to the cached
398   objects
399 * The cached data can be searched and or filtered
400 * Limits the amount of traffic between the web server and Ganeti cluster.
402 The cache system is transparent and will load cached data automatically when
403 the object is initialized.
405 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/Cache_System
411 Ganeti Web Manager provides an in browser console using noVNC_, an HTML5
412 client.  noVNC requires WebSockets to function. Support for older browsers is
413 provided through a flash applet that is used transparently in the absence of
414 WebSockets.
416 .. _noVNC: https://github.com/kanaka/noVNC
418 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC
420 =============
421 VNC AuthProxy
422 =============
424 VNC Auth proxy [#]_ is required for the console tab to function. VNC
425 servers do not speak websockets and our proxy allows your ganeti cluster
426 to sit behind a firewall, VPN, or NAT.
428 .. [#] http://code.osuosl.org/projects/twisted-vncauthproxy
430 Enabling in settings.py
431 -----------------------
433 Set the host and port that the proxy will be running at with the
434 VNC_PROXY setting. For development this is typically "localhost:8888"
435 but for production you would use the name of the server its running on.
436 See the instructions in settings.py for more details.
438 Starting the Daemon
439 -------------------
441 Twisted VNC Authproxy is started with twistd, the twisted daemon.
442 Eventually we will include init.d scripts for better managing the
443 daemon. You may want to open port 8888 in your firewall for production
444 systems::
446     $ twistd --pidfile=/tmp/proxy.pid -n vncap
448 Starting Flash Policy Server
449 ----------------------------
451 Browsers that do not support WebSockets natively are supported through
452 the use of a flash applet. Flash applets that make use of sockets must
453 retrieve a policy file from the server they are connecting to. Twisted
454 VNCAuthProxy includes a policy server. It must be run separately since
455 it requires a root port. You may want to open port 843 in your firewall
456 for production systems.
458 Start the policy server with twistd::
460     $ sudo twistd --pidfile=/tmp/policy.pid -n flashpolicy
463 Possible issues
464 ---------------
465 You may encounter an issue where twisted fails to start and gives you an
466 error.  This is usually caused by the environment variable PYTHONPATH
467 not being exported correctly if you sudo up to root. To fix it type::
469     $ export PYTHONPATH="."
471 Try executing twisted again and it should work.
473 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/VNC#VNC-Authproxy
475 ========
476 SSH Keys
477 ========
479 Ganeti Web Manager allows users to store SSH Keys. Each virtual machine
480 has a view that will return SSH keys for users with access. This can be
481 used as a Ganeti post-install hook to deploy user's keys on the VMs.
483 To allow VMs to copy keys, copy util/hooks/sshkeys.sh to the instance
484 definition hooks directory on every node in the cluster and make the
485 file executable. Next, add the required variables to the variant config
486 file or main instance definition config file. The config file can be
487 found in util/hooks/sshkeys.conf and includes documentation for each
488 variable.
490 Also see: http://code.osuosl.org/projects/ganeti-webmgr/wiki/PermissionsSSHKeys