24
This page describes the configuration of IVLE. This consists of populating the
25
:file:`ivle.conf` file and configuring Apache to serve the IVLE webapp and
26
Subversion repositories.
28
.. _ref-configuration-options:
24
This page describes the configuration of IVLE, which is done by editing the
25
file :file:`ivle.conf`, located by default in :file:`/etc/ivle/ivle.conf`.
30
27
Configuration options
31
28
=====================
33
Most of the configuration of IVLE is done by editing the file
34
:file:`ivle.conf`, located by default in :file:`/etc/ivle/ivle.conf`. These
35
settings are required as part of the :ref:`install process <ref-install>`,
36
though the :ref:`admin script <ref-admin-scripts>` :program:`ivle-config` can
37
be used to propagate most of these settings.
39
It uses the `ConfigObj`_ text format which is heavily based on the 'INI' text
40
format. Of particular note, lists with single items need to be terminated
41
with a ',' otherwise it will be treated as a list of characters (usually not
44
.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
48
32
Configuration of URLs used by the IVLE webapp.
244
Settings for configuring external user authentication with
245
:ref:`authentication modules <ref-auth-modules>` and automatic subject
246
enrollment with :ref:`subject pulldown modules
247
<ref-subject-pulldown-modules>`.
228
Settings for configuring external user authentication with `authentication
229
modules <ref-auth-modules>`_ and automatic subject enrollment with `subject
230
pulldown modules <ref-subject-pulldown-modules>`_.
249
232
.. describe:: modules
251
234
:type: string_list(default=list())
253
List of :ref:`authentication modules <ref-auth-modules>` to attempt to
236
List of `authentication modules <ref-auth-modules>`_ to attempt to
254
237
authenticate with if a user does not have a password set in the local
332
315
:type: string_list(default=list())
334
317
A list of extra source locations to be added to the jail builder (such as
335
for site specific packages). For example, 'deb
336
http://ppa.launchpad.net/wgrant/ivle/ubuntu/ hardy main,'.
318
for site specific packages).
338
320
.. describe:: extra_packages
340
322
:type: string_list(default=list())
342
324
A list of extra packages to be installed in addition to the core packages
343
required for IVLE. For example, 'python-scipy, python-networkx,'
327
.. FIXME: Is this correct. Is it extra user packages (such as
328
python-scipy) or all packages that aren't in a standard debootstrap build
329
(such as python-svn and python-cjson)?.
345
331
.. describe:: extra_keys
349
335
Any extra package signing keys to accept as correctly validate installed
350
336
packages. Typically used for validating ``extra_sources`` packages.
352
Keys can be provided in tripple quoted blocks. For multiple keys, simply
353
concatinate the key blocks. For example::
355
extra_keys = '''-----BEGIN PGP PUBLIC KEY BLOCK-----
358
mI0ESXMxaQEEAMdundmJeTMUcB6fRXGQ3WJH+5hlfj3ehurF3u0ubr4sQpxfJvl6/KV4UcOC
359
RvK4aufNInJxKrT6xvzdMNE9z5NO/ZVZdkr2NfcRO/0Yxgmaft9qjxfV+3NEBrvJkqm8ApVO
360
hsxFW6VWyeHBELSiNxNGToPp+2g3i5VAlWbtzaapABEBAAG0H0xhdW5jaHBhZCBQUEEgZm9y
361
IFdpbGxpYW0gR3JhbnSIRgQQEQIABgUCSXOMJAAKCRABz5LwpyR9xeXXAJ97VdeI3lLDvyM9
362
TLeb48Ylj8dWdQCfcOJDRGfjRu9PI2+ekIoV8TqaC0GItgQTAQIAIAUCSXMxaQIbAwYLCQgH
363
AwIEFQIIAwQWAgMBAh4BAheAAAoJECp86x2KYmtCEBED/0aRhr7wKmA/nyX2rUN/1dpyYT2T
364
khxJT0F7l91/PGRkLUdvcX81ceRcYeiiR1x8N1tL7pwrTWZwaQ/HTHF19ZAXjptnn8zaLKUc
365
VwhOrUdFE2FzNo42BWpXQAuJuBCG3DeIXDDuPRvtL+sx7h8PD/DlE5RsTaztkkbWdpkMtJp9
367
-----END PGP PUBLIC KEY BLOCK-----
368
-----BEGIN PGP PUBLIC KEY BLOCK-----
369
Version: GnuPG v1.4.9 (GNU/Linux)
371
mQGiBEFEnz8RBAC7LstGsKD7McXZgd58oN68KquARLBl6rjA2vdhwl77KkPPOr3O
372
YeSBH/voUsqausJfDNuTNivOfwceDe50lbhq52ODj4Mx9Jg+4aHn9fmRkIk41i2J
373
3hZiIGPACY/FsSlRq1AhBH2wZG1lQ45W/p77AeARRehYKJP9HY+1h/uihwCgrVE2
374
VzACJLuZWHbDsPoJaNQjiFcEAKbUF1rMyjd1xJM7bZeXbs8c+ohUo/ywSI/OIr8n
376
RwIbDAAKCRBAl26vQ30FtdxYAJsFjU+xbex7gevyGQ2/mhqidES4MwCggqQyo+w1
379
-----END PGP PUBLIC KEY BLOCK-----
338
.. note:: Cannot have triple-quoted list members.
407
365
Apache configuration
408
366
====================
409
Apache is used in IVLE for hosting of the IVLE web application and hosting
410
Subversion repositories over WebDAV. Typically the Subversion repository will
411
run on the Master server and the Web Application will be run on a collection
412
of slaves. It is also possible to combine the two function together to run as
418
The IVLE web application runs on Apache using ``mod_python``. An example
419
configuration is provided in the file :file:`examples/config/apache.conf`.
421
At minimum the following settings must be specified:
423
.. describe:: ServerName
425
Should be the formal hostname of the server, typically one that users will
426
use to access IVLE. For example, 'ivle.org'.
428
.. describe:: ServerAlias
430
Should be set to the value of ``[urls] public_host`` that is specified in
431
:file:`ivle.conf`. This is to ensure that Apache will correctly handle
432
requests for the public content.
434
.. describe:: SetHandler
436
Must be ``mod_python``
438
.. describe:: PythonHandler
440
Must be ``ivle.dispatch``
442
.. describe:: PythonOption mod_python.file_session.database_directory
444
Session directory for mod_python. This must be a shared directory between
445
all Slave servers, in particular when operating through a load balancer.
446
If not provided then users will encounter inconsistent behavior such as
447
being thrown back to the login screen after logging in.
449
Optional settings are:
451
.. describe:: PythonOption mod_python.session.cookie_name
453
The name to be set for cookies rather than the one automatically generated
454
by mod_python. For example, 'ivle'.
456
.. describe:: PythonDebug
458
If this option is set, any uncaught errors from mod_python will be sent to
459
the browser rather than being sent to the error log. It is recommended
460
that this setting is only used for development or debugging.
462
Subversion Repository
463
---------------------
464
IVLE also uses Apache to provide HTTP access to user's Subversion repositories
465
using ``mod_dav_svn``. Typically this is run on a single, stand alone server;
466
though it may be run in conjunction with the Web Application. An example
467
configuration is provided in the file :file:`examples/config/apache-svn.conf`.
468
IVLE will automatically generate password hash and repository permission files
469
that are used to control access to the repositories.
471
IVLE expects to find the paths ``users/`` and ``groups/`` at the URL provided
472
by the value of ``[urls] svn_addr`` set in :file:`ivle.conf`. Thus there
473
should be two ``Location`` clauses configured, one for users and one for
483
.. describe:: SVNParentPath
485
Directory where user repositories are stored. Should be the value of
486
``[path] [[svn]] repo_path`` in :file:`ivle.conf` with 'users' appended.
487
For example, '/var/lib/ivle/svn/repositories/users'.
489
.. describe:: AuthzSVNAccessFile
491
Location of the configuration file used to assign permissions to user
492
repositories. Should be the same value as ``[path] [[svn]] conf`` in
495
.. describe:: Require
497
Must be ``valid-user``
499
.. describe:: AuthType
503
.. describe:: AuthName
505
The name that should appear on authentication requests. For example, 'IVLE
506
Subversion repository'.
508
.. describe:: AuthUserFile
510
Location of the password hash file for Subversion users. Should be the
511
same as the value of ``[path] [[svn]] auth_ivle``. For example,
512
'/var/lib/ivle/svn/ivle.auth'.
521
.. describe:: SVNParentPath
523
Directory where user repositories are stored. Should be the value of
524
``[path] [[svn]] repo_path`` in :file:`ivle.conf` with 'groups' appended.
525
For example, '/var/lib/ivle/svn/repositories/groups'.
527
.. describe:: AuthzSVNAccessFile
529
Location of the configuration file used to assign permissions to group
530
repositories. Should be the same value as ``[path] [[svn]] group_conf`` in
533
.. describe:: Require
535
Must be ``valid-user``
537
.. describe:: AuthType
541
.. describe:: AuthName
543
The name that should appear on authentication requests. For example, 'IVLE
544
Subversion repository'.
546
.. describe:: AuthUserFile
548
Location of the password hash file for Subversion users. Should be the
549
same as the value of ``[path] [[svn]] auth_ivle``. For example,
550
'/var/lib/ivle/svn/ivle.auth'.
added
removed
doc/man/config.rst
