v.1.7.5.1
Christophe
Courtois
([email protected])
- 1.7.5.x : November 2005
- 1.7.5.x : May 2005
- 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
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.7. There are good chances it will work for following versions.
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/.
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!'.
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 on Linux Debian, and 1.7.5 on Mac OS X 10.4.3 with XCode). 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 and Mac OS X, but should be okay for most Unices. If you know of some platform-specific installation problems, please ask me to add it there.
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.
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 an old Debian Woody,
you'll have to install the autoconf and automake1.7
package from
the testing distribution).
Mac OS X users must download development tools from Apple website
(especially gcc, included in XCode).
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 ([email protected]) 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
[email protected]
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
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.7.5. 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 of njudge 1.5 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).
Mac users among others, please note : The following documentation assumes an Unix-like system with usual conventions. With Mac OS X, you must use /Users instead of /home in the following examples. Be careful if the user name contains uppercase letters too.
- 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 (in a non-interactive shell). 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.7.5.tar.gz.
- Extract the archive:
tar xzvf njudge-1.7.5.tar.gz
(NB : If you have Mac OS X and Safari, you may have an already-uncompressed archive file named njudge-1.7.5.tar.gz. Un-tar it with tar xvf njudge-1.7.5.tar )
The file is extracted into a new directory called njudge-1.7.5. 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.7.5 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 ~/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 instead of /home/judge/dip.
- 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:
cd ~/source
/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 *
- 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 |
'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 <[email protected]>
To: $3
_EOF_
cat dip.msg $1 dip.footer >> /tmp/dip.reply
/usr/sbin/sendmail -f [email protected] </tmp/dip.reply $3
rm -f /tmp/dip.reply
rm -f dip.xfail
'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
- This file contains judge default parameters that can't be changed without recompiling the judge. See README.hackers if you want to change some.
If you have a very busy judge, the MAXUSER parameter in dip.h, set by default to 8000, may be increased.
No known last-minute patch to add to the official version. (Stable versions are not so much fun anymore ;-)
- 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).
- 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 dip/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.
- 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'.
- 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 experimentaln and this package is probably
an older njudge version than the current one.
- 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.
- 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.
- 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?]
- (This bug should be corrected in recent 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.
(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.
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
At this point, the judge should be ready to run.
It's time to configure the dip.msg and dip.footer in the new binaries directory.
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).
| rdip | Its purpose is to read in mail and copy it to a file for later processing, it is invoked by incoming mail. |
| dip | Main 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. |
| diprun | This is the script which is called by 'at' and launches rdip. |
| dipclean | This 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. |
| smail | Shell script which creates and launch the mails to the players. See above. |
| atrun | Shell 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'). |
| newlogs | Shell scripts which compress old dip.log, dip.rlog, mail.log files into compressed *.Z files. (You can use 'uncompress' to extract them). |
(See content for more information)
| dip.conf | All parameters on the judge which can be changed without recompiling the judge. |
| dip.master | It contains all the information on the games: parameters, players... |
| dip.whois | This is a database containing the registration information for the people who have registered with the adjudicator. |
| dip.addr | This file associates a user number and siteid with an email address and vice versa. Each user may have multiple email addresses. |
| dip.msg, dip.footer | Messages at the end and at the beginning of each mail sent by the judge. Used by smail. |
| dip.nocreate | If 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.ded | binary file where dedication are stored. |
| dip.dedicate | Binary dedication database. |
| map.n | Compiled data files, one for each variant. |
| data/map.<variant_name> | Real map source files |
| data/info | Help 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...) |
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/Gnnn | File for turn nnn of the game xxx. |
| Dxxx/Mnnn | This 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/Pnnn | The 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/Tnnn | These 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/archive | This 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/info | Information 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/summary | The summary, as seen by a player in the game. |
| Dxxx/msummary | The summary, as seen by a master of the game. |
| Dxxx/start | The date and time when the game started (the point when the countries were assigned). This is used in the summary. |
| Dxxx/draw | Contains 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. |
| install.log | Logs all variant map files compiled with cmap. |
| dip.log | This 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.rlog | Logs the activity of rdip. |
| mail.log | This logs all the mails sent by the judge. |
| dip.ignore | Bounce mail is written to this file. See README.ignore. |
| dip.log.xxx.Z | Compressed archives of the same files. |
| stats | Statistics directory (if enabled by STATS_FLAG=1 in dip.conf). See README.statistics. |
| dip.incoming | File containing the last mail received or processed. |
| dip.lock1, dip.lock2 | Used internally by flock. |
| dip.broadcast.xxxx | |
| dip.mbroadcast.xxxx | |
| dip.control | |
| dip.xcontrol | |
| dip.xfail | If it exists, the judge bails out (used to check if smail works.) |
| dip.tmast | Temporary backup file of dip.master. |
| dip.reply | |
| dip.result | |
| dip.temp | Used for mail construction. |
| zforward | See README.bailout. After a judge crash, .forward is renamed to zforward, and the judge won't be run by an incoming email. |
| 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). |
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.7.5 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.7.5 judge) would be good too.
Yes, it would be fine to have one. As far as I know, nobody finished one yet.
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 bailout | The 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 exists | You 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 variant | Look 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.
- 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.
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.
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.7.5 tree).
Lock the judge: enter 'flock dip.log' in the executables (often 'dip/') directory.
- 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.7.5 njudge-1.7.5-patch1
- Make the 'source' symlink to point to the new directory.
rm source
ln -s /home/alex/njudge-1.7.5-patch1 source
This part is now useless, as the new autoconf/automake process generates automatically the Makefile.
Read docs/README.hackers until this part is updated.
- 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'.
- 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 :-)
- Run 'dipclean' (especially after upgrading)
- Go into the 'dip/' directory, unlock the judge ('flock') and test it!
The author is 31 years old, writes SQL all day long for big corporations to eat and to pay the mortgage, and tries to learn Java, C and PHP (the most difficult part is to find some time for it...)
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.
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 what you're making while you're at it).
Translators are also advised to contact the author before translating
(no translation known for the moment; it would not make much sens
anyway).