Fix braces
[crawl.git] / crawl-ref / docs / ssh_guide.txt
1 Guide to online play
2 ====================
3
4 The following guide explains, in layman's terms, how to access server
5 play for Dungeon Crawl. It is directed at Windows users as we expect
6 Linux and OS/X users to have simple access to ssh.
7 Written up by Archibald, with modifications by Butch.
8
9 Goal: learn how to "ssh to crawl.akrasiac.org (cao)". If you know
10 this already, you can stop reading.
11
12 Before we go any further here's what playing on the akrasiac server
13 allows you to do:
14
15 *  play the latest version of crawl stone soup online
16 *  watch other players' games
17 *  have the ability to chat and comment in-game
18 *  have your game stats uploaded/recorded on the homepage
19 *  encounter and kill/be killed by other players' ghosts
20
21 ----
22
23 So you've downloaded the latest version of Crawl Stone Soup and have
24 been playing offline (or 'local') and you thoroughly enjoy it. You
25 may have noticed from the akrasiac homepage, http://crawl.akrasiac.org/
26 or posts in forums that there is a way to enhance your gaming experience
27 by playing 'online' using something called 'SSH'.
28
29 If only you could figure out how. Well, if like me (to begin with)
30 you really are at a loss as to where on earth to start with all this
31 stuff, what you need is some assistance. Wouldn't it be nice if
32 someone could take the time to write an 'Idiots Guide' - a step by
33 step list in easy to understand language, telling you from the very
34 beginning exactly what to do...
35
36 Oh look! somebody has - done just that! Great, then let's get started.
37
38 ----
39
40 1. Get the PuTTY program
41 ------------------------
42 Firstly you will need a means of accessing the server. The easiest
43 and most common method is by using an SSH (Secure SHell) connection,
44 we are going to learn here how to use the 'PuTTY' terminal to do this.
45 In layman's terms PuTTY is simply a small programme that acts as your
46 interface between you (the player) and the server (the host).
47
48 In order to download PuTTY, simply click on the following link:
49   http://www.chiark.greenend.org.uk/~sgtatham/putty/
50
51 As you can see, this is the homepage for 'PuTTY: A Free Telnet/SSH
52 Client'.
53
54 Now go to the downloads section. Scroll down to the Windows downloads
55 section and look for the first option down - you will see that it is
56 called 'PuTTY'.
57
58 That's the one you want, so click on the 'putty.exe' download link and
59 choose to save it to your desktop (well, that's how I did it anyway).
60 This should place an icon on your desktop that resembles two blue screens
61 with a yellow connection/electricity bolt joining them - it should be
62 named 'putty'.
63
64 2. Configure PuTTY connection: SSH, port 22
65 -------------------------------------------
66 So far, so good? Good. Okay, now double click on the putty icon to
67 open the interface which is called  'PuTTY Configuration'. Here you
68 will be presented with an interface in a small window. On the
69 left-hand side you will see a 'Category' tree and on the right-hand
70 side a series of boxes and radio buttons under the heading 'Basic
71 options for your PuTTY session'.
72
73 Don't be daunted here by all the technical looking jargon, we're only
74 concerned with a couple of easy to do actions and then we're almost
75 there!
76
77 You will see the cursor flashing in the following box: 'Host Name (or
78 IP address)'. Here you need to type in the following:
79
80 crawl.akrasiac.org
81
82 Done that? We next need to set one option: There are five radio buttons
83 underneath the 'Host Name (or IP address)' fields, called 'Connection
84 type:' Here you need to choose the SSH button; it should be highlighted
85 green. If it's not already, simply click on it so that it is green.
86 When SSH is selected, the Port field will automatically change to 22.
87
88 Finally, enable SSH compression by using
89 Category: Connection > SSH > Protocol Options > Enable compression.
90 It's disabled by default but helps on a busy server as akrasiac.
91
92
93 3. Set controls to 'Nethack'
94 ----------------------------
95 Next we need to ensure our keyboard will work properly, once connected.
96 So, to the left of the interface (the 'Category' tree) you need to
97 click/select the 'keyboard' option. Doing this will change the options
98 on the right-hand side to 'Options controlling the effects of keys'.
99 Mid-way down that section under 'Application keypad settings:', click on
100 the 'Nethack' radio button so it is highlighted.
101
102 4. Saving these options
103 -----------------------
104 Click on the 'Session' in the Category tree. Enter your preferred name for
105 the session (for example 'Crawl') in the 'Saved Session' input box under
106 'Load, save or delete a stored session'. Then press the 'Save' button. This
107 will save all the configuration options and a host name. Your session name
108 should now appear in the box below just under the Default Settings. To
109 restore the changes you made so far, after starting the program simply
110 one-click the name of the session and press the 'Load' button.
111 Double-clicking the name of the session will immediately start the session
112 (just like pressing the 'Open' button).
113
114 5. Connecting to akrasiac
115 --------------------------
116 We're ready!  Make sure you are connected to the internet and simply
117 click on 'Open' and you will have a black console screen open up and be
118 asked to 'login as:', here you need to type in the word 'joshua'. This
119 is the default log-in name set by the administrator to connect to CAO.
120 Once entered, you will be asked to enter 'jos...@crawl.akrasiac.org.'s
121 password:' - again, type in the word 'joshua' (yes, you guessed it - the
122 default password!).
123
124 The screen will refresh and you will now be presented with the
125 following initial display:
126
127 ________________________________________________________________
128
129  Crawl server (North America) hosted and maintained by Rax E. Dillon.
130  ------------------------------------------------------------------------------
131  Server information: http://crawl.akrasiac.org
132  Webtiles:           http://webtiles.akrasiac.org/
133  Crawl information:  http://crawl.develz.org
134  ------------------------------------------------------------------------------
135  ** Games on this server are recorded for in-progress viewing and playback! **
136  ------------------------------------------------------------------------------
137
138  Not logged in.
139
140  W) Watch games in progress
141
142  R) Register as new user
143  L) Login
144
145  Q) Quit
146
147  =>
148 ________________________________________________________________
149
150
151 6. Creating an account
152 ----------------------
153 Now all you need to do is create an account. Hit the 'r' key and
154 continue as prompted. When you have chosen your player/user name,
155 this will be the name of every character you play with on that
156 account. The rest should be self explanatory and easy to follow.
157
158 7. Playing online
159 -----------------
160 Each time you want to play all you have to do is open PuTTY, log-in
161 to CAO with (joshua/joshua) and then log-in with your player details.
162 Dead easy!
163
164 For in-game instructions hit '?' and you may need to toggle the
165 Num-Pad in order to use it.
166
167 Happy Crawling!
168
169
170
171 Below, we list steps that make logging into the server more convenient.
172
173 8.1 Automatic 'joshua' (login)
174 ------------------------------
175 If you do not want to enter the user name 'joshua' every time you start
176 a new session, just go to 'Session' (the initial display) in the Category
177 tree and type 'joshua@crawl.akrasiac.org' in the 'Host name (or IP address)'
178 input box (as opposed to 'crawl.akrasiac.org' you typed earlier, if you
179 were following the guide).
180
181 8.2 Automatic 'joshua' (password)
182 ---------------------------------
183 If you do not want to enter the password 'joshua' every time you start a
184 new session, then download the file 'cao_key.ppk' from
185
186 http://crawl.akrasiac.org/cao_key.ppk
187
188 and put it in your PuTTY directory. Then start PuTTY, load your stored
189 session and go to 'Connection' ---> 'SSH' ---> 'Auth' in the Category
190 tree. Press the 'Browse' button near the input box labelled 'Private key
191 file for authentication', choose the 'cao_key.ppk' file you have just
192 downloaded and press the 'Open' button. Save the changes as in step 4.
193
194 8.3 A shortcut for Windows
195 --------------------------
196 Once you are satisfied with the configuration, you may speed up things
197 further: go to your PuTTY directory and create a shortcut to putty.exe.
198 Then open the Properties of the newly created shortcut and add
199  -load "your_session_name"
200 (including spaces and quotation marks; replace "your_session_name" by
201 "Crawl" if you followed this guide so far) to the Target object input box
202 at the end of the path, for example,
203 C:\PuTTY\putty.exe -load "Crawl"
204 Now you can rename the shortcut (to for example 'CAO'). Double-clicking
205 the shortcut will immediately start your saved session. If you followed
206 this guide from the beginning, after a while you will arrive at the DGL
207 initial display without the need to type a word.