Admin Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 47

Download
Open PDF In Browser	View PDF

DOMjudge Administrator's Manual

by the DOMjudge team

Sat, 15 Dec 2018 13:24:21 +0000

This document provides information about DOMjudge installation, conguration and operation for the DOMjudge
administrator. A separate manual is available for teams and for jury members. Document version: 7887684

Contents
1 DOMjudge overview

1.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.3 Copyright and licencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.4 Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2 Contest planning

2.1 Contest hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3 Installation and conguration

3.1 Quick installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3 Installation system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.4 Database installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.5 Web server conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.6 Fine tuning server settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.7 Installation of a judgehost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.8 Building and installing the submit client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.9 Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.10 OpenID Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.11 Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.12 Conguration of languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.13 Conguration of special run and compare programs . . . . . . . . . . . . . . . . . . . . . . . . 22
3.14 Alerting system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.15 Other congurable scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.16 Logging & debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2

CONTENTS

3.17 (Re)generating documentation and the team manual . . . . . . . . . . . . . . . . . . . . . . . 24
3.18 Optional features

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

3.19 Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4 Setting up a contest

4.1 Congure the contest data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2 Contest milestones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.3 User authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4 Providing testdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.5 Start the daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.6 Check that everything works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.7 Testing jury solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5 Team Workstations

6 Web interface

6.1 Jury and Administrator view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.2 The scoreboard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6.3 Balloons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
7 Security

7.1 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.2 Internal security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.3 Root privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.4 File system privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.5 External security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
A Common problems and their solutions

A.1 Java compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
A.2 The Java virtual machine (jvm) and memory limits . . . . . . . . . . . . . . . . . . . . . . . . 41
A.3 Java class naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
A.4 GCJ compiler warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
A.5 Memory limit errors in the web interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
A.6 Compiler errors: `runguard: root privileges not dropped'

. . . . . . . . . . . . . . . . . . . . 43

A.7 found processes still running ... apport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
A.8 Enforcement of time limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

CONTENTS

B Multi-site contests

C Developer information

C.1 Bootstrapping from Git repository sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
C.2 Maintainer mode installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
C.3 Makele structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

DOMjudge overview

DOMjudge is a system for running programming contests, like the ICPC regional and world championship
programming contests.
This means that teams are on-site and have a xed time period (mostly 5 hours) and one computer to solve a
number of problems (mostly 8-11). Problems are solved by writing a program in one of the allowed languages,
that reads input according to the problem input specication and writes the correct, corresponding output.
The judging is done by submitting the source code of the solution to the jury. There the jury system
automatically compiles and runs the program and compares the program output with the expected output.
This software can be used to handle the submission and judging during such contests. It also handles
feedback to the teams and communication on problems (clarication requests). It has web interfaces for the
jury, the teams (their submissions and clarication requests) and the public (scoreboard).

1.1 Features
A global overview of the features that DOMjudge provides:
• Automatic judging with distributed (scalable) judge hosts
• Web interface for portability and simplicity
• Modular system for plugging in languages/compilers and validators
• Detailed jury information (submissions, judgings, dis) and options (rejudge, clarications, resubmit)
• Designed with security in mind

DOMjudge has been used in many live contests (see for an overview)
and is Open Source, Free Software.

1.2 Requirements
This is a (rough) list of the requirements for DOMjudge.
• At least one machine running Linux, with (sudo) root access
• Apache web server with PHP 5.3.3 or newer and PHP-command line interface
• MySQL or MariaDB database server version 5.3.3 or newer
• Compilers for the languages you want to support

A 2.2 (detailed list of requirements) is contained in the 3 (Installation and Conguration) chapter.

CHAPTER 1.

DOMJUDGE OVERVIEW

1.3 Copyright and licencing
DOMjudge is developed by Jaap Eldering, Nicky Gerritsen, Keith Johnson, Thijs Kinkhorst and Tobias
Werth; Peter van de Werken has retired as developer. Many other people have contributed (apologies for
any oversights): Michael Baer, Jeroen Bransen, Stijn van Drongelen, Rob Franken, Marc Furon, Jacob
Kleerekoper, Ruud Koot, Jan Kuipers, Richard Lobb, Alex Muntada, Dominik Paulus, Bert Peters, Jeroen
Schot, Matt Steele, Shuhei Takahashi, Hoai-Thu Vuong, and Jeroen van Wolelaar. Some code has been
ported from the ETH Zurich fork by Christoph Krautz, Thomas Rast et al.
DOMjudge is Copyright (c) 2004 - 2018 by the DOMjudge developers and its contributors.
DOMjudge, including its documentation, 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, or (at your option) any later version. See the le COPYING.
This software is partly based on code by other people. These acknowledgements are made in the respective
les, but we would like to name them here too (with non-GPL licences listed where applicable):
• dash (i386) is included, statically compiled from the Debian dash sources (copyright by various
people under the BSD licence and a part under the GNU GPL version 2. See COPYING.BSD
doc/dash.copyright for more details). Sources can be downloaded from: .
• basename.h is a modied version from the GNU libiberty library (copyright Free Software Foundation).
• lib.database.php by Jeroen van Wolelaar et al.
• runguard.c was originally based on timeout from The Coroner's Toolkit by Wietse Venema.
• sorttable.js, by Stuart Langridge, licenced under the MIT licence, see COPYING.MIT. It was downloaded
from .
• jscolor.js by Jan Odvarko, licenced under the GNU LGPL. It was obtained at

• tabber.js by Patrick Fitzgerald, licenced under the MIT licence, see COPYING.MIT. It was downloaded

from

.
• Ace code editor by Ajax.org B.V., licenced under the BSD licence, see COPYING.BSD. It was downloaded

from

, the src-min-noconflict version.
• jQuery JavaScript library by the jQuery Foundation, licenced under the MIT licence, see COPYING.MIT.
It was downloaded from .
• jQuery TokenInput by James Smith, dual licenced under the GPL and MIT licences, see COPYING and
COPYING.MIT. It was downloaded from

.
• JavaScript Cookie by Klaus Hartl and Fagner Brack, licenced under the MIT licence, see COPYING.MIT.
It was downloaded from .

CHAPTER 1.

DOMJUDGE OVERVIEW

• The Spyc PHP YAML parser by Chris Wanstrath and Vlad Andersen, licenced under the MIT licence,
see COPYING.MIT. It was downloaded from .
• The default compare script was included from the Kattis problemtools package, and licenced under the
MIT licence, see COPYING.MIT. It was downloaded from

.
• The DOMjudge logo is based on the NKP 2004 logo made by Erik van Sebille.
• Several icons have been taken from the phpMyAdmin project.
• Several M4 autoconf macros from the Autoconf archive by various people are included under m4/.

These are licenced under all-permissive and GPL3+ licences; see the respective les for details.

1.3.1

About the name and logo

The name of this judging system is inspired by a very important and well known landmark in the city of
Utrecht: the dome tower, called the `Dom' in Dutch. The logo of the 2004 Dutch Programming Championships (for which this system was originally developed) depicts a representation of the Dom in zeros and
ones. We based the name and logo of DOMjudge on that.
We would like to thank Erik van Sebille, the original creator of the logo. The logo is under a GPL licence,
although Erik rst suggested a "free as in beer" licence rst: you're allowed to use it, but you owe Erik a
free beer in case might you encounter him.

1.4 Contact
The DOMjudge homepage can be found at: https://www.domjudge.org/
We have a low volume mailing list for announcements of new releases.
The authors can be reached through the development mailing list: domjudge-devel@domjudge.org . You
need to be subscribed before you can post. See the list information page for subscription and more details.
Some developers and users of DOMjudge linger on the IRC channel dedicated to DOMjudge on the Freenode
network: server irc.freenode.net, channel #domjudge. Feel free to drop by with your questions and
comments, but note that it may sometimes take a bit longer than a few minutes to get a response.

Contest planning

2.1 Contest hardware
DOMjudge discerns the following kinds of hosts:
Team computer

Workstation for a team, where they develop their solutions and from which they submit them to the
jury system. The only part of DOMjudge that runs here is the optional command line submit client;
all other interaction by teams is done with a browser via the web interface.
DOMjudge server

A host that receives the submissions, runs the database and serves the web pages. This host will run
the Apache webserver and MySQL database. Also called domserver for brevity.
Judgehosts

A number of hosts, at least one, that will retrieve submitted solutions from the DOMjudge server,
compile and run them and send the results back to the server. They will run the judgedaemon from
DOMjudge.
Jury / admin workstations

The jury members (persons) that want to monitor the contest need just any workstation with a web
browser to access the web interface. No DOMjudge software runs on these machines.
One (virtual) machine is required to run the DOMserver. The minimum amount of judgehosts is also one,
but preferably more: depending on congured timeouts, judging one solution can tie up a judgehost for
several minutes, and if there's a problem with one judgehost it can be resolved while judging continues on
the others.
As a rule of thumb, we recommend one judgehost per 20 teams.
However, overprovisioning does not hurt: DOMjudge scales easily in the number of judgehosts, so if hardware
is available, by all means use it. But running a contest with fewer machines will equally work well, only the
waiting time for teams to receive an answer may increase.
Each judgehost should be a dedicated (virtual) machine that performs no other tasks. For example, although
running a judgehost on the same machine as the domserver is possible, it's not recommended except for testing
purposes. Judgehosts should also not double as local workstations for jury members. Having all judgehosts
be of uniform hardware conguration helps in creating a fair, reproducible setup; in the ideal case they are
run on the same type of machines that the teams use.
DOMjudge supports running multiple judgedaemons in parallel on a single judgehost machine. This might
be useful on multi-core machines. Note that although each judgedaemon process can be bound to one single
CPU core (using Linux cgroups), shared use of other resources such as disk I/O might still have a minor
eect on run times. For more details on using this, see the section 3.18 (Installation: optional features).

CHAPTER 2.

CONTEST PLANNING

2.2 Requirements
2.2.1

System requirements

The requirements for the deployment of DOMjudge are:
• Computers for the domserver and judgehosts must run Linux (or the domserver possibly a Unix vari-

ant). This software has been developed mostly under Debian GNU/Linux, and the manual adds some
specic hints for that, which also apply to Debian derivative distributions like Ubuntu. DOMjudge has
also been tested under RedHat-like Linux distributions. We try to adhere to POSIX standards, but
especially the judgehost security solution is Linux-specic.

• (Local) root access on the domserver and judgehosts for conguring sudo, installing some les with

restricted permissions and for (un)mounting the proc le system. See 7.3 (Security: root privileges)
for more details.

• A TCP/IP network which connects all DOMjudge and team computers. Extra network security which

restricts internet access and access to other services (ssh, mail, talk, etc..) is advisable, but not provided
by this software, see 7.5 (Security: external security) for more details. All network-based interactions
are done over HTTP or HTTPS (tcp port 80 or 443):
HTTP trac from teams, the public and jury to the web server.
The judgehosts connect to the DOMjudge API on the webserver over HTTP(S).
The `submit' command line client connects to API on the web server also via HTTP(S).

2.2.2

Software requirements

The following software is required for running DOMjudge.
• For every supported programming language a compiler is needed; preferably one that can generate

statically linked stand-alone executables.

• Apache web server with mod_rewrite and support for PHP >= 7.0 and the mysqli, GD, curl, json,

mbstring, intl, zip and XML extensions for PHP. We also recommend the posix extension for extra
debugging information. A conguration le for the Nginx webserver is also included, and may be used
instead of Apache. However, this setup is less well tested and documented.

• MySQL or MariaDB >= 5.5.3 database and client software.
• PHP >= 7.0 command line interface and the curl and json extensions.
• A POSIX compliant shell in /bin/sh (e.g. bash or ash).
• A statically compiled POSIX shell, located in lib/judge/sh-static (dash is included for Linux

i386/amd64).

• libcgroup , to enable support for Linux cgroup accounting and security on the judgehosts. See section

3.7 (installation of a judgehost ).

• A lot of standard (GNU) programs, a probably incomplete list: hostname, date, dirname, basename,

touch, chmod, cp, mv, cat, grep, di, wc, mkdir, mkfo, mount, sleep, head, tail, pgrep, zip, unzip.

CHAPTER 2.

CONTEST PLANNING

• Sudo to gain root privileges.
• A LaTeX installation to regenerate the team PDF-manual with site specic conguration settings

included.

The following items are optional, but may be required to use certain functionality or are generally useful.
• phpMyAdmin , to be able to access the database in an emergency or for data import/export
• An NTP daemon (for keeping the clocks between jury system and team workstations in sync)
• libcurl and libJSONcpp to use the command line submit client.
• libmagic (for command line submit client to detect binary le submissions)
• PECL xdi extension (to reliably make dis between submissions, DOMjudge will try alternative

approaches if it is not available)

• beep for audible notication of errors, submissions and judgings, when using the default alert script.

Software required for building DOMjudge:
• gcc and g++ with standard libraries. Other compilers and libraries might also work: we have success-

fully compiled DOMjudge sources with Clang from the LLVM project; the C library should support
the POSIX.1-2008 specication.

• GNU make

2.2.3

Requirements for team workstations

In the most basic setup the team workstations only need (next to the tools needed for program development)
a modern web browser. We support all versions of Firefox, Chrome and Edge.

Installation and conguration

This chapter details a fresh installation of DOMjudge. The rst section is a Quick Installation Reference,
but that should only be used by those already acquainted with the system. A detailed guide follows after
that.

3.1 Quick installation
Note: this is not a replacement for the thorough installation instructions below, but more a cheat-sheet for
those who've already installed DOMjudge before and need a few hints. When in doubt, always consult the
full installation instruction.

External software:
• Install the MySQL-server and set a root password for it.
• Install Apache, PHP and (recommended) phpMyAdmin.
• Make sure PHP works for the web server and command line scripts.
• Install necessary compilers on the judgehosts.
• See also 3.2 (an example command line for Debian and RedHat).

DOMjudge:
• Extract the source tarball
with-baseurl=.

and

run

./configure [enable-fhs|prefix=]

• Run make domserver judgehost docs or just those targets you want installed on the current host.
• Run make install-{domserver,judgehost,docs} as root to install the system.

On the domserver host:
• Install the MySQL database using e.g. bin/dj_setup_database -u root -r install on the dom-

server host.

• Add etc/apache.conf to your Apache conguration, edit it to your needs, reload web server:
sudo ln -s /domserver/etc/apache.conf /etc/apache2/conf-available/domjudge.conf
&& sudo a2enmod rewrite && sudo a2enconf domjudge && sudo apache2ctl graceful
• Check that the web interface works (/team, /public and /jury).
• Change the admin password from its default value ('admin').
• Check that the API (/api) works and create credentials for the judgehosts.
• Create teams, user accounts and add useful contest data through the jury web interface or with php-

MyAdmin.

CHAPTER 3.

INSTALLATION AND CONFIGURATION

• Run the cong checker in the jury web interface.

On the judgehosts:
• useradd -d /nonexistent -U -M -s /bin/false domjudge-run
• Add to /etc/sudoers.d/ or append to /etc/sudoers the sudoers conguration as in
etc/sudoers-domjudge.
• Set up cgroup support: enable kernel parameters in /etc/default/grub and reboot, then use
misc/create_cgroups to create cgroups for DOMjudge.
• Put the right credentials in the le etc/restapi.secret on all judgehosts (copied from the domserver).
• Start the judge daemon: bin/judgedaemon

It should be done by now. As a check that (almost) everything works, the set of test sources can be submitted:
cd tests
make check

Note

that this requires some conguration depending on the AUTH_METHOD
etc/domserver-config.php, see 3.8 (submit client conguration) for more details.

selected

Then, in the main jury web interface, select the admin link judging verier to automatically verify most of
the test sources, except for a few with multiple possible outcomes; these have to be veried by hand. Read
the test sources for a description of what should (not) happen.
Optionally:
• Install the submit client on the team workstations.
• Start the balloon notication daemon: cd bin; ./balloons; or use the balloon web interface.
• On the judgehosts, create a pre-built chroot tree to support interpreted or byte-compiled languages

such as Java:

sudo bin/dj_make_chroot [optional arguments]
$EDITOR lib/judge/chroot-startstop.sh
Modifying chroot-startstop.sh is typically not necessary, but might be in circumstances where your
interpreters are not installed under /usr or require les from other locations. See also the section 3.7.3

(creating a chroot environment).

• For additional features in the jury web interface, the following PHP extensions can be installed:

xdi PECL extension for dis between submissions;

3.2 Prerequisites
For a detailed list of the hardware and software requirements, please refer to the previous chapter on contest
planning.

CHAPTER 3.

3.2.1

INSTALLATION AND CONFIGURATION

Debian and RedHat installation commands

For your convenience, the following command will install needed software on the DOMjudge server as mentioned above when using Debian GNU/Linux, or one of its derivate distributions like Ubuntu.
sudo apt install gcc g++ make zip unzip mariadb-server \
apache2 php php-cli libapache2-mod-php php-zip \
php-gd php-curl php-mysql php-json php-xml php-intl php-mbstring \
acl bsdmainutils ntp phpmyadmin python-pygments \
libcgroup-dev linuxdoc-tools linuxdoc-tools-text \
groff texlive-latex-recommended texlive-latex-extra \
texlive-fonts-recommended texlive-lang-european
# To enable the command-line submit client, also add:
sudo apt install libcurl4-gnutls-dev libjsoncpp-dev libmagic-dev

Note that PHP modules may need to be enabled depending on your distribution. E.g. on Ubuntu run
sudo phpenmod json

to enable the JSON module.
The following command can be used on RedHat Enterprise Linux, and related distributions like CentOS and
Fedora.
sudo yum install gcc gcc-c++ make zip unzip mariadb-server \
httpd php-gd php-cli php-intl php-mbstring php-mysql php-xml \
python-pygments ntp linuxdoc-tools libcgroup-devel \
texlive-collection-latexrecommended texlive-wrapfig
# To enable the command-line submit client, also add:
sudo yum install libcurl-devel jsoncpp-devel file-devel

Note that the TeX Live packages expdlist, moreverb, and svn still have be installed manually to rebuild
the team manuals. Furthermore, phpmyadmin is available from the Fedora EPEL repository . The package
jsoncpp-devel is available in Fedora, but not in RHEL/CentOS.
Libmagic is not strictly required, but highly recommended for detecting binary le submissions. Pass the
option enable-static-linking to congure so that these libraries are statically linked into the submit
binary and not needed on the team workstations where submit is installed.
On a judgehost, the following should be sucient. The last two lines show some example compilers to install
for C, C++, Java (OpenJDK), Haskell and Pascal; change the list as appropriate.
For Debian:
sudo apt install make sudo debootstrap libcgroup-dev \
php-cli php-curl php-json php-xml php-zip procps \
gcc g++ openjdk-8-jre-headless \
openjdk-8-jdk ghc fp-compiler

CHAPTER 3.

INSTALLATION AND CONFIGURATION

For RedHat:
sudo yum install make sudo libcgroup-devel \
php-cli php-mbstring php-xml php-process procps-ng \
gcc gcc-c++ glibc-static libstdc++-static \
java-1.7.0-openjdk-headless java-1.7.0-openjdk-devel \
ghc-compiler fpc

Note that fpc is not available in RedHat 7.

3.3 Installation system
There is a separate maintainer installation method meant for those wishing to do development on the
DOMjudge source code. See the C (appendix with developer information) and skip the rest of this section.
The DOMjudge build/install system consists of a configure script and makeles, but when installing it,
some more care has to be taken than simply running './configure && make && make install'. DOMjudge
needs to be installed both on the server and on the judgehosts. These require dierent parts of the complete
system to be present and can be installed separately. Within the build system these parts are referred to as
domserver, judgehost and additionally docs for all documentation.
DOMjudge can be installed with two dierent directory layouts:
Single directory tree

With this method all DOMjudge related les and programs are installed in a single directory tree which
is specied by the prex option of congure, like
./configure --prefix=$HOME/domjudge --with-baseurl=https://domjudge.example.com/

This will install each of the domserver, judgehost, docs parts in a subdirectory
$HOME/domjudge/domserver etc.
These subdirectories can be overridden from the defaults
with options like with-domserver_root=DIR, see configure help for a complete list. The prex
defaults to /opt/domjudge.
Besides the installed les, there will also be directories for logging, temporary les, submitted sources
and judging data:
log

contains all log les.
tmp

contains temporary les.
submissions

(optionally) on the domserver contains all correctly submitted les: as backup only, the database
is the authoritative source. Note that this directory must be writable by the web server for this
feature to work.

CHAPTER 3.

INSTALLATION AND CONFIGURATION

judgings

location on judgehosts where submissions are tested, each in its own subdirectory.
This method of installation is the default and probably most practical for normal purposes as it keeps
all les together, hence easily found.
FHS compliant

This method installs DOMjudge in directories according to the Filesystem Hierarchy Standard . It can
be enabled by passing the option enable-fhs to configure and in this case the prex defaults to
/usr/local. Files will be placed e.g. in PREFIX/share/domjudge, PREFIX/bin, PREFIX/var/log,
PREFIX/etc/domjudge, while /tmp will be used for temporary les. You may want to pass options
sysconfdir=/etc and localstatedir=/var to configure to disable the prex for these.
Note that the with-baseurl congure option is not required but highly recommended, as it allows building
the submit client and team documentation with the correct URL preset. The option is required when using
3.10 (OpenID). If needed, the setting can later be updated in etc/domserver-static.php on the domserver,
and in etc/submit-config.h in the source tree for rebuilding the submit client.
After running the configure script, the system can be built and installed. Each of the domserver,
judgehost, docs parts can be built and installed separately, respectively by:
make domserver && sudo make install-domserver
make judgehost && sudo make install-judgehost
make docs && sudo make install-docs

Note that root privileges are required to set permissions and user and group ownership of password les
and a few directories. If you run the installation targets as non-root, you will be warned that you have to
perform these steps manually. Although DOMjudge can be installed as root, one should not run DOMjudge
programs and daemons under the root user, but under a normal user: runguard is specically designed to
be the only part invoked as root (through sudo) to make this unnecessary. Also, running as root will give
rise to problems, see A.6 (runguard: root privileges not dropped) in the common problems section.
For a list of basic make targets, run make in the source root directory without arguments.

3.4 Database installation
DOMjudge uses a MySQL or MariaDB database server for information storage. Where this document talks
about MySQL, it can be understood to also apply to MariaDB.
The database structure and privileges are included in MySQL dump les in the sql subdirectory. The
default database name is domjudge. This can be changed manually in the etc/dbpasswords.secret le:
the database name as specied in this le will be used when installing.
Installation of the database is done with bin/dj_setup_database. For this, you need an installed and
congured MySQL server and administrator access to it. Run
dj_setup_database genpass
dj_setup_database [-u ] [-p |-r] install

CHAPTER 3.

INSTALLATION AND CONFIGURATION

This rst creates the DOMjudge database credentials le etc/dbpasswords.secret (optionally change the
random generated password, although it is not needed for normal operation). Then it creates the database
and user and inserts some default/example data into the domjudge database. The option -r will prompt
for a password for mysql; when no user is specied, the mysql client will try to read credentials from
$HOME/.my.cnf as usual. The command uninstall can be passed to dj_setup_database to remove the
DOMjudge database and users; this deletes all data!
The domjudge database contains a number of tables, some of which need to be manually lled with data
before the contest can be run. See the 4.1 (database section of Contest setup) for details.
3.4.1

Setting up replication or backups

The MySQL server is the central place of information storage for DOMjudge. Think well about what to do
if the MySQL host fails or loses your data.
A very robust solution is to set up a replicating MySQL server on another host. This will be a hot copy of
all data up to the second, and can take over immediately in the event of failure. The MySQL manual has
more information about setting this up.
Alternatively, you can make regular backups of your data to another host, for example with mysqldump, or
using a RAID based system.
Replication can also be used to improve performance, by directing all select-queries to one or more replicated
slave servers, while updates will still be done to the master. This is not supported out of the box, and will
require making changes to the DOMjudge source.
3.4.2

Storage of submissions

The database is the authoritative version for submission source les; le system storage is available as an
easy way to access the source les and as backup, but only when the web server has write permissions to
. File system storage is ignored if these permissions are not set. The programs
bin/save_sources2file and bin/restore_sources2db are available to store and recover the submission
table in the database to/from these les.

3.5 Web server conguration
For the web interface, you need to have a web server (e.g. Apache) installed on the domserver and made
sure that PHP correctly works with it. Refer to the documentation of your web server and PHP for details.
To congure the web server for DOMjudge, use the Apache conguration snippet from etc/apache.conf. It
contains examples for conguring the DOMjudge pages with an alias directive, or as a virtualhost, optionally
with SSL; it also contains PHP and security settings. Reload the web server for changes to take eect.
ln -s etc/apache.conf /etc/apache2/conf-available/domjudge.conf
a2enmod rewrite
a2enconf domjudge
service apache2 reload

CHAPTER 3.

INSTALLATION AND CONFIGURATION

An Nginx webserver conguration snippet is also provided in etc/nginx-conf. This alternative webserver
is less well-tested than the Apache setup, so your mileage may vary. Feedback is very welcome, though.
The judgehosts connect to DOMjudge via the DOMjudge API so need to be able to access at least this part
of the web interface.

3.6 Fine tuning server settings
For Apache, there are countless documents on how to maximize performance. Of particular importance is
to ensure that the MaxClients setting is high enough to receive the number of parallel requests you expect,
but not higher than your amount of RAM allows. Furthermore, we recommend to turn KeepAlive o, or
at least make sure that KeepAliveTimeout is set to only a few seconds. Otherwise, a large number of page
view requests from teams and public can easily exhaust the Apache workers, resulting in an unresponsive
website, which will also aect the judgedaemons.
As for PHP, the use of an opcode cache like the Alternative PHP Cache (Debian package: php-apc) is
benecial for performance. For uploading large testcases, see the A.5 (section about memory limits).
It may be desirable or even necessary to ne tune some MySQL default settings:
• max_connections: The default 100 is too low, because of the connection caching by Apache threads.

1000 is more appropriate.

• max_allowed_packet: The default of 16MB might be too low when using large testcases. This should

be changed both in the MySQL server and client conguration and be set to about twice the maximum
testcase size.

• innodb_log_file_size: The default of 48MB might be too low on MySQL servers with version 5.6.20

or newer due to changes to the redo log. You should set it 10 times higher than the maximum testcase
size.

• Root password: MySQL does not have a password for the root user by default. It's very desirable to

set one.

• When maximising performance is required, you can consider to use the Memory table storage engine

for the scorecache and rankcache tables. They will be lost in case of a full crash, but can be recalculated
from the jury interface.

3.7 Installation of a judgehost
Some extra steps have to be taken to completely install and congure a judgehost.
3.7.1

Unprivileged user and group

For running solution programs under a non-privileged user, a user and group have to be added to the
system(s) that act as judgehost. This user does not need a home-directory or password, so the following
command would suce to add a user and group `domjudge-run' with minimal privileges.
On Debian and Redhat based Linux distributions use:

CHAPTER 3.

INSTALLATION AND CONFIGURATION

useradd -d /nonexistent -U -M -s /bin/false domjudge-run

For other systems check the specics of your useradd command. This user must also be congured as the
user under which programs run via configure enable-runuser=USER; the default is domjudge-run. By
default the group is set to the same, this can be modied with the option enable-rungroup=GROUP
3.7.2

Sudo permissions

Runguard needs to be able to become root for certain operations like changing to the runuser and performing
a chroot. Also, the default chroot-startstop.sh script uses sudo to gain privileges for certain operations.
There's a pregenerated /etc/sudoers.d/ snippet in etc/sudoers-domjudge that contains all required rules.
You can put the lines in the snippet at the end of /etc/sudoers, or, for modern sudo versions, place the
le in /etc/sudoers.d/. If you change the user you run the judgedaemon as, or the installation paths, be

sure to update the sudoers rules accordingly.
3.7.3

Creating a chroot environment

The judgedaemon executes submissions inside a chroot environment for security reasons. By default it mounts parts of a prebuilt chroot tree read-only during this judging process (using the script
lib/judge/chroot-startstop.sh). This is needed to support extra languages that require access to interpreters or support libraries at runtime, for example Java, C#, and any interpreted languages like Python,
Perl, Shell script, etc.
This chroot tree can be built using the script bin/dj_make_chroot. On Debian and Ubuntu the same
distribution and version as the host system are used, on other Linux distributions the latest stable Debian
release will be used to build the chroot. Any extra packages to support languages can be passed with the
option -i or be added to the INSTALLDEBS variable in the script. The script bin/dj_run_chroot runs an
interactive shell or a command inside the chroot. This can be used for example to install new or upgrade
existing packages inside the chroot. Run these scripts with option -h for more information.
Finally, if necessary edit the script lib/judge/chroot-startstop.sh and adapt it to work with your local
system. In case you changed the default pre-built chroot directory, make sure to also update the sudo rules
and the CHROOTORIGINAL variable in chroot-startstop.sh.
When the chroot setting is enabled (default), a static POSIX shell has to be available for copying it into the
chroot environment. For Linux i386, a static Dash shell is included, which works out of the box, also for
the Linux Intel/AMD 64 architecture. For other architectures or operating systems, a shell has to be added
manually. Then simply point the lib/sh-static symlink to this le.
3.7.4

Linux Control Groups

DOMjudge uses Linux Control Groups or cgroups for process isolation in the judgedaemon. Linux cgroups
give more accurate measurement of actually allocated memory than traditional resource limits (which is
helpful with interpreters like Java that reserve but not actually use lots of memory). Also, cgroups are
used to restrict network access so no separate measures are necessary, and they allow running multiple
judgedaemons on a multi-core machine by using CPU binding.

CHAPTER 3.

INSTALLATION AND CONFIGURATION

The judgedaemon needs to run a recent Linux kernel (at least 3.2.0). The following steps congure cgroups
on Debian wheezy. Instructions for other distributions may be dierent (send us your feedback!). Edit
grub cong to add cgroup memory and swap accounting to the boot options. Edit /etc/default/grub and
change the default commandline to
GRUB_CMDLINE_LINUX_DEFAULT="quiet cgroup_enable=memory swapaccount=1"

Then run update-grub and reboot. After rebooting check that /proc/cmdline actually contains
the added kernel options.
On VM hosting providers such as Google Cloud or DigitalOcean,
GRUB_CMDLINE_LINUX_DEFAULT may be overwritten by other les in /etc/default/grub.d/.
You have now congured the system to use cgroups, but you need to create the actual cgroups that DOMjudge
will use. For that, you can use the script under misc-tools/create_cgroups. Edit the script to match your
situation rst. This script needs to be re-run after each boot (it has already been added to the judgedaemon
init script).
3.7.5

REST API credentials

The judgehost connects to the domserver via a REST API. You need to create an account for the judgedaemons to use (this may be a shared account between all judgedaemons) with a dicult, random password and
the 'judgehost' role. On each judgehost, copy from the domserver (or create) a le etc/restapi.secret
containing the id, URL, username and password whitespace-separated on one line, for example:
default http://example.edu/domjudge/api/

judgehosts

MzfJYWF5agSlUfmiGEy5mgkfqU

Note that the password must be identical to that of the judgehost user in the admin web interface. Multiple
lines may be specied to allow a judgedaemon to work for multiple domservers. The id is used to dierentiate
between multiple domservers, and should be unique within the restapi.secret le.
3.7.6

Starting the judgedaemon

Finally start the judgedaemon (optionally binding it to CPU core X):
bin/judgedaemon [-n X]

If using the -n X option, then an extra user domjudge-run-X must also be created.
Upon its rst connection to the domserver API, the judgehost will be auto-registered and will be by default
enabled. If you wish to add a new judgehost but have it initially disabled, you can add it manually through
the DOMjudge web interface and set it to disabled before starting the judgedaemon.

3.8 Building and installing the submit client
DOMjudge supports two submission methods: via the command line submit program and via the web
interface. From experience, both methods have users that prefer the one above the other.

CHAPTER 3.

INSTALLATION AND CONFIGURATION

The command line submit client sends submissions using the API interface internally. This requires the
libcURL and libjsonCPP library development les at compile time. The submit client can be statically
linked using the enable-static-linking congure option to avoid a runtime dependency.
The submit client can be built with make submitclient. There is no make target to install the submit
client, as its location will very much depend on the environment. You might e.g. want to copy it to all team
computers or make it available on a network lesystem. Note that if the team computers run a dierent
(version of the) operating system than the jury systems, then you need to build the submit client for that
OS.
The submit client needs to know the URL of the domserver. This can be passed as a command line option
or environment variable. The latter option makes for easier usage. A sample script submit_wrapper.sh is
included, which sets this variable. See that script for more details on how to set this up.
The submit client authenticates to the DOMjudge API via either the congured authentication scheme, or
can use the DOMjudge internal username and password combination for a given user account regardless of
authentication scheme. For example, when the IPADDRESS scheme is used, no additional conguration is
required because submissions will come from the correct IP address of the team. When another scheme is
used, it may be necessary to place username and password combinations in the team's account so the submit
client can use those. In this case these are always the DOMjudge internal password, so not e.g. LDAP
passwords when using that scheme. The credentials are placed in the le /.netrc, with example content:
machine domserver.example.com login user0123 password Fba^2bHzz

See the netrc(4) manual page for more details. You may want to distribute those .netrc les in advance to
the team accounts. Make sure they are only readable for the user itself.
3.8.1

The submit client under Windows/Cygwin

Note: this feature is not well supported anymore; we recommend using the web interface for submitting in
Windows.

The submit client can also be built under Windows when the Cygwin environment is installed. First install
Cygwin , and include GCC, curl-devel and maybe some more packages. When Cygwin is correctly installed with all necessary development tools, the submit binary can be
created by running configure followed by make submit.exe in the submit directory.

3.9 Conguration
Conguration of the judge system is mostly done by editing the conguration variables on the page
Configuration settings available in the administrator interface, and changes take eect immediately.
The administrator interface can be reached on http(s)://yourhost.example.edu/domjudge/jury/ and
the default username is admin with password admin. Make sure to change the default password immediately.
Some settings that are tightly coupled to the lesystem can be congured in the les in etc:
domserver-config.php, judgehost-config.php, common-config.php for the conguration options of
the domserver, judgehost and shared conguration options respectively. Descriptions of settings are included in these les. The judgedaemon must be restarted for changes to take eect, while these are directly
picked up by the webinterfaces.

CHAPTER 3.

INSTALLATION AND CONFIGURATION

Besides these settings, there are a few other places where changes can be made to the system, see 3.15 (other
congurable scripts).

3.10 OpenID Connect
DOMjudge supports allowing users to log in using your favorite OpenID Connect provider, such as google
(or ICPC accounts in the future). Some things need to be congured on the Configuration Settings page
for this to work properly.
3.10.1

Google

To use Google as an OpenID Provider, you need to obtain a clientID and clientSecret. You can get these
values from Google Developer Console .
Navigate to Credentials under the API Manager heading. Then Create Credentials for OAuth Client
ID. This will give you the client ID and secret you need. For the openid provider set the URL to
https://accounts.google.com. You also need to set the Authorized redirect URIs to the full url to
/domjudge/auth/oid_cb.php. E.g. http(s)://yourhost.example.edu/domjudge/auth/oid_cb.php
Finally, enable the setting Allow openid auth.

3.11 Executables
DOMjudge supports executable archives (uploaded and stored in ZIP format) for conguration of languages,
special run and compare programs. The archive must contain an executable le named build or run. When
deploying a new (or changed) executable to a judgehost build is executed once if present. Afterwards an
executable le run must exist (it may have existed before), that is called to execute the compile, compare,
or run script. The specic formats are detailed below.
Executables may be changed via the web interface in an online editor or by uploading a replacement zip le.
Changes apply immediately to all further uses of that executable.

3.12 Conguration of languages
Compilers can be congured by creating or selecting/editing an executable in the web interface. When
compiling a set of source les, the run executable is invoked with the following arguments: destination le
name, memory limit (in KB), main (rst) source le, other source les. For more information, see for example
the executables c or java_javac_detect in the web interface. Note that compile scripts are included for
most common languages already.
Interpreted languages and non-statically linked binaries (for example, Oracle Java) can in principle also be
used, but require that all runtime dependencies are added to the chroot environment. See section 3.7.3
(creating a chroot environment).
Interpreted languages do not generate an executable and in principle do not need a compilation step. However, to be able to use interpreted languages (also Oracle's Java), during the compilation step a script must

CHAPTER 3.

INSTALLATION AND CONFIGURATION

be generated that will function as the executable: the script must run the interpreter on the source. See for
example pl and java_javac_detect in the list of executables.

3.13 Conguration of special run and compare programs
To allow for problems that do not t within the standard scheme of xed input and/or output, DOMjudge
has the possibility to change the way submissions are run and checked for correctness.
The back end script testcase_run.sh that handles the running and checking of submissions, calls separate
programs for running submissions and comparison of the results. These can be specialised and adapted to
the requirements per problem. For this, one has to create executable archives as described above. Then the
executable must be selected in the special_run and/or special_compare elds of the problem (an empty
value means that the default run and compare scripts should be used; the defaults can be set in the global
conguration settings). When creating custom run and compare programs, we recommend re-using wrapper
scripts that handle the tedious, standard part. See the boolnd example for details.
3.13.1

Compare programs

Compare scripts/programs should follow the Kattis/problemarchive output validator format . DOMjudge
uses the default output validator specied there as its default, which can be found at
.

Note that DOMjudge only supports a subset of the functionality described there. In particular, the calling
syntax is
/path/to/compare_script/run <

where testdata.in testdata.ans are the jury reference input and output les, feedbackdir the directory
containing e.g. the judging response le judgemessage.txt to be written to (the only other permitted
les there are teammessage.txt score.txt judgeerror.txt diffposition.txt), compare_args a list of
arguments that can set when conguring a contest problem, and program.out the team's output. The
validator program should not make any assumptions on its working directory.
For more details on writing and modifying a compare (or validator) scripts, see the boolfind_cmp example
and the comments at the top of the le testcase_run.sh.
3.13.2

Run programs

Special run programs can be used, for example, to create an interactive problem, where the contestants'
program exchanges information with a jury program and receives data depending on its own output. The
problem boolfind is included as an example interactive problem, see docs/examples/boolfind.pdf for the
description.
Usage is similar to compare programs: you can either create a program run yourself, or use the provided
wrapper script, which handles bi-directional communication between a jury program and the contestants'
program on stdin/stdout (see the run le in the boolfind_run executable).

CHAPTER 3.

INSTALLATION AND CONFIGURATION

For the rst case, the calling syntax that the program must accept is equal to the calling syntax of
run_wrapper, which is documented in that le. When using run_wrapper, you should copy it to run
in your executable archive. The jury must write a program named exactly runjury, accepting the calling
syntax
runjury

where the arguments are les to read input testdata from and write program output to, respectively. This
program will communicate via stdin/stdout with the contestants' program. A special compare program
must probably also be created, so the exact data written to is not important, as long as
the correctness of the contestants' program can be deduced from the contents by the compare program.

3.14 Alerting system
DOMjudge includes an alerting system. This allows the administrator to receive alerts when important
system events happen, e.g. an error occurs, or a submission or judging is made.
These alerts are passed to a plugin script alert which can easily be adapted to t your needs. The default
script emits dierent beeping sounds for the dierent messages when the beep program is available, but it
could for example also be modied to send a mail on specic issues, connect to monitoring software like
Nagios, etc. For more details, see the script lib/alert.

3.15 Other congurable scripts
There are a few more places where some conguration of the system can be made. These are sometimes
needed in non-standard environments.
• In bin/dj_make_chroot on a judgehost some changes to variables can be made, most notably
DEBMIRROR to select a Debian mirror site near you.
• The script lib/judge/chroot-startstop.sh can be modied to suit your local environment. See

comments in that le for more information.

3.16 Logging & debugging
All DOMjudge daemons and web interface scripts support logging and debugging in a uniform manner via
functions in lib.error.*. There are three ways in which information is logged:
• Directly to stderr for daemons or to the web page for web interface scripts (the latter only on serious

issues).

• To a log le set by the variable LOGFILE, which is set in each program. Unsetting this variable disables

this method.

CHAPTER 3.

INSTALLATION AND CONFIGURATION

• To syslog. This can be congured via the SYSLOG conguration variable in etc/common-config.php.

This option gives the exibility of syslog, such as remote logging. See the syslog(daemon) documentation for more information. Unsetting this variable disables this method.

Each script also denes a default threshold level for messages to be logged to stderr (VERBOSE: defaults
to LOG_INFO in daemons and LOG_ERR in the web interface) and for log le/syslog (LOGLEVEL: defaults to
LOG_DEBUG).
In case of problems, it is advisable to check the logs for clues. Extra debugging information can be obtained
by setting the cong option DEBUG to a bitwise-or of the available DEBUG_* ags in etc/common-config.php,
to e.g. generate extra SQL query and timing information in the web interface.

3.17 (Re)generating documentation and the team manual
There are three sets of documentation available under the doc directory in DOMjudge:
the admin-manual

for administrators of the system (this document),
the judge-manual

for judges, describing the jury web interface and giving some general information about this system,
the team-manual

for teams, explaining how to use the system and what restrictions there are.
The team manual is only available in PDF format and must be built from the LaTeX sources in doc/team after
conguration of the system. A prebuilt team manual is included, but note that it contains default/example
values for site-specic conguration settings such as the team web interface URL and judging settings such
as the memory limit. We strongly recommend rebuilding the team manual to include site-specic settings
and also to revise it to reect your contest specic environment and rules.
Besides a standard LaTeX installation, the team manual requires the svn and expdlist packages. These are
available in TeX Live in the texlive-latex-extra package in any modern Linux distribution. Alternatively,
you can download and install them manually from their respective subdirectories in .
When the docs part of DOMjudge is installed and site-specic conguration set, the team manual can be
generated with the command genteammanual found under docs/team. The PDF document will be placed in
the current directory or a directory given as argument. The following should do it on a Debian-like system:
sudo apt install make texlive-latex-extra texlive-latex-recommended texlive-lang-european
cd /docs/team
./genteammanual [targetdir]

The administrator's and judge's manuals are available in PDF and HTML format and prebuilt from SGML
sources. Rebuilding these is not normally necessary. To rebuild them on a Debian-like system, the following
commands should do it:

CHAPTER 3.

INSTALLATION AND CONFIGURATION

sudo apt install linuxdoc-tools make zip ghostscript groff texlive-latex-recommended
make -C doc/admin docs
make -C doc/judge docs

3.18 Optional features
3.18.1

Multiple judgedaemons per machine

You can run multiple judgedaemons on one multi-cpu or multi-core machine, dedicating one cpu core to each
judgedaemon.
To that end, add extra unprivileged users to the system, i.e. add users domjudge-run- (where X runs
through 0,1,2,3) with useradd as described in section 3.7 (installation of a judgehost). Finally, start each
of the judgedaemons with
judgedaemon -n

to bind it to core X.
3.18.2

Encrypted communications (HTTPS)

DOMjudge can be congured to run on HTTPS, so teams and judgedaemons communicate with the domserver securely over encrypted SSL/TLS connections. Setting up SSL for Apache is documented in the
Apache manual and in many tutorials around the web.
The judgedaemons must recognise the CA you're using, otherwise they will refuse to connect over HTTPS. If
your judgedaemon gives an error message about an untrusted certicate, put your domserver's certicate in
/etc/ssl/certs/yourname.crt of each judgehost (and on the team machines when using the commandline
submit client) and run:
sudo c_rehash

When loading teams from the ICPC registration system through the import feature in DOMjudge, the
certicate from icpc.baylor.edu must similarly be accepted by your local installation or if not, added via the
procedure above.
3.18.3

NTP time synchronisation

We advise to install an NTP-daemon (Network Time Protocol) to make sure the time between domserver,
judgehosts, and jury and team computers is in sync.
3.18.4

Printing

It is recommended to congure the local desktop printing of team workstations where ever possible: this has
the most simple interface and allows teams to print from within their editor.

CHAPTER 3.

INSTALLATION AND CONFIGURATION

If this is not feasible, DOMjudge includes support for printing via the DOMjudge web interface: the DOMjudge server then needs to be able to deliver the uploaded les to the printer. It can be enabled via the
enable_printing conguration option in the administrator interface. The exact command used to send the
les to a printer can be changed in the function send_print() in lib/www/printing.php.
3.18.5

Judging consistency

The following issues can be considered to improve consistency in judging.
• Disable CPU frequency scaling and Intel "Turbo Boost" to prevent uctuations in CPU power.
• Disable address-space randomization to make programs with memory addressing bugs give more reproducible results. To do that, you can add the following line to /etc/sysctl.conf:

kernel.randomize_va_space=0

This will restore these settings permanently across reboots. Then run the following command:
sudo sysctl -p

to directly activate these settings.

3.19 Upgrading
There is some support to upgrade DOMjudge to newer versions. Note that this functionality is not extensively
tested, so when you plan to upgrade, you are strongly advised to backup the DOMjudge database and other
data before continuing . We also advise to check the ChangeLog le for important changes.
Upgrading the lesystem installation is probably best done by installing the new version of DOMjudge in a
separate place and transferring the conguration settings from the old version.
There are SQL upgrade scripts to transform the database including its data to the layout of a newer version.
The scripts can be found under sql/upgrade and each script applies changes between two consecutive
DOMjudge versions. At the beginning of each script, a check is performed which will let MySQL bail out
with an error if it should not be applied anymore. Note that the scripts must be applied in order (sorted by
release). These scripts can be applied by running dj_setup_database upgrade. Be aware that these scripts
are conservative in adding and upgrading SQL data, so check that e.g. new compile scripts are present or
add them manually, and check the upgrade scripts manually for any other data upgraded.

Setting up a contest

After installation is successful, you want to run your contest! Conguring DOMjudge to run a contest (or a
number of them, in sequence) involves the following steps:
• Congure the contest data;
• Set up authentication for teams;
• Supply in- and output testdata;
• Check that everything works.

4.1 Congure the contest data
DOMjudge stores and retrieves most of its data from the MySQL database. Some information must be lled
in beforehand, other tables will be populated by DOMjudge.
You can use the jury web interface to add, edit and delete most types of data described below. It's advised to
keep a version of phpMyAdmin handy in case of emergencies, or for general database operations like import
and export.
This section describes the meaning of each table and what you need to put into it. Tables marked with an
`x' are the ones you have to congure with contest data before running a contest (via the jury web interface
or e.g. with phpMyAdmin), the other tables are used automatically by the software:

CHAPTER 4.

x
x
x
x
x
x
x
x

x
x
x
x
x
x

SETTING UP A CONTEST

auditlog
balloon
clarication
conguration
contest
contestproblem
contestteam
event
executable
internal_error
judgehost
judgehost_restriction
judging
judging_run
language
problem
rankcache
rejudging
role
scorecache
submission
submission_le
team
team_aliation
team_category
team_unread
testcase
user
userrole

Log of every state-changing event.
Balloons to be handed out.
Clarication requests/replies are stored here.
Runtime conguration settings.
Contest denitions with start/end time.
Coupling of problems to contests and data specic to it.
Coupling of teams to contests.
Log of events during contests.
Executable compile/run/compare scripts.
Stores errors that occurred on judgehosts including logs.
Computers (hostnames) that function as judgehosts.
Optional restriction sets on submissions taken by judgehosts.
Judgings of submissions.
Result of one testcase within a judging.
Denition of allowed submission languages.
Denition of problems (name, timelimit, etc.).
Cache of team ranking data for public/teams and for the jury.
Metadata for batched rejudging.
Possible user roles.
Cache of the scoreboards for public/teams and for the jury.
Submission metadata of solutions to problems.
Submitted code les.
Denition of teams.
Denition of institutions a team can be aliated with.
Dierent category groups teams can be put in.
Records which clarications are read by which team.
Denition of testdata for each problem.
Users that will able to access the system.
Mapping of users to their roles.

Now follows a longer description (including elds) per table that has to be lled manually. As a general
remark: almost all tables have an identier eld. Most of these are numeric and automatically increasing;
these do not need to be specied. The tables executable and language have text strings as identier elds.
These need to be manually specied and only alpha-numeric, dash and underscore characters are valid, i.e.
a-z, A-Z, 0-9, -, _.
conguration
This table contains conguration settings. These entries are simply stored as name, value pairs, where
the values are JSON encoded, type contains the allowed data type, and description documents the
conguration setting.
contest
The contests that the software will run. E.g. a test session and the live contest.
cid is the reference ID and contestname is a descriptive name used in the interface, while shortname
is the publicly visible identier.
activatetime, starttime and endtime are required elds and specify when this contest is active
and open for submissions. Optional freezetime and unfreezetime control scoreboard freezing and

CHAPTER 4.

SETTING UP A CONTEST

deactivatetime when the contest is not visible anymore. For a detailed treating of these, see section
4.2 (Contest milestones). All contest times can be specied relative to starttime, except of course
starttime itself. The input given in the jury interface (either relative or absolute) is stored in the
*time_string elds, while a calculated absolute version is stored in the elds without the _string

sux.

The public eld can be used to limit which contests are displayed as public scoreboards (as opposed
to privately to a selected set of teams), while enabled can be used to (temporarily) disable a contest
altogether.
contestproblem

This table couples problems to contests: cid and probid describe the pairing.
Furthermore, it stores problem data that is specic for the included contest: shortname is a contestunique identier string for the problem, points defaults to 1 and can be set to assign non-even scoring;
allow_submit determines whether teams can submit solutions for this problem. Non-submittable
problems are also not displayed on the scoreboard. This can be used to dene spare problems, which
can then be added to the contest quickly; allow_judge determines whether judgehosts will judge
submissions for this problem. See also the explanation for language.
The color tag can be lled with a CSS colour specication to associate with this problem; see also
section 6.2.1 (Scoreboard: colours).
contestteam

This table couples teams to contests. Teams can only submit solutions to problems in contests that
are public or which they are part of.
executable

This table stores zip-bundles of executable scripts that can be used as compile, run, and compare
scripts.
judgehost_restriction

This table encodes restriction sets for selecting which submissions are sent to a judgehost. The restrictions are JSON encoded in the restrictions column, and can be set in the admin web interface
to restrict on specic contests, problems, languages, and to never rejudge on the same judgehost. A
restriction set can be assigned to judgehost(s) on the edit page of the judgehosts overview.
language

Programming languages in which to accept and judge submissions. langid is a string of maximum
length 8, which references the language. name is the displayed name of the language; extensions is
a JSON encoded list of recognized lename extensions; allow_submit determines whether teams can
submit using this language; allow_judge determines whether judgehosts will judge submissions for
this problem. This can for example be set to no to temporarily hold judging when a problem occurs
with the judging of a specic language; after resolution of the problem this can be set to yes again.
time_factor is the relative factor by which the timelimit is multiplied for solutions in this language;
compile_script refers to a compile executable script that is used for this language.

problem

CHAPTER 4.

SETTING UP A CONTEST

This table contains the problem denitions. probid is the reference ID, cid is the contest ID this
problem is (only) dened for: a problem cannot be used in multiple contests. name is the full name
(description) of the problem.
allow_submit determines whether teams can submit solutions for this problem. Non-submittable

problems are also not displayed on the scoreboard. This can be used to dene spare problems, which
can then be added to the contest quickly; allow_judge determines whether judgehosts will judge
submissions for this problem. See also the explanation for language.
timelimit is the timelimit in seconds within which solutions for this problem have to run (taking into
account time_factor per language). See also A.8 (enforcement of time limits) for more details.
memlimit is the memory limit in kB allotted for this problem. If empty then the global conguration
setting memory_limit is used. Equivalently for outputlimit.

special_run if not empty denes a custom run program run_ to run compiled submissions for this problem and special_compare if not empty denes a custom compare program
compare_ to compare output for this problem.

The color tag can be lled with a CSS colour specication to associate with this problem; see also
section 6.2.1 (Scoreboard: colours).
In problemtext a PDF, HTML or plain text document can be placed which allows team, public and
jury to download the problem statement. Note that no additional ltering takes place, so HTML (and
PDF to some extent) should be from a trusted source to prevent cross site scripting or other attacks.
The le type is stored in problemtext_type.
team

Table of teams: teamid is (internal) ID of the team, while externalid can be used to store an ID for
im/exporting to other systems. name the displayed name of the team, categoryid is the ID of the
category the team is in; affilid is the aliation ID of the team.
When enabled is set to 0, the team immediately disappears from the scoreboards and cannot use the
team web interface anymore, even when already logged in. One use case could be to disqualify a team
on the spot.
members are the names of the team members, separated by newlines and room is the location or room
of the team, both for display only; comments can be lled with arbitrary useful information and is
only visible to the jury. The timestamp teampage_first_visited and the hostname eld indicate

when/whether/from where a team visited its team web interface.

The penalty eld can be used to give this team a (positive or negative) number of penalty minutes to
correct for exceptional circumstances.
team_aliation
affilid is the reference ID and name the name of the institution. country should be the 3 character
ISO 3166-1 alpha-3 abbreviation of the country and comments is a free form eld that is displayed in

the jury interface.

A country ag can be displayed on the scoreboard. For this to work, the country eld must match
a (ag) picture in webapp/web/images/countries/.png. All country ags are present
there, named with their 3-character ISO codes. See also webapp/web/images/countries/README.
team_category

CHAPTER 4.

SETTING UP A CONTEST

categoryid is the reference ID and name is a string: the name of the category. sortorder is the order

at which this group must be sorted in the scoreboard, where a higher number sorts lower and equal
sort depending on score.
The color is again a CSS colour specication used to discern dierent categories easily. See also section
6.2.1 (Scoreboard: colours).
The visible ag determines whether teams in this category are displayed on the public/team scoreboard. This feature can be used to remove teams from the public scoreboard by assigning them to a
separate, invisible category.

testcase
The testcase table contains testdata for each problem; testcaseid is a unique identier, input and
output contain the testcase input/output and image an optional graphical representation of the testcase for the jury. The elds md5sum_input, md5sum_output, and md5sum_image contain their respective
md5 hashes to check for up-to-date-ness of cached versions by the judgehosts and image_thumb and
image_type a thumbnail version and mimetype string for the image. The eld probid is the corresponding problem and rank determines the order of the testcases for one problem. description is an
optional description for this testcase. See also 4.4 (providing testdata).
user

This table has the users that the system knows about with their login credentials. Each user may have
one or more roles, like being part of a team, being a jury member or administrator. There are also
functional accounts, like for judgedaemons.

4.2 Contest milestones
The contest table species timestamps for each contest that mark specic milestones in the course of the
contest.
The triplet activatetime , starttime and endtime dene when the contest runs and are required elds (activatetime and starttime may be equal).
activatetime is the moment when a contest rst becomes visible to the public and teams . Nothing can be
submitted yet and the problem set is not revealed. Clarications can be viewed and sent.
At starttime, the scoreboard is displayed and submissions are accepted. At endtime the contest stops. New
incoming submissions will still be processed and judged, but the result will not be shown anymore to teams;
they instead receive the verdict`too-late'. Unjudged submissions received before endtime will still be judged
normally.
freezetime and unfreezetime control scoreboard freezing. freezetime is the time after which the public and
team scoreboard are not updated anymore (frozen). This is meant to make the last stages of the contest
more thrilling, because no-one knows who has won. Leaving them empty disables this feature. When using
this feature, unfreezetime can be set to automatically `unfreeze' the scoreboard at that time. For a more
elaborate description, see also section 6.2.3 (Scoreboard: freezing and defrosting).

The scoreboard, results and clarications will remain to be displayed to team and public after a contest,
until the deactivatetime .
All events happen at the rst moment of the dened time. That is: for a contest with starttime "12:00:00"
and endtime "17:00:00", the rst submission will be accepted at 12:00:00 and the last one at 16:59:59.

CHAPTER 4.

SETTING UP A CONTEST

The following ordering must always hold: activatetime <= starttime < (freezetime <=) endtime (<=
unfreezetime) (<= deactivatime).

4.3 User authentication
The authentication system lets the domserver know which user it is dealing with and which role(s) the user
has. The 6.0 version of DOMjudge only supports username/password authentication.
Each user receives a password and PHP's session management is used to keep track of which user is logged
in. It does require the administrator to generate users and passwords for all teams (this can be done in the
jury interface) and distribute those. Each team has to login each time they (re)start their browser. The
password is stored in a salted hash in the password eld in database (user table).

4.4 Providing testdata
Testdata is used to judge the problems: when a submission run is given the input testdata, the resulting
output is compared to the reference output data using a compare script . The default compare script simply
checks if the outputs are equal up to whitespace dierences, but more elaborate comparisons can be done,
see e.g. the float and boolfind_cmp scripts.
The database has a separate table named testcase, which can be manipulated from the web interface. Under
a problem, click on the testcase link. There the les can be uploaded. The judgehosts cache a copy based
on MD5 sum, so if you need to make changes later, re-upload the data in the web interface and it will
automatically be picked up.
Testdata can also be imported into the system from a problem zip le, following the Kattis problem package
format .

4.5 Start the daemons
Once everything is congured, you can start the daemons. They all run as a normal user on the system.
The needed root privileges are gained through sudo only when necessary.
• One or more judgedaemons: one on each judgehost (or optionally multiple per host; then the -n X

option should be used to bind a judgedaemon to CPU X to prevent CPU resource conicts).

• Optionally the balloon notication daemon (as an alternative to the web interface).

4.6 Check that everything works
If the daemons have started without any problems, you've come a long way! Now to check that you're ready
for a contest.
First, go to the jury interface: http(s)://yourhost.example.edu/domjudge/jury. Look under all the
menu items to see whether the displayed data looks sane. Use the cong-checker under `Admin Functions'
for some sanity checks on your conguration.

CHAPTER 4.

SETTING UP A CONTEST

Go to a team workstation and see if you can access the team page and if you can submit solutions.
Next, it is time to submit some test solutions. If you have the default Hello World problem enabled, you can
submit some of the example sources from under the doc/examples directory. They should give `CORRECT'.
You can also try some (or all) of the sources under tests. Use make check to submit a variety of tests; this
should work when the submit client is available and the default example problems are in the active contest.
There's also make stress-test, but be warned that these tests might crash a judgedaemon. The results
can be checked in the web interface; each source le species the expected outcome with some explanations.
For convenience, there is a link judging verier in the admin web interface; this will automatically check
whether submitted sources from the tests directory were judged as expected. Note that a few sources have
multiple possible outcomes: these must be veried manually.
When all this worked, you're quite ready for a contest. Or at least, the practice session of a contest.

4.7 Testing jury solutions
Before running a real contest, you and/or the jury will want to test the jury's reference solutions on the
system.
The simplest way to do this is to include the jury solutions in a problem zip le and upload this. You can
also upload a zip le containing just solutions to an existing problem. Note that the zip archive has to adhere
to the Kattis problem package format . For this to work, the jury/admin who uploads the problem has to
have an associated team to which the solutions will be assigned. The solutions will automatically be judged
if the contest is active (but it need not have started yet). You can verify whether the submissions gave the
expected answer from the link on the jury/admin index page.

Team Workstations

Here's a quick checklist for conguring the team workstations. Of course, when hosting many teams, it
makes sense to generate a precongured account that has these features and can be distributed over the
workstations.
1. The central tool teams use to interact with DOMjudge is the web browser.
• If possible, set the Home Page to your.domjudge.location/team/
• Go to the team page and check if this team is correctly identied.
• If using https and a self signed certicate, add this certicate to the browser certicate list to

prevent annoying dialogs.

2. Make sure compilers for the supported languages are installed and working.
3. Provide teams with the command line submit client and check that it works.
• If needed, set environment variables to congure the client.
• Optionally distribute .netrc les with team credentials.
• If using https and a self signed certicate, add this certicate to the local trust store (see 3.18.2

(HTTPS setup)).

4. Make the sample in- and output data from the problem set available.
5. Add your SSH key to their authorized_keys le, so you can always access their account for wiping and
emergencies.
6. Check that internet access is blocked.

Web interface

The web interface is the main point of interaction with the system. Here you can view submissions coming
in, control judging, view the standings and edit data.

6.1 Jury and Administrator view
The jury interface has two possible views: one for jury members, and one for DOMjudge administrators.
The second view is the same as the jury view, but with more features added, and can be enabled by giving
a user the 'admin' role (instead of or next to the 'jury' role).
This separation is handy as a matter of security (jury members cannot (accidentally) modify things that
shouldn't be) and clarity (jury members are not confused / distracted by options they don't need).
Options oered to administrators only:
• Adding and editing any contest data
• Managing team passwords
• The cong checker
• Refreshing the scoreboard & hostname caches
• Rejudge 'correct' submissions
• Restart 'pending' judgings

Furthermore, some quick link menu items might dier according to usefulness for jury or admins.
A note on rejudging: it is policy within the DOMjudge system that a correct solution cannot be reverted
to incorrect. Therefore, administrator rights are required to rejudge correct or pending (hence, possibly
correct) submissions. For some more details on rejudging, see the jury manual.

6.2 The scoreboard
The scoreboard is the canonical overview for anyone interested in the contest, be it jury, teams or the general
public. It deserves to get a section of its own.
6.2.1

Colours and sorting

Each problem can be associated with a specic colour, e.g. the colour of the corresponding balloon that is
handed out. DOMjudge can display this colour on the scoreboard, if you ll in the `color' attribute in the
`problem' table; set it to a valid CSS colour value (e.g. `green' or `#0000', although a name is preferred for
displaying colour names).

CHAPTER 6.

WEB INTERFACE

It's possible to have dierent categories of teams participating, this is controlled through the `team_category'
table. Each category has its own background colour in the scoreboard. This colour can be set with the `color'
attribute to a valid CSS colour value.
If you wish, you can also dene a sortorder in the category table. This is the rst eld that the scoreboard is
sorted on. If you want regular teams to be sorted rst, but after them you want to sort both spectator- and
business teams equally, you dene `0' for the regular category and `1' for the other categories. To completely
remove a category from the public (but not the jury) scoreboard, the category visible ag can be set to `0'.
6.2.2

Starting and ending

A contest can be selected for viewing after its activation time, but the scoreboard will only become visible
to public and teams once the contest starts. Thus no data such as problems and teams is revealed before
then.
When the contest ends, the scores will remain displayed until the deactivation time passes.
6.2.3

Freezing and defrosting

DOMjudge has the option to `freeze' the public- and team scoreboards at some point during the contest.
This means that scores are no longer updated and remain to be displayed as they were at the time of the
freeze. This is often done to keep the last hour interesting for all. The scoreboard freeze time can be set
with the `freezetime' attribute in the contest table.
The scoreboard freezing works by looking at the time a submission is made. Therefore it's possible that
submissions from (just) before the freezetime but judged after it can still cause updates to the public
scoreboard. A rejudging during the freeze may also cause such updates.
If you do not set any freeze time, this option does nothing. If you set it, the public and team scoreboards will
not be updated anymore once this time has arrived. The jury will however still see the actual scoreboard.
Once the contest is over, the scores are not directly `unfrozen'. This is done to keep them secret until e.g.
the prize ceremony. You can release the nal scores to team and public interfaces when the time is right.
You can do this either by setting a predened `unfreezetime' in the contest table, or you push the `unfreeze
now' button in the jury web interface, under contests.
6.2.4

Clickability

Almost every cell is clickable in the jury interface and gives detailed information relevant to that cell. This is
(of course) not available in the team and public scoreboards, except that in the team and public interface the
team name cell links to a page with some more information and optionally a team picture, and the problem
header cells link to the problem text, if available.
6.2.5

Caching

The scoreboard is not recalculated on every page load, but rather cached in the database. It should be safe
for repeated reloads from many clients. In exceptional situations (should never occur in normal operation,
e.g. a bug in DOMjudge), the cache may become inaccurate. The jury administrator interface contains an

CHAPTER 6.

WEB INTERFACE

option to recalculate a fresh version of the entire scoreboard. You should use this option only when actually
necessary, since it puts quite a load on the database.
6.2.6

Exporting to an external website

In many cases you might want to create a copy of the scoreboard for external viewing from the internet. Just
for that, the public interface can be called with the url parameter ?static=1. It produces a version of the
scoreboard with refresh meta-tags, login facilities and links to team pages removed. This can for example
be requested every minute via curl and the output be placed as static content on a publicly reachable
webserver.

6.3 Balloons
In many contests balloons are handed out to teams that solve a particular problem. DOMjudge can help
in this process: both a web interface and a notication daemon are available to notify that a new balloon
needs to be handed out. Note that only one should be used at a time.
The web based tool is reachable from the main page in the jury interface, where each balloon has to be
checked o by the person handing it out.
For the daemon, set the BALLOON_CMD in etc/domserver-config.php to dene how notications are
sent. Examples are to mail to a specic mailbox or to send prints to a printer. When congured, start
bin/balloons and notication will start.
Notications will stop as soon as the scoreboard is frozen. Enable the show_balloons_postfreeze conguration option to keep issuing balloon notications after the freeze.

Security

This judging system was developed with security as one of the main goals in mind. To implement this
rigorously in various aspects (restricting team access to others and the internet, restricting access to the
submitted programs on the domjudge systems, etc...) requires root privileges to dierent parts of the whole
contest environment. Also, security measures might depend on the environment. Therefore we have decided
not to implement security measures which are not directly related to the judging system itself. We do have
some suggestions on how you can setup external security.

7.1 Considerations
Security considerations for a programming contest are a bit dierent from those in normal conditions: normally users only have to be protected from deliberately harming each other. During a contest we also have
to restrict users from cooperatively communicating, accessing restricted resources (like the internet) and
restrict user programs running on judgehosts.
We expect that chances are small that people are trying to cheat during a programming contest: you have
to hack the system and make use of that within very limited time. And you have to not get caught and
disqualied afterwards. Therefore passive security measures of warning people of the consequences and only
check (or probe) things might be enough.
However we wanted the system to be as secure as possible within reason. Furthermore this software is open
source, so users can try to nd weak spots before the contest.

7.2 Internal security
Internal security of the system relies on users not being able to get to any vital data (jury input/output and
users' solutions). Data is stored in two places: in les on the DOMjudge system account and in the SQL
database.
Files should be protected by restricting permission to the relevant directories.
Note: the database password is stored in etc/dbpasswords.secret. This le has to be non-readable to
teams, but has to be readable to the web server to let the jury web interface work. A solution is to make it
readable to a special group the web server runs as. This is done when using the default conguration and
installation method and when make install-{domserver,judgehost} is run as root. The webserver group
can be set with configure with-webserver-group=GROUP; by default it is tried to be determined from
groups available on the system, e.g. www-data or apache.

Judgehosts and the domserver communicate with each other over HTTP. Also all parties accessing the
domserver web interface obviously use this protocol. We advise to setup HTTPS so interactions between
domserver, judgehosts and teams are all protected. If you need to use a self-signed certicate, you can
consider to install it on the team workstations beforehand to minimize hassle.
When using IP address authentication, one has to be careful that teams are not able to spoof their IP (for
which they normally need root/administrator privileges), as they would then be able to view other teams'
38

CHAPTER 7.

SECURITY

submission info (not their code) and clarications and submit as that team. Note: This means that care has
to be taken e.g. that teams cannot simply login onto one another's computer and spoof their identity.
Problem texts can be uploaded to DOMjudge. No ltering is performed there, so make sure they are from
trusted sources to, in the case of HTML, prevent cross site scripting code to be injected.

7.3 Root privileges
A dicult issue is the securing of submitted programs run by the jury. We do not have any control over
these sources and do not want to rely on checking them manually or ltering on things like system calls
(which can be obscured and are dierent per language).
Therefore we decided to tackle this issue by running these programs in a environment as restrictive as
possible. This is done by setting up a minimal chroot environment with Linux cgroup process control. For
this, root privileges on the judgehosts and statically compiled programs are needed. By also limiting all
kinds of system resources (memory, processes, time, unprivileged user and network access) we protect the
system from programs which try to hack or could crash the system.

7.4 File system privileges
Of course you must make sure that the le system privileges are set such that there's no unauthorised
access to sensitive data, like submitted solutions or passwords. This is quite system dependent. At least
should not be readable by other users than DOMjudge.
7.4.1

Permissions for the web server

The default installation sets permissions correctly for the web server user (commonly www-data or apache).
The following information is for those who want to verify the setup or make modications to the settings.
Care should be taken with the etc directory: the domserver-{config,static}.php, dbpasswords.secret
and restapi.secret les should all be readable, but dbpasswords.secret and restapi.secret should
not be readable by anyone else. This can be done for example by setting the etc directory to owner:group
: and permissions drwxr-x-, denying users other than yourself
and the web server group access to the conguration and password les.
If you want the web server to also store incoming submission sources on the le system (next to the database),
then must be writable for the web server, see also 3.4.2 (storage of submissions).
You should take care not to serve any les over the web that are not under the DOMjudge 'www/' directory,
because they might contain sensitive data (e.g. those under etc/). DOMjudge comes with .htaccess les
that try to prevent this, but double-check that it's not accessible.

7.5 External security
The following security issues are not handled by DOMjudge, but left to the administrator to set up.

CHAPTER 7.

SECURITY

Network trac between team computers, domserver and the internet should be limited to what is allowed.
Possible ways of enforcing this might be: monitor trac, modify rewall rules on team computers or (what
we implemented with great satisfaction) put all team computers behind a rewalling router.
Solutions are run within a restricted (chroot/cgroup) environment on the judgehosts which restricts outgoing
network access.

Common problems and their
solutions
A.1 Java compilers
Java is dicult to deal with in an automatic way. It is probably most preferable to use OpenJDK or Oracle
Java, because that's the version contestants will be used to. The GNU Compiler for Java (GCJ) is easier to
deal with but may lack some features.
The recommended way of using Java is by setting up the chroot (see section 3.7.3 (creating a chroot environment)), but you can also choose one of the alternatives as described below.
1. As an alternative the gcj compiler from GNU can be used instead of Oracle's version. This one
generates true machine code and can link statically. However a few function calls cannot be linked
statically (see `GCJ compiler warnings' in this FAQ). Secondly, the static library libgcj.a doesn't
seem to be included in all GNU/Linux distributions: at least not in RedHat Enterprise Linux 4.
2. One can disable the chroot environment in etc/judgehost-config.php by disabling USE_CHROOT.
Disabling the chroot environment removes this layer of security against submissions that attempt to
cheat, but it is a simple solution to getting Java to work, for demo or testing purposes. Note: no
guarantees about system security can be made when running a contest with chroot disabled!

A.2 The Java virtual machine (jvm) and memory limits
DOMjudge imposes memory limits on submitted solutions. These limits are imposed before the compiled
submissions are started. On the other hand, the Java virtual machine is started via a compile-time generated
script which is run as a wrapper around the program. This means that the memory limits imposed by
DOMjudge are for the jvm and the running program within it. As the jvm uses approximately 300MB,
this reduces the limit by this signicant amount. See the java_javac and java_javac_detect compile
executable scripts for the implementation details.
If you see error messages of the form
Error occurred during initialization of VM
java.lang.OutOfMemoryError: unable to create new native thread

or
Error occurred during initialization of VM
Could not reserve enough space for object heap

Then the problem is probably that the jvm needs more memory than what is reserved by the Java compile
script. You should try to increase the MEMRESERVED variable in the java compile executable and check that
41

APPENDIX A.

COMMON PROBLEMS AND THEIR SOLUTIONS

the conguration variable memory limit is set larger than MEMRESERVED. If that does not help, you should
try to increase the conguration variable process limit (since the JVM uses a lot of processes for garbage
collection).
Note that (especially on x86_64 machines) the jvm seems to preallocate huge amounts of memory, up to 2
GB! This is not actually all used, but the memory restriction in DOMjudge will ag it as such, unless Linux
cgroups are enabled, then the actual memory used is measured. Thus, we strongly recommend using Linux
cgroups when using the Oracle jvm.

A.3 Java class naming
Java requires a specic naming of the main class. When declaring the main class public, the lename must
match the class name. Therefore one should not declare the main class public; from experience however,
many teams do so. Secondly, the Java compiler generates a bytecode le depending on the class name. There
are two ways to handle this.
The simplest Java compile script java_javac requires the main class to be named Main with method
public static void main(String args[])

The alternative (and default) is to use the script java_javac_detect, which automatically detects the main
class and even corrects the source lename when it is declared public.
When using the GNU gcj compiler, the same holds for the java_gcj script as for java_javac.

A.4 GCJ compiler warnings
When using the GNU GCJ compiler script java_gcj for compiling Java sources, it can give a whole lot of
warning messages of the form
/usr/lib/gcc-lib/i386-linux/3.2.3/libgcj.a(gc_dlopen.o)(.text+0xbc):
In function `GC_dlopen': Using 'dlopen' in statically linked
applications requires at runtime the shared libraries from the glibc
version used for linking

These are generated because you are trying to compile statically linked sources, but some functions can not
be static, e.g. the `dlopen' function above. These are warnings and can be safely ignored, because under
normal programming contest conditions people are not allowed to use these functions anyway (and they are
not accessible within the chroot-ed environment the program is run in).

A.5 Memory limit errors in the web interface
When uploading large testdata les, one can run into an error in the jury web interface of the form:

APPENDIX A.

COMMON PROBLEMS AND THEIR SOLUTIONS

Fatal error: Allowed memory size of XX bytes exhausted (tried to
allocate YY bytes) in /home/domjudge/system/lib/lib.database.php
on line 154

This means that the PHP engine has run out of memory. The solution is to raise the memory limits for PHP.
This can be done by either editing etc/apache.conf and raising the memory_limit, upload_max_filesize
and post_max_size values to well above the size of your largest testcase. You can change these parameters
under the jury directory or by directly editing the global Apache or php.ini conguration. Note also that
max_file_uploads must be larger than the maximum number of testcases per problem to be able to upload
and edit these in the web interface.
The optional PHP Suhosin module may also impose additional limits; check your error logging to see if these
are triggered. You may also need to raise MySQL's max_allowed_packet parameter in /etc/mysql/my.cnf
on both server and client.

A.6 Compiler errors: `runguard: root privileges not dropped'
Compiling failed with exitcode 255, compiler output:
/home/domjudge/system/bin/runguard: root privileges not dropped

When the above error occurs on submitting any source, this indicates that you are running the judgedaemon
as root user. You should not run any part of DOMjudge as root; the parts that require it will gain root by
themselves through sudo. Either run it as yourself or, probably better, create dedicated a user domjudge
under which to install and run everything.
Also do not confuse this with the domjudge-run user: this is a special user to run submissions as and should
also not be used to run normal DOMjudge processes; this user is only for internal use.

A.7 found processes still running ... apport
error: found processes still running as 'domjudge-run', check manually:
2342 apport

The above error occurs on submitting segmentation fault solutions if you have apport installed (which is
default on Ubuntu). Disable or uninstall the apport daemon on all judgehosts.

A.8 Enforcement of time limits
Time limits within DOMjudge are enforced primarily in CPU time, and secondly a more lax wall clock time
limit is used to make sure that submissions cannot idle and hog judgedaemons. The way that time limits
are calculated and passed through the system involves a number of steps, so documented here.
Time limits are set per problem in seconds. Each language in turn may dene a time factor (defaulting to
1) that multiplies it to get a specic time limit for that problem/language combination. This is the soft
timelimit . The conguration setting timelimit overshoot is then used to calculate a hard timelimit . This
overshoot can be specied in terms of an absolute and relative margin.

APPENDIX A.

COMMON PROBLEMS AND THEIR SOLUTIONS

The soft:hard timelimit pair is passed to testcase_run.sh and then on to runguard as both wall clock
and CPU limit. Since the CPU option is passed second, this one is used by runguard when reporting whether
the soft, actual timelimit has been surpassed. The submitted program gets killed when either the hard wall
clock or CPU time has passed.

Multi-site contests

This manual assumed you are running a singe-site contest; that is, the teams are located closely together,
probably in a single physical location. In a multi-site or distributed contest, teams from several remote
locations use the same DOMjudge installation. An example is a national contest where teams can participate
at their local institution.
DOMjudge supports such a setup on the condition that a central installation of DOMjudge is used to which
the teams connect over the internet. It is here where all submission processing and judging takes place.
Because DOMjudge uses a web interface for all interactions, teams and judges will interface with the system
just as if it were local. Still, there are some specic considerations for a multi-site contest.
Network: there must be a relatively reliable network connection between the locations and the central
DOMjudge installation, because teams cannot submit or query the scoreboard if the network is down.
Because of traversing an unsecured network, you may want to consider HTTPS for encrypting the trac. If
you want to limit internet access, it must be done in such a way that the remote DOMjudge installation can
still be reached.
Team authentication: the IP-based authentication will still work as long as each team workstation has a
dierent public IP address. If some teams are behind a NAT-router and thus all present themselves to
DOMjudge with the same IP-address, another authentication scheme must be used (e.g. PHP sessions).
Judges: if the people reviewing the submissions will be located remotely as well, it's important to agree
beforehand on who-does-what, using the submissions claim feature and how responding to incoming clarication requests is handled. Having a shared chat/IM channel may help when unexpected issues arise.
Scoreboard: by default DOMjudge presents all teams in the same scoreboard. Per-site scoreboards can be
implemented either by using team categories or team aliations in combination with the scoreboard ltering
option.

Developer information

This section contains instructions specically for those wishing to modify the DOMjudge source. If you have
any questions about developing DOMjudge, or if you want to share your changes that may be useful to
others, please don't hesitate to contact us through our development mailing list .

C.1 Bootstrapping from Git repository sources
The installation steps in this document assume that you are using a downloaded tarball from the DOMjudge
website. If you want to install from Git repository sources, because you want to use the bleeding edge code
or consider to send a patch to the developers, the congure/build system rst has to be bootstrapped.
This requires additional software to be installed:
• The GNU autoconf/automake toolset
• Composer - PHP Package Manager.
• Linuxdoc and gro to build the admin and judge documentation from SGML sources and a LaTeX

installation to generate the PDF admin, judge and default team manual.

On Debian(-based) systems, the following apt command should install the additionally required packages
(next to the 3.2 (standard set of packages)):
sudo apt install autoconf automake git composer

Composer is packaged since Debian Stretch and Ubuntu Xenial. Alternatively, it can be installed by following
the documentation located here .
When this software is present, bootstrapping can be done by running make dist, which creates the
configure script, downloads and installs the PHP dependencies via composer and generates documentation
from SGML/LaTeX sources.

C.2 Maintainer mode installation
Besides the two modes of installation described in section 3.3 (Installation system), DOMjudge provides a
special maintainer mode installation. This method does an in-place installation within the source tree. This
allows one to immediately see eects when modifying code.
This method requires some special steps which can most easily be run via makele rules as follows:
sudo apt install acl
make maintainer-conf [CONFIGURE_FLAGS=]
make maintainer-install

APPENDIX C.

DEVELOPER INFORMATION

Note that these targets have to be executed separately and they replace the steps described in the section
3.3 (Installation system); also no prefix ag or other directories have to be specied to configure. In
this case the binaries (e.g. judgedaemon and dj_setup_database) can be found in their respective source
directories, and are also symlinked in bin.

C.3 Makele structure
The Makeles in the source tree use a recursion mechanism to run make targets within the relevant subdirectories. The recursion is handled by the REC_TARGETS and SUBDIRS variables and the recursion step is
executed in Makefile.global. Any target added to the REC_TARGETS list will be recursively called in all
directories in SUBDIRS. Moreover, a local variant of the target with -l appended is called after recursing into
the subdirectories, so recursion is depth-rst.
The targets dist, clean, distclean, maintainer-clean are recursive by default, which means that these
call their local -l variants in all directories containing a Makele. This allows for true depth-rst traversal,
which is necessary to correctly run the *clean targets: otherwise e.g. paths.mk will be deleted before
subdirectory *clean targets are called that depend on information in it.

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 47
Page Mode                       : UseOutlines
Author                          : 
Title                           : 
Subject                         : 
Creator                         : LaTeX with hyperref
Producer                        : pdfTeX-1.40.19
Create Date                     : 2018:12:15 13:27:11Z
Modify Date                     : 2018:12:15 13:27:11Z
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.14159265-2.6-1.40.19 (TeX Live 2019/dev/Debian) kpathsea version 6.3.1/dev

EXIF Metadata provided by EXIF.tools

Admin Manual

Navigation menu

Versions of this User Manual:

Views

Navigation