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
18
.. _ref-configuring-ivle:
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:
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>` and
36
for actual running of IVLE.
38
It uses the `ConfigObj`_ text format which is heavily based on the 'INI' text
41
.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
45
Configuration of URLs used by the IVLE webapp.
49
:type: string(default="/")
51
Path on HTTP server that IVLE is served from.
53
.. describe:: public_host
57
The server goes into "public mode" if the browser sends a request with
58
this host. This is for security reasons - we only serve public student
59
files on a separate domain to the main IVLE site.
60
Public mode does not use cookies, and serves only public content.
61
Private mode (normal mode) requires login, and only serves files relevant
62
to the logged-in user. e.g. 'public.ivle.org'
64
.. describe:: svn_addr
68
The base url for accessing subversion repositories. e.g.
73
Configuration for IVLE installation and data paths.
77
:type: string(default="/usr/local")
79
The prefix that is prepended to installation paths.
83
:type: string(default="/var/lib/ivle")
85
Directory where IVLE data such as user jails will be stored.
89
:type: string(default="/var/log/ivle")
91
Directory where IVLE log files such as :file:`ivle_error.log` will be
95
:type: string(default="${prefix}/share/ivle")
97
Directory where IVLE shared data such as ``usrmgt-server``,
98
``python-console`` and services will be installed.
102
:type: string(default="${prefix}/lib/ivle")
104
Directory where IVLE libraries such as ``trampoline`` and ``timount`` will
109
Configuration paths for user `Jails <ref-jail>`_.
113
:type: string(default="${data}/jailmounts"))
115
Directory where complete jails will be mounted.
120
:type: string(default="${data}/jails")
122
Directory where user specific jail content will be stored.
124
.. describe:: template
126
:type: string(default="${src}/__base__")
128
Directory where template file system for each jail will be stored.
130
.. describe:: template_build
132
:type: string(default="${src}/__base_build__")
134
Directory where template file system will be built before being moved to
135
the ``template`` directory.
139
Configuration paths for Subversion repositories.
143
:type: string(default="${data}/svn")
145
Directory where Subversion data will be stored
149
:type: string(default="${base}/svn.conf")
151
Location of Subversion WebDAV AuthzSVNAccessFile configuration file for
152
user repositories will be stored.
154
.. describe:: group_conf
156
:type: string(default="${base}/svn-group.conf")
158
Location of Subversion WebDAV AuthzSVNAccessFile configuration file for
159
group repositories will be stored.
161
.. describe:: repo_path
163
:type: string(default="${base}/repositories")
165
Location where user and group repositories will be stored.
167
.. describe:: auth_ivle
169
:type: string(default="${base}/ivle.auth")
171
Location where Subversion WebDAV AuthUserFile password hash file will be
176
Configuration of `media serving <ref-media-serving>`_.
178
.. describe:: version
180
:type: string(default=None)
182
Media files such as images, CSS and JavaScript are aggressively cached in
183
IVLE. If this value is set then IVLE will send media URLs containing this
184
version number and content will be served with an ``Expires`` header set a
185
year in the future. This means that the client should only request a media
186
URL once and use the cached copy from then on. This version number should
187
be incremented each time any media is changed (typically this should just
188
be set to the IVLE release number) so that updated media will be sent to
191
If not provided or set to :const:`None`, IVLE will use standard browser
196
Configuration details for external media dependencies used by IVLE.
200
:type: string(default="/usr/share/javascript/jquery")
202
Directory where jQuery library is installed.
207
Configuration for the PostgreSQL database that IVLE uses.
211
:type: string(default="localhost")
213
Hostname of database IVLE server.
217
:type: integer(default=5432)
219
Port the database runs on.
223
:type: string(default="ivle")
225
Name of the IVLE database on the database server.
227
.. describe:: username
231
Username which IVLE uses on the database server.
233
.. describe:: password
237
Password which IVLE uses for authentication with the database server.
241
Settings for configuring external user authentication with `authentication
242
modules <ref-auth-modules>`_ and automatic subject enrollment with `subject
243
pulldown modules <ref-subject-pulldown-modules>`_.
245
.. describe:: modules
247
:type: string_list(default=list())
249
List of `authentication modules <ref-auth-modules>`_ to attempt to
250
authenticate with if a user does not have a password set in the local
253
.. describe:: ldap_url
255
:type: string(default=None)
257
URL of the LDAP server to be used by authentication modules.
259
.. describe:: ldap_format_string
261
:type: string(default=None)
264
.. describe:: subject_pulldown_modules
266
:type: string_list(default=list())
268
List of `subject pulldown modules <ref-subject-pulldown-modules>`_ to be
269
checked when a user signs into IVLE to see what subjects a student is
274
Settings for the `User Management Server <ref-usrmgt-server>`_.
278
:type: string(default="localhost")
280
The hostname where the User Management Server is running.
284
:type: integer(default=2178)
286
The port that the User Management Server is running on.
292
The shared secret used to secure communication between IVLE Web
293
Application and the User Management Server.
297
Options that control how the `Jail <ref-jail>`_ is built.
299
.. describe:: devmode
301
:type: boolean(default=False)
303
If set, copies IVLE files from the local machine into the jail rather than
304
installing them from a package.
308
If the Python site packages directory differs between the local
309
machine and the jail (such as if different versions of Python are
310
installed) you will need to supply the site packages to be installed
311
with the ``--python-site-packages`` option to ``ivle-buildjail``.
315
:type: string(default="hardy")
317
Which suite the jail will build with. This need not be the same as what
318
the local machine is running.
322
:type: string(default="http://archive.ubuntu.com/ubuntu")
324
The location of a HTTP mirror containing the specified suite.
326
.. describe:: extra_sources
328
:type: string_list(default=list())
330
A list of extra source locations to be added to the jail builder (such as
331
for site specific packages).
333
.. describe:: extra_packages
335
:type: string_list(default=list())
337
A list of extra packages to be installed in addition to the core packages
340
.. FIXME: Is this correct. Is it extra user packages (such as
341
python-scipy) or all packages that aren't in a standard debootstrap build
342
(such as python-svn and python-cjson)?.
344
.. describe:: extra_keys
346
:type: string(default=None)
348
Any extra package signing keys to accept as correctly validate installed
349
packages. Typically used for validating ``extra_sources`` packages.
351
.. note:: Cannot have triple-quoted list members.
356
User specific settings that are added to a user's :file:`ivle.conf` file
361
This should be in a user-specific place but since we're worried a user
362
may delete his/her .conf file, we put it here for now). These properties
363
**should not** be set in the server's :file:`/etc/ivle/ivle.conf`.
367
:type: string(default=None)
369
The login name of the user.
371
.. describe:: svn_pass
373
:type: string(default=None)
375
The key used to access repositories on the Subversion server.
380
Apache is used in IVLE for hosting of the IVLE web application and hosting
381
Subversion repositories over WebDAV. Typically the Subversion repository will
382
run on the Master server and the Web Application will be run on a collection
383
of slaves. It is also possible to combine the two function together to run as
389
The IVLE web application runs on Apache using ``mod_python``. An example
390
configuration is provided in the file :file:`examples/config/apache.conf`.
392
At minimum the following settings must be specified:
394
.. describe:: ServerName
396
Should be the formal hostname of the server, typically one that users will
397
use to access IVLE. For example, 'ivle.org'.
399
.. describe:: ServerAlias
401
Should be set to the value of ``[urls] public_host`` that is specified in
402
:file:`ivle.conf`. This is to ensure that Apache will correctly handle
403
requests for the public content.
405
.. describe:: SetHandler
407
Must be ``mod_python``
409
.. describe:: PythonHandler
411
Must be ``ivle.dispatch``
413
.. describe:: PythonOption mod_python.file_session.database_directory
415
Session directory for mod_python. This must be a shared directory between
416
all Slave servers, in particular when operating through a load balancer.
417
If not provided then users will encounter inconsistent behavior such as
418
being thrown back to the login screen after logging in.
420
Optional settings are:
422
.. describe:: PythonOption mod_python.session.cookie_name
424
The name to be set for cookies rather than the one automatically generated
425
by mod_python. For example, 'ivle'.
427
.. describe:: PythonDebug
429
If this option is set, any uncaught errors from mod_python will be sent to
430
the browser rather than being sent to the error log. It is recommended
431
that this setting is only used for development or debugging.
433
Subversion Repository
434
---------------------
435
IVLE also uses Apache to provide HTTP access to user's Subversion repositories
436
using ``mod_dav_svn``. Typically this is run on a single, stand alone server;
437
though it may be run in conjunction with the Web Application. An example
438
configuration is provided in the file :file:`examples/config/apache-svn.conf`.
439
IVLE will automatically generate password hash and repository permission files
440
that are used to control access to the repositories.
442
IVLE expects to find the paths ``users/`` and ``groups/`` at the URL provided
443
by the value of ``[urls] svn_addr`` set in :file:`ivle.conf`. Thus there
444
should be two ``Location`` clauses configured, one for users and one for
454
.. describe:: SVNParentPath
456
Directory where user repositories are stored. Should be the value of
457
``[path] [[svn]] repo_path`` in :file:`ivle.conf` with 'users' appended.
458
For example, '/var/lib/ivle/svn/repositories/users'.
460
.. describe:: AuthzSVNAccessFile
462
Location of the configuration file used to assign permissions to user
463
repositories. Should be the same value as ``[path] [[svn]] conf`` in
466
.. describe:: Require
468
Must be ``valid-user``
470
.. describe:: AuthType
474
.. describe:: AuthName
476
The name that should appear on authentication requests. For example, 'IVLE
477
Subversion repository'.
479
.. describe:: AuthUserFile
481
Location of the password hash file for Subversion users. Should be the
482
same as the value of ``[path] [[svn]] auth_ivle``. For example,
483
'/var/lib/ivle/svn/ivle.auth'.
492
.. describe:: SVNParentPath
494
Directory where user repositories are stored. Should be the value of
495
``[path] [[svn]] repo_path`` in :file:`ivle.conf` with 'groups' appended.
496
For example, '/var/lib/ivle/svn/repositories/groups'.
498
.. describe:: AuthzSVNAccessFile
500
Location of the configuration file used to assign permissions to group
501
repositories. Should be the same value as ``[path] [[svn]] group_conf`` in
504
.. describe:: Require
506
Must be ``valid-user``
508
.. describe:: AuthType
512
.. describe:: AuthName
514
The name that should appear on authentication requests. For example, 'IVLE
515
Subversion repository'.
517
.. describe:: AuthUserFile
519
Location of the password hash file for Subversion users. Should be the
520
same as the value of ``[path] [[svn]] auth_ivle``. For example,
521
'/var/lib/ivle/svn/ivle.auth'.
added
removed
doc/man/config.rst
