Update README file
[capablanca.git] / lasker-2.2.3 / README
1 Introduction
2 ------------
3
4 This is a version of the internet chess server which supports a wider
5 variety of variants, allowing other board sizes than 8x8 and more pieces
6 than the 6 orthodox piece types. I renamed it 'capablanca', in remembrance
7 of Jose Capablanca, who rediscovered and popularized Chess on a 10x8 board.
8 (Which is one of the better known variants now supported, next to Xiangqi
9 and Shogi.) It was derived from 'lasker', of which the original README is
10 shown below.
11
12 It also fixes some bugs that remained in the original code.
13
14 H.G. Muller
15
16 ---------------------------------------------------------------------
17
18 This is an enhanced version of the 'lasker' internet chess server. I
19 started to enhance Lasker when I needed a working chess server for a
20 local school. You can get the original 'lasker' release from
21 http://chessd.sourceforge.net/ and you can get my enhanced version
22 from http://chess.samba.org/
23
24 Here is a list of some of the new features in this version:
25
26      - lots and lots of bugs fixed
27      - timeseal support added (see timeseal/README for details)
28      - server configuration via 'aconfig' command instead of config.h
29      - added multi-part command parsing (commands separated by ';')
30      - enhanced aliases
31      - build/install process fixed
32      - fixed help system
33      - transparent server reload (upgrade without disturbing connections or games)
34
35
36 Installation
37 ------------
38
39 First you need to configure and compile the chessd server. Do
40 something like the following:
41
42           cd src
43           ./configure --prefix=/usr/local
44           make
45
46 Then to install the server run "make install". That will install a
47 basic skeleton installation in /usr/local/chessd. 
48
49 Setting up
50 ----------
51
52 Next you will want to launch your chess server using the command:
53      bin/chessd -f -p 5000
54 while in the chessd/ directory. This will launch the chess server
55 using the skeleton data you installed above.
56
57 I highly recommend creating a separate account on your machine to run
58 the chess daemon. This user should own all files in the chessd
59 directory.
60
61 After you launch chessd for the first time you will need to login as
62 the special user 'admin'. That username will be recognised as the
63 server administrator and you will be logged in with the rather unusual
64 combination of a head administrator who is also an unregistered
65 player.
66
67 The first thing you will want to do as the admin user is create a
68 proper 'admin' account with a password. Use the command 'addplayer'
69 while logged in as the admin user to create the admin account. You
70 will be told the password. Then you should immediately logout and log
71 back in using the admin password you have just been given. You will
72 probably want to change this password using the 'asetpass' command. 
73
74 You may also find the following commands useful:
75     ahelp addplayer
76     ahelp asetpass
77     ahelp commands
78
79
80 Securing your server
81 --------------------
82
83 The source code for this chess server has been hacked on by dozens of
84 people over the years. It almost certainly has exploitable buffer
85 overruns or other security holes. If you are like me then you won't
86 like the idea of running an insecure program like that on your server.
87
88 To make it a lot more secure you can choose to run the chess server in
89 a chroot jail. This makes it much harder for an attacker to gain a
90 foothold on your server. It won't prevent them from crashing the
91 chessd process but it will prevent them from gaining access to other
92 parts of the system.
93
94 To run chessd in a chroot jail you need to do the following:
95
96    1) chessd needs to be setuid root. I know this sounds bizarre, but
97       it needs root privileges to use the chroot() system
98       call. Immediately after the chroot chessd will permanently lose
99       its root privileges and instead become the user that launched
100       chessd. To make chessd setuid root do this as root:
101               chown root chessd
102               chmod u+s chessd
103
104    2) pass the command line option -R to tell chessd that it should
105       chroot to the current directory. So to launch chessd you can use
106       this:
107                 chessd -p 5000 -T /usr/local/bin/timeseal_decoder -R /usr/local/chessd
108
109       You may also like to look at the start_chessd script in the
110       scripts directory. This is the script I use to keep chessd
111       always running on my machine.
112
113 If you do use the -R option then I also recommend that you don't place
114 any of the chess server binaries (or any other binaries or libraries)
115 inside the chessd directory. That will increase the security of your
116 server a little.
117
118
119 Email spool
120 -----------
121
122 This chess server does not send emails directly, instead it puts
123 outgoing emails in the spool/ directory and waits for some external
124 program or script to deliver them. I designed it this way as it makes
125 it possible to send email from a chess server in a chroot jail, and
126 offers more flexibility in how email is handled (as that tends to vary
127 a lot between systems).
128
129 If you run sendmail then the sample script in scripts/spool_sendmail
130 might be good enough. Just run this script at startup and it will send
131 all spooled mail every minute.
132
133
134 Server reload
135 -------------
136
137 This version of chessd supports reloading the server code without
138 having to shutdown the server or disturb any games that are in
139 progress. This allows for on the fly upgrades, hopefully without the
140 users even noticing that the system is being upgraded.
141
142 In order to support this functionality I had to make the source code
143 rather more Linux specific than it was previously, but I think that is
144 worth it for the functionality. It would be possible to port the code
145 to many other platforms, but I have not yet done so.
146
147 To reload the server use the command 'areload'. You must be at the
148 ADMIN_GOD admin level to issue this command.
149
150 Updates
151 -------
152
153 Updates will be available on http://chess.samba.org/
154
155 You may wish to use the cvs version to enable you to update more
156 easily. I will only be doing tar ball releases occasionally.
157
158 License
159 -------
160
161 This chess server release is under the GNU General Public License,
162 which is the license used by the original chess server written by
163 Richard Nash. Various parts of the server are under different
164 licenses, depending on who wrote what part, but I believe that all of
165 the licenses are compatible with the GPL.
166
167 The reason I chose the GPL for this release is that I don't want this
168 code to become proprietary again. This has happened at least 3 times
169 in the past with this source code and while I'm sure there were very
170 good reasons at the time, it does mean that the freely available chess
171 servers have not benefited from the considerable development that has
172 happened over the past seven years. 
173
174 I also chose the GPL because it allows me to incorporate source code
175 from other GPLd projects. This saved me quite a lot of time, and is
176 sure to be useful again.
177
178
179 --------------------------------
180 Andrew Tridgell
181 tridge@chess.samba.org June 2002
182 --------------------------------