131
126
-------------------------
133
128
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.
129
user's local home directory with the base image. In the first release of IVLE
130
this was done off-line by hardlinking all the files into the target directory,
131
but for more than a handful of users this process could take several hours and
132
also ran the risk of exhausting inodes on the underlying file system.
134
The first solution was to use `AUFS <http://aufs.sourceforge.net/>`_ to mount
135
the user's home directory over a read-only version of the base on demand. This
136
was implemented as part of ``trampoline`` and used a secondary program
137
``timount`` (see :file:`bin/timount/timount.c`) run at regular intervals to
138
unmount unused jails. This uses the :const:`MNT_EXPIRE` flag for
139
:manpage:`umount(2)` (available since Linux 2.6.8) that only unmounts a
140
directory if it hasn't been accessed since the previous call with
143
While quite effective, AUFS appears to cause NFS caching issues when IVLE is
144
run as a cluster as well as questionable inclusion status in newer
145
distributions. The current system used in IVLE the much older *bind mount*
146
feature which allows directories to be accessible from another location in the
147
file system. By carefully read-only bind mounting the jail image and then bind
148
mounting the user's :file:`/home` and :file:`/tmp` directory data over the top
149
we can create a jail with only three bind mounts and at virtually no
164
152
Entering the Jail
165
153
-----------------
280
249
exception and :const:`TRACEBACK` is a string of the traceback generated by the
281
250
server's exception handler.
283
.. seealso:: Source code :file:`ivle/chat.py`
252
See :file:`ivle/chat.py` for details.
289
Along with traditional file system access, IVLE allows users to version their
290
files using Subversion_. Much like how Subversion workspaces are used on a
291
standard desktop, workspaces are checked out into users home directories where
292
they can be manipulated through a series of AJAX requests to the
295
Like all other user file system actions, version control actions need to be
296
executed inside the user's :ref:`jail <ref-jail>`. Requests are made to the
297
``fileservice`` app in :mod:`ivle.webapp.fileservice` which then calls the
298
``fileservice`` CGI script using ``trampoline``. This script is simply a
299
wrapper around :mod:`ivle.fileservice_lib` which actually contains the code to
300
handle each of the actions.
302
Manipulation of the Subversion workspaces is done using the pysvn_ library.
304
.. _Subversion: http://subversion.tigris.org/
305
.. _pysvn: http://pysvn.tigris.org/
311
Each user is allocated a Subversion repository when their :ref:`Jail
312
<ref-jail>` is created by the :ref:`User Management Server
313
<ref-usrmgt-server>`. Repository are stored in the location specified by
314
``paths/svn/repo_path`` in :file:`/etc/ivle/ivle.conf` (by default
315
:file:`/var/lib/ivle/svn/repositories/`). User repositories are stored in the
316
:samp:`users/{USERNAME}/` subdirectory and group repositories in
317
:samp:`groups/{SUBJECT}_{YEAR}_{SEMESTER}_{GROUP}`.
321
While it would be possible to give users direct access to their repository
322
using Subversion's file backend, this would allow users to potentially
323
modify the history of any repository that they had access to. To ensure
324
repository integrity, all Subversion interaction must be done remotely.
330
These repositories are served by Apache using ``mod_dav_svn`` allowing access
331
over Subversion's WebDAV HTTP or HTTPS backends. Users are authenticated using
332
a randomly generated key which is stored in the database and is made available
333
to each user inside their jail (``svn_pass`` property inside
334
:file:`/home/.ivle.conf`). This key is automatically provided when doing
335
Subversion actions, but can be manually entered when accessing a user's
336
repository from an external Subversion client such as with :samp:`svn checkout
337
{svn_addr}/users/{USERNAME}/ workspace`.
339
Repository permissions for ``AuthzSVNAccessFile`` are automatically generated
340
and placed in the file specified by the ``paths/svn/conf`` config option
341
(usually ``/var/lib/ivle/svn/svn.conf``) for user repositories and the
342
``paths/svn/group_conf`` option for group repositories (usually
343
``/var/lib/ivle/svn/svn-group.conf``). User authentication keys for
344
``AuthUserFile`` are stored in the file specified by ``paths/svn/auth_ivle``,
345
usually ``/var/lib/ivle/svn/ivle.auth``. These will be regenerated each time
346
user or group repository settings change.
352
Worksheets provide a way for users to be able to attempt a set of coding
353
exercises along with accompanying instructions. In the past worksheets were
354
created directly using an XML format, but this has been deprecated in favour
355
of being generated automatically from reStructuredText.
357
Worksheets are now stored in the database as a :class:`Worksheet` object (see
358
:file:`ivle/database.py`). This allows them to be treated with the same
359
access permissions available to other objects and lays down the ground work
360
for providing versioned worksheets.
366
When users submit an exercise, the user's solution is tested against a series
367
of test cases which can be used to check if a solution is acceptable. Almost
368
all the behavior for exercises is contained within
369
:file:`ivle/webapp/tutorial/test/TestFramework.py`.
372
The TestFramework module is one of the oldest and most complicated in
373
IVLE, largely taken directly from the IVLE prototype. As such it has a
374
design that doesn't quite match the current architecture of IVLE, such as
375
using slightly different terminology and having a few testing facilities
376
that are untested or untested. It requires a substantial rewrite and
377
comprehensive test suite to be developed.
379
At the top level exists the :class:`Exercise` object (known as ``TestSuite``
380
in :file:`TestFramework.py`). This object encompasses the entire collection of
381
tests for a given exercise and details such as the exercise name, provided
382
solution and any "include code" (Python code available for all test cases, but
383
not the user's submission).
385
Each exercise may contain one or more :class:`TestSuite` objects (known as
386
``TestCase`` in :file:`TestFramework.py`. A test suite is a collection of
387
tests that run with some sort of common input - be that stdin contents, a
388
virtual file system configuration (presently disabled), inputs to particular
389
function or defining the contents of one or more variables. A test suite will
390
typically run until the first test case fails, but can be configured to
391
continue running test cases even after one has failed. Exceptions raised by
392
submitted code will typically cause the test to fail except if it is marked as
393
an "allowed exception".
395
Individual units to be tested (something that can pass or fail) are contained
396
within :class:`TestCase` objects (known as ``TestCaseParts`` in
397
:file:`TestFramework.py`). A test case can test the value of source code text,
398
the function return value (Will be ``None`` for scripts), stdout contents,
399
stderr contents, name of any raised exception and contents of the virtual file
400
system (presently disabled) of code submitted by users. These checks are
401
contained in a :class:`TestCasePart`. In addition, a normalisation function or
402
custom comparison function can be used instead of comparing the raw values
403
directly. By default, the value of each check will be ignored unless
404
overidden by a test case part.
413
URLs are resolved with a small IVLE-specific object publishing framework --
414
that is, resolution is implemented as traversal through an object graph. The
415
framework lives in :mod:`ivle.webapp.publisher`, and has an extensive test
418
This object graph is constructed by the dispatcher. Any plugin class deriving
419
from ViewPlugin will be searched for ``forward_routes``, ``reverse_routes``
420
and ``views`` sequences. Everything is class-based -- an object's routes
421
and views are determined by its class.
423
Forward routes handle resolution of URLs to objects. Given a source object
424
and some path segments, the route must calculate the next object.
425
A forward route is a tuple of ``(source class, intermediate path segments,
426
function, number of subsequent path segments to consume)``, or simply a
427
reference to a decorated function (see :mod:`ivle.webapp.admin.publishing`
428
for decoration examples). The function must return the next object in the
431
A reverse route handles URL generation for an object. Given just an object,
432
it must return a tuple of ``(previous object, intermediate path segments)``.
433
This creates a chain of objects and path segments until the root is reached.
434
Due to IVLE's lack of a utility framework, reverse routes at the root of the
435
URL space need to refer to the root object with the magical
436
:mod:`ivle.webapp.publisher.ROOT`.
438
Views are registered with a tuple of ``(source class, intermediate path segments,
441
In all of the above, "intermediate path segments" can either be a single
442
segment string, or a sequence of multiple strings representing multiple
446
While many applications prefer a pattern matching mechanism, this did not
447
work out well for IVLE. Our deep URL structure and multitude of nested
448
objects with lots of views meant that match patterns had to be repeated
449
tediously, and views required many lines of code to turn a match into a
450
context object. It also made URL generation very difficult.
452
The simple object publishing framework allows views to be registered with
453
just one line of code, getting their context object for free. URL
454
generation now comes at a cost of approximately one line of code per class,
455
and breadcrumbs are easy too. The reduced code duplication also improves
264
.. TODO: Not yet merged
added
removed
doc/dev/architecture.rst
