INSTALL

Public ADOM Server install directions
See LICENSE for copyright and licensing details

Table of contents:
        I. Setup
                i. Install required tools
               ii. Local users
              iii. passwd.py
               iv. termrec
                v. sudo
               vi. quota
              vii. su to adomown
       II. Install
             viii. Check out code
               ix. Add other ADOM versions
                x. Patch and install ADOM versions; compile wrappers
                    a. Patch ADOM
                    b. Compile wrappers
                    c. Compile Sage
               xi. SSH key for spectating
              xii. Guidebook
             xiii. crontab
      III. Configuration
              xiv. etc/config
               xv. Back to root
              xvi. Permissions
             xvii. HISCORES
            xviii. Admin SSH key
              xix. ldconfig
               xx. Stats
                    a. PostgreSQL setup
              xxi. Web server
             xxii. SSHd settings
	
I. Setup
---------

These instructions are written with a Debian or Ubuntu-based system in mind.
Any relatively modern Linux distribution will work, but Debian 6+ or Ubuntu
12.04+ are recommended.

i. Install required tools
==========================

The following software is required for all pieces to work:

* OpenSSH
* bash
* inotify (kernel 2.6.12+)
* quota support and quota tools
* sudo
* screen
* tmux 1.5+
* nano
* vim
* ELinks
* termrec (included)
* unzip
* sed
* Python 2.6+
* Perl (optional, for the database bot)
* PHP (optional, for minor Web page uses)
* PostgreSQL (optional, for stat & history tracking)
Python modules for the score announcing bot:
** IRCLib
** Pyinotify
** ConfigObj
** OAuth
** Tweepy 2.0+
** Feedparser
** Passwd (included)
Perl modules:
** CGI::Compress::Gzip
** Bot::BasicBot
** Try::Tiny 
** String::Approx
** Sub::Exporter
** Term::ReadKey
** Config::Simple
** POE::Component::SSLify 
** Text::LevenshteinXS

On a Debian-based system, the following command, run as root, should bring
in all you need:

apt-get install python-irclib elinks inotify-tools quotatool quota bash \
 libbot-basicbot-perl libtry-tiny-perl libstring-approx-perl vim \
 libsub-exporter-perl sudo screen bsdiff nano hexcurse libterm-readkey-perl \
 wget python-pyinotify libpoe-component-sslify-perl python-configobj \
 python-oauth git openssh-server openssh-client unzip libconfig-simple-perl \
 python-feedparser libtext-levenshteinxs-perl tmux python-pip postgresql && 
 pip install tweepy 

On RedHat-based systems, the following command, run as root, should bring in
all you need (tested on Fedora 17):

yum -y install inotify-tools elinks quota sudo screen tmux bsdiff nano hexedit\
 wget git elinks openssh-client openssh-server unzip python-irclib python-pip\
 python-oauth python-feedparser python-inotify python-configobj vim-enhanced\
 perl-Bot-BasicBot perl-Try-Tiny perl-String-Approx perl-TermReadKey\
 perl-POE-Component-SSLify perl-Config-Simple perl-Text-LevenshteinXS bash\
 postgresql-server && python-pip install tweepy

For compiling binaries from source, or related tools, a compiler and
some development libraries are required:

apt-get install libncurses5-dev libbz2-dev zlib1g-dev gcc-multilib make \
 autoconf g++-multilib
#or
yum groupinstall "development tools"; yum install ncurses-devel\
  bzip2-devel zlib-devel

If running on a 64-bit system, you will need the 32-bit development libraries
of all the above, and libc6 and libstdc++.

Notes:

- Debian Squeeze users will have to build libtext-levenshteinxs-perl and tmux
  from source or another source (like Wheezy).
- Since Twitter deprecated the 1.0 API, most users will need to install Tweepy
  manually instead of via the package manager.  This can be done via pip as
  above.

ii. Local Users
================

The following users and group must be set up for full funcationality:

Group adomusers
Users adomown, adom, spectator, and ttyrecplay

Commands:

groupadd adomusers
useradd -d /var/lib/adom -c "ADOM owner" -s /bin/bash -g adomusers adomown
mkdir /var/lib/adom
chown adomown:adomusers /var/lib/adom
useradd -d /var/lib/adom -c "ADOM public login" -s\
 /var/lib/adom/server/public_login adom
useradd -M -d /var/lib/adom/server/spectator -c "ADOM spectator" -s\
 /var/lib/adom/server/spec_login spectator
useradd -M -d /var/lib/adom/server/ttyrecplay -c "ADOM TTY playback" -s\
 /var/lib/adom/server/ttyrecplay_login ttyrecplay

For adom, spectator, and ttyrecplay, set passwords the same as their username.
adomown can be given a password or remain locked but the install will require 
a lot of commands to be run as adomown.

Commands:

passwd adom
passwd spectator
passwd ttyrecplay

iii. passwd.py
===============

Install passwd.py (latest can be found at
http://newcenturycomputers.net/projects/passwd.html ).

Commands:

cd /tmp
wget http://newcenturycomputers.net/projects/download.cgi/passwd.py
python passwd.py install

iv. termrec 
============

Install termrec & termplay (latest at http://angband.pl/termrec.html ).

Commands:

cd /tmp
wget http://prdownloads.sourceforge.net/termrec/termrec-0.16.tar.gz
tar xzf termrec-0.16.tar.gz
cd termrec-0.16/
./configure && make && make install

v. sudo
========

The adom user requires permission to add new users and set their quotas.

Add the following line to /etc/sudoers or /etc/sudoers.d/50-adom
(must be chmod 0440):

adom    ALL = NOPASSWD: /usr/sbin/adduser, /usr/sbin/setquota

Commands:

echo "adom    ALL = NOPASSWD: /usr/sbin/adduser, /usr/sbin/setquota"\
 > /etc/sudoers.d/50-adom
chmod 0440 /etc/sudoers.d/50-adom

vi. quota
==========

Quota support should be added to prevent a user from filling up the disk.
ttyrecs take a LOT of space. It is optional, however.

Edit /etc/fstab and add the following to the filesystem options: 

relatime,errors=remount-ro,usrquota,usrjquota=aquota.user,jqfmt=vfsv0

Then run commands:

mount -o remount,usrquota /
quotacheck -avugm 
quotaon -a

vii. su to adomown
===================

The next steps should be done as the adomown user.  You'll be told when
it's time to return to root.

Run:

su - adomown
or
sudo -u adomown bash

II. Install
------------

This section should be done as the non-root user you set up for this, e.g.
adomown.

viii. Check out code
=====================

Pick a directory (for now, this must be /var/lib/adom) and finally, check out 
the code:

TAG="2.0b3"
cd /var/lib/adom
git clone https://github.com/AlucardZero/adom-server.git .
git checkout ${TAG}

ix. Add other ADOM versions
============================

Download any desired additional ADOM game versions.  The freely distributable
versions, including 1.0.0, 1.1.1, and the public 1.2.0 prereleases, are 
included in the same way as from ancardia.com (due to the license), but private
versions cannot be distributed this way. You must have donated to the ADOM 
Resurrection IndieGoGo campaign to download and play the private 1.2.0
prereleases.
 
Where you have a choice, get the Debian 32-bit version, as that is what Sage 
supports.

Place the archives, just as you downloaded them, in /var/lib/adom/software/ .

x. Patch and install ADOM versions
===================================

A wrapper binary is used to make some decisions and add some features and must
be compiled.

Also, a binary that facilitates message sending, and one that opens the door to
the Bug Temple, must be compiled.

Small changes to the distributed ADOM binaries are required to separate HISCORE
files. This can be done with sed (as below) or with a hex editor. To do
manually, edit the adom binary in a hex editor (like hexcurse) and change both
mentions of adom_ds.cfg to something unique. Then create this file in /etc 
with contents being the directory the .HISCORE file should be. 1.2.0p14 needs
special treatment due to a bug (#2161); the commands below create a second P14
binary used solely for high score dumping.

I have used:

1.0.0           adom_ds.100
1.1.1           adom_ds.111
League 1.1.1:   adom_ds.lea
Swapgame 1.1.1: adom_ds.swp
1.2.0p1-3:      adom_ds.12a
1.2.0p4-5:      adom_ds.12b
1.2.0p6-13:     adom_ds.12c
1.2.0p14:       adom_ds.12d
1.2.0p16-20:    adom_ds.12e
1.2.0p21-23:    adom_ds.12f
r48-51:		adom_ds.12g
r59-:           adom_ds.12h

Finally, Sage should be checked out and compiled.

a. Patch ADOM
++++++++++++++

Patch the binaries with the following commands:

cp etc/config.bak etc/config
. etc/config
mkdir -p /tmp/adom && cd $_

tar xzf /var/lib/adom/software/adom-111-elf.tar.gz 
for i in 111 lea swp; do
  sed -e "s/adom_ds.cfg/adom_ds.$i/g" adom/adom > /var/lib/adom/bin/adom-$i-bin
done
rm -rf ./adom

tar xzf /var/lib/adom/software/adom-100-elf.tar.gz
sed -e 's/adom_ds.cfg/adom_ds.100/g' adom/adom > /var/lib/adom/bin/adom-100-bin
rm -rf ./adom

shopt -s extglob
where="a"
for i in $(seq ${MIN_PRE} ${MAX_PRE}); do
  versstr="1.2.0_pre$i";
  if [ $i -gt 3 ]; then where="b"; fi
  if [ $i -gt 5 ]; then where="c"; fi
  if [ $i -gt 13 ]; then where="d"; fi
  if [ $i -gt 14 ]; then where="e"; fi
  if [ $i -gt 20 ]; then where="f"; fi
  if [ $i -gt 23 ] && [ $i -lt 48 ]; then continue; fi
  if [ $i -ge 48 ]; then versstr="r${i}"; fi
  if [ $i -ge 48 ] && [ $i -ne 50 ]; then where="g"; fi
  if [ $i -ge 59 ]; then where="h"; fi
  if [ -f /var/lib/adom/software/adom_linux_debian_32_${versstr}*.tar.gz ]; then
    tar xzf /var/lib/adom/software/adom_linux_debian_32_${versstr}*.tar.gz &&
    sed -e "s/adom_ds.cfg/adom_ds.12${where}/g" adom/adom > /var/lib/adom/bin/adom-${versstr//+([_.]|re)/}-bin
    if [ $i -eq 14 ]; then
        sed -e "s/adom_ds.cfg/adom_ds.14d/g" adom/adom > /var/lib/adom/bin/adom-120p14-hs-bin
    fi
  fi
  rm -rf ./adom
done
cd -

These are the md5sums of the resulting binaries:

2e870f9207c08e736d2e2a81ae1f7098  adom-100-bin
c7d6813e48cf19c163ac1a6eba8122ee  adom-111-bin
fdb6df78f676510c375c01d15e627d33  adom-120p10-bin
f8564ee528b1236ae76e4728684ec9d5  adom-120p11-bin
306ec7abaf85d69d699a4f95fac312cc  adom-120p12-bin
a19288bf21a3bf5fe8137fd3d18e83f1  adom-120p13-bin
bdf59bc910357b07368722a06e3edbb1  adom-120p14-bin
c644cafa6ab9b6a26c757a45c2269ccd  adom-120p14-hs-bin
5cf05dac5d5157d8ab2c236268882a8c  adom-120p16-bin
6a327de1a19bc3312d35fbfa3088934e  adom-120p17-bin
db18a7ffffbf6f7d1c1743c558a6e155  adom-120p18-bin
76517e9574100b2eea7b1ebb419d9c5b  adom-120p19-bin
c185ede1856d6bbcf283517bfdaf47d5  adom-120p20-bin
2da778a43c35cb503143e48f53c8507e  adom-120p21-bin
e28aca366e6f04308ceaf0132314158e  adom-120p22-bin
ca1195016d0c5138ed69d59b748faa7b  adom-120p23-bin
d95a75aa104dd306833ff3207ef022ed  adom-120p3-bin
43dd575a1196def002ee50d45cc4afa3  adom-120p4-bin
11d27e4466b94e1667916296178785d9  adom-120p5-bin
ec0100d0cf56c910916c7bdbfa2c2887  adom-120p6-bin
2e176b5cfa5e942b393ac8c46e574ac7  adom-120p7-bin
090afcc61cff60f4cd6304fa1ef87501  adom-120p8-bin
7ada15a894e2664c61e050439bb08d99  adom-120p9-bin
979e65fce3f6f67e093d9f95c4209720  adom-lea-bin
0353c54099cfb1b1fa9ee26c5f126a0b  adom-r48-bin
c0d583f3dcfbff579669e3e2c1ddc9c3  adom-r49-bin
8ebd70075cc690e3184a4364e3e9ebd5  adom-r51-bin
b798bf39d7bc655dadeb7343665e0039  adom-r59-bin
3128f86a6900e99e3ba0ec40b98e31d9  adom-swp-bin

b. Compile wrappers
++++++++++++++++++++

The wrapper binaries decide whether to use Sage or not, and help announce
when players enter significant locations.

cd /var/lib/adom
. etc/config
SUPVER="100 111"
for i in $(seq ${MIN_PRE} ${MAX_PRE}); do
  if [ -f bin/adom-120p$i-bin ]; then
    SUPVER+=" 120p${i}"  
  elif [ -f bin/adom-r$i-bin ]; then
    SUPVER+=" r${i}"
  fi
done
# normal games:
for i in $SUPVER; do
  gcc -m32 -DADOM_$i -Wall src/adom-wrapper.c -o bin/adom-$i
done

#Challenge games:
cd bin/
for j in etr ste brm iro lth; do
  for i in $SUPVER; do
    ln -s adom-$i adom-$i-$j
  done
done
cd ..

#Compile message dispatcher:
gcc -m32 src/message_dispatch.c -o bin/message_dispatch

#Compile the bug temple entrance:
gcc -m32 src/modify_cnt.c -o bin/modify_cnt

c. Compile Sage
++++++++++++++++

Run the following commands to compile and install Sage.  Replace the value for 
STAG if there is a newer released version.

STAG="0.9.25"
git submodule init
git submodule update
cd sage
git fetch --tags
git checkout master
git pull
git checkout ${STAG}
make clean
make
cp adom-sage ../bin/adom-sage-${STAG}
cp adom-sage.so ../bin/adom-sage-${STAG}.so
cd ..

xi. SSH key for spectating
===========================

Generate an ssh key for spectating from the user menu. Don't add a passphrase.

ssh-keygen -t rsa -b 2048 -C "Pubkey for ADOMers to spectate" -f\
 /var/lib/adom/etc/adomusers_key

cat /var/lib/adom/etc/adomusers_key.pub >>\
 /var/lib/adom/server/spectator/.ssh/authorized_keys
cat /var/lib/adom/etc/adomusers_key.pub >>\
 /var/lib/adom/server/ttyrecplay/.ssh/authorized_keys

xii. Guidebook
===============

Download and install the Guidebook to public_html.

Commands:

cd public_html/guidebook
wget http://www.adomgb.info/adomgb-html.zip
unzip adomgb-html.zip
mv adomgb-toc.html index.html
grep -lI adomgb-toc.html * | xargs sed -i -e 's/adomgb-toc.html/index.html/g'
#that's lowercase L, uppercase i
wget -q http://adomgb.info/challenge.html
cd ../..

xiii. crontab
==============

Add the contents of etc/crontab to adomown's crontab.

Command (still as adomown):

crontab etc/crontab

III. Configure
---------------

xiv. etc/config 
================

Edit etc/config and fill in the values.

The SERVNAME field is the domain name of the server, through which HTTP access
will be available, like adom.example.com or ancardia.us.to.

The prerelease section defines the minimum and maximum 1.2.0p versions 
supported. 

The twitter section is for announcing scores on Twitter. Sign up for a Twitter
account then enable API access and generate and find the access and consumer
tokens.
See https://dev.twitter.com/docs/auth/tokens-devtwittercom for help generating.

The donation section is for enabling private 1.2.0 prereleases for people who
donated to the ADOM Resurrection IndieGoGo campaign.  Obviously, you have to
have donated to fill them in, but they cannot be provided or distributed.

xv. Back to root
=================

The rest of the steps should be done as root.

xvi. Permissions
=================

Git does not store permissions besides the executable bit, so some work is
needed to allow multiple users to play on the server.

** NOTE ON SETUID **
Spectating requires 'screen' to be suid root, this makes sure that is set.
However, you may think this is a security risk.  But if you don't set it,
spectating (which uses the multi-user feature of screen) won't work.  By
setting this you are basically trusting screen not to have any bugs an
attacker could use to take over the system.
The message_dispatch binary also must be setuid root for sending messages to
other players to work.  This is a simple program whose source is in src/.

Commands:

cd /var/lib/adom
# for playing
chgrp adomusers public_html/adom_users/ tmp/sockets
chmod 1775 public_html/adom_users/ tmp/sockets
# for running, be sure
chmod ugo+x bin/*
# for scoring
cd var
chgrp adomusers 1* lea swapgame 1*/*HISCORE lea/.HISCORE\
 swapgame/.HISCORE r*
chmod 775 1* lea swapgame r*
chmod 664 */*HISCORE
cd ..
chmod 1777 /var/lib/adom/tmp/
# for announcing locs
chmod 1775 /var/lib/adom/tmp/player_locations
# for spectating
chmod u+s `which screen`
chmod 755 /var/run/screen/
# for messaging
chgrp adomusers /var/lib/adom/var/log/messages_sent
chmod 664 /var/lib/adom/var/log/messages_sent
chown root:adomusers /var/lib/adom/bin/message_dispatch
chmod 4710 /var/lib/adom/bin/message_dispatch
# for keys
chmod 600 /var/lib/adom/server/spectator/.ssh/authorized_keys\
 /var/lib/adom/server/ttyrecplay/.ssh/authorized_keys
chmod 700 /var/lib/adom/server/spectator/.ssh\
 /var/lib/adom/server/ttyrecplay/.ssh
chown -R spectator /var/lib/adom/server/spectator
chown -R ttyrecplay /var/lib/adom/server/ttyrecplay
chmod 660 /var/lib/adom/etc/adomusers_key

xvii. HISCORES
===============

To tell ADOM where to put its .HISCORE files for all, copy server/etc/adom_ds* 
to /etc/:

cp etc/adom_ds* /etc/

xviii. Admin SSH key
=====================

(Optional) Add your (the administrator's) SSH public key to 
/var/lib/adom/etc/skel/.ssh/authorized_keys to let him or her SSH in as any 
created user, to see their issues or shut down their games (say to prepare for 
a reboot).

xix. ldconfig
==============

"ldconfig" may need to be run if a package was installed from source
(I had to when I installed tmux)

xx. Stats, SQL
===============

Game stats can be tracked via SQL and displayed via the Web. This is done via
parsing end game logs (.flg) and storing the data in a database, so .flg files
must be generated when prompted.  ADOM Sage will automatically answer 'Y' to
the prompt as of version 0.9.13, but if Sage is not in use, users should
remember to answer Y.

The player stats can be found at /stats.pl?user=username.  Your Web server 
needs to support Perl.

a. PostgreSQL setup
++++++++++++++++++++

Become the psql user that was created upon PostgreSQL install:

su - postgres # probably as root

Start psql:

psql

Create a user and schema. Choose & remember a user and password:

CREATE USER adomstats WITH PASSWORD 'adomstats';
CREATE DATABASE adomstats OWNER adomstats;

Exit PostgreSQL and exit the psql user.  Become the ADOM server owner:

su - adomown # probably as root

Start psql as the ADOM owner:

psql adomstats -U adomstats -h localhost -W

Create the table:

CREATE TABLE stats (
  id serial PRIMARY KEY,
  username varchar(16) NOT NULL,
  name varchar(16) NOT NULL, 
  align varchar(2) NOT NULL, 
  score bigint NOT NULL, 
  level smallint NOT NULL, 
  race varchar(16) NOT NULL, 
  class varchar(16) NOT NULL, 
  reason text NOT NULL, 
  time varchar(16) NOT NULL, 
  turns integer NOT NULL, 
  catlover boolean, 
  bs smallint NOT NULL, 
  date int NOT NULL,
  filename varchar(64) NOT NULL,
  version varchar(16) NOT NULL
);
CREATE INDEX ON stats (username);

Exit PostgreSQL.

Edit etc/config and fill in the database section with the username and
password chosen earlier.

xxi. Web server
================

A Web server should be set up to provide the readme, display hi scores on the
web, and allow users to (optionally) download their files.  Setting up the
server itself is out of scope for this document.

A public_html folder is provided, and should be set as the Web server's
document root, or linked in to its tree.

If PHP is enabled on the Web server, edit the top of public_html/index.php
with the name and other details of the server, and remove index.html.

Alternately, edit the static index.html and remove index.php.

Perl should also be able to be run as CGI on the Web server, for stat display.

To serve up ADOM's text files in a browser, the MIME types of some file 
extensions should be touched. Specifically, the following types would benefit 
from being sent as text/plain:
  flg ssh slg kbd cfg msg vlg
And the following would benefit from being sent as application/octet-stream:
  svg

xxii. SSHd settings
====================

The following unusual SSH daemon settings are recommended (the config file is
usually at /etc/ssh/sshd_config):

  TCPKeepAlive yes
  Compression delayed
  X11Forwarding no
  AllowAgentForwarding no
  AllowTcpForwarding no
  PrintMotd no
  PermitTunnel no
  # Disable SFTP by commenting out the line:
  #Subsystem sftp /usr/lib/openssh/sftp-server