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/.

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.

- 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).

- 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.

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).

- 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.

- 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:

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:

try to launch automake and aclocal and try ./configure and
make all again,

or upgrade to automake 1.7 and begin from a fresh tarball again (anyway, I had to do that).

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

'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:

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).

'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 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.

- 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 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.

- 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?]

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.

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).

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.

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).

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.

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.

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.5.1 if you are dealing with the
standard judge), the number of registered players and running games.

- 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 :-)

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.

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.

- 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.

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).