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

.. 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-admin-scripts:

*************
Admin scripts
*************

IVLE has a number of admin scripts for uncommon configuration or other
functionality not available in the web application.

Most of these scripts must be run as root.

ivle-addexercise
----------------

.. program:: ivle-addexercise

:program:`ivle-addexercise <EXERCISE>`

Adds an XML encoded exercise to the IVLE database. This is primarily
for importing exercises that pre-date the database storage system.

The exercise's name will be set to the complete path specified on the
command line -- keep this in mind when choosing a working directory.

.. cmdoption:: <EXERCISE>

    The XML file containing the exercise to be uploaded.

ivle-adduser
------------

.. program:: ivle-adduser

:program:`ivle-adduser [OPTIONS] <LOGIN> <FULLNAME>`

Creates a new user in the database. On-disk structures (jails and
Subversion repositories) will be created upon first login.

.. FIXME: "This can also be done through the administration interface."
    (Not yet!)


.. cmdoption:: <LOGIN>

    Login name of the new user

.. cmdoption:: <FULLNAME>

    Full name of the user

.. cmdoption:: -p <PASSWORD>, --password <PASSWORD>

    Cleartext password. If omitted, external authentication mechanisms
    will be tried.

.. cmdoption:: -n <NICK>, --nick <NICK>

    Display name (defaults to <FULLNAME>)

.. cmdoption:: -e <EMAIL>, --email <EMAIL>

    Email address

.. cmdoption:: -s <SID>, --studentid <SID>

    Student ID

.. cmdoption:: --admin

    Give the user global IVLE administrative privileges


ivle-buildjail
--------------

.. program:: ivle-buildjail

:program:`ivle-buildjail [OPTIONS]`

Creates or updates the IVLE jail template. 

.. cmdoption:: -r, --recreate

    Completely recreate the jail - don't just update its IVLE code.

    .. warning::

        This may download hundreds of megabytes from the location specified by 
        ``<MIRROR>``.

.. cmdoption:: -u, --upgrade

    Apply any package updates in the jail.

.. cmdoption:: -m <MIRROR>, --mirror <MIRROR>

    Sets the APT mirror. May also be specified in the ``jail/mirror``
    config key.


ivle-cloneworksheets
--------------------

.. program:: ivle-cloneworksheets

:program:`ivle-cloneworksheets <OLDSUBJECTCODE> <OLDYEAR> <OLDSEMESTER> 
<NEWSUBJECTCODE> <NEWYEAR> <NEWSEMESTER>`

Populates the offering specified by ``<NEWSUBJECTCODE> <NEWYEAR> 
<NEWSEMESTER>`` with a copy of the worksheets from the offering specified by 
``<OLDSUBJECTCODE> <OLDYEAR> <OLDSEMESTER>``.


ivle-config
-----------

.. program:: ivle-config

:program:`ivle-config [ARG1] [ARG2] ...`

Configures IVLE with machine-specific details, most notably various paths.
Either prompts the administrator for these details or accepts them as
command line arguments.

Command line arguments may be any of the :ref:`configuration option 
<ref-configuration-options>` used in :file:`ivle.conf`. They are provided in 
the form of :samp:`--{section}/{subsection}/{property} {VALUE}` such as 
``--urls/root ivle.org`` or ``--media/externals/jquery 
/usr/share/javascript/jquery``.

Creates or updates :file:`/etc/ivle/ivle.conf` with the selected values,
and overwrites :file:`/etc/ivle/plugins.d/000default` with the latest
default plugin list.


ivle-createdatadirs
-------------------

.. program:: ivle-createdatadirs

:program:`ivle-createdatadirs`

Creates the IVLE data hierarchy (by default under :file:`/var/lib/ivle`) if
it does not already exist.


ivle-enrol
----------

.. program:: ivle-enrol

:program:`ivle-enrol <LOGIN> <SUBJECTCODE> <YEAR> <SEMESTER> [ROLE]`

Enrols a user in an offering.

.. note::
    Users may also be enrolled from the offering administration panel
    in the web interface.

.. cmdoption:: <LOGIN>

    Login of the user to enrol

.. cmdoption:: <SUBJECTCODE>

    Subject code

.. cmdoption:: <YEAR>

    Offering year

.. cmdoption:: <SEMESTER>

    Offering semester

.. cmdoption:: [ROLE]

    Role of the user. Should be one of 'student' (default), 'tutor' or
    'lecturer'.


ivle-enrolallusers
------------------

.. program:: ivle-enrolallusers

:program:`ivle-enrolallusers`

Adds enrolments for all users on the system.
Pulls from the configured :ref:`subject pulldown module 
<ref-subject-pulldown-modules>` the subjects each student
is enrolled in, and adds enrolments to the database.
Does not remove any enrolments.

.. note::
    Pulldown modules are consulted for each user each time they log in,
    so use of this script may not be required.

.. cmdoption:: -u <LOGIN>, --user <LOGIN>

    Just perform enrolment for user ``<LOGIN>``

.. cmdoption:: -v, --verbose

    Print out the details of each enrolment.


ivle-fetchsubmissions
---------------------

.. program:: ivle-fetchsubmissions

:program:`ivle-fetchsubmissions [OPTIONS] <SUBJECT> <PROJECT>`

Retrieves all submissions for a given project. Places each submission in its 
own subdirectory of the current directory. Any errors are reported to stderr
(otherwise is silent).

.. note::
    Since this script accesses Subversion repositories through the
    filesystem, it must be run on the master server.

.. cmdoption:: <SUBJECT>

    Subject short (URL) name

.. cmdoption:: <PROJECTNAME>

    Project short (URL) name

.. cmdoption:: -s <SEMESTER>, --semester <SEMESTER>

    Semester of the offering (eg. 2009/1). Defaults to the currently
    active semester.

.. cmdoption:: -d <PATH>, --dest <PATH>

    Destination directory (defaults to the current directory) in
    which to place submissions. Will create subdirectories in this
    directory of the form ``subject/year/semester/project``.

.. cmdoption:: -z, --zip

    Store each submission in a Zip file.

.. cmdoption:: -v, --verbose

    Print the name of each submission as it is extracted.

.. cmdoption:: --no-txt

    Disable writing a text file with metadata about each submission.


ivle-listusers
--------------

.. program:: ivle-listusers

:program:`ivle-listusers [OPTIONS]`

Lists all users in the IVLE database.

.. cmdoption:: -n, --names

    Print only each user's login name


ivle-marks
----------

.. program:: ivle-marks

:program:`ivle-marks [OPTIONS] <SUBJECT>`

Reports each student's marks for a given subject offering.

.. cmdoption:: <SUBJECT>

    Subject short (URL) name

.. cmdoption:: -s <SEMESTER>, --semester <SEMESTER>

    Semester of the offering (eg. 2009/1). Defaults to the currently
    active semester.

.. cmdoption:: -c <CUTOFF>, --cutoff <CUTOFF>

    Cutoff date (calculate the marks as of this date). Should be provided in 
    the form of ``YYYY-MM-DD H:M:S``.


ivle-mountallusers
------------------

.. program:: ivle-mountallusers

:program:`ivle-mountallusers`

Attempts to mount the jails of all users.

.. note::

    Administrators should not need to manually run this script for regular
    operation.  IVLE will automatically mount users' jails on demand.

.. cmdoption:: -v, --verbose

    Print a message for each mount or unmount.

.. cmdoption:: -u, --unmount

    Unmount jails instead of mounting them.


ivle-refreshfilesystem
----------------------

.. program:: ivle-refreshfilesystem

:program:`ivle-refreshfilesystem`

Refresh parts of the filesystem to match the database.

In particular:
 - all jails are rebuilt
 - missing user jails are created
 - missing user and group Subversion repositories are created
 - jails for missing users are removed
 - Subversion repositories for missing users or groups are removed
 - the Subversion password file is updated
 - the Subversion authorisation files are rewritten

.. warning::
    Due to the full jail rebuilds, existing jail mounts may be broken
    after this script has run. To recover from this situation, use
    ``ivle-mountallusers`` to unmount all of the jails.

.. note::
    Jails and Subversion repositories are not entirely removed. They
    can be found in a timestamped directory alongside their parent.


ivle-remakeuser
---------------

.. program:: ivle-remakeuser

:program:`ivle-remakeuser [OPTIONS] <USER>`

:program:`ivle-remakeuser [OPTIONS] -a`

Rebuilds the jail of a single user or of all users in IVLE. This will
retain all user data, but recreate the rest of the hierarchy and
internal configuration files.

.. cmdoption:: <USER>

    Login of the user whose jail should be rebuilt

.. cmdoption:: -a, --all

    Rebuild the jail of every user

.. cmdoption:: -v, --verbose

    Print a message as each user's jail is remade


ivle-showenrolment
------------------

.. program:: ivle-showenrolment

:program:`ivle-showenrolment <USER>`

Shows the enrolments of a user. Prints subject code, subject name, year, 
semester and the held role for each subject in which they are enrolled.

.. cmdoption:: <USER>

    Login of the user