~azzar1/unity/add-show-desktop-key

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
.. IVLE - Informatics Virtual Learning Environment
   Copyright (C) 2007-2009 The University of Melbourne

.. This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

.. This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

.. You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

.. _ref-configuring-ivle:

****************
Configuring IVLE
****************

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

.. _ref-configuration-options:

Configuration options
=====================

Most of the configuration of IVLE is done by editing the file 
:file:`ivle.conf`, located by default in :file:`/etc/ivle/ivle.conf`. These 
settings are required as part of the :ref:`install process <ref-install>`, 
though the :ref:`admin script <ref-admin-scripts>` :program:`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).

.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html

[urls]
------
Configuration of URLs used by the IVLE webapp.

.. describe:: root

    :type: string(default="/")

    Path on HTTP server that IVLE is served from.

.. describe:: 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'

.. describe:: 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.

.. describe:: prefix

    :type: string(default="/usr/local")

    The prefix that is prepended to installation paths.

.. describe:: data

    :type: string(default="/var/lib/ivle")

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

.. describe:: logs

    :type: string(default="/var/log/ivle")

    Directory where IVLE log files such as :file:`ivle_error.log` will be 
    saved.
.. describe:: share

    :type: string(default="${prefix}/share/ivle")

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

.. describe:: lib

    :type: string(default="${prefix}/lib/ivle")

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

[[jails]]
~~~~~~~~~
Configuration paths for user :ref:`Jails <ref-jail>`.

.. describe:: mounts

    :type: string(default="${data}/jailmounts"))

    Directory where complete jails will be mounted.


.. describe:: src

    :type: string(default="${data}/jails")

    Directory where user specific jail content will be stored.

.. describe:: template

    :type: string(default="${src}/__base__")

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

.. describe:: 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.

.. describe:: base

    :type: string(default="${data}/svn")

    Directory where Subversion data will be stored

.. describe:: conf

    :type: string(default="${base}/svn.conf")

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

.. describe:: group_conf

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

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

.. describe:: repo_path

    :type: string(default="${base}/repositories")

    Location where user and group repositories will be stored.

.. describe:: auth_ivle

    :type: string(default="${base}/ivle.auth")

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

.. _ref-configuration-policy:

[policy]
--------
Site-specific policy decisions on permissions, etc. These modify the user
roles, as described in :ref:`ref-user-roles`.

.. describe:: 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.

.. describe:: 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.

.. describe:: 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 :const:`None`, IVLE will use standard browser 
    caching.

[[externals]]
~~~~~~~~~~~~~
Configuration details for external media dependencies used by IVLE.

.. describe:: jquery

    :type: string(default="/usr/share/javascript/jquery")

    Directory where jQuery library is installed.

.. describe:: codemirror

    :type: string(default="/usr/share/javascript/codemirror")

    Directory where CodeMirror library is installed.

[database]
----------
Configuration for the PostgreSQL database that IVLE uses.

.. describe:: host

    :type: string(default="localhost")

    Hostname of database IVLE server.

.. describe:: port

    :type: integer(default=5432)

    Port the database runs on.

.. describe:: name

    :type: string(default="ivle")

    Name of the IVLE database on the database server.

.. describe:: username

    :type: string

    Username which IVLE uses on the database server.

.. describe:: password

    :type: string

    Password which IVLE uses for authentication with the database server.

[auth]
------
Settings for configuring external user authentication with
:ref:`authentication modules <ref-auth-modules>` and automatic subject
enrollment with :ref:`subject pulldown modules
<ref-subject-pulldown-modules>`.

.. describe:: modules

    :type: string_list(default=list())

    List of :ref:`authentication modules <ref-auth-modules>` to attempt to 
    authenticate with if a user does not have a password set in the local 
    database.

.. describe:: ldap_url

    :type: string(default=None)

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

.. describe:: ldap_format_string

    :type: string(default=None)


.. describe:: subject_pulldown_modules

    :type: string_list(default=list())

    List of :ref:`subject pulldown modules <ref-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 :ref:`User Management Server <ref-usrmgt-server>`.

.. describe:: host

    :type: string(default="localhost")

    The hostname where the User Management Server is running.

.. describe:: port

    :type: integer(default=2178)

    The port that the User Management Server is running on.

.. describe:: 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 :ref:`Jail <ref-jail>` is built.

.. describe:: 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``.

.. describe:: 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.

.. describe:: mirror

    :type: string(default="http://archive.ubuntu.com/ubuntu")

    The location of a HTTP mirror containing the specified suite.

.. describe:: 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,'.

.. describe:: 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,'

.. describe:: 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 :file:`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 :file:`/etc/ivle/ivle.conf`.

.. describe:: login

    :type: string(default=None)

    The login name of the user.

.. describe:: 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 
:file:`examples/config/apache.conf` and an example configuration for using 
Secure HTTP using SSL certificates is provided in the file 
:file:`examples/config/apache-ssl.conf`.

At minimum the following settings must be specified:

.. describe:: ServerName

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

.. describe:: ServerAlias

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

.. describe:: SetHandler

    Must be ``mod_python``

.. describe:: PythonHandler

    Must be ``ivle.dispatch``

.. describe:: 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:

.. describe:: 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'.

.. describe:: 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 :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 :file:`ivle.conf`. Thus there 
should be two ``Location`` clauses configured, one for users and one for 
groups.

User Repositories
~~~~~~~~~~~~~~~~~

.. describe:: DAV

    Must be ``svn``

.. describe:: SVNParentPath

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

.. describe:: AuthzSVNAccessFile

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

.. describe:: Require

    Must be ``valid-user``

.. describe:: AuthType

    Must be ``Basic``

.. describe:: AuthName

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

.. describe:: 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
~~~~~~~~~~~~~~~~~~

.. describe:: DAV

    Must be ``svn``

.. describe:: SVNParentPath

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

.. describe:: AuthzSVNAccessFile

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

.. describe:: Require

    Must be ``valid-user``

.. describe:: AuthType

    Must be ``Basic``

.. describe:: AuthName

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

.. describe:: 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'.