Installation-HOWTO for the Diplomacy judge

v.1.5.1.2
Christophe Courtois (christophe@courtois.cc)

1 Introduction
1.1 History
1.2 Last version
1.3 Why?
1.4 Configuration
2 Before installing
2.1 Material, learning and paperwork
2.2 Getting the source code or the package
2.3 Judge user: unix level configuration
2.4 Configure before compilation
2.5 The Makefile
2.6 smail.in script
2.7 sendmail problems
2.8 atrun script
2.9 Changing default parameters in defaults.inc.in
2.10 Other source modifications
2.11 Patches
3 Compilation and installation
3.1 Compilation
3.2 Installation
3.3 Cleaning
4 Installing the Debian package
5 Configuring your new judge
5.1 Dip.conf
5.2 Other dip.* files
5.3 dipclean
5.4 .forward
5.5 dip.control date problems
5.6 Ready?
5.7 Customise e-mails from the judge

6 What are these files?
6.1 Documentation
6.2 Binaries
6.3 Shell scripts
6.4 Parameter and data files
6.5 Maps and 'data' directory
6.6 Games
6.7 Log files
6.8 Temporary files
6.9 Files created or left behind by a crashed judge
6.10 Other files
7 Testing the judge, first game
7.1 Manual basic testing
7.2 Automatic judge tester
8 Troubleshooting
9 Other customisations
10 Backup
11 Upgrading and patching a judge
11.1 Locking the judge
11.2 Archiving
11.3 Makefile variables
11.4 Patching or upgrading source code
11.5 Recompiling and installation
11.6 Relaunching the judge
12 Links
13 Misc
13.1 The author
13.2 Thanks
13.3 Copyright and boring stuff


1 Introduction

1.1 History

- 1.5.1.x : September 2003

- 1.5.1.0 : August 2003

- 1.3.2.x : March-May 2003
- 1.3.0-pre : December 2002
- 1.1.1.x : May 2002
- 1.0.1.x : February 2002
- 1.0.0.0-2 : January 2002
- 0.8.9.2 : August 2001
- 0.8.9 : July 2001
- 0.0 - 0.8.7 : February/March 2001

1.2 Last version

This is an installation guide which aims to be more complete and newbie-friendly than the INSTALL file.

This file deals with installing a clean standard version of njudge v 1.5.1. There are good chances it will work for following versions (especially as the installation process has stabilized recently).

The version number of this file follows judge versions.
The reference version is now the HTML guide. The text should be automatically generated against the HTML.
Anyway, the last version of this file should always be in the last CVS snapshot of the judge at http://www.njudge.org/.

1.3 Why?

Once upon a time, a young man decided to install a Diplomacy judge on his Linux box. He wanted to learn C, improve his Unix administration knowledge, code some new variants, and say to his friends on the mailing list 'Look! I have a judge!'.

This is a story of stupid mistakes, problematic compilations, crashing code, lost mails, strange behaviour, and friendly help from the Friends Who Know (thanks Philippe and the other JKs!).

As he wanted the others not to suffer as much as he did, as he wanted to contribute to the Diplomacy community, as he couldn't do anything else than writing documentation, he wrote the present installation guide.

It is a compilation of what I have read in the judge files and code, on the judge-maint mailing-list, of what I have learned myself by installing the judge (versions: 0.8.6-FROG, 0.8.7, 0.8.9, 1.0.0, 1.1.1, 1.3.0-pre, 1.3.2, 1.5.1). Comments, advice, corrections [including spelling and grammar, I'm not a native English speaker] are welcomed (in French, English or German)!

This guide is focused on the installation on Linux, but should be okay for most Unices. If you know of some platform-specific installation problems, please ask me to add it there.

1.4 Configuration

The present HOWTO comes from my experience in installing the judge ALEX on my Linux box.
Computer: Pentium 75
OS: Linux Debian 3.0 (woody) (+ tools from Debian Sarge)
Judge: njudge 1.5.1 compiled from source

2 Before installing

2.1 Material, learning and paperwork

Before installing the judge there are a few things you need to do :

- Find a box (a 486 is enough, such a powerful machine didn't even exist when the first version of the judge was written; the real load will come from your OS and the e-mail amount).

- Install a Unix system on it. For example, Linux (any distribution is good enough), as the last versions of the judge are often running and maintained on Linux.
In the past, many judges were running on SunOS, HP-UX or Irix, but the judge wasn't recently compiled on it. Some judges run currently on Solaris, Linux-x86 (different distributions), and Linux-alpha (Debian).
The judge does compile on FreeBSD-x86, Darwin-ppc (and then on MacOS X); I don't know if some judges use these systems.
There was some discussion on a Win32 port. Maybe is it possible to use Cygwin to run a judge on Windows.

- As development tools, you'll need gcc, and to be on the safe side at least version 2.50 of autoconf and 1.7 of automake. If your system/distribution does not have it, you can get them on GNU.org.
(If you have a Debian Woody, you'll have to install the autoconf and automake1.7 package from the testing distribution).
If these tools are too old, you can obtain some very strange compilation bugs.

- Connect it permanently on the Internet through modem, xDSL, T1, cable... (although a disconnected judge should perfectly work only for local users, or could work with an intermittent connection if the deadlines are long enough).

- Learn the basis of system administration (users, access rights, shell, basic commands, compiling).

- Begin to learn C. It is not necessary to install the judge (I'm a living proof of that), but it is to search efficiently for bugs or modify the source. You don't really need it for creating simple variants.

- Decide what you will do with that judge: experimentation? private for friends? candidate for the biggest running judge? just for fun?

- Decide what name you'll give to your judge. Theoretically, it should begin by the ISO code of the country it is in. FROG is in France, ALEX should have been in Albania, USEF is in the United States and so on.

- Not necessary for a private judge: Send a mail to Nicholas Fitzpatrick (nfitz@sentex.net) to tell him that you want to open a judge, and ask him to bless its name and add it in its list of judges

- If you want your judge to go more or less public and Nicholas is okay with the name, you can add it on the DipPouch Judge Registration Form (http://devel.diplom.org/DipPouch/Email/registration.html) to make it easier for people to register on your judge.

- Subscribe to the judge-keepers mailing-list (send a mail to majordomo@diplom.org with 'help' in the body). It is actually a judge maintenance mailing list. The JKs just happen to all be there.
There are archives of this list available on Alain Tesio's website: http://www.floc.net/exarch/judgemaint.html

2.2 Getting the source code or the package

Download the source of the judge from the net : http://www.njudge.org/ is the official download site from Millis Miller and should indicate which is the last official judge version available, and give you a link to download it.

A CVS snapshot is available too. It is a tarball generated every day from the CVS (development) tree. It is the most current (and unstable!) judge, only for people who know what they are doing. A direct CVS access is possible only with an account on the development computer.

Other sources where you can search in case of a problem on njudge.org: * ftp.diplom.org/pub/diplomacy/Sources/

- The official judge is distributed as a source code tarball called njudge-1.X.Y.tar.gz, where X and Y change with time. Current version is 1.5.1. Please ignore njudge-0.8.X and dipsrc-9XXX files if you find some, they are out of date.

- If you're lucky enough to work with a Debian Linux, you have a package by Jaldhar H. Vyas available at Braincells: http://src.braincells.com/debian/woody/njudge/
See below (section 4.) how to install it. You can skip the Unix configuration and the compilation below. Your judge will use the 'judge' user name, and will be installed directly in /home/judge (no dip/ binary directory).

2.3 Judge user: unix level configuration

- Create an account for the judge on your system. The name of the account may be anything as long as it does NOT contain a '-'. It is often judge@... The judge must have its own e-mail address. You can create aliases to redirect judge@... on any other account (the setup is usually in /etc/aliases).
For ALEX, the user is 'alex' and 'judge' is redirected on it.

NB: To write to the judge from the Internet, you need a valid domain (like foo.com, toto.fr, bar.edu), which can be obtained only with a permanent IP. If the box has no permanent IP address (like most personal computers on xDSL or cable), it is possible to use dynamic DNS (for example Dyndns.org) to have an address anybody on the net can write to. Or you can hack something (with fetchmail for example) to retrieve mail every 10 minutes from a 'real' account (good thing for a disconnected judge).

- Log out and log yourself as the judge user.

- Verify that the commands rm, cat, date, echo, at, atrm are ready to use without any directory indication. They must be in directories of $PATH. If you use bash as often on Linux, you may need to modify .bashrc and/or .profile.

- As the judge script use the csh shell (and not the more popular bash), put the judge binary directories in the .cshrc file. For example:
setenv PATH /usr/bin:/usr/local/bin:/home/alex/dip:/home/alex:/bin:~:.

- All the examples here deal with njudge-1.5.1.tar.gz.

- Extract the archive:

tar xzvf njudge-1.5.1.tar.gz

The file is extracted into a new directory called njudge-1.5.1. As I have many versions of the judge on my hard disk, I have created a 'source' symbolic link which points to the real current source directory.

cd ~
ln -s njudge-1.5.1 source

- Browse the files you have obtained. You can read the README.* or docs/README.* files now, even if you don't understand everything now. (Some of them are clearly out-of-date; they are usually in docs/archives/).

- Create a new directory in the judge's home for the compiled judge. It will contain binaries, judge configuration files, games, maps... The directory is often called 'dip'.

For ALEX :

mkdir /home/alex/dip

This may be useless as the installation process should create the directory; but it can't hurt. Note that many people like to install the binaries directly under /home/judge.

2.4 Configure before compilation

- The judge uses the GNU Autotools (automake, autoconf) as its build system (thanks for that, Jaldhar ;-) automake and autoconf are pretty much standard on Unix-like systems these days but if your vendor or distribution does not provide them, you can download them from ftp://ftp.gnu.org/pub/gnu/. You will need at least version 2.50 of autoconf.

- Some modifications (including changing the judge version if you modify it) involves modifications before launching ./configure. Read docs/README.hackers or wait until the present guide is updated.

- A simple './configure' at the command line is not really enough; as you may have another user than 'judge' and may want to use the 'dip' directory to store the binaries instead of the root of the user directory, the command line is more something like:

./configure --with-dir=/home/alex/dip --with-user=alex --with-domain=christophecourtois.org

where alex must be replaced by your judge user name, christophecourtois.org by the domain of your judge where the address must appear to come from.

If you're using csh on an old version of System V, you might need to type 'sh ./configure' instead to prevent csh from trying to execute configure itself.

There are many other command line flags you can give (type './configure --help' for a full list) but --with-dir and --with-user are the main ones you're likely to use.

This command will detect your system configuration, binaries paths... to generate a Makefile suited to your system.

There may be a problem if you have a sendmail binary or alias which is not easy to find by the script. Although every MTA (Exim, Postfix, Qmail, Sendmail itself...) seems to provide a compatibility mode, it is sometimes not easy to find, and often not in the $PATH. If the ./.configure fails by telling you it didn't find sendmail, search for it yourself with find / -name sendmail -print, and add another parameter to the script: --with-sendmail=/path_where_sendmail_is. Thank you for telling us this unknown path, it will be added in the script in the next version

. If the ./configure finds it, but the compilation fails by not finding it itself, you may have to:

- (This should not be necessary on new judges) Verify permissions and change them if necessary to be able to write to the files.

cd ~/source
chmod -R u+w *

2.5 The Makefile

- The Makefile was created through ./configure. It must not be modified anymore (as in the good old times).

- The following targets exist in the Makefile, with their use:
all: Rebuild all programs
ascii_to_ded: Convert text file ded.txt to dip.ded
ded_to_ascii: Convert dip.ded to text file
dip: Rebuild dip program
cmap: Rebuild cmap program
summary: Rebuild summary program
deddump: Rebuild deddump program
delgame: Rebuild delgame program (to erase permanentely a game)
flock: Rebuild flock program (used for locking of dip.log)
fmtwho: Rebuild fmtwho program
ign: Rebuild ign program
pdip: Rebuild pdip program (no longer used?)
rdip: Rebuild rdip program
install: build and install a judge (Note: this will check if dip.master file exists and refuse to run if so, avoiding inadvertently deleting an existing njudge installation.)
upgrade: Rebuild all the programs and install them in correct directory (used principally for updating a running judge)
install-strip, upgrade-strip: Same as above, with smaller binary files.
remap: Force binary map files to be regenerated if required
flist: Rebuild the help file "flist"
dist: Build an update distribution (calls targz)
clean: Remove all output files
magic: Used to generate .magic.dat file (for random seed).
size_check: Builds executable that checks sizes of char, int and long (to give error if judge ported to a machine with different values for this!)
zpblind: Blind post-processor executable
dist-gzip: Create a tar.gz of the judge source code
dist-zip: Idem, with zip instead of gzip
dist (or dist-all): Makes both

2.6 smail.in script

'smail' is the script which builds the messages and sends them. This script is created during the compilation. There is a smail.in script which contains the default lines. (Change only smail.in, as smail is destroyed when launching ./configure).

- You should not change the FROM line: there go the user and the domain that you indicated when launching ./configure.

- The judge uses dip.msg (if it exists) as a header for all messages. You can create such a file with any content you like. It uses dip.footer as a footer.

- Warning : dip.msg and dip.footer must be configured AFTER the installation in the binaries directory, they won't be copied when installing.
Think to remove the useless blank lines in them. Don't try to add too much and take the risk to break some tools relying on the judge e-mail format.

- The smail script may need other modifications. For example, Greg Greenman had some problem on USTX with the mails headers with sendmail. This is his smail script which solves the problems:


#!/bin/csh
# /bin/sh (Note: /bin/sh fails to work if N files are open)
#
# Invoked as smail file subject address
#
# parameters
# $1 - name of the file containing the message body
# $2 - subject
# $3 - e-mail address
date >>mail.log
echo "===== mail sent to $3/$2" >>mail.log
/usr/bin/head -10 $1 >>mail.log
cat > /tmp/dip.reply << _EOF_
Subject: $2
From: USTX Diplomacy Judge <judge@spencersoft.com>
To: $3

_EOF_
cat dip.msg $1 dip.footer >> /tmp/dip.reply
/usr/sbin/sendmail -f judge@spencersoft.com </tmp/dip.reply $3
rm -f /tmp/dip.reply
rm -f dip.xfail

2.7 sendmail problems


Some people had problems with some sendmail configuration (especially with Red Hat Linux). If you use smrsh, place a symbolic link to rdip in the /etc/smrsh/ dir. Also make sure only the owner has write permission to the .forward file.
(Briefly: smrsh allows only programs from a unique directory to call sendmail, allowing the system administrator to choose the set of acceptable commands).

2.8 atrun script

'atrun' is responsible for putting the 'diprun' script in the 'at' queue. 'at' is a system command to schedule launch of programs. 'diprun' will itself launch the 'rdip' program.

NB: If you schedule any jobs as the judge user using at, they will be deleted the next time that the Judge receives an e-mail.

There are three predefined versions in atrun for Solaris, Linux (see below) and MIPS. Activate the version which suits your system.

A problem is that some Linux versions of atq don't tell you the command each entry will run at the given time, so there is no way to delete the rdip entry but not the dipclean entry. So the way to get around this in some Linux system, is to put one on one queue, and one on another queue, and then search by queue.

This is the script if you need it:


#! /bin/csh
#
# Invoked as: atrun norm time month day
# or: atrun dorm time month day
#
if ("$1" == "dorm") then
atrm `atq | awk '{print $1}'` >& /dev/null
endif

at -q b -f diprun $2 $3 $4
rm -f dip.xfail

2.9 Changing default parameters in defaults.inc.in

- This file contains judge default parameters that can't be changed without recompiling the judge. See README.hackers if you want to change some.

2.10 Other source modifications

If you have a very busy judge, the MAXUSER parameter in dip.h, set by default to 8000, may be increased.

2.11 Patches

No known last-minute patch to add to the official version. (Stable versions are not so much fun anymore ;-)

3 Compilation and installation

3.1 Compilation

- It should be easy and painless. Enter on the command line:

make all

and the judge will be compiled. Any error that you could meet in an official release is probably caused by compilation tools (see autoconf and automake requested versions above).

3.2 Installation

- Type:

make install #for a new judge only!

This copies everything that the judge needs into the destination directory you gave to ./configure. On a running judge, use 'make upgrade' (see below). You don't need to be root, and nothing will be installed outside of the judge directory.

- Total compilation time: it depends of your CPU, of course. On my old P75 with 24 Mb memory, it takes less than 30 minutes.

- The installation ends with a message telling you to modify dip.conf and other files (what you have already done), and to activate the judge by renaming xxxx-forward as .forward (see below).

- Compiled programs will not be stripped of debug and other extra information. If you want to make compiled programs a little smaller, you can type 'make install-strip' or 'make upgrade-strip' instead. This may give a few harmless errors (when it tries to strip scripts) but you can ignore them.

3.3 Cleaning

- You can remove the program binaries and object files from the source code directory by typing `make clean'. To also remove the files that `configure' created (so you can compile the package for a different kind of computer), type `make distclean'.

4 Installing the Debian package

- To avoid compiling yourself, you can get the Debian package from Jaldhar Vyas.
Download the version suitable for your architecture from http://www.njudge.org/ if it is available there, or from http://src.braincells.com/debian/woody/njudge/, and (as root) use dpkg to install it, or add the lines given on the site to your /etc/apt/sources.list, run apt-get update and apt-get install it.
It is still to be considered experimental.

- It will create a user called 'judge', with its directory '/home/judge' containing all binaries and data files (yes, it is against the Debian policy).
There is no dip/ directory.

Before running the judge, you still must configure dip.conf as described below.

5 Configuring your new judge

5.1 Dip.conf

- Go to the binary directory ( /home/alex/dip in my example, /home/judge or /home/judge/dip/ maybe for you).

- In the binary of the executables, the configuration file dip.conf contains all non-hard-coded parameters before compilation. You must check the following variables:

* GAMES_MASTER: put YOUR email address or an alias on it, NOT the judge address!!.
* OURSELVES: the Unix user name of the judge, already filed by the --with-user option of ./configure; it is used to avoid mail loops.
* JUDGE_CODE: codename of your judge (ALEX,FROG,USEF...), you MUST change it.
* SPECIAL_PW: the password for the judge-keeper, keep it for yourself!).
* AUTO_MASTER: yes or no; whatever the default is, you should put 'yes' for an 'official' judge, you can put 'no' for an experimental one.

- Optionally, you can decide in which directory must go all running games by setting the GAME_DIR variable. You MUST create the directory before running the judge.
Example, to use the games directory in the user's home:

GAME_DIR=games/

Don't forget the last '/'!

By default (and conservatism compatibility with old judges), GAME_DIR=D. If you leave this variable commented out, the games subdirectories will accumulate in the dip/ directory with a name beginning by D (example : Dtest). So if you move existing game subdirectories from ~/dip/ to ~/dip/my_games/, you must set GAME_DIR=./my_games/D (or remove the leading D from all game subdirectories). You must set the full path if going outside the judge directory (ex: /home/alex/games/ ).

Don't use it to share the games across more than one judge, unless you share other files like dip.whois or dip.addr and avoid concurrent access (dangerous!).

- Default values for other parameters are usually okay. You may need to comment out some of them before changing them. Be careful with HALL_KEEPER, GAMES_OPENER and other mail variables, that MUST be commented out if you're not running a public stable judge with real games. Don't change variables like XFORWARD, KEEPOUT;.. if you don't know what you're really doing.

5.2 Other dip.* files

- Verify the existence of the following files. If they are not there, create them using the 'touch' command. They contain the games data:
- dip.master (should already exist with a game named 'control'; you may log into the game and edit dip.master to promote yourself as master, in order to receive some administrative mail from the judge)
- dip.whois
- dip.addr

- Create or fill in the following files:
- dip.msg : each message sent by the judge to players begins with the content of this file. Put welcome messages there, address of the judge keeper... May be empty.
- dip.footer : each message ends by the content of this file (optional, see 'smail' script above). May be empty.
- ALLOW.map (if you want to allow use of the map command to produce .ps maps of a game)
- ALLOW.map-star (if you want to allow use of the 'map *' command to produce .ps maps of a game based on a LIST output). [Do these options really work nowadays?]

5.3 dipclean

- (This bug should be corrected in 1.5.1 judges) Open the 'dipclean' script and change any path that doesn't match your system (especially the first line).

- It is now useless to run it for a first install.

5.4 .forward

(Already done if installing through the Debian package).

In the home directory of the judge, a file '.forward' must be created. It is usually enough to rename the 'xxxx-forward' file (where xxxx is your judge name) in the dip/ directory. It was generated while compiling. It will redirect automagically all the incoming mails to the judge program.

It must contain one line (there is no leading space and a comma at the beginning). For example:

,"| /home/alex/dip/rdip -b -d /home/alex/dip "

(for a judge in /home/alex, with binaries in /home/alex/dip ; change it according to your needs, but the install process should have made it for you).

Some judges (FROG for example) don't use this file and call procmail to make some processing instead of or before launching the judge program (mainly logging). Ask on the judge-keepers list (especially to Philippe Lalande) for more information.

5.5 dip.control date problems

The dip.master file is generated from the Makefile, and according to the configuration of your system, it can be faulty (although it may be corrected on 1.3 judges).

Check that:
- it does not contain AM or PM
- that months are Jan, Feb, Mar, Apr, May, Jul, Aug, Sep, Oct, Nov, Dec, and nothing else (see source file jm.c). If your computer is not English-speaking, and does not put a capital at the beginning, it will bail out.

This is for example a valid file:


control    001 S1801MX 1 1 1 0 2 18 7
Process    Mon Jan 06 14:05:45 2003
Start      Sun Jan 06 14:05:45 2002

5.6 Ready?

At this point, the judge should be ready to run.

5.7 Customise e-mails from the judge

It's time to configure the dip.msg and dip.footer in the new binaries directory.

6 What are these files?

6.1 Documentation

The docs/ directory of the source code contains mainly documentation and, README files on many subjects. You'll find too the LICENSE file, which indicate who owns the source code, the AUTHORS which lists all contributors to the Diplomacy judge, TODO, which contains bugs, whishlist, and modifications in progress, CHANGES, if you need to know the last modifications.

The archives/ subdirectory contains files which are out-of-date but may be useful for old versions of the judge, for migrating, or for historical purpose.

(If you used the Debian package, documentation is in /usr/share/doc/njudge).

6.2 Binaries

rdip Its purpose is to read in mail and copy it to a file for later processing, it is invoked by incoming mail.
dipMain file. Invoked by rdip.
pdip Reads a mail file and pass each message to dip. Used when the judge has bailed out and mail has stacked up in the spool queue.
flock It must be used when you modify more or less anything in the dip directory. Lock the judge by entering 'flock dip.log'. It will remind you every 5 minutes on your console that the judge is locked. To unlock the judge, just execute flock.
deddump Dump/load the binary dedication file to/from a text file.
delgame Used to delete a game (even an active game!)
ign Used to process bounced mail. See README.ignore.
fmtwho Used for the maintenance of the user base. See README.fixids
cmap Responsible for generation of compiled map files from textual map files.
summary Creates the summary of a game.

6.3 Shell scripts

diprunThis is the script which is called by 'at' and launches rdip.
dipcleanThis is a csh script that cleans old log files. It should put itself onto the at queue for subsequent runs on Saturdays at 2pm. This script relies on the flock program.
smailShell script which creates and launch the mails to the players. See above.
atrunShell script which puts the judge in the 'at' queue to awaken it when needed. (NB: If you put a deadline in the very near future (less than one hour for example), don't expect the judge to awaken exactly at this time. You can check the next time the judge will wake up by looking the at queue with the command 'atq').
newlogsShell scripts which compress old dip.log, dip.rlog, mail.log files into compressed *.Z files. (You can use 'uncompress' to extract them).

6.4 Parameter and data files

(See content for more information)
dip.confAll parameters on the judge which can be changed without recompiling the judge.
dip.masterIt contains all the information on the games: parameters, players...
dip.whoisThis is a database containing the registration information for the people who have registered with the adjudicator.
dip.addrThis file associates a user number and siteid with an email address and vice versa. Each user may have multiple email addresses.
dip.msg, dip.footerMessages at the end and at the beginning of each mail sent by the judge. Used by smail.
dip.nocreateIf you add this file, game creation is disabled. When someone tries to create a game, the content of this file is sent back to them, so please put there the reason why game creation is not allowed.
dip.dedbinary file where dedication are stored.
dip.dedicateBinary dedication database.

6.5 Maps and 'data' directory

map.nCompiled data files, one for each variant.
data/map.<variant_name>Real map source files
data/infoHelp file sent to players
data/seed.*Initial position of units on the map
data/report.*Initial position report in a game. (You can put any other information, text or joke there!!)
data/Other files that can get by the players by the 'get' command (help files...)

6.6 Games

By default, games are located in the binary directory as subdirectories whose name begins by a D. You can change that with the GAME_DIR parameter in dip.conf (see above).
Dxxx/All the data of the game xxx is stored in this directory.
Dxxx/GnnnFile for turn nnn of the game xxx.
Dxxx/MnnnThis is the current set of moves for game xxx. Only the highest numbered file is necessary unless you have a rollback. The dipclean script will remove movement files that have not been accessed for more than 90 days.
Dxxx/PnnnThe P files contain the pending orders for a particular turn. Only the highest numbered file is necessary. Most of these files will be zero length because people don't usually send their orders in ahead of time.
Dxxx/TnnnThese files are temporary files that can be cleaned up if they are found left lying around. The dipclean script will get rid of them eventually.
Dxxx/archiveThis is the archive of broadcasts and game information that an observer would see for any given game. This information can be retrieved with the HISTORY command.
Dxxx/infoInformation about the game, which can be set with the SET COMMENT command. This information is shown in the summary, and in the full list.
Dxxx/summaryThe summary, as seen by a player in the game.
Dxxx/msummaryThe summary, as seen by a master of the game.
Dxxx/startThe date and time when the game started (the point when the countries were assigned). This is used in the summary.
Dxxx/drawContains the date and time when the game ended, and the result. This is used in the summary. If this file has been created, it will be deleted if another turn processes.

6.7 Log files

install.logLogs all variant map files compiled with cmap.
dip.logThis is an interlock file that keeps two dips from running at the same time. In addition, all received mail is written to this file to allow reconstruction should some drastic event occur. The dipclean script will move this file to dip.log.0 once per week to keep it from getting out of hand. Before editing dip.master or any of the other databases that the adjudicator maintains you should lock this file to shut it out. The flock program can be used to do this interlocking. This is the first place to go and look when a problem occurs. This file can become huge!
dip.rlogLogs the activity of rdip.
mail.logThis logs all the mails sent by the judge.
dip.ignoreBounce mail is written to this file. See README.ignore.
dip.log.xxx.ZCompressed archives of the same files.
statsStatistics directory (if enabled by STATS_FLAG=1 in dip.conf). See README.statistics.

6.8 Temporary files

dip.incomingFile containing the last mail received or processed.
dip.lock1, dip.lock2Used internally by flock.
dip.broadcast.xxxx
dip.mbroadcast.xxxx
dip.control
dip.xcontrol
dip.xfailIf it exists, the judge bails out (used to check if smail works.)
dip.tmastTemporary backup file of dip.master.
dip.reply
dip.result
dip.tempUsed for mail construction.

6.9 Files created or left behind by a crashed judge

zforwardSee README.bailout. After a judge crash, .forward is renamed to zforward, and the judge won't be run by an incoming email.

6.10 Other files

xforward When healing a dead judge, zforward must be renamed to xforward. See README.bailout.
text.ded (generated by deddump),
recdump, plyrdata, text.rc
(From Tim Miller) My recdump program (for viewing the new plyrdata records) creates a file called text.rec, which is similar (recdump also allows the JK to modify the binary plyrdata file, but that's covered in the README.plyrdata I put in with my changes).
/var/spool/mail/<user_name>System spool file where the mail for the judge is stacked when the .forward file is not there. (The exact path may change according to your system and distribution).

7 Testing the judge, first game

7.1 Manual basic testing

If you have configured everything, the judge should be able to answer. If any of the following tests fails, see 'Troubleshooting', and check that everything above is OK.

- From your normal account, with any mail agent you want, send him a mail with only 'version' in the body. It should answer very quickly (if the machine is not overloaded and if there is no network problem) with its version number (probably 1.5.1 if you are dealing with the standard judge), the number of registered players and running games.

- Ask him the help files : 'get package', 'get index' , 'get info'

- Register as a new player. In case you had forgotten the syntax:

REGISTER
Name: Marechal Joffre
Country: France
Site: Verdun
Email: put_your_email@here
Age: 142
Phone:0123456789
END

- Then, verify in dip.addr and dip.whois that you are registered.

- Create a new game. Don't set it 'private' or 'nolist'. Don't become master now (NB: you may have to change AUTO_MASTER in dip.conf), or use different e-mail accounts for game creator and players.
Take a script for a standard game (let's call it 'test'), and send it. For example :

create ?test password standard
set list
set dedication -666
set access anysite
set level any
set comment FIRST GAME !!!!!!
set press white/grey
set partial
set observer no
set all press
set rated
set noreveal
set DIAS
set NONMR
set move delay 0.01
set adjust delay 0
set retreat delay 0

- Send another message to the judge : 'list'. Then 'list full'. Then 'list test'. The judge should answer you and give you the game parameters.

- Now the funny part : send:

signon ?test password
set players 1

As you're the only player, and not the master, the game should begin at this moment. You can enter orders the way you want, you are all players at the same time! You will receive a lot of mail saying that the game is starting.

You don't need to be the master. You can always act as a master in the game by sending mail as the judge keeper:

signon @test SPECIAL_PW (where SPECIAL_PW is the one defined in dip.conf)

- Check press (grey, white...) by sending mail between powers.

- Now let's test the deadline system: send a deadline in a few minutes, check that the grace date is postponed, and wait for the players to fall late or abandon. You can always raise your dedication back with 'adjust <user_id> <increase>' later (anyway, JKs are not supposed to play real games on their own judge :-)

- Move everything, make convoys (now, you can freely make a Lvn-Syr convoy :-). Try phase orders. Try proxy orders.

- Check that dedication evolves when you give orders.

- Verify that 'process' and 'rollback' do function. If you want the game to finish normally and quickly, change the parameters to NoDIAS, make a quick draw.

- Check variants too! A h32 (Hundred) could be quicker to check the full commands than a standard. A 'chess' variant (not yet on a 1.5.1 judge) would be good too.

7.2 Automatic judge tester

Yes, it would be fine to have one. As far as I know, nobody finished one yet.

8 Troubleshooting

These are some problems and solutions:
Nothings happen when sending something to the judge and in dip.log, the judge complains he didn't find rm, date, echo... and other commands This is a PATH problem. Be careful : The script uses csh as a shell, and not bash that often. Check '.cshrc' in the home directory. Check that mail and head are in the locations defined in Makefile (to avoid a reinstallation, add symbolic links).
Judges makes a bailoutThe judge can send to the judgekeeper a message saying 'Bailout executed'. It means that the judge died. It has crashed. .forward was renamed to zforward. To solve the problem without losing some mails, you must follow the instructions in README.bailout.
The judge complains that dip.input existsYou didn't clean this file after a previous crash. See README.bailout if you don't want to lose what it contains.
The judge crashes at the first time, in dipent.c Check that the dip.master file was not generated with a bad format in dip.control (see 5.5).
The judge crashes when you try a new variantLook in install.log what variants are installed. Check that all files (source and compiled) are there.

For other problems, read all the log files, the answer must be there.
dip.log contains what came to the judge and the actions it tried to do,
mail.log contains all mails sent. At the very beginning, you have to check the existence of all files (including dip.master, dip.whois...) And don't forget to read README.bailout.

9 Other customisations

- You can change the text in dip.msg and dip.footer any way you want, these are just files added at the beginning or the end of mails sent by the judge.

The report.* files in data/ are the beginning positions sent to the judge when a game begins. They're just text and you can change whatever you want there and add silly comments. (Be careful not to break software like DipChief or web observers...). If you want to add variants, see documentation in the judge code, in VariantsHOWTO.html or njudgemapdatahowto.htm.

You can read README.hackers if you change the code.

10 Backup

As far as I know and have experimented, the easiest way to backup the judge is to make a big archive of it and put it anywhere else where it is safe. Usually the judge doesn't use any file outside its home directory. For example :

tar czvf /backup-directory/judge-archive.tgz /home/alex/*

You can copy it uncompressed on another drive (this example copies only newer files):

cp -upR /home/alex/* /backup-directory/

Anyway, the backup must be made as often as possible (put it in your /etc/crontab).

Be careful: it will probably change in the next versions of the judge, with data in /var/njudge for example.

11 Upgrading and patching a judge

11.1 Locking the judge

Let's suppose that you want to modify the source code of the judge with a patch found on judge-maint. (This example suppose that you have a symlink 'source' pointing to the real 1.5.1 tree).

Lock the judge: enter 'flock dip.log' in the executables (often 'dip/') directory.

11.2 Archiving

- Copy the 'dip/' directory and archive it. For example:

cp -R dip dip.backup

- Create a new source directory to be sure

cp -R njudge-1.5.1 njudge-1.5.1-patch1

- Make the 'source' symlink to point to the new directory.

rm source
ln -s /home/alex/njudge-1.5.1-patch1 source

11.3 Makefile variables

This part is now useless, as the new autoconf/automake process generates automatically the Makefile.

Read docs/README.hackers until this part is updated.

11.4 Patching or upgrading source code

- Modify the .c code, or apply a patch (this way for example: patch summary.c patch-bug160701 ), or download the last CVS version if you have an account on devel.diplom.org, or download a whole new source code tarball in a *new* source directory.

- You should really read docs/README.hackers from Jaldhar Vyas when playing with judge source code modifications, as it sometimes involves to re-run automake/autoconf.

- If you use a new source directory (when upgrading), you won't compile without making a './configure' again. You should use the same parameters and it will spit the same Makefile. But if you have changed them before, you must get the smail.in and defaults.inc.in from your old judge source.
Don't forget to read the INSTALL and InstallationHOWTO.html files of this new version to be sure that the important configuration files to move across both versions are the same (judge maintainers try to do it).

- dip.conf is the configuration file, stored in the binaries directory, and will not be overwritten. Please check that the new version doesn't contain new parameters. Other customisation files (dip.msg, dip.footer...) won't be overwritten.

- Add any new file that the judge would need (variants...). Be very careful of including files of the form foo.[0-9x] in the data/ directory. The tools that maintain the flist handle them in a different way, which can produce some really weird results.
See README.hackers too.

- Lauch the configure. In my example :

./configure --with-dir=/home/alex/dip --with-user=alex --with-domain=christophecourtois.org

- If you just want to rebuild the map files (because e.g. you added a new variant,) type 'make remap'.

11.5 Recompiling and installation

- Recompile and reinstall:

make clean
make all
make upgrade

(NB: if you make a mistake and type 'make install', it will fail but you won't break anything. It was not the case before 0.8.10 :-)

11.6 Relaunching the judge

- Run 'dipclean' (especially after upgrading)

- Go into the 'dip/' directory, unlock the judge ('flock') and test it!

12 Links

13 Misc

13.1 The author

The author is 29 years old, writes SQL all day long for big corporations to eat and pay the mortgage, and is trying to learn Java, C and PHP (The most difficult part is to find some time for it...)

13.2 Thanks

Many parts of this HowTo are cut-and-pasted from README and INSTALL files, from source code and from mails of the judge-maint mailing list.

Thanks to Philippe Lalande, JK of Frog, who was soooooo patient with all my questions on the judge, and the members of the judge-maint mailing-list.

13.3 Copyright and boring stuff

Permission is granted to make and distribute copies of this text provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the derived work is distributed under the terms of a permission notice identical to this one. Translations fall under the category of "modified versions".
Warranty: None. Nothing. Nada. Rien. Que dalle. Nitchevo. Nichts. Do everything at your own risk. Remember this is a sum-up of a non-native English speaker on a subject he recently discovered.
Redistribution is allowed and encouraged; however, it is strongly recommended that the redistributor contact the author before the redistribution, in the interest of keeping things up-to-date (you could send me a copy of the thing you're making while you're at it).
Translators are also advised to contact the author before translating (no translation known for the moment).


Valid HTML 4.01!