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>`,
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
Configuration of URLs used by the IVLE webapp.
52
:type: string(default="/")
54
Path on HTTP server that IVLE is served from.
56
.. describe:: public_host
60
The server goes into "public mode" if the browser sends a request with
61
this host. This is for security reasons - we only serve public student
62
files on a separate domain to the main IVLE site.
63
Public mode does not use cookies, and serves only public content.
64
Private mode (normal mode) requires login, and only serves files relevant
65
to the logged-in user. e.g. 'public.ivle.org'
67
.. describe:: svn_addr
71
The base url for accessing subversion repositories. e.g.
76
Configuration for IVLE installation and data paths.
80
:type: string(default="/usr/local")
82
The prefix that is prepended to installation paths.
86
:type: string(default="/var/lib/ivle")
88
Directory where IVLE data such as user jails will be stored.
92
:type: string(default="/var/log/ivle")
94
Directory where IVLE log files such as :file:`ivle_error.log` will be
98
:type: string(default="${prefix}/share/ivle")
100
Directory where IVLE shared data such as ``usrmgt-server``,
101
``python-console`` and services will be installed.
105
:type: string(default="${prefix}/lib/ivle")
107
Directory where IVLE libraries such as ``trampoline`` and ``timount`` will
112
Configuration paths for user :ref:`Jails <ref-jail>`.
116
:type: string(default="${data}/jailmounts"))
118
Directory where complete jails will be mounted.
123
:type: string(default="${data}/jails")
125
Directory where user specific jail content will be stored.
127
.. describe:: template
129
:type: string(default="${src}/__base__")
131
Directory where template file system for each jail will be stored.
133
.. describe:: template_build
135
:type: string(default="${src}/__base_build__")
137
Directory where template file system will be built before being moved to
138
the ``template`` directory.
142
Configuration paths for Subversion repositories.
146
:type: string(default="${data}/svn")
148
Directory where Subversion data will be stored
152
:type: string(default="${base}/svn.conf")
154
Location of Subversion WebDAV AuthzSVNAccessFile configuration file for
155
user repositories will be stored.
157
.. describe:: group_conf
159
:type: string(default="${base}/svn-group.conf")
161
Location of Subversion WebDAV AuthzSVNAccessFile configuration file for
162
group repositories will be stored.
164
.. describe:: repo_path
166
:type: string(default="${base}/repositories")
168
Location where user and group repositories will be stored.
170
.. describe:: auth_ivle
172
:type: string(default="${base}/ivle.auth")
174
Location where Subversion WebDAV AuthUserFile password hash file will be
177
.. _ref-configuration-policy:
181
Site-specific policy decisions on permissions, etc. These modify the user
182
roles, as described in :ref:`ref-user-roles`.
184
.. describe:: tutors_can_enrol_students
186
:type: boolean(default=False)
188
If True, tutors can enrol any IVLE user as a student in a subject they are
189
tutoring. This is disabled by default, as it is generally considered
190
unnecessary for tutors to have such power.
192
.. describe:: tutors_can_edit_worksheets
194
:type: boolean(default=True)
196
If True, tutors can create and edit worksheets in a subject they are
197
tutoring, and can create and edit *any exercise in the system*. This is
198
turned on by default, but should be used carefully. Untrusted tutors could
199
create site-wide problems.
201
(The reason tutors can edit any exercise is because exercises are not
202
stored per-subject, so it isn't possible to limit them just to exercises
203
for a particular subject.)
207
Configuration of media serving.
209
.. describe:: version
211
:type: string(default=None)
213
Media files such as images, CSS and JavaScript are aggressively cached in
214
IVLE. If this value is set then IVLE will send media URLs containing this
215
version number and content will be served with an ``Expires`` header set a
216
year in the future. This means that the client should only request a media
217
URL once and use the cached copy from then on. This version number should
218
be incremented each time any media is changed (typically this should just
219
be set to the IVLE release number) so that updated media will be sent to
222
If not provided or set to :const:`None`, IVLE will use standard browser
227
Configuration details for external media dependencies used by IVLE.
231
:type: string(default="/usr/share/javascript/jquery")
233
Directory where jQuery library is installed.
235
.. describe:: codemirror
237
:type: string(default="/usr/share/javascript/codemirror")
239
Directory where CodeMirror library is installed.
243
Configuration for the PostgreSQL database that IVLE uses.
247
:type: string(default="localhost")
249
Hostname of database IVLE server.
253
:type: integer(default=5432)
255
Port the database runs on.
259
:type: string(default="ivle")
261
Name of the IVLE database on the database server.
263
.. describe:: username
267
Username which IVLE uses on the database server.
269
.. describe:: password
273
Password which IVLE uses for authentication with the database server.
277
Settings for configuring external user authentication with
278
:ref:`authentication modules <ref-auth-modules>` and automatic subject
279
enrollment with :ref:`subject pulldown modules
280
<ref-subject-pulldown-modules>`.
282
.. describe:: modules
284
:type: string_list(default=list())
286
List of :ref:`authentication modules <ref-auth-modules>` to attempt to
287
authenticate with if a user does not have a password set in the local
290
.. describe:: ldap_url
292
:type: string(default=None)
294
URL of the LDAP server to be used by authentication modules.
296
.. describe:: ldap_format_string
298
:type: string(default=None)
301
.. describe:: subject_pulldown_modules
303
:type: string_list(default=list())
305
List of :ref:`subject pulldown modules <ref-subject-pulldown-modules>` to
306
be checked when a user signs into IVLE to see what subjects a student is
311
Settings for the :ref:`User Management Server <ref-usrmgt-server>`.
315
:type: string(default="localhost")
317
The hostname where the User Management Server is running.
321
:type: integer(default=2178)
323
The port that the User Management Server is running on.
329
The shared secret used to secure communication between IVLE Web
330
Application and the User Management Server.
334
Options that control how the :ref:`Jail <ref-jail>` is built.
336
.. describe:: devmode
338
:type: boolean(default=False)
340
If set, copies IVLE files from the local machine into the jail rather than
341
installing them from a package.
345
If the Python site packages directory differs between the local
346
machine and the jail (such as if different versions of Python are
347
installed) you will need to supply the site packages to be installed
348
with the ``--python-site-packages`` option to ``ivle-buildjail``.
352
:type: string(default="hardy")
354
Which suite the jail will build with. This need not be the same as what
355
the local machine is running.
359
:type: string(default="http://archive.ubuntu.com/ubuntu")
361
The location of a HTTP mirror containing the specified suite.
363
.. describe:: extra_sources
365
:type: string_list(default=list())
367
A list of extra source locations to be added to the jail builder (such as
368
for site specific packages). For example, 'deb
369
http://ppa.launchpad.net/wgrant/ivle/ubuntu/ hardy main,'.
371
.. describe:: extra_packages
373
:type: string_list(default=list())
375
A list of extra packages to be installed in addition to the core packages
376
required for IVLE. For example, 'python-scipy, python-networkx,'
378
.. describe:: extra_keys
380
:type: string(default=None)
382
Any extra package signing keys to accept as correctly validate installed
383
packages. Typically used for validating ``extra_sources`` packages.
385
Keys can be provided in tripple quoted blocks. For multiple keys, simply
386
concatinate the key blocks. For example::
388
extra_keys = '''-----BEGIN PGP PUBLIC KEY BLOCK-----
391
mI0ESXMxaQEEAMdundmJeTMUcB6fRXGQ3WJH+5hlfj3ehurF3u0ubr4sQpxfJvl6/KV4UcOC
392
RvK4aufNInJxKrT6xvzdMNE9z5NO/ZVZdkr2NfcRO/0Yxgmaft9qjxfV+3NEBrvJkqm8ApVO
393
hsxFW6VWyeHBELSiNxNGToPp+2g3i5VAlWbtzaapABEBAAG0H0xhdW5jaHBhZCBQUEEgZm9y
394
IFdpbGxpYW0gR3JhbnSIRgQQEQIABgUCSXOMJAAKCRABz5LwpyR9xeXXAJ97VdeI3lLDvyM9
395
TLeb48Ylj8dWdQCfcOJDRGfjRu9PI2+ekIoV8TqaC0GItgQTAQIAIAUCSXMxaQIbAwYLCQgH
396
AwIEFQIIAwQWAgMBAh4BAheAAAoJECp86x2KYmtCEBED/0aRhr7wKmA/nyX2rUN/1dpyYT2T
397
khxJT0F7l91/PGRkLUdvcX81ceRcYeiiR1x8N1tL7pwrTWZwaQ/HTHF19ZAXjptnn8zaLKUc
398
VwhOrUdFE2FzNo42BWpXQAuJuBCG3DeIXDDuPRvtL+sx7h8PD/DlE5RsTaztkkbWdpkMtJp9
400
-----END PGP PUBLIC KEY BLOCK-----
401
-----BEGIN PGP PUBLIC KEY BLOCK-----
402
Version: GnuPG v1.4.9 (GNU/Linux)
404
mQGiBEFEnz8RBAC7LstGsKD7McXZgd58oN68KquARLBl6rjA2vdhwl77KkPPOr3O
405
YeSBH/voUsqausJfDNuTNivOfwceDe50lbhq52ODj4Mx9Jg+4aHn9fmRkIk41i2J
406
3hZiIGPACY/FsSlRq1AhBH2wZG1lQ45W/p77AeARRehYKJP9HY+1h/uihwCgrVE2
407
VzACJLuZWHbDsPoJaNQjiFcEAKbUF1rMyjd1xJM7bZeXbs8c+ohUo/ywSI/OIr8n
409
RwIbDAAKCRBAl26vQ30FtdxYAJsFjU+xbex7gevyGQ2/mhqidES4MwCggqQyo+w1
412
-----END PGP PUBLIC KEY BLOCK-----
418
User specific settings that are added to a user's :file:`ivle.conf` file
423
This should be in a user-specific place but since we're worried a user
424
may delete his/her .conf file, we put it here for now). These properties
425
**should not** be set in the server's :file:`/etc/ivle/ivle.conf`.
429
:type: string(default=None)
431
The login name of the user.
433
.. describe:: svn_pass
435
:type: string(default=None)
437
The key used to access repositories on the Subversion server.
442
Apache is used in IVLE for hosting of the IVLE web application and hosting
443
Subversion repositories over WebDAV. Typically the Subversion repository will
444
run on the Master server and the Web Application will be run on a collection
445
of slaves. It is also possible to combine the two function together to run as
451
The IVLE web application runs on Apache using ``mod_python``. An example
452
configuration for normal HTTP is provided in the file
453
:file:`examples/config/apache.conf` and an example configuration for using
454
Secure HTTP using SSL certificates is provided in the file
455
:file:`examples/config/apache-ssl.conf`.
457
At minimum the following settings must be specified:
459
.. describe:: ServerName
461
Should be the formal hostname of the server, typically one that users will
462
use to access IVLE. For example, 'ivle.org'.
464
.. describe:: ServerAlias
466
Should be set to the value of ``[urls] public_host`` that is specified in
467
:file:`ivle.conf`. This is to ensure that Apache will correctly handle
468
requests for the public content.
470
.. describe:: SetHandler
472
Must be ``mod_python``
474
.. describe:: PythonHandler
476
Must be ``ivle.dispatch``
478
.. describe:: PythonOption mod_python.file_session.database_directory
480
Session directory for mod_python. This must be a shared directory between
481
all Slave servers, in particular when operating through a load balancer.
482
If not provided then users will encounter inconsistent behavior such as
483
being thrown back to the login screen after logging in.
485
Optional settings are:
487
.. describe:: PythonOption mod_python.session.cookie_name
489
The name to be set for cookies rather than the one automatically generated
490
by mod_python. For example, 'ivle'.
492
.. describe:: PythonDebug
494
If this option is set, any uncaught errors from mod_python will be sent to
495
the browser rather than being sent to the error log. It is recommended
496
that this setting is only used for development or debugging.
498
Subversion Repository
499
---------------------
500
IVLE also uses Apache to provide HTTP access to user's Subversion repositories
501
using ``mod_dav_svn``. Typically this is run on a single, stand alone server;
502
though it may be run in conjunction with the Web Application. An example
503
configuration is provided in the file :file:`examples/config/apache-svn.conf`.
504
IVLE will automatically generate password hash and repository permission files
505
that are used to control access to the repositories.
507
IVLE expects to find the paths ``users/`` and ``groups/`` at the URL provided
508
by the value of ``[urls] svn_addr`` set in :file:`ivle.conf`. Thus there
509
should be two ``Location`` clauses configured, one for users and one for
519
.. describe:: SVNParentPath
521
Directory where user repositories are stored. Should be the value of
522
``[path] [[svn]] repo_path`` in :file:`ivle.conf` with 'users' appended.
523
For example, '/var/lib/ivle/svn/repositories/users'.
525
.. describe:: AuthzSVNAccessFile
527
Location of the configuration file used to assign permissions to user
528
repositories. Should be the same value as ``[path] [[svn]] conf`` in
531
.. describe:: Require
533
Must be ``valid-user``
535
.. describe:: AuthType
539
.. describe:: AuthName
541
The name that should appear on authentication requests. For example, 'IVLE
542
Subversion repository'.
544
.. describe:: AuthUserFile
546
Location of the password hash file for Subversion users. Should be the
547
same as the value of ``[path] [[svn]] auth_ivle``. For example,
548
'/var/lib/ivle/svn/ivle.auth'.
557
.. describe:: SVNParentPath
559
Directory where user repositories are stored. Should be the value of
560
``[path] [[svn]] repo_path`` in :file:`ivle.conf` with 'groups' appended.
561
For example, '/var/lib/ivle/svn/repositories/groups'.
563
.. describe:: AuthzSVNAccessFile
565
Location of the configuration file used to assign permissions to group
566
repositories. Should be the same value as ``[path] [[svn]] group_conf`` in
569
.. describe:: Require
571
Must be ``valid-user``
573
.. describe:: AuthType
577
.. describe:: AuthName
579
The name that should appear on authentication requests. For example, 'IVLE
580
Subversion repository'.
582
.. describe:: AuthUserFile
584
Location of the password hash file for Subversion users. Should be the
585
same as the value of ``[path] [[svn]] auth_ivle``. For example,
586
'/var/lib/ivle/svn/ivle.auth'.
added
removed
doc/man/config.rst
