Configuring IVLE

This page describes the configuration of IVLE. This consists of populating the ivle.conf file and configuring Apache to serve the IVLE webapp and Subversion repositories.

Configuration options

Most of the configuration of IVLE is done by editing the file ivle.conf, located by default in /etc/ivle/ivle.conf. These settings are required as part of the install process, though the admin script ivle-config can be used to propagate most of these settings.

It uses the ConfigObj text format which is heavily based on the ‘INI’ text format. Of particular note, lists with single items need to be terminated with a ‘,’ otherwise it will be treated as a list of characters (usually not what is desired).

[urls]

Configuration of URLs used by the IVLE webapp.

root

Type:string(default=”/”)

Path on HTTP server that IVLE is served from.

public_host

Type:string

The server goes into “public mode” if the browser sends a request with this host. This is for security reasons - we only serve public student files on a separate domain to the main IVLE site. Public mode does not use cookies, and serves only public content. Private mode (normal mode) requires login, and only serves files relevant to the logged-in user. e.g. ‘public.ivle.org’

svn_addr

Type:string

The base url for accessing subversion repositories. e.g. ‘http://svn.ivle.org‘

[paths]

Configuration for IVLE installation and data paths.

prefix

Type:string(default=”/usr/local”)

The prefix that is prepended to installation paths.

data

Type:string(default=”/var/lib/ivle”)

Directory where IVLE data such as user jails will be stored.

logs

Type:string(default=”/var/log/ivle”)

Directory where IVLE log files such as ivle_error.log will be saved.

share

Type:string(default=”${prefix}/share/ivle”)

Directory where IVLE shared data such as usrmgt-server, python-console and services will be installed.

lib

Type:string(default=”${prefix}/lib/ivle”)

Directory where IVLE libraries such as trampoline and timount will be installed.

[[jails]]

Configuration paths for user Jails.

mounts

Type:string(default=”${data}/jailmounts”))

Directory where complete jails will be mounted.

src

Type:string(default=”${data}/jails”)

Directory where user specific jail content will be stored.

template

Type:string(default=”${src}/__base__”)

Directory where template file system for each jail will be stored.

template_build

Type:string(default=”${src}/__base_build__”)

Directory where template file system will be built before being moved to the template directory.

[[svn]]

Configuration paths for Subversion repositories.

base

Type:string(default=”${data}/svn”)

Directory where Subversion data will be stored

conf

Type:string(default=”${base}/svn.conf”)

Location of Subversion WebDAV AuthzSVNAccessFile configuration file for user repositories will be stored.

group_conf

Type:string(default=”${base}/svn-group.conf”)

Location of Subversion WebDAV AuthzSVNAccessFile configuration file for group repositories will be stored.

repo_path

Type:string(default=”${base}/repositories”)

Location where user and group repositories will be stored.

auth_ivle

Type:string(default=”${base}/ivle.auth”)

Location where Subversion WebDAV AuthUserFile password hash file will be stored.

[policy]

Site-specific policy decisions on permissions, etc. These modify the user roles, as described in User roles.

tutors_can_enrol_students

Type:boolean(default=False)

If True, tutors can enrol any IVLE user as a student in a subject they are tutoring. This is disabled by default, as it is generally considered unnecessary for tutors to have such power.

tutors_can_edit_worksheets

Type:boolean(default=True)

If True, tutors can create and edit worksheets in a subject they are tutoring, and can create and edit any exercise in the system. This is turned on by default, but should be used carefully. Untrusted tutors could create site-wide problems.

(The reason tutors can edit any exercise is because exercises are not stored per-subject, so it isn’t possible to limit them just to exercises for a particular subject.)

[media]

Configuration of media serving.

version

Type:string(default=None)

Media files such as images, CSS and JavaScript are aggressively cached in IVLE. If this value is set then IVLE will send media URLs containing this version number and content will be served with an Expires header set a year in the future. This means that the client should only request a media URL once and use the cached copy from then on. This version number should be incremented each time any media is changed (typically this should just be set to the IVLE release number) so that updated media will be sent to clients.

If not provided or set to None, IVLE will use standard browser caching.

[[externals]]

Configuration details for external media dependencies used by IVLE.

jquery

Type:string(default=”/usr/share/javascript/jquery”)

Directory where jQuery library is installed.

[database]

Configuration for the PostgreSQL database that IVLE uses.

host

Type:string(default=”localhost”)

Hostname of database IVLE server.

port

Type:integer(default=5432)

Port the database runs on.

name

Type:string(default=”ivle”)

Name of the IVLE database on the database server.

username

Type:string

Username which IVLE uses on the database server.

password

Type:string

Password which IVLE uses for authentication with the database server.

[auth]

Settings for configuring external user authentication with authentication modules and automatic subject enrollment with subject pulldown modules.

modules

Type:string_list(default=list())

List of authentication modules to attempt to authenticate with if a user does not have a password set in the local database.

ldap_url

Type:string(default=None)

URL of the LDAP server to be used by authentication modules.

ldap_format_string

Type:string(default=None)

subject_pulldown_modules

Type:string_list(default=list())

List of subject pulldown modules to be checked when a user signs into IVLE to see what subjects a student is enrolled in.

[usrmgt]

Settings for the User Management Server.

host

Type:string(default=”localhost”)

The hostname where the User Management Server is running.

port

Type:integer(default=2178)

The port that the User Management Server is running on.

magic

Type:string

The shared secret used to secure communication between IVLE Web Application and the User Management Server.

[jail]

Options that control how the Jail is built.

devmode

Type:boolean(default=False)

If set, copies IVLE files from the local machine into the jail rather than installing them from a package.

Note

If the Python site packages directory differs between the local machine and the jail (such as if different versions of Python are installed) you will need to supply the site packages to be installed with the --python-site-packages option to ivle-buildjail.

suite

Type:string(default=”hardy”)

Which suite the jail will build with. This need not be the same as what the local machine is running.

mirror

Type:string(default=”http://archive.ubuntu.com/ubuntu“)

The location of a HTTP mirror containing the specified suite.

extra_sources

Type:string_list(default=list())

A list of extra source locations to be added to the jail builder (such as for site specific packages). For example, ‘deb http://ppa.launchpad.net/wgrant/ivle/ubuntu/ hardy main,’.

extra_packages

Type:string_list(default=list())

A list of extra packages to be installed in addition to the core packages required for IVLE. For example, ‘python-scipy, python-networkx,’

extra_keys

Type:string(default=None)

Any extra package signing keys to accept as correctly validate installed packages. Typically used for validating extra_sources packages.

Keys can be provided in tripple quoted blocks. For multiple keys, simply concatinate the key blocks. For example:

extra_keys = '''-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: SKS 1.0.10

mI0ESXMxaQEEAMdundmJeTMUcB6fRXGQ3WJH+5hlfj3ehurF3u0ubr4sQpxfJvl6/KV4UcOC
RvK4aufNInJxKrT6xvzdMNE9z5NO/ZVZdkr2NfcRO/0Yxgmaft9qjxfV+3NEBrvJkqm8ApVO
hsxFW6VWyeHBELSiNxNGToPp+2g3i5VAlWbtzaapABEBAAG0H0xhdW5jaHBhZCBQUEEgZm9y
IFdpbGxpYW0gR3JhbnSIRgQQEQIABgUCSXOMJAAKCRABz5LwpyR9xeXXAJ97VdeI3lLDvyM9
TLeb48Ylj8dWdQCfcOJDRGfjRu9PI2+ekIoV8TqaC0GItgQTAQIAIAUCSXMxaQIbAwYLCQgH
AwIEFQIIAwQWAgMBAh4BAheAAAoJECp86x2KYmtCEBED/0aRhr7wKmA/nyX2rUN/1dpyYT2T
khxJT0F7l91/PGRkLUdvcX81ceRcYeiiR1x8N1tL7pwrTWZwaQ/HTHF19ZAXjptnn8zaLKUc
VwhOrUdFE2FzNo42BWpXQAuJuBCG3DeIXDDuPRvtL+sx7h8PD/DlE5RsTaztkkbWdpkMtJp9
=5ocD
-----END PGP PUBLIC KEY BLOCK-----
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.9 (GNU/Linux)

mQGiBEFEnz8RBAC7LstGsKD7McXZgd58oN68KquARLBl6rjA2vdhwl77KkPPOr3O
YeSBH/voUsqausJfDNuTNivOfwceDe50lbhq52ODj4Mx9Jg+4aHn9fmRkIk41i2J
3hZiIGPACY/FsSlRq1AhBH2wZG1lQ45W/p77AeARRehYKJP9HY+1h/uihwCgrVE2
VzACJLuZWHbDsPoJaNQjiFcEAKbUF1rMyjd1xJM7bZeXbs8c+ohUo/ywSI/OIr8n
<SNIP>
RwIbDAAKCRBAl26vQ30FtdxYAJsFjU+xbex7gevyGQ2/mhqidES4MwCggqQyo+w1
Twx6DKLF+3rF5nf1F3Q=
=PBAe
-----END PGP PUBLIC KEY BLOCK-----
'''

[user_info]

User specific settings that are added to a user’s ivle.conf file inside their jail.

Warning

This should be in a user-specific place but since we’re worried a user may delete his/her .conf file, we put it here for now). These properties should not be set in the server’s /etc/ivle/ivle.conf.

login

Type:string(default=None)

The login name of the user.

svn_pass

Type:string(default=None)

The key used to access repositories on the Subversion server.

Apache configuration

Apache is used in IVLE for hosting of the IVLE web application and hosting Subversion repositories over WebDAV. Typically the Subversion repository will run on the Master server and the Web Application will be run on a collection of slaves. It is also possible to combine the two function together to run as a standalone server.

Web Application

The IVLE web application runs on Apache using mod_python. An example configuration for normal HTTP is provided in the file examples/config/apache.conf and an example configuration for using Secure HTTP using SSL certificates is provided in the file examples/config/apache-ssl.conf.

At minimum the following settings must be specified:

ServerName

Should be the formal hostname of the server, typically one that users will use to access IVLE. For example, ‘ivle.org’.

ServerAlias

Should be set to the value of [urls] public_host that is specified in ivle.conf. This is to ensure that Apache will correctly handle requests for the public content.

SetHandler

Must be mod_python

PythonHandler

Must be ivle.dispatch

PythonOption mod_python.file_session.database_directory

Session directory for mod_python. This must be a shared directory between all Slave servers, in particular when operating through a load balancer. If not provided then users will encounter inconsistent behavior such as being thrown back to the login screen after logging in.

Optional settings are:

PythonOption mod_python.session.cookie_name

The name to be set for cookies rather than the one automatically generated by mod_python. For example, ‘ivle’.

PythonDebug

If this option is set, any uncaught errors from mod_python will be sent to the browser rather than being sent to the error log. It is recommended that this setting is only used for development or debugging.

Subversion Repository

IVLE also uses Apache to provide HTTP access to user’s Subversion repositories using mod_dav_svn. Typically this is run on a single, stand alone server; though it may be run in conjunction with the Web Application. An example configuration is provided in the file examples/config/apache-svn.conf. IVLE will automatically generate password hash and repository permission files that are used to control access to the repositories.

IVLE expects to find the paths users/ and groups/ at the URL provided by the value of [urls] svn_addr set in ivle.conf. Thus there should be two Location clauses configured, one for users and one for groups.

User Repositories

DAV

Must be svn

SVNParentPath

Directory where user repositories are stored. Should be the value of [path] [[svn]] repo_path in ivle.conf with ‘users’ appended. For example, ‘/var/lib/ivle/svn/repositories/users’.

AuthzSVNAccessFile

Location of the configuration file used to assign permissions to user repositories. Should be the same value as [path] [[svn]] conf in ivle.conf.

Require

Must be valid-user

AuthType

Must be Basic

AuthName

The name that should appear on authentication requests. For example, ‘IVLE Subversion repository’.

AuthUserFile

Location of the password hash file for Subversion users. Should be the same as the value of [path] [[svn]] auth_ivle. For example, ‘/var/lib/ivle/svn/ivle.auth’.

Group Repositories

DAV

Must be svn

SVNParentPath

Directory where user repositories are stored. Should be the value of [path] [[svn]] repo_path in ivle.conf with ‘groups’ appended. For example, ‘/var/lib/ivle/svn/repositories/groups’.

AuthzSVNAccessFile

Location of the configuration file used to assign permissions to group repositories. Should be the same value as [path] [[svn]] group_conf in ivle.conf.

Require

Must be valid-user

AuthType

Must be Basic

AuthName

The name that should appear on authentication requests. For example, ‘IVLE Subversion repository’.

AuthUserFile

Location of the password hash file for Subversion users. Should be the same as the value of [path] [[svn]] auth_ivle. For example, ‘/var/lib/ivle/svn/ivle.auth’.