1
.. IVLE - Informatics Virtual Learning Environment
2
Copyright (C) 2007-2009 The University of Melbourne
4
.. This program is free software; you can redistribute it and/or modify
5
it under the terms of the GNU General Public License as published by
6
the Free Software Foundation; either version 2 of the License, or
7
(at your option) any later version.
9
.. This program is distributed in the hope that it will be useful,
10
but WITHOUT ANY WARRANTY; without even the implied warranty of
11
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
GNU General Public License for more details.
14
.. You should have received a copy of the GNU General Public License
15
along with this program; if not, write to the Free Software
16
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22
IVLE is a complex piece of software that integrates closely with the
23
underlying system. It can be considered part web service and part local system
24
daemon. Due to the implementation of these parts it is tied to Apache Web
25
Server (mainly due to the use of mod_python) and Linux.
31
IVLE uses mod_python_ to allow Python scripts to be called from Apache. We
32
register the :mod:`ivle.dispatch` module as the ``PythonHandler`` in the
33
associated VirtualHost, allowing us to intercept all HTTP requests to the web
36
The :mod:`ivle.dispatch` module is responsible for mapping requests from the
37
client to the correct application plugin. Plugins can be specified by placing
38
a :file:`*.conf` file into the :file:`/etc/ivle/plugins.d/` directory
39
containing lines of the form :samp:`[{plugin_module}#{classname}]`.
41
.. TODO: Document Plugin Format and Routing Strings
43
In future, this may be ported to a WSGI (:pep:`333`) based dispatch to allow
44
IVLE to be run on web servers other than Apache.
46
.. _mod_python: http://www.modpython.org/
51
IVLE uses the Genshi_ XHTML template system to generate all HTML pages. We
52
have an inheritance-based "views" system. :class:`BaseView` is a class from
53
which all views derive.
55
There are 3 sub-types of :class:`BaseView` (more can be implemented if
59
* browser, console, debuginfo, diff, forum, groups, help, home, logout,
60
settings, subjects, svnlog, tos, tutorial
64
* consoleservice, fileservice, tutorialservice, userservice
66
The apps each derive from one of the above.
69
IVLE used to write its HTML output as a raw stream to an output file, until
70
it was refactored to use Genshi. All apps which haven't yet been refactored
71
properly were ported to use the "raw byte streaming" view.
73
.. _Genshi: http://genshi.edgewall.org/
81
One of the main features of IVLE is it's ability to execute user's code in a
82
customised environment that prevents access to other users files or underlying
83
file system as well as placing basic resource limits to prevent users from
84
accidentally exhausting shared resources such as CPU time and memory.
90
To each user, it appears that they have their own private Unix filesystem
91
containing software, libraries and a home directory to do with what they
92
please. This is mainly done by the setuid root program ``trampoline`` which
93
mounts the users home directory, sets up the users environment, jumps into the
94
user's jail using the :manpage:`chroot(2)` system call and finally drops
95
privileges to the desired user and group.
97
To prevent abuse, ``trampoline`` can only be used by root or one of the uids
98
specified when trampoline is built by ``setup.py build`` (defaults to UID 33,
99
www-data on Debian systems). Since it's one of two C programs involved in IVLE
100
and runs setuid root it is rather security sensitive.
102
.. seealso:: Source code :file:`bin/trampoline/trampoline.c`
105
Base Image Generation
106
---------------------
108
All user jails share a common base image that contains the files required for
109
both IVLE's operation and for executing user code. This base image is
110
generated automatically by the ``ivle-buildjail`` script. This then calls the
111
distribution dependant details in :mod:`ivle.jailbuilder` module. At present
112
we only support building jails for Debian derived systems using
113
:program:`debootstrap`.
115
The contents of the base image contains a few core packages required for the
116
operation of IVLE - Python and the Python CJSON and SVN libraries. Other
117
options that can be configured in :file:`/etc/ivle/ivle.conf` are the file
118
mirror that debootstrap should use, the suite to build (such as hardy or
119
jaunty), extra apt-sources, extra apt keys and any additional packages to
122
To prevent users from altering files in the base image we change the
123
permissions of :file:`/tmp`, :file:`/var/tmp` and :file:`/var/lock` to not be
124
world writeable and check that no other files are world writeable.
126
Finally we make the user dependent :file:`/etc/passwd` and
127
:file:`/etc/ivle/ivle.conf` symlinks to files in the :file:`/home` directory
128
so that they will be used when we mount a user's home directory.
130
Mounting Home Directories
131
-------------------------
133
To give the appearance of a private file system we need to merge together a
134
user's local home directory with the base image.
135
To achieve this, IVLE uses the *bind mount* feature of Linux, which allows
136
directories to be accessible from another location in the file system. By
137
carefully bind-mounting the jail image as read-only and then bind-mounting the
138
user's :file:`/home` and :file:`/tmp` directory data over the top, we create a
139
jail with only three bind mounts and at virtually no file system overhead.
142
IVLE has historically used numerous solutions to this problem, which are
143
chronicled here to avoid the same mistakes being made again.
145
In the first release of IVLE this was done offline by hard-linking all the
146
files into the target directory, but for a large number of users, this
147
process can take several hours, and also runs the risk of exhausting
148
the number of inodes on the underlying file system.
150
The second solution was to use `AUFS <http://aufs.sourceforge.net/>`_ to
151
mount the user's home directory over a read-only version of the base on
152
demand. This was implemented as part of ``trampoline`` and used a secondary
153
program ``timount`` (see :file:`bin/timount/timount.c`), run at regular
154
intervals, to unmount unused jails. This used the :const:`MNT_EXPIRE` flag
155
for :manpage:`umount(2)` (available since Linux 2.6.8) that only unmounts a
156
directory if it hasn't been accessed since the previous call with
159
While quite effective, AUFS appeared to cause NFS caching issues when IVLE
160
was run as a cluster, and as its inclusion status in future Linux
161
distributions is questionable, the developers elected to use the much older
162
bind mount feature instead.
167
Before running the specified program in the users jail we need to
168
:manpage:`chroot(2)` into the users jail and update the processes environment
169
so that we have the correct environment variables and user/group ids.
171
At this stage we also may apply a number of resource limits (see
172
:manpage:`setrlimit`) to prevent run away processes (such as those containing
173
infinite loops or "fork bombs") from exhausting all system resources. The
174
default limits are on maximum address space (:const:`RLIMIT_AS`), process data
175
space (:const:`RLIMIT_DATA`), core dump size (:const:`RLIMIT_CORE`), CPU time
176
(:const:`RLIMIT_CPU`), file size (:const:`RLIMIT_FSIZE`) and number of
177
processes that may be spawned (:const:`RLIMIT_NPROC`).
179
Unfortunately due to glibc's :manpage:`malloc(2)` implementation being able to
180
allocate memory using :manpage:`mmap(2)`, :const:`RLIMIT_DATA` does not
181
provide an effective limit on the amount of memory that a process can allocate
182
(short of applying a kernel patch). Thus the only way to limit memory
183
allocations is by placing limits on the address space, but this can cause
184
problems with certain applications that allocate far larger address spaces
185
than the real memory used. For this reason :const:`RLIMIT_AS` is currently set
189
.. ref-python-console
194
IVLE provides a web based programming console, exposing similar features to
195
Python's command line console. It is built around python script
196
:file:`services/python-console` which opens up a socket to which `JSON`_
197
encoded chat requests can be made. A new console is typically from launched on
198
demand by the web client to the HTTP API, which in turn calls the wrapper
199
class :class:`ivle.console.Console` to start a new console in the user's jail.
201
.. _JSON: http://json.org
204
.. _ref-usermgt-server:
206
User Management Server
207
======================
209
The **User Management Server** is a daemon responsible for handling privileged
210
actions on IVLE and should be launched along with IVLE. It is primarily
213
* Creating user jails, Subversion repositories, and Subversion authentication
215
* Creating group Subversion repositories.
216
* Rebuilding Subversion authorization files.
218
Communication with the Server is done using the `Chat Protocol <ref-chat>`_.
219
To prevent unauthorized use, communication with the User Management Server
220
requires that a *shared secret* be used to communicate with the server. This
221
secret is stored in the `magic` variable in the `[usrmgt]` section of
222
:file:`/etc/ivle/ivle.conf`.
224
The User Management Server is called almost exclusively from the
225
:mod:`ivle.webapp.userservice` module.
227
.. seealso:: Source code :file:`services/usrmgt-server`
234
**Chat** is our JSON_-based client/server communication protocol used in
235
communicating to `Python Console <ref-python-console>`_ processes and `User
236
Management Server <ref-usrmgt-server>`_. Since it is JSON-based it can be
237
called from either Python or JavaScript.
241
The protocol is a fairly simple client/server based one consisting of a single
242
JSON object. Before communication starts a shared secret :const:`MAGIC` must
243
be known by both parties. The shared secret is then used to form a
244
'keyed-Hash Message Authentication Code' to ensure that the content is valid
245
and not been modified in transit.
247
The client request takes the following form::
254
where :const:`DATA` is any valid JSON value and :const:`HASH` is an string
255
containing the MD5 hash of the :const:`DATA` appended to :const:`MAGIC` and
258
The server will respond with a JSON value corresponding to the request.
259
If an error occurs then a special JSON object will be returned of the
265
"traceback": TRACEBACK
268
where :const:`NAME` is a JSON string of the exception type (such as
269
'AttributeError'), :const:`VALUE` is the string value associated with the
270
exception and :const:`TRACEBACK` is a string of the traceback generated by the
271
server's exception handler.
273
.. seealso:: Source code :file:`ivle/chat.py`
279
Along with traditional file system access, IVLE allows users to version their
280
files using Subversion_. Much like how Subversion workspaces are used on a
281
standard desktop, workspaces are checked out into users home directories where
282
they can be manipulated through a series of AJAX requests to the
285
Like all other user file system actions, version control actions need to be
286
executed inside the user's :ref:`jail <ref-jail>`. Requests are made to the
287
``fileservice`` app in :mod:`ivle.webapp.fileservice` which then calls the
288
``fileservice`` CGI script using ``trampoline``. This script is simply a
289
wrapper around :mod:`ivle.fileservice_lib` which actually contains the code to
290
handle each of the actions.
292
Manipulation of the Subversion workspaces is done using the pysvn_ library.
294
.. _Subversion: http://subversion.tigris.org/
295
.. _pysvn: http://pysvn.tigris.org/
301
Each user is allocated a Subversion repository when their :ref:`Jail
302
<ref-jail>` is created by the :ref:`User Management Server
303
<ref-usermgt-server>`. Repository are stored in the location specified by
304
``[paths] [[svn]] repo_path`` in :file:`/etc/ivle/ivle.conf` (by default
305
:file:`/var/lib/ivle/svn/repositories/`). User repositories are stored in the
306
:samp:`users/{USERNAME}/` subdirectory and group repositories in
307
:samp:`groups/{SUBJECT}_{YEAR}_{SEMESTER}_{GROUP}`.
311
While it would be possible to give users direct access to their repository
312
using Subversion's file backend, this would allow users to potentially
313
modify the history of any repository that they had access to. To ensure
314
repository integrity, all Subversion interaction must be done remotely.
320
These repositories are served by Apache using ``mod_dav_svn`` allowing access
321
over Subversion's WebDAV HTTP or HTTPS backends. Users are authenticated using
322
a randomly generated key which is stored in the database and is made available
323
to each user inside their Jail (``svn_pass`` property inside
324
:file:`/home/.ivle.conf`). This key is automatically provided when doing
325
Subversion actions, but can be manually entered when accessing a users
326
repository from an external Subversion client such as with :samp:`svn checkout
327
{svn_addr}/users/{USERNAME}/ workspace`.
329
Repository permissions for ``AuthzSVNAccessFILE`` are automatically generated
330
and placed in the file located at ``[paths] [[svn]] conf`` for user
331
repositories and ``[paths] [[svn]] group_conf`` for group repositories. User
332
authentication keys for ``AuthUserFile`` are stored in the file located at
333
``[path] [[svn]] auth_ivle``. These will be regenerated each time user or
334
group repository settings change.
343
.. TODO: Not yet merged
added
removed
doc/dev/architecture.rst
