-*- mode: text; mode: auto-fill -*-
$Id: INSTALL 4700 2008-02-18 17:59:33Z cher $

Brief instructions for installation of ejudge system
====================================================
This section describes the ejudge installation process, which
requires minimal manual configuration. This method of
installation is recommented for novice users. If this method of
installation does not work on your system, or you are not
satisfied with the default settings, you should read the verbose
manual further in this file.

So, installation step by step
-----------------------------
1. Create a new user `ejudge' with the home directory as
`/home/ejudge'. Create a separate user group `ejudge' with the
only member `ejudge'. If you don't know how to create new users,
please, refer to the system manuals.
2. Create a new directory `/home/judges'. The owner of this
directory must be `ejudge', and the group must be `ejudge' as
well. The root privilegies are required to create this
directory, so become root and issue the following commands:
mkdir /home/judges
chown ejudge:ejudge /home/judges
3. Log in as the `ejudge' users, unpack, compile and install the
reuse library in the home directory.

cd ~
tar xvfz REUSE-ARCH-DIR/reuse-VERSION.tgz
cd reuse/source
./configure
make
make install

Here REUSE-ARCH-DIR is the directory where the reuse library
archive is downloaded. VERSION is the library version. Always
use the latest version (as of this writing it is 4.2.3).
4. Change directory to the home directory and unpack the ejudge archive.

cd ~
tar xvfz EJUDGE-ARCH-DIR/ejudge-VERSION.tgz
cd ejudge

5. Configure the ejudge

./configure --prefix=/home/ejudge/inst-ejudge --with-reuse=/home/ejudge/reuse  --enable-charset=utf-8 --enable-contests-home-dir=/home/judges --enable-conf-dir=/home/judges/data --enable-cgi-conf-dir=../cgi-data --with-httpd-cgi-bin-dir=CGI-BIN-DIR --with-httpd-htdocs-dir=HTDOCS-DIR --enable-ajax --enable-hidden-server-bins --enable-local-dir=/var/lib/ejudge

Here CGI-BIN-DIR is the CGI directory of your web server
installation (for example, `/home/httpd/cgi-bin'), HTDOCS-DIR is
the root of the HTML documents of your web server installation
(for example, `/home/httpd/html'). Refer to your system manuals
for exact information on this paths.
6. Compile and install the ejudge system.

make
make install

7. Run the `ejudge-setup' program, go to the "Administrator
 identity" menu and fill up the required fields:

./ejudge-setup
Admin ID:       1
Admin Login:    ejudge
Admin e-mail:   YOUR-E-MAIL
Admin name:     Ejudge administrator
Admin password: PASSWORD

Then generate the setup script using the "Save setup script"
menu item. When you invoke this menu item, the setup script file
name will be requested. Preserve the default name `ejudge-install.sh'.

8. Invoke the setup script as the root user.
su -
cd ~ejudge/ejudge
./ejudge-install.sh

9. Start the ejudge system. The programs must be started by the
`ejudge' user.

ejudge-control start

10. Download the DoJo Toolkit
(http://download.dojotoolkit.org/release-0.4.3/dojo-0.4.3-ajax.tar.gz).
Install it to HTDOCS-DIR/ejudge:
cd HTDOCS-DIR/ejudge
tar xvf dojo-0.4.3-ajax.tar.gz
mv dojo-0.4.3-ajax/* .

Make sure, that the access permissions of the `/home/ejudge'
directory allows reading of files for arbitrary users. Some
Linux distributions by default create the user home directory
with the 0700 permissions. In this case the ejudge CGI-programs
and the necessary libraries will be unavailable for the
web-server. So, the permissions for the `/home/ejudge' directory
should be changed to 0755 or 0775.

For the Fedora Core distributions make sure, that the SELinux
module is disabled. Check the SELinux configuration file
`/etc/selinux/config'. For more information (or, if you want to
configure the SELinux for the ejudge system) refer to the
SELinux documentation (man selinux).

The installation of the ejudge system is complete. Now you can
test the installation typing the
`http://localhost/cgi-bin/serve-control' URL in the web browser.
Of course, the web server should be started.

If some step of the installation process described above has
failed, you do not understand some steps, or you want to change
some default settings, read the documentation below.

Ejudge system installation manual
=================================

This file contains the instructions on installation and initial
setup for the ejudge contest management system. The installation
and setup process consists of the following steps:
  1) configuration of the system for compilation for the
     sources;
  2) compilation of the system;
  3) installation of the compiled files;
  4) generation of the setup script;
  5) execution of the setup script;
  6) checking of the system operation;
  7) post-install steps.
All these steps are further described in detail.

This installation instruction applies to the ejudge system
starting from the version 2.1.30. For earlier versions of the
ejudge system the installation instructions are available from
the Internet at the address
http://acm.msu.ru/ejudge/old-install.shtml. However, please
consider upgrading the ejudge system to the latest version. The
latest version is always available at the address
http://acm.msu.ru/ejudge/download.

Software requirements
---------------------
In order to successfully compile the ejudge contest management
system the following tools must be installed in your system:
  - the GNU C compiler (gcc);
  - the make utility;
  - gettext and xgettext localization tools;
  - the expat XML parsing library.
As a rule all these tools are installed automatically during
installation of modern distributions of Linux.

Also the reuse library is required. The reuse library contains
general purpose functions and a portability layer for Linux and
Win32. The library is developed by the author of the ejudge and
may be downloaded from the ejudge's site.

1. Configuration of the system
------------------------------
Before compilation the ejudge system must be configured. During
the configuration the following actions are performed
automatically: the necessary compilation switches are detected,
the required programs are found, etc. As a result, the
Makefiles, compilation scripts and the config.h header files are
tuned for the current operating system settings. A user may
influence the configuration process using the command-line
options.

In order to configure the ejudge system the `configure' script
is used, which is located in the source directory of the ejudge
system. The `configure' supports --help option, which may be
used to print all the command line options supported by the
configure script. The task of the configure script is to
generate the Makefiles, compilation scripts and the config.h
file according to the automatically detected and user specified
options.

If you use the snapshot of the ejudge from CVS, the `configure'
script must be generated using the `autoconf' utility. The
autoconf version 2.59 or above is required.

All the options, supported by the `configure' script may be
divided into the following groups: mandatory, recommended,
programming language support, fine tuning. All the options are
described below in details.

1.1. Mandatory options
----------------------
The options of this group must be specified in the configure's
command line, or compilation of ejudge is impossible, and the
ejudge script will report a fatal error. Currently, the
mandatory options are as follows.

    --with-reuse=REUSE-PATH
        This option allows specifying the path to the root
        directory of the reuse library installation. The
        REUSE-PATH must be an absolute path and point to the
        directory, where the reuse library is installed. This
        directory must contain `bin', `include', and `lib'
        subdirectories containing the corresponding components
        of the reuse library.

        The reuse library version 3.0.17 or above is required
        for compilation of the ejudge system. If the REUSE-PATH
        does not contain the reuse library, or the library
        version does not satisfy the above mentioned requirement,
        the configure script terminates with error. The latest
        version of the reuse library is recommended for use, as
        of this writing - 4.2.3.

        As a rule, the reuse library is compiled and installed
        in the same directory, where the source archive is
        extracted. Thus, if the source code is extracted into
        the /home/you/reuse directory and is compiled there, the
        /home/you/reuse directory should contain the `bin',
        `include', and `lib' directories containing the
        configuration scirpt, the header files, and the library
        files respectively. In order to use the reuse library
        installed into /home/you/reuse directory the option
        --with-reuse=/home/you/reuse should be used.

    --enable-charset=CHARSET
        This option allows specifying the "internal" charset
        encoding, i.e. the encoding which is used to store
        character strings in memory. If this option is not
        specified, the "UTF-8" charset encoding is used. To
        handle character strings the ejudge system uses the
        string functions of the Standard C Library, thus the
        internal encoding must be compatible with the string
        functions of the C Standard Library, i.e. the internal
        encoding must not allow NUL ('\0') bytes in the middle
        of character strings. For example, UTF-16 is not such an
        encoding, whereas UTF-8 is.

        All the textual configuration files (.cfg) are assumed
        to be stored in the internal encoding, so no charset
        conversion is performed during their parsing. During
        parsing of the XML files the external charset of the XML
        document (as specified in the document header) is
        converted into the internal charset. The `iconv'
        function of the C Standard Library is used, so almost
        all reasonable charset encodings are supported. All the
        generated XML documents are also written in the internal
        charset.

        When a HTML file is generated by the ejudge programs,
        its encoding is specified as defined in the
        corresponding configuration variables in the ejudge
        program's configuration files (by default it is the
        internal encoding). In theory, the encoding of HTML
        documents may be different from the configuration files
        encoding or from the internal encoding. However the
        current version of the ejudge system does not support
        conversion of strings in the internal charset into the
        charset of the HTML document, if they are different. The
        strings are inserted into the HTML document without
        conversion, which may result in incorrent HTML
        documents. Thus, in the current version of the ejudge
        system for correctness and safety the internal charset
        and the output HTML document charset must be the same.
        So it is strongly not recommended to explicitly specify
        the charset encoding for the generated HTML documents in
        the ejudge configuration files, but use the default
        value.

        During the configuration of the ejudge system it is
        recommended to specify the system character encoding as
        the value of this option. The system character encoding
        depends on the locale settings. You may view the system
        character encoding using "echo $LANG" command.

1.2. Recommended options
------------------------
The options of this group allows defining default values for
major configuration variables of the ejudge system. This greatly
simplifies further configuration of the system and reduce the
number of required configuration files. A user may always
specify new values of all configuration variables in the
configuration files. The values explicitly defined in the
configuration files has priority over default values.

In particular, specifying of options --enable-charset,
--enable-socket-path, --enable-contests-dir will result in
correct default values for all the required configuration
variables for the CGI programs master, judge, team, register,
users. As a consequence, the master.cfg, judge.cfg, team.cfg,
register.xml, and users.xml configuration files and the CGI
configuration directories are not required.

The description of all the recommended options is given below.
    --prefix=PREFIX
        This option allows specifying the directory, which will
        be used as the root directory for installation of
        executable files and libraries of the ejudge system. If
        this option is not specified, its default value is
        ${HOME}/inst-ejudge, i.e. the system will be installed
        to the inst-ejudge directory of the home directory of
        the user that invoked the configure script. Possibility
        of using the standard installation prefix directory
        (/usr, /usr/local) was not yet tested. This possibility
        should be used with caution, because conflicts between
        the names of the ejudge's files and the system files are
        possible.

        By default the ejudge installation directory will have
        the structure as follows. This structure may be changed
        using the fine-tuning options of the configure script.
                bin/            the executable files
                cgi-bin/        the executable files of CGI
                                programs
                include/        the libchecker library header
                                files
                lib/            the libchecker library object
                                modules
                libexec/ejudge  various additional programs and
                                scripts
                share/ejudge    the testlib library source code
                                (pascal)
                share/locale    message localization directory

        If you are not sure which value to specify in this
        option, leave its default value unchanged.

    --enable-socket-path=PATH
        This option allows specifying the default path to the
        UNIX-socket, which is used for data exchange between the
        user database server `userlist-server' and the other
        programs of the ejudge system. The PATH must be the full
        absolute path to a non-existent file in an existent
        directory. Upon startup the `userlist-server' will
        create a UNIX socket bound to this PATH. The PATH must
        not reside on network file systems (smb, nfs) or file
        systems without UNIX socket support (vfat). It is
        recommended to put the UNIX socket to a local public
        accessible file system. /tmp or /var/tmp are good
        candidates. For example, use the following option:
        --enable-socket-path=/tmp/userlist-socket

        If you are not sure, use the PATH as given above,
        /tmp/userlist-socket.

    --enable-super-serve-socket=PATH
        This option allows specifying the default path to the
        UNIX-socket, which is used for controlling the
        `super-serve' program by the `serve-control' CGI
        program. The PATH must be the full absolute path to a
        non-existent file in an existent directory. Upon startup
        the `userlist-server' will create a UNIX socket bound to
        this PATH. The PATH must not reside on network file
        systems (smb, nfs) or file systems without UNIX socket
        support (vfat). It is recommended to put the UNIX socket
        to a local public accessible file system. /tmp or
        /var/tmp are good candidates. For example, use the
        following option:
        --enable-super-serve-socket=/tmp/userlist-socket

        If you are not sure, use the PATH as given above,
        /tmp/super-serve-socket.

    --enable-conf-dir=DIR
        This option allows specifying the path to the ejudge
        configuration directory. The path to each individual
        configuration file may be further refined using the
        corresponding fine-tuning options of the configure
        script. The value of the --enable-conf-dir option
        influences the default values for the
        --enable-ejudge-xml and --enable-contests-dir options.
        For example, if specify the DIR equal to
        /home/judges/data using the option
        --enable-conf-dir=/home/judges/data
        then the default value for --enable-ejudge-xml will be
        /home/judges/data/ejudge.xml and the default value for
        --enable-contests-dir will be /home/judges/data/contests.
        The specified directory will be created, if necessary,
        during execution of the setup script.

        If you are not sure, specify the path /home/judges/data
        as the value of --enable-conf-dir option.

    --enable-contests-home-dir=DIR
        This option allows specifying the default directory
        where the home directories of the contests will be
        located. For example, if the /home/judges PATH is
        specified as the value of this option, the sample
        contest 1 will be installed to the directory
        /home/judges/000001. The specified directory will be
        created, if necessary, during execution of the setup
        script.

        If you are not sure, specify the path /home/judges as
        the value of --enable-contests-home-dir option.

    --with-httpd-cgi-bin-dir=DIR
        This option allows specifying the CGI directory of the
        http server. During execution of the setup script
        symlinks from the CGI programs of the ejudge system to
        the directory DIR are created. Many Linux distributions
        are supplied with the apache web server already
        installed with the /home/httpd/cgi-bin directory for
        CGI programs. Please, refer to the documentation on your
        system to clarify whether the apache http server is
        pre-installed and the path to its cgi-bin directory.

        If you do not want (or has no permissions) to install
        the ejudge's CGI programs into the primary web server
        directory of CGI files, you may specify any other
        directory in this option. Make sure, that files in this
        directory are treated as CGI programs by the web
        server. Often the web server is configured in a way,
        that a file is treated as a CGI program, if its name has
        the special suffix (usually .cgi). In this case consider
        using the --enable-cgi-suffix of the configure script.

        Note, that during execution of the setup script symlinks
        to the ejudge's CGI programs are installed into the web
        server CGI directory rather then the files. Thus, the
        web server must support symbolic links in the CGI
        directory. In the apache web server the configuration
        directive "Options FollowSymLinks" may be used to achieve
        the desirable effect.

    --with-httpd-htdocs-dir=DIR
        This option allows specifying the root directory for the
        web server HTML document hierarchy. The web server HTML
        document root directory is used by the contest server
        program `serve' to install symlinks to the files with
        the current standing tables.

        Many Linux distributions are supplied with the
        pre-installed apache web server and /home/httpd/html
        directory as the HTML document root directory. Please
        refer to the documentation on your system to clarify
        whether the apache http server is pre-installed and
        which is the path to its HTML document root directory. 

1.3. Options for programming languages support tuning
-----------------------------------------------------
During the configuration of the ejudge system the configure
script tries to determine which compilers and interpreters are
installed in the system and enables their support in the ejudge
system in the compilation server compile and the test contest
1. Currently the following compilers and interpreters are
automatically detected and supported:
  o GNU C                               http://gcc.gnu.org
  o GNU C++                             http://gcc.gnu.org
  o GNU Java (CGJ)                      http://gcc.gnu.org
  o GNU Fortran 77 (g77)                http://gcc.gnu.org
  o GNU Prolog                          http://pauillac.inria.fr/~diaz/gnu-prolog
  o GNU Pascal                          http://www.gnu-pascal.de
  o Free Pascal                         http://www.freepascal.org
  o Borland Delphi (Kylix)              http://www.borland.com
  o YaBasic (Basic Interpreter)         http://www.yabasic.de
  o Dr. Scheme (Scheme Interpreter)     http://www.drscheme.org
  o Python                              http://www.python.org
  o Perl                                http://www.cpan.org
  o SUN Java SDK 2                      http://java.sun.com
  o Mono C# (mcs)                       http://www.mono-project.com
  o Mono Visual Basic (mbas)            http://www.mono-project.com

If a supported compiler or interpreter is located in a
non-standard location, i.e. it is not accessible via the PATH
environment variable passed to the configure script, the path to
the compiler or interpreter may be specified explicitly using
the corresponding language support tuning option of the
configure script. And vice versa, if you want to disable support
for a compiler or interpreter, you may use option --without-LANG
in the configure's command line, where LANG is the language to
disable.

    --with-gcc
        Specify the path to the GNU C (gcc) compiler to be used
        in contests.
    --with-gpp
        Specify the path to the GNU C++ (g++) compiler.
    --with-fpc
        Specify the path to the Free Pascal (fpc) compiler.
    --with-gpc
        Specify the path to the GNU Pascal (gpc) compiler.
    --with-gcj
        Specify the path to the GNU Java (gcj) compiler.
    --with-g77
        Specify the path to the GNU Fortran 77 (g77) compiler.
    --with-dcc
        Specify the path to the Borland Delphi (dcc) compiler.
    --with-prolog
        Specify the path to the GNU Prolog (gplc) compiler.
    --with-yabasic
        Specify the path to the Basic (yabasic) interpreter.
    --with-scheme
        Specify the path to the Scheme (mzscheme) interpreter.
    --with-python
        Specify the path to the Python (python) interpreter.
    --with-perl
        Specify the path to the Perl (perl) interpreter.
    --with-javac
        Specify the path to the Java bytecode compiler (javac).
    --with-mcs
        Specify the path to the Mono C# compiler (mcs).
    --with-mbas
        Specify the path to the Mono Visual Basic compiler
        (mbas).

Note, that support for the Mono C# and Visual Basic languages is
experimental. The current version of the mono package does not
support specification of data size and stack size limitations as
well as specification of security policy. Thus use of these
compilers in open (untrusted) contests is not recommended. Even
if the mcs and mbas compilers are found in the system, they are
disabled in the serve.cfg configuration file for the test
contest 1. To enable their use it is necessary to edit the
serve.cfg file manually and remove `disabled = 1' line from the
language configuration section of these languages.

1.4. Fine tuning options for configuration paths and directories
----------------------------------------------------------------
The options of this group allow modifying the default settings
for various paths to the ejudge's components. All the options
have reasonable default values, which reflect typical use of the
system. Thus, it is not recommended to use these option without
strong need.

    --exec-prefix=EPREFIX
        This option allows specifying the directory (prefix) for
        installation of platform-dependent files and libraries
        of the ejudge system. If the --exec-prefix option is not
        specified, it default value is equal to the value of the
        --prefix option.

    --bindir=DIR
        This option allows specifying the directory for
        installation of the executable files of the ejudge
        system. All the ejudge's program except the CGI programs
        master, judge, team, register, users are installed into
        this directory. The ejudge-config script is installed
        there as well. If this option is not specified, its
        default value is EPREFIX/bin.

    --enable-cgi-bin-dir=DIR
        This option allows specifying the directory for
        installation of the CGI programs. The CGI programs
        master, judge, team, register, users are installed
        there. If this option is not specified, its default
        value is EPREFIX/cgi-bin.

    --libexecdir=DIR
        This option allows specifying the directory for
        installation of auxiliary executable programs and
        scripts. In particular, all the compilation scripts for
        all the supported languages, as well as the standard
        testing programs are installed there. If this option is
        not specified, its default value is EPREFIX/libexec/ejudge.

    --datadir=DATA-DIR
        This option allows specifying the directory for
        installation of platform-independent components of the
        ejudge system. The message localization catalog is
        installed into DATA-DIR/locale, and the testlib library
        for writing testing programs in Pascal is installed into
        DATA-DIR/ejudge directory. If this option is not
        specified in the configure's command line, its default
        value is PREFIX/share.

    --libdir=DIR
        This option allows specifying the directory for
        installation of the library files for the libchecker
        library. The libchecker library is used to write testing
        programs in C and C++. If this option is not specified,
        its default value is EPREFIX/lib.

    --includedir=DIR
        This option allows specifying the directory for
        installation of the libchecker library header files. If
        this option is not specified in the configure's command
        line, its default value is PREFIX/include.

    --enable-cgi-conf-dir=DIR
        This option allows specifying the directory for
        configuration files of the CGI programs. The directory
        may be specified either as absolute, or as relative
        path. If the path DIR is relative (for example,
        ../cgi-data), the absolute path to the CGI configuration
        directory is computed relative to the directory, from
        which a CGI program is started. The symlinks are not
        processed. For example, let the directory of CGI programs
        of the web server be /home/httpd/cgi-bin, and there is a
        symlink `master' pointing to the executable file at the
        path /home/you/inst-ejudge/cgi-bin/master. The value of
        this option is ../cgi-data. The `master' CGI program is
        started from the web server's CGI directory (i.e. the
        corresponding URL is http://HOST/cgi-bin/master). Then
        the absolute path to the CGI configuration directory is
        /home/httpd/cgi-bin/../cgi-data equals to /home/httpd/cgi-data.

        The value given in this option cannot be further changed
        in the configuration files, because this value is
        built-in into the CGI programs and used to calculate
        the path to the configuration file. The default value of
        this option is ../cgi-data.

    --enable-ejudge-xml
        This option allows specifying the default file name for
        the main configuration file ejudge.xml. This file is
        used by the userlist-server, super-serve, edit-userlist
        programs. If this option is not specified, but the
        option --enable-conf-dir=CONF-DIR is specified, the
        default value for this option is CONF-DIR/ejudge.xml.
        If neither --enable-ejudge-xml, nor --enable-conf-dir
        options are not specified, the default path to the
        ejudge.xml configuration file is undefined and must be
        specified explicitly in arguments of the respective
        programs. In any way, explicit specification of the path
        to the configuration file has priority over the default
        value.

    --enable-contests-dir=DIR
        This option allows specifying the path to the contest
        configuration files directory. This directory contains
        the contest.xml configuration file for all the contests
        defined in the ejudge system. If this option is not
        specified in the configure's command line, but the
        option --enable-conf-dir=CONF-DIR is specified, the
        default value for this option is CONF-DIR/contests.
        If neither --enable-ejudge-xml, nor --enable-conf-dir
        options are not specified, the default path to the
        contest configuration directory is undefined and thus
        must be specified explicitly in all the configuration
        files.

        The contest configuration directory is used by all the
        programs of the ejudge system. If the default value of
        the path is undefined, the path must be specified
        explicitly in all the configuration files of all the
        programs of the ejudge system (ejudge.xml, serve.cfg,
        master.cfg, judge.cfg, team.cfg, register.xml,
        users.xml). But if the path is defined explicitly in a
        configuration file, it has priority over implicit
        default value.

1.5. Compile-time fine-tuning options
-------------------------------------
The options of this group allow refining paths to the
directories of include files and/or directories of library files
of the libraries required for compilation of the ejudge system.
The default values of these options corresponds to the most
commonly used way of installation of the libraries. In most
cases, explicit use of the compile-time fine-tuning options is
not necessary.

    --with-libcap=LIBCAP-DIR
        This option allows specifying the root directory of the
        libcap library installation. If the libcap library is
        compiled with support for special capability bits
        (CAP_SYS_OPERATIONS, CAP_SYS_ONE_EXEC), provided by the
        ejudge's Linux kernel patch (http://acm.msu.ru/ejudge/kernel.shtml),
        the configure script enables compilation of the capexec
        program and the libdropcaps.so shared library, which are
        used for secure execution of tested programs. If the
        libcap library is installed in standard locations (/usr,
        /usr/local), the --with-libcap option is not necessary.

        If the libcap library is not found in the system, or
        does not support the required capability bits, or these
        capability bits are not supported by the current Linux
        kernel at the moment of configuration of the ejudge
        system, compilation of the capexec program and the
        libdropcaps.so shared library is disabled. Compilation
        of them may also be disabled explicitly using the
        --with-libcap configure option.

    --with-libcap-include-dir=DIR
        This option allows specifying the path to the include
        files for the libcap library. This must be the directory
        containing <sys/capability.h> header file. The default
        value for this option is LIBCAP-DIR/include, if the
        option --with-libcap is specified. The standard include
        directories are used elsewhere.

    --with-libcap-lib-dir=DIR
        This option allows specifying the path to the library
        files for the libcap library. This must be the directory
        containing libcap.a (libcap.so) library file. The
        default value for this directory is LIBCAP-DIR/lib, if
        the --with-libcap option is specified. The standard
        library directories are used elsewhere.

    --with-expat=EXPAT-DIR
        This option allows specifying the root directory of the
        expat library installation. Expat is a XML parsing
        library. The most of the modern Linux distributions are
        supplied with this library already installed. This
        option is not necessary, if the expat library is located
        at the standard system directories (/usr, /usr/local).

        If the configure script does not found the expat
        library, or the library is not suitable for compilation
        of the ejudge system, the configure script reports a
        fatal error and aborts, because the expat library is
        required for compilation.

    --with-expat-include-dir=DIR
        This option allows specifying the directory with the
        expat header file. This directory must contain the
        <expat.h> file. The default value for this option is
        EXPAT-DIR/include, if the --with-expat option is
        specified. The standard include directories are used
        elsewhere.

    --with-expat-lib-dir=DIR
        This option allows specifying the directory with the
        expat library file. This directory must contain the
        files libexpat.a or libexpat.so. The default value for
        this option is EXPAT-DIR/lib, if the --with-expat option
        is specified. The standard library directories are used
        elsewhere.

    --with-reuse-include-dir=DIR
        This option allows specifying the directory with the
        reuse library header files. The default value of this
        option is REUSE-DIR/include. This corresponds to the
        standard structure of the directories of the reuse
        library installation.

    --with-reuse-lib-dir=DIR
        This option allows specifying the directory with the
        reuse library object files. The default value of this
        option is REUSE-LIB/lib. This corresponds to the
        standard structure of the directories of the reuse
        library installation.

1.6. Other options
------------------
    --with-reuse-config=CONFIG-NAME
        This option allows explicit specifying of the reuse
        configuration name, if it cannot be detected
        automatically (for example, the script REUSE-DIR/etc/config.guess 
        is missing). For the Linux systems the reuse
        configuration name is equal to ix86-linux.

    --enable-cgi-suffix=SUFFIX
        This option allows specifying the suffix for the names
        of the executable files of CGI programs. For example,
        sometimes the web server is configured so, that all
        files with the .cgi suffix are treated as CGI scripts.
        In this case you may specify "--enable-cgi-suffix=.cgi"
        option for the configure script.

    --enable-static
        Link all the executable files statically. The executable
        files in this case will not depend upon shared
        libraries. However, the size of the executables will be
        significantly larger. Additionally, this option disables
        compilation of the shared version of the libchecker
        library (libchecker.so).

    --disable-rpath
        This option disables use of the -rpath option of the
        linker. The option is effective only if --enable-static
        option is not defined (i.e. use of shared libraries is
        enabled). The -rpath linker option is used to embed the
        path to the shared libraries into the executable files.
        If the -rpath feature is disabled and a library is
        located at a non-standard path, the directory with the
        library should either be listed in the system
        configuration files (/etc/ld.so.conf), or be specified
        in the LD_LIBRARY_PATH environment variable.

        In the current version of the ejudge system this
        influences only on linking of testing programs against
        the libchecker library. In the future version this
        option may influence linking of the ejudge's programs
        against other libraries (reuse, expat, cap).

    --disable-nls
        This option allows disabling the support for interface
        localization, in case, when the operating system
        contains all the necessary support. All the interface
        will be provided in English only.

    --with-festival=PATH
        This option allows specifying the path, where the
        festival speech synthesizer is installed. PATH must be
        specified so, that the `festival' program is located in
        the ${PATH}/bin directory. The current version of the
        configure does not check the correctness of the
        PATH specification.

2. Compilation of the ejudge system
-----------------------------------
In order to compile the ejudge system execute the `make'
command. In the make command line you may specify certain
variables to tune the compilation process. These variables are
described below.

    STATIC=1
        Link statically the executable files. Use of this
        variable is equivalent to specification of the
        --enable-static option in the configure's command line.

    NO_KERNEL=1
        Disable compilation of the capexec program and the
        libdropcaps.so library. Use of this variable is
        equivalent to specification of the --without-libcap
        option in the configure's command line. If the libcap
        library is not found in the system, or is not suitable,
        or the current kernel does not support the required
        capability bits, the NO_KERNEL variable is set to 1
        automatically by the configure script.

    RELEASE=1
        Enable compilation of the ejudge system in the release
        mode. In this mode compiler optimization (-O2) is
        enabled, debugging information is disabled, and the
        diagnostic macros (like assert) are disabled as well. In
        the non-release (debugging) mode, optimization is not
        enabled, debugging info and diagnostic macros are
        enabled.

    CDEBUGFLAGS=FLAGS
        Specify explicitly the optimization and debugging flags
        for the C compiler, for example CDEBUGFLAGS="-O3 -Wall".
        If this variable is specified, use of the RELEASE
        variable will have no effect, just because the RELEASE
        variable selects an alternative value for CDEBUGFLAGS,
        which is actually overridden from the command line.

3. Installation of the compiled files
-------------------------------------
For installation of the compiled files the "make install"
command is used. Special variables, which influence the
installation process may be specified in the make command
line. These variables are described below.

If a system directory was specified as the installation
directory (using the --prefix option of the configure script),
the root privileges may be required to perform "make install"
command.

    DESTDIR=DIR
        Allow specifying the path prefix, which will be added to
        all the paths during the ejudge system installation. For
        example, if the --prefix option is equals to
        /usr/local/pkg/ejudge-2.1.30, and the DESTDIR variable
        is specified as DESTDIR=/tmp/build, all the files of the
        ejudge system will be installed into the directory
        /tmp/build/usr/local/pkg/ejudge-2.1.30. This option is
        mainly for package distributors and supported by most
        programs following the GNU coding style.

4. Generation of the setup script
---------------------------------
On the previous stage all the ejudge's files were installed into
the directory specified by the --prefix option of the configure
script. Now it is necessary to perform setup of the ejudge
system. On this step the paths to the configuration files are
refined, the ejudge system administrator identity is defined,
the necessary configuration files for the ejudge's programs are
generated, and the test contest 1 is set up.

The initial setup of the ejudge system is performed in two
steps. On the first step the setup script is generated. The
ejudge-setup program is used to generate the setup script, and
this program is run under a regular user. On the second step the
generated setup script is executed, which may require the
administrator (root) privileges.

Generation of the setup script using the ejudge-setup program is
described in detail below. The ejudge-setup program allows
defining the values of many configuration variables of the
ejudge system using a menu-oriented user interface. If during
the configuration step all the recommended configure's options
were defined to correct values, almost all the configuration
variables will be set to correct values in the ejudge-setup
program. The only thing, that must be specified in this case is
the ejudge system administrator identity, which could be changed
using the "Edit Administrator Identity" menu item. Nevertheless,
it is recommended to review all the remaining menu items to
ensure, that all the configuration variables are set to correct
values and fix them, if necessary.

The main screen of the ejudge-setup program is the menu
containing 7 items.
        Edit paths
        Edit global settings
        Edit administrator identity
        Preview files
        Preview install script
        Save install script
        Quit

4.1. The "Quit" menu item
------------------------
Selection of this menu item makes the ejudge-setup to finish its
execution. All unsaved changed made in the configuration
variables will be lost.

4.2. The "Save setup script" menu item
--------------------------------------
This menu item allows saving the generated setup script. After
choosing this menu item a dialog will be displayed to specify
the name of the setup script. Relative path is calculated
starting from the current directory of the ejudge-setup
program. The default value for the setup script name is
ejudge-install.sh.

Saving of the setup script is possible, if all the configuration
variables are set to correct values. Incorrect values are marked
with exclamation sign '!' near with configuration variable
name. If the setup script cannot be saved, an error message
containing the name of the first configuration variable with
invalid value is displayed.

4.3. The "Preview setup script" menu item
-----------------------------------------
This menu item allows previewing of the setup script before its
saving to a file. Previewing of the setup script is possible if
all the configuration variables are set to correct values.

4.4. The "Preview files" menu item
----------------------------------
This menu item allows previewing of all the configuration files,
which are generated by the ejudge-setup program. After choosing
this menu item the 2-nd level menu is displayed, allowing
choosing a file to preview. This menu contains the following
items:
        To upper level menu
        ejudge.xml
        userlist.xml
        000001.xml
        compile.cfg
        serve.cfg
        master.cfg
        judge.cfg
        team.cfg
        register.xml
        users.xml

4.4.1. The "Preview files->To upper level menu" menu item
Allows returning to the main menu of the ejudge-setup program. 

4.4.2. The "Preview files->ejudge.xml" menu item
Allows previewing the contents of the main configuration file
ejudge.xml. In the first line of the screen the path, where the
ejudge.xml file will be installed, is displayed.

4.4.3. The "Preview files->userlist.xml" menu item
Allows previewing the initial contents of the user database.
Initially the user database contains only record about the
ejudge system administrator. The parameters of the administrator
identity are specified in the "Edit administrator identity"
menu.

4.4.4. The "Preview files->000001.xml" menu item
Allows previewing the contents of the test contest 1 XML
configuration file.

4.4.5. The "Preview files->compile.cfg" menu item
Allows previewing the contents of the compilation server
configuration file.

4.4.5. The "Preview files->serve.cfg" menu item
Allows previewing the contents of the test contest 1 server
configuration file.

4.4.5. The "Preview files->master.cfg" menu item
Allows previewing the contents of the configuration file for the
`master' CGI program. If during the configuration of the ejudge
all the recommended configuration options were specified
correctly and their values were not changed in the ejudge-setup
program, then all the necessary values are already built-in into
the program code. The configuration files for CGI programs in
this situation are not required, and attempt to preview the
contents of the CGI program configuration files the message
"This configuration file is not needed!" will be displayed.

4.4.6. The "Preview files->judge.cfg" menu item
Allows previewing the contents of the configuration file for the
`judge' CGI program. See section 4.4.5 for further detail.

4.4.7. The "Preview files->team.cfg" menu item
Allows previewing the contents of the configuration file for the
`team' CGI program. See section 4.4.5 for further detail.

4.4.8. The "Preview files->register.xml" menu item
Allows previewing the contents of the configuration file for the
`register' CGI program. See section 4.4.5 for further detail.

4.4.9. The "Preview files->users.cfg" menu item
Allows previewing the contents of the configuration file for the
`users' CGI program. See section 4.4.5 for further detail.

4.5. The "Edit administrator identity" menu item
------------------------------------------------
This menu item allows defining the parameters of the
administrator of the ejudge system. The administrator user has
the full privileges for user database editing and for contest
management. The parameters of the administrator will be stored
in the user database file userlist.xml.

When this menu item is chosen, the administrator identity
editing screen is displayed. The screen contains the following
controls. If some configuration variable has invalid value, it
is marked with exclamation sign `!'.

    Return to upper-level menu
        Allows returning to the main menu of the ejudge-setup
        program.

    Admin ID
        Allows specifying the user identifier for the
        administrator. The user identifier is an integer number
        in range from 1 to 999999. There is no "magic" numbers
        (like uid 0 in Unix systems) in the ejudge system. The
        privileges of a user are fully determined by the set of
        capabilities defined for this user.

    Admin login
        Allows specifying the administrator login. The
        administrator login is entered in the login screen of
        the ejudge CGI programs. The login may consists of small
        and capital Latin letters, digits and `_' and `-'
        signs. All other characters are invalid. The maximal
        length of the administrator login is not limited,
        however, the ejudge-setup program does not support
        logins longer than 63 characters.

    Admin e-mail
        Allows specifying the e-mail of the administrator user.
        In the current version of the ejudge system the email
        address is not used and is entered just for
        completeness. The maximal length of the administrator
        e-mail is not limited, however the ejudge-setup program
        does not support e-mail addresses longer than 255
        characters.

    Admin name
        Allows specifying the administrator name. The
        administrator name is an arbitrary string (like gecos
        field in the /etc/passwd database). The ejudge-setup
        program does not support user names longer then 255
        characters.

    Admin password
        Allows specifying the administrator password. The
        password is asked twice and is displayed with `*'. If
        the password is entered correctly, a message box
        "The password sha1 hash is XXX!" is displayed, where XXX
        is the hash of the password.

4.6. The "Edit global settings" menu item
-----------------------------------------
This menu item allows defining the global settings of the
ejudge system. These parameters will be stored in several
configuration files, including ejudge.xml, serve.cfg,
compile.cfg. When this menu item is chosen the global settings
editing screen is displayed, which contains the controls as
follows. If a configuration variable has invalid value, this
variable is marked with an exclamation sign `!'.

    Default charset
        The default charset encoding for the generated HTML
        documents. As it has been mentioned above in the
        description of the --enable-charset option of the
        configure script, in the current version of the ejudge
        system the encoding of the HTML documents must be the
        same, as the ejudge internal charset encoding, as
        specifyed by the --enable-charset option of the
        configure script. Thus it is strongly not recommended to
        change the value of this configuration variable.

        If this configuration variable is undefined, return to
        the configuration step and specify the correct encoding
        in the configure's command line.

    Sendmail program
        This menu item allows specifying the full path to the
        mail transport agent, which is responsible for sending
        e-mails. By default this path is equal to
        /usr/sbin/sendmail. You may change this path to the path
        to any other mail transport agent (MTA). Do not specify
        the path to a mail user agent (MUA) in this
        configuration variable. A mail user agent is a program,
        which provides the user interface to work with e-mail
        (for example, pine, mutt, etc). The path specified in
        this configuration variable must be the path to the
        existing program which can be executed by the current
        users. The value of this configuration variable will be
        stored as element <email_program> of the ejudge.xml
        configuration file and may be edited in future.

    `register' email
        This menu item allows specification of the e-mail
        address, which will be used as "From:" address in the
        messages, which are send as confirmation for the
        registration. This message contains automatically
        generated password, which must be used for the initial
        login to the ejudge system. The initial value of this
        configuration variable is USER@HOST, where USER is the
        login of the user running the ejudge-setup program, and
        HOST is the name of the current host. The value of this
        configuration variable will be stored as element
        <register_email> if the ejudge.xml configuration file
        and may be edited in future. Note, that the register
        e-mail address may be defined for each contest
        individually.

        Please, check the initial auto-generated value of this
        configuration variable and fix it, if necessary.

    `register' URL
        This menu item allows specifying the URL for initial
        login after the registration in the ejudge system of a
        new user. The registration procedure for a new user is
        as follows: the user specifies a desired login and his
        email address, then the ejudge system generates the
        initial password and sends it to the provided email
        address. This message contains the randomly generated
        password and the URL, which may be used for initial
        login. This URL is specified in this configuration
        variable. The URL must refer to the register CGI
        program, but must not contain any parameters of the
        register CGI program, because the necessary parameters
        will be added automatically. The initial value of this
        variable is http://HOST/cgi-bin/register, where HOST is
        the hostname of the computer. The value of this
        configuration variable will be stored as <register_url>
        element of the ejudge.xml configuration file and may be
        edited in future. Note, that the register URL may be
        defined for each contest individually.

        Please, check the initial auto-generated value of this
        configuration variable and fix it, if necessary.

    Serialization key
        This menu item allows defining the key of the
        serialization semaphore. The key is an integer number in
        range from 1 to 29999 and must not be equal to the
        semaphore keys used by other programs on the current
        system (use ipcs for information about the occupied
        keys). The serialization semaphore is used to prevent
        several instances of `compile' or `run' programs from
        running compilation or testing task simultaneously on the
        same computer. The initial value of this configuration
        variable is 22723. The serialization semaphore key is
        stored in the <serialization_key> element of the
        ejudge.xml configuration file as well as in the
        serialization_key global configuration variable of the
        compile.cfg compilation server configuration file and
        serve.cfg test contest 1 server configuration file.
        Thus, if the serialization key value must be changed in
        future, this will require changing the compile.cfg file
        and all the serve.cfg configuration files for all the
        contests defined in the ejudge system.

        It is advised not to change the value of this
        configuration variable.

    System uid
        This menu item allows defining the system login of the
        Linux user, who will be the owner of all the directories
        and files, which will be created during execution of the
        ejudge setup script. The initial value of this
        configuration variable is equal to the user login of the
        user, who runs the the ejudge-setup program.

        The user login specified in this configuration variable
        must be valid for this computer, i.e. there must be a
        record corresponding to this login in the /etc/passwd
        file.

    System gid
        This menu item allows defining the system user group of
        the Linux group, which will be the owner of all the
        directories and files, which will be created during
        execution of the ejudge setup script, generated by the
        ejudge-setup program. The initial value of this
        configuration variable is equal to the user primary
        group of the user, who runs the ejudge-setup program.

        The group name specified in this configuration variable
        must be valid for this computer, i.e. there must be a
        record corresponding to this group in the /etc/group
        file.

    Create workdisk?
        This menu item allows changing the value of the workdisk
        creation flag. The workdisk creation flag may have value
        either "yes" or "no". If the value is "yes", during
        execution of the setup script a virtual file system for
        execution of programs being tested will be created. This
        file system is mapped to a file using ext2 file system
        and loop mounting (see the section below on path
        configuration).

        Creation of the work disk is not a mandatory step during
        execution of ejudge setup script. In the path
        configuration section (see below) it is possible to
        specify a working directory common for all the contests,
        and even if the common working directory is not
        specified, private working directories will be used for
        each contest. However, creation of the separate file
        system for working directory of the programs under
        testing is strongly recommended, because allows better
        isolation of the program under testing from the
        operating system. For example, if the program under
        testing caused (unintentionally or intentionally)
        complete exhausting of free disk space, this will not
        affect other programs in this computer.

    Workdisk size (MB)
        This menu item allows changing the size of the virtual
        file system for working directory. The size is specified
        in megabytes. This configuration variable is available,
        if the "Create workdisk?" configuration variable is set
        to "yes". Note, that the free size available to the
        programs is slightly less than the size of the workdisk
        due to file system data.

    Install to cgi-bin?
        This menu item allows changing the cgi-bin installation
        flag. The value of this configuration variable may
        either be "yes" or "no". If the variable is set to
        "yes", during execution of the ejudge setup script
        symlinks to the ejudge's CGI programs will be installed
        to the web server CGI directory.

4.7. The "Edit paths" menu item
-------------------------------
    Socket path
        This menu item allows changing the path to the UNIX
        socket, which is used for data exchange between the user
        database server userlist-server and all other programs
        of the ejudge system. This configuration variable
        corresponds to the --enable-socket-path option of the
        configure script. If this option were specified during
        the configuration step, its value will be displayed
        here. In this case it is not recommended to change it,
        because the new value of the path has to be specified in
        all the configuration files, including the configuration
        files of the CGI programs. Otherwise, if during the
        configuration step the --enable-socket-path option was
        not specified, the "Socket path" configuration variable
        must be specified in the ejudge-setup program, or the
        ejudge setup script will not be generated.

    Super-serve socket path
        This menu item allows changing the path to the UNIX
        socket, which is used for controlling the super-serve
        program by the serve-control CGI program. This
        configuration variable corresponds to the
        --enable-super-serve-socket option of the configure
        script. If this option were specified during the
        configuration step, its value will be displayed 
        here. In this case it is not recommended to change it,
        because the new value of the path has to be specified in
        all the configuration files, including the configuration
        files of the CGI programs. Otherwise, if during the
        configuration step the --enable-super-serve-socket
        option was not specified, the "Super-serve socket path"
        configuration variable must be specified in the
        ejudge-setup program, or the ejudge setup script will
        not be generated.

    Config directory
        This menu item allows changing the path to the ejudge
        configuration directory. This configuration variable
        corresponds to the --enable-conf-dir option of the
        configure script. If this option was specified during
        configuration of the ejudge system, its value will be
        displayed here. In this case it is not recommended to
        change it here. In other case, if the --enable-conf-dir
        option were not specified, the path to the configuration
        directory must be specified in this configuration
        variable, or the setup script will not be generated.

    Path to ejudge.xml
        This menu item allows changing the path to the main
        ejudge's configuration file ejudge.xml. This variable
        corresponds to the --enable-ejudge-xml option of the
        configure script. If this option was specified during
        configuration of the ejudge system, its value will be
        displayed here. In this case it is not recommended to
        change it. In other case, if the --enable-ejudge-xml
        option were not specified, this configuration variable
        must be set, or the setup script will not be generated.

    Contest XML dir
        This menu item allows changing the path to the directory
        of the contest configuration files contest.xml. This
        configuration variable corresponds to the
        --enable-contests-dir option of the configure script. If
        this option was specified during configuration of the
        ejudge system, its value will be displayed here. In this
        case it is not recommended to change it, because the new
        path to the contest configuration directory must be
        specified explicitly in all the configuration files of
        the ejudge system. In the other case, if the
        --enable-contests-dir option were not specified, this
        configuration variable must be set, or the setup script
        will not be generated.

    Contests home dir
        This menu item allows defining or changing the path to
        the directory to store the contest home directories.
        This configuration variable corresponds to the
        configure's option --enable-contests-home-dir. If this
        option was specified in the configure's command line
        during configuration of the ejudge system, its value
        will be displayed here. The value of this configuration
        variable may be freely changed, because this value is
        not built-in into the executables and influences only
        the installation path of the test contest 1. The value
        of this configuration variable is stored only in the
        main ejudge.xml configuration file in the element
        <contests_home>. If the --enable-contests-home-dir
        option was not specified during the configuration step,
        this configuration variable must be set, or the setup
        script will not be generated.

    httpd cgi-bin dir
        This configuration variable allows specifying the path
        to the directory for CGI programs of the web server. The
        configuration variable corresponds to the
        --with-httpd-cgi-bin-dir option of the configure
        script. If this option was specified during the
        configuration step, its value will be displayed here.
        The value of this configuration variable may freely be
        changed, because it only influences on the path for
        installation (creation of symlinks) of the CGI
        programs. If the `Install to cgi-bin?' configuration
        variable is set to "yes", and the --with-httpd-cgi-bin-dir
        option was not specified in the configure's command
        line, the `httpd cgi-bin dir' configuration variable
        must be specified. If the `Install to cgi-bin?'
        configuration variable is set to "no", this
        configuration variable is not displayed and cannot be
        changed since it is not used during the setup process.
        Also see the description of the `Full CGI config dir'
        configuration variable below.

    httpd html dir
        This menu item allows specifying the HTML document root
        directory of the web server. This configuration variable
        corresponds to the --with-httpd-htdocs-dir option of the
        configure script. If this option was specified in the
        configure's command line, it is displayed here. In this
        case it is not recommended to change its value, because
        its value is the default value for the `serve' program,
        thus changing the default value will require explicit
        specification of the `htdocs_dir' configuration variable
        in all the serve.cfg configuration files for all the
        contests defined in the ejudge system. The `httpd html dir'
        configuration variable is not mandatory, i.e. if the
        --with-httpd-htdocs-dir option was not specified in the
        configure command line and this configuration variable
        remains undefined in the ejudge-setup program, automatic
        installation of symlinks to the HTML files with the
        current contest standings will be disabled. The value of
        this configuration variable may further be refined for
        each contest individually using the `htdocs_dir' global
        configuration variable of the serve.cfg contest
        configuration file.

    CGI config dir
        This menu items displays the path to the configuration
        directory for the CGI programs. This path cannot be
        changed from the ejudge-setup program just because it is
        built-in into the CGI programs and is used to find the
        configuration files. The specified path may either be
        absolute or relative. If the path is relative, the full
        path is calculated relative to the path to the CGI
        programs of the web server (see the description of the
        `httpd cgi-bin dir' configuration variable above).
        If there is a configuration variable, necessary for the
        CGI programs but is not set to its default value, the
        CGI configuration files will be created during execution
        of the ejudge setup script, and this requires
        specification of the `httpd cgi-bin dir' configuration
        variable. If the path to CGI configuration directory is
        absolute, the value of the `httpd cgi-bin dir'
        configuration variable is not required.

    Full CGI config dir
        This menu item displays the full path to the
        configuration directory of the CGI programs. This path
        is calculated automatically using the value of the
        `CGI config dir' configuration variable and the value of
        the `httpd cgi-bin dir' configuration variable (if
        necessary). This menu item is automatically updated each
        time these configuration variables are changed by user.

    User XML database
        This menu item allows specifying the path to the user
        database file. If the `Config directory' (see above)
        configuration variable is set, the initial value of this
        variable is equal to CONF-DIR/db/userlist.xml. In the
        other case the initial value of this variable is
        undefined and must be specified by user. The path to the
        user database file is stored in the <db_path> element of
        the ejudge.xml configuration file.

    Compile server dir
        This menu item allows specifying the home directory for
        the compilation server. The test contest 1 is set up in
        the way, that in order to compile the programs before
        testing a separate "compilation server" (the compile
        program) is used, which home directory is located
        separately from the home directory of the contest
        itself. It allows sharing the same compilation server
        between all the contests of the ejudge system. If during
        the configuration step the --enable-contests-home-dir
        option of the configure script was specified, the
        initial value of this configuration variable is set
        automatically to CONTESTS-HOME-DIR/compile. In the other
        case the compile server home directory must be specified
        by user.

        The compile server home directory is stored in several
        configuration files: the main configuration file
        ejudge.xml, the compilation server configuration file
        compile.cfg, and the test contest 1 configuration file
        serve.cfg. Thus changing the compilation server home
        directory in future will require modifying several
        configuration files and is not recommended.

    Sample contest dir
        This menu item allows specifying the home directory of
        the test contest 1. The test contest is used to ensure
        correct operation of the ejudge system after its
        installation and setup. The test contest has the contest
        identifier equal to 1. If on the configuration step the
        --enable-contests-home-dir option was specified in the
        configure's command line, then the initial value of this
        configuration variable is automatically set to
        CONTESTS-HOME-DIR/000001. In the other case this
        configuration variable must be set by user.

        In future all the home directories for the new contests
        will be located in the CONTESTS-HOME-DIR directory and
        have the names equal to their contest identifiers
        (aligned to 6 characters with zeros).

    standings.html path
        This menu item allows specifying the relative path to
        the file containing the current standings of the test
        contest. The path is specified relative to the web
        server HTML document root directory (see the description
        of the `httpd html dir' configuration variable above).
        During the contest the contest server `serve' generates
        and periodically updates the table of the current
        standings in the contest, but the primary location of
        the standing files is in the contest working directory
        (CONTEST-HOME/var/status/dir). Note, that the contest
        working directory must not be accessible by the clients
        of the web server (i.e. it must be located outside of
        the web server HTML document directory hierarchy). In
        order to make the current standings available to the
        clients of the web server the contest server `serve'
        upon startup creates at the specified in this
        configuration variable location in the web server HTML
        document directory hierarchy symlinks to the HTML files
        with the current standings in the working directory of
        the contest. If the `httpd html dir' configuration
        variable is not set, or this configuration variable is
        not set, the symlink will not be created automatically
        and must be created manually, if necessary.

    Full standings path
        This menu item displays the full path to the file with
        the current standings of the test contest 1. As
        mentioned above, this file is the symlink to the
        original file in the working directory of the contest.
        The full path is built automatically using the values of
        the `httpd html dir' and the `standings.html path'
        configuration variables (see above). This field cannot
        be edited directly, but is updated each time the value
        of any of the above mentioned configuration variables is
        changed.

    Testing working dir
        This menu item allows defining the directory to be
        used for testing. This menu item is displayed only if
        the `Create workdisk?' configuration variable (see
        above) is set to "No", i.e. when no working disk will be
        created during execution of the ejudge setup script. In
        this case this configuration variable allows specifying
        an arbitrary existing directory to be used as the
        working directory during testing of participant's
        programs. 

        This configuration variable is not mandatory. If it is
        undefined, each contest will use its own private
        directory in the contest home directory as the working
        directory for testing. This is not recommended, though.

    Workdisk image path
        This menu item allows specifying the path to the working
        directory virtual file system file. This menu item is
        displayed, if the configuration variable `Create workdisk?' 
        is set to "yes", i.e. when the working disk will be
        created during execution of the setup script. This
        configuration file defines the path to a file, which
        will be created during execution of the setup script.
        An ext2 file system is then created in this file, and it
        will be mounted as loop device. Note, that the size of
        this file will be fairly big, and this file must not be
        located in the network file system.

        The initial value for this configuration variable is set
        to CONTESTS-HOME-DIR/work-img, if the --enable-contests-home-dir
        option was specified in the configure's command line, or
        undefined in the other case, so it must be defined
        manually by user. The value of this configuration
        variable may be freely changed.

    Workdisk mount dir
        This menu item allows specifying the mount point for the
        testing working directory file system. This menu item is
        displayed only if the `Create workdisk?' configuration
        variable is set to "yes". The ejudge setup script will
        create and initialize the working disk image, create the
        workdisk mount point, if necessary, and then mount the
        working disk image at the specified mount point.

        Note, however, that the ejudge setup script does not
        modify the system startup scripts. So, the working disk
        will not be mounted after the reboot of the system, and
        as a consequence, the ejudge system may fail to start.
        You may either mount the working disk manually after each
        reboot, or modify the system startup script. See below
        on instructions on modifying startup scripts.

    Ejudge cgi-bin dir
        This menu item allows changing the path to the
        directory with the ejudge CGI programs. This
        configuration variable corresponds to the
        --enable-cgi-bin-dir option of the configure script. It
        is not recommended to change the value of this
        configuration variable.

    Localization dir
        This menu item allows changing the path to the message
        localization directory. This menu item is displayed only
        if localization is enabled by the configure script. It
        is not recommended to change the value of this
        configuration variable.

    Script dir
        This menu item allows changing the path to the directory
        with the auxiliary programs and scripts of the ejudge
        system. This configuration variable corresponds to the
        --libexecdir option of the configure script. This
        directory contains the compilation scripts for all the
        supported programming languages and the standard
        checking programs. It is not recommended to change the
        value of this configuration variable.

    Path to `serve'
        This menu item allows changing the path to the `serve'
        (the contest server) program of the ejudge system. It is
        not recommended to change the value of this
        configuration variable.

    Path to `run'
        This menu item allows changing the path to the `run'
        (the contest testing server) program of the ejudge
        system. It is not recommended to change the value of
        this configuration variable.

5. Execution of the setup script
--------------------------------
The mission of the initial configuration program ejudge-setup is
to create the setup script, which will perform the actual setup
actions. This script is saved to a file using the menu item
`Save setup script'. The default name of the setup script is
ejudge-install.sh, but it can be freely changed by user. For
simplicity we assume, that the name of the setup script was not
changed and is equal to ejudge-install.sh.

It is recommended to review this script in order to ensure, that
all the configuration variables are set to the correct values,
and also to ensure, that the script will not perform any
undesirable action.

In order to create the necessary directories, create and
initialize the working disk, and to mount it the administrator
(root) privileges are required, thus the ejudge-install.sh
script must be run by root. You may either login on another
console (virtual terminal) as root, or use the "su -" command.
However, if creation of the working disk is disabled (see the
`Create workdisk?' configuration variable) and all the
directories and files are located so that they can be created by
a regular user, no root privileges are required for execution of
the ejudge-install.sh script. The latter mode of operation is
not recommended, though.

To execute the setup script it is enough just to start it from
the command line. The setup script does not demand any command
line arguments. During its execution the setup script prints
verbose information about performed actions, and in case of
error it will print the detailed description of the error.

The setup script uses the `uudecode' program. If this program is
not installed in your system, you need to install the
`sharutils' package, which contains this program. Please refer
your operating system information for further information about
the sharutils package and package installation.

The setup script also uses the following programs: install, dd,
mke2fs, mount, ln, chown, tar. These programs should be
installed in any Linux distribution by default.

6. Checking the correct operation of the ejudge system
------------------------------------------------------
If execution of the ejudge setup script is completed
successfully, the ejudge system is ready to work.

Note, that all the programs of the ejudge system cannot be run
under the `root' (superuser) system account. You should either
use an existing unprivileged account, or create a new account.

In order to check its operation it is necessary to perform the
following actions:
  1) start the user database server userlist-server.
        To do this change the current directory to the
        EJUDGE-CONF-DIR directory and start the server with the
        command
                EJUDGE-BIN-DIR/userlist-server ejudge.xml
        If on the configuration step the --enable-ejudge-xml or
        the --enable-conf-dir options were specified in the
        configure's command line, and the path to the ejudge.xml
        configuration file was not changed in the ejudge-setup
        program (see the `Path to ejudge.xml' configuration
        variable), then the correct path to the ejudge.xml
        configuration file will be built-in into the
        userlist-server, and thus the corresponding argument may
        be omitted. Then the command to start the user database
        server will be just
                EJUDGE-BIN-DIR/userlist-server

        Note, that the ejudge programs does not switch to daemon
        mode, so they occupy the current terminal in the
        foreground mode. On the first hand, it is possible to
        start them is background mode using the command
                EJUDGE-BIN-DIR/userlist-server &
        However, this way has its drawbacks, that, first, the
        started program cannot be terminated just by pressing
        Ctrl-C (you have to get its pid using the `ps' command
        and then send the SIGTERM signal to this pid), and,
        second, the diagnostic and logging output of the program
        will mix with the output from other programs running on
        the same terminal. That's why its recommended to start
        each ejudge program in its own terminal, and to keep the
        terminal session when the user is not logged in use the
        `screen' program.
  2) start the compilation server `compile'.
        To do this change the current directory to the
        COMPILE-HOME-DIR directory and start the compilation
        server using the command
                EJUDGE-BIN-DIR/compile conf/compile.cfg
  3) start the contest management server `super-serve'.
        To do this change the current directory to the
        CONTESTS-HOME-DIR directory and start the contest
        manager using the command
	       EJUDGE-BIN-DIR/super-serve

After starting of all these programs ensure, that the web server
also started, and start it, if necessary.

Now you may enter the contestant's personal page located at the
URL http://localhost/cgi-bin/team?contest_id=1. Specify the
login and password you specified in the ejudge-setup program in
the administrator identity section. You may also enter the
administrator's personal page, located at the URL
URL http://localhost/cgi-bin/master?contest_id=1. Also specify
the login and password you specified in the ejudge-setup program
in the administrator identity section. Check that all actions
work correct. Note, that the solutions for all the supported
languages for the tasks of the test contest 1 are located in the
CONTEST1-HOME-DIR/solutions directory.

You may use the URL http://localhost/cgi-bin/serve-control to
control the contest manager. You can view the current status of
all the contests and you can edit the contest configuration
files.

By default, the ejudge system is configured so, that only
localhost (i.e. the computer running the ejudge programs) is
allowed to access them. To access the running contest from other
computers, you should edit the XML contest configuration file
000001.xml, which is usually located in the
/home/judges/data/contests directory. There are XML elements
corresponding to each ejudge CGI program, these XML elements
determine, which IP-addresses are allowed, and which are not.

7. Post-installation steps
--------------------------
As it was mentioned above, the setup script creates the working
disk and mounts it to the specified directory. However, after
reboot this mount command will be reset. In order to mount the
working disk automatically during the system startup you may
perform as root the following steps:
  1) add a record to the /etc/fstab file
                WORKDISK-IMAGE WORKDISK-MOUNT-POINT ext2 loop,noauto 0 0
        Here WORKDISK-IMAGE is the path to the working disk
        image (see the `Workdisk Image Path' configuration
        directory), WORKDISK-MOUNT-POINT is the mount point
        directory (see the `Workdisk Mount Point' configuration
        variable).
        The `noauto' flag is set to prevent automatic mounting
        on the early step of booting, because on this step
        mounting of a loopback device fails.
  2) at the end of the /etc/rc.d/rc.local file add the following
        command to mount the working disk
                mount WORKDISK-MOUNT-POINT

The ejudge system supports contests of unlimited duration and
virtual contests. Such contests are active and must accept user
request at any time for considerable period (months or more).
Moreover, the ejudge system supports several active contests at
a time, both regular (i.e. limited in time) and unlimited. For
all the served contests only one server of the user database
`userlist-server' and only one compilation server `compile' are
required. All the contests will share them. However, each
contest is served by a separate contest server `serve' and
testing server `run'. When several contests are active, two
processed for each contest are required, and they are
considerable resource consumers.

Fortunately, if no user uses the contest, no serving programs
are required for this contest, thus starting the servers on
demand may reduce the resource consumption. This is the goal of
the `super-serve' program. It watches the requests to active
contests, and starts the required server programs on demand. The
server programs `serve' and `run' support inactivity timeouts
and exit when no requests were accepted in the specified period
(usually 5 mins). The active contests are marked for the
`super-serve' programs by setting the managed and run_managed
attributes of the <contest> element of the contest.xml
configuration file to "yes", for example: `managed="yes"'. The
`managed' attribute means, that the `super-serve' program will
watch the requests to the contest server `serve', and the
`run_managed' attribute means, that the `super-serve' program
will watch the requests to the testing server `run'. The
attributes are independent from each other. It is possible to
watch only requests to the `serve', or only requests to the
`run'.

In order to start the `super-serve' program change the current
directory to the EJUDGE-CONF-DIR directory and execute the
following command:
        EJUDGE-BIN-DIR/super-serve ejudge.xml
If the path to the ejudge.xml configuration file was correctly
specified during the configuration of the ejudge system using
the --enable-ejudge-xml or the --enable-conf-dir options of the
configure scripts, the argument of the `super-serve' program may
be omitted.

Note, that if a contest is managed by the `super-serve' program
you should not start the `serve' and the `run' programs
manually.

Note also, that in order to make a contest manageable by the
`super-serve' program, all the necessary directories in the
contest working directory must be created. To create them you
may start the `serve' program manually and after all the
directories are created terminate it. After this the `serve'
program should not be started manually, but using the
`super-serve' program.

Note, that the current version of the `super-serve' does not
handle certain kind of errors very well. For example, if the
server configuration file `serve.cfg' contains errors the
`serve' or `run' programs will fail to start. The `super-serve'
program will notice, that the `serve' or the `run' program
terminated just after start, and will disable the corresponding
contest for several minutes reporting the error:
"contest N serve (run) respawns too fast, disabling for 60 seconds"
onto the standard error stream. The contest administrator should
notice this message and fix the error in the configuration files.
