Empty archive directory into keep or delete
[openafs-wiki.git] / keep / WindowsEndUserQuickStartGuide.mdwn
1 [[!toc levels=3]]
2
3 # End User Quick Start Guide
4
5 ## Introduction
6
7 This guide is a (hopefully) straightforward manual for setting up [[OpenAFS]]
8 for Windows <del>1.3.70</del> **1.7.4**. It was written with the not-so-
9 experienced user in mind and is a step-by-step description of a sample
10 configuration. Changing the settings to your specific needs should pose no
11 problems.
12
13 _**(The changes for 1.7.4 are incomplete; none of the pictures are up to date.
14 When complete, the markup should be removed --jtb) **_
15
16 ### Before the Installation
17
18 Before we start, let us take a moment and just skim through the installation.
19 For the impatient, this section may not be what you are looking for. This is
20 an introduction to the concepts of AFS'ing in Windows -- "basic" knowledge you
21 should have before attempting to connect to the world.
22
23 #### System Requirements
24
25 First of all, check that your system and network is capable of using
26 [[OpenAFS]] for Windows. You will need <del>Windows 2000 or later. Support for
27 Windows NT and the Windows 9x (including ME) series has been discontinued. If
28 you succeed with the installation, it is sheer luck!</del> **Windows XP SP3,
29 Windows Server 2003 SP2, Windows Vista SP1, Windows Server 2008, Windows 7,
30 Windows Server 2008 R2**.
31
32 The disc usage of [[OpenAFS]] is pretty limited: around <del>50</del>**100**
33 MB in the standard installation. You may later increase the cache size, thus
34 using up more.
35
36 To be able to access files, you will need the network up and running. AFS is
37 not very demanding on bandwidth, but realize that every byte of a file is
38 transmitted over the wire (or air) uncompressed. The use of the client cache
39 helps reduce bandwidth requirements.
40
41 #### Kerberos: An Analogy
42
43 AFS uses an access-restriction system called Kerberos, originally developed at
44 MIT. Kerberos is a three-part authenticator. You could say the Kerberos server
45 (a.k.a. KDC, Kerberos Domain Controller) is somewhat like an ID-card archive.
46 When Adam wants to loan a car from Eve, Eve may trust Adam. Adam is trusted to
47 leave the car back as agreed. In this case, Adam needs simply state "I am
48 Adam". Eve lends him the car, and everything is fine.
49
50 However, if Eve has never met this Adam fellow, she might not want to just
51 give him the car and hope he returns with it. This is where the three-part
52 authentication comes in. Authorities are trusted by most people. So, imagine
53 this scenario instead: Adam tells Eve he wants to borrow her car.
54
55   * Eve: "Fine, but how do I know you are who you say you are?"
56   * Adam: "Do you trust the ID Authority and that they will only give out ID cards to the right person?"
57   * Eve: "Yes, sure I do, they have information on everyone. Including me."
58   * Adam: "So, you would accept if I were to show you my ID card, signed by the ID Authority?"
59   * Eve: "Absolutely, and apparently, you trust them too, so I could do the same for you."
60
61 Both Adam and Eve go about sending in their secret password (known only to the
62 respective person and the computer at ID Authority). They flash their fresh ID
63 cards, and accept each others identity. Instead of the two trusting each
64 other, they only have to trust one common party.
65
66 #### Kerberos in practice
67
68 In AFS, you (the Windows Client, actually) are Adam, and the AFS server is
69 Eve. They both communicate with a KDC.
70
71 However, in the digital reality, things are not quite as easy as borrowing a
72 car: Originally, version four of Kerberos was used in AFS. It turned out this
73 was an insecure concept; many others then moved to [[KerberosV]] (version 5).
74 [[OpenAFS]] followed as soon as possible, without breaking backward
75 compatibility. <del>Unfortunatly, the Windows client was not updated with
76 [[KerberosV]] when the Unix client was, which led Windows developers to create
77 external tools for [[KerberosV]].</del>
78
79 Nowadays, [[OpenAFS]] for Windows does support [[KerberosV]] tickets ("ID
80 cards") directly, <del>but the variety of utilities still exist, creating the
81 problem of choosing which one to use</del> **but MIT no longer supports its
82 Kerberos for Windows implementation, requiring a transition to other
83 implementations. Currently OpenAFS recommends that you use ``Heimdal''
84 Kerberos.**
85
86 In order to use [[KerberosV]] (recommended), you will have to use Kerberos for
87 Windows <del>an MIT product</del>. Of course, this requires that you use
88 [[KerberosV]] servers, which still is not always the case. Small sites may
89 still use [[OpenAFS]]'s own Kerberos IV server implementation, called the
90 **_kaserver_** **but since this option is no longer supported, this
91 introduction will no longer discuss it**.
92
93 ### A Word of Advice
94
95 While installing and configuring AFS, you should keep in mind that the
96 authentication part is the part which most often causes problems. This is
97 partly due to the fact that different generations of Kerberos are kept in the
98 software for backward compatiblity. It may also be that some information is
99 not available to the [[OpenAFS]] developers. Please be patient about getting
100 Kerberos to work.
101
102 If the AFS servers you are about to connect to are already set up and in use,
103 you may be able to browse public areas without being authenticated. This way,
104 you can check if AFS or Kerberos is causing your headache.
105
106 ### The Software Installation
107
108 Now that you know about the existence and uses of Kerberos, we can continue
109 with the installation. This guide will first discuss the installation screens,
110 then continuing with a simple sample configuration and end with some
111 references. Happy installing!
112
113 ## Step by Step
114
115 ### <del>Optionally:</del> Download and Install Kerberos for Windows
116
117 <del>If you know, or believe, that the AFS cell you will be connecting to uses
118 [[KerberosV]], you should download [MIT Kerberos for
119 Windows](http://web.mit.edu/kerberos/www/). The latest release is available on
120 [this page](http://web.mit.edu/kerberos/www/dist/). The download of interest
121 is the **Installer** for Windows.</del>
122
123 Download and install Heimdal Kerberos for Windows from [Secure
124 Endpoints](https://www.secure-endpoints.com/heimdal). You can choose the
125 "Typical Install'' _Maybe there's a way to set flags during installation?_
126 _(NB: should give picture here)_.
127
128 After installing Kerberos, you must edit the file
129 `%SystemDrive%\ProgramData\Kerberos\krb5.conf` (usually equivalent to:
130 `C:\Documents and Settings\All Users\Application Data\Kerberos\krb5.conf`) in
131 Notepad as Administrator. Most of the file is useless but innocuous. But the
132 first lines should say:
133
134 >
135 >     [libdefaults]
136 >         allow_weak_crypto = true
137 >
138
139 You will need to add the line about weak cryptography. A later planned release
140 in the 1.7.X branch will avoid the need to make this configuration file
141 change.
142
143 Note that installing <del>MIT</del> Kerberos for Windows will not prevent you
144 from using the old Kerberos 4 protocol. It will, however, set up your computer
145 for [[KerberosV]] as a first choice.
146
147 ### Download and Install Network Identity Manager (v2)
148
149 Download and install Network Identity Manager (v2) also from [Secure
150 Endpoints](https://www.secure-endpoints.com/netidmgr/v2/index.html). The
151 "Typical Install" is all one needs here. _(NB: shoudl give picture here>_**
152
153 ### Obtaining [[OpenAFS]] for Windows
154
155 The main site for [[OpenAFS]] is [openafs.org](http://openafs.org). From here
156 you can download the latest releases of all versions of the [[OpenAFS]]
157 package. On [this page](http://openafs.org/windows.html) you will always find
158 the latest releases.
159
160 For 64 bit machines, there are two MSI installers you need to run:
161
162   * The OpenAFS File System with 64-bit Explorer Shell and Authentication Libraries
163   * 32-bit Explorer Shell and Authentication Libraries.
164
165 For 32 bit machines, there is one MSI installer that you need. It contains
166
167   * The OpenAFS File System with 32-bit Explorer Shell and Authentication Libraries.
168
169 In the remainder of this document we assume you have a 64-bit system. (Stopped
170 here with 1.7.4 changes.)
171
172 ### Start the Installation
173
174 To begin installing, run the file you downloaded. The screens are pretty
175 standard. Let us go through them one by one.
176
177 ![](http://www.e.kth.se/~tommie/openafs/screens/install/msi/1 welcome.png)
178
179 ![](http://www.e.kth.se/~tommie/openafs/screens/install/nis/1 welcome.png)
180
181 Installation begins at the welcome screen, shown to the right. Next, you will
182 have to agree with the license. Those were the basic steps. From now on, you
183 will need to make decisions. Some of them are "best practice," but some are
184 site ("cell", in AFS lingo) specific.
185
186 ![](http://www.e.kth.se/~tommie/openafs/screens/install/msi/3 type.png)
187
188 After the license agreement, you have the option of doing a "client only"
189 installation (Typical) or a complete installation. You may also choose to
190 configure [[OpenAFS]]'s components manually.
191
192 In the Typical Installation, only enough to get your Windows Client working is
193 installed. Some configuration is postponed until after the installation. Using
194 the Complete Installation, everything will be installed, including the
195 experimental AFS Server, a software development kit and (rather outdated)
196 administration documentation.
197
198 This choice is skipped in the [[NullSoft]] installer.
199
200 #### Custom Installation
201
202 ![](http://www.e.kth.se/~tommie/openafs/screens/install/msi/4 custom.png)
203
204 ![](http://www.e.kth.se/~tommie/openafs/screens/install/nis/2 components.png)
205
206 Choosing Custom Installation gives you more control over what is installed
207 onto your computer. This is shown to the right. There are three different
208 icons used when presenting the components: a grey, a white and a red cross.
209 Installation using the Nullsoft Installer is similar, except a standard
210 checkbox list is being used.
211
212 The icon with a grey background indicates **_some_** of the subcomponents will
213 be installed. The one with a white background indicates that the **_entire_**
214 component will be installed. Last, the red cross shows that the component will
215 not be installed. Pressing the "Disk Usage" button brings up an overview of
216 your computer's storage. From there, you can find a drive with enough space
217 left to install [[OpenAFS]]. Press "OK" to return to the previous screen.
218
219 ![](http://www.e.kth.se/~tommie/openafs/screens/install/nis/3 location.png)
220
221 In the Nullsoft Installer, another dialog is used to specify the installation
222 directory. The default location is a good choice.
223
224 ![](http://www.e.kth.se/~tommie/openafs/screens/install/nis/4 cellservdb.png)
225
226 For the Nullsoft Installer executable, you also have to decide which
227 [[CellServDB]] to use. This is a deprecated way of telling [[OpenAFS]] which
228 servers to contact to reach files from a specific cell. New sites use DNS
229 lookups instead.
230
231 In the Microsoft Installer package, the [[CellServDB]] is preserved if found.
232 Otherwise, the packaged file will be installed. You will not need to confirm
233 this.
234
235 If you already have a [[CellServDB]], you should use the existing file. If you
236 are doing a fresh install, download the file from grand.central.org if
237 possible. Otherwise, use the packaged file.
238
239 ![](http://www.e.kth.se/~tommie/openafs/screens/install/msi/6 configure.png)
240
241 ![](http://www.e.kth.se/~tommie/openafs/screens/install/nis/5 cellname.png)
242
243 In the next step, you will need to decide upon (from the Microsoft Installer):
244
245   * **Default Cell**
246
247     The cell which knows what other cells you will be able to see. It is also
248     used to find out which Kerberos KDC to authenticate your identity against. See
249     also "Freelance Mode" below.
250
251   * **Integrated Logon**
252
253     This feature allows [[OpenAFS]] to use the username and password you
254     entered during Windows Login. If you have the same username and password for
255     your AFS account as in Windows, you will probably want to enable this feature.
256     Anyway, if your usernames and passwords do not match, AFS will ignore the
257     login, thus letting you login to AFS at a later time. (Default is
258     **_enabled_**.)
259
260   * **AFS crypt security**
261
262      Even though you are authenticated without sending your password in clear
263      over the network, the files and directories AFS transfers were historically
264      sent without encryption. AFS for Windows now has support for encrypting all
265      network traffic. Unless you need to access old AFS servers, you should have
266      this enabled. (Default is **_enabled_**.)
267
268   * **Freelance mode**
269
270     AFS was originally intended to be run on stationary office computers. It
271     required the AFS servers to be reachable at any time. Now, the laptop has made
272     that an impossibility. Users disconnect and connect their computers to
273     different networks several times a day. This led the AFS community to the
274     invention of "Freelance Mode". Since the user's default cell determines which
275     cells will be visible to the user, a workaround was neccessary when laptops
276     began moving around. If you have a laptop, or will otherwise be without a
277     connection to the servers of your default cell, you should have this enabled.
278     If your computer can always communicate with the servers of the default cell,
279     this mode is superfluous. (Default is **_enabled_**.)
280
281   * **Lookup cells in DNS**
282
283     In the early days of AFS, the mapping between cell names (often coinciding
284     with the domain name) and the servers of the cell was made in a file called
285     [[CellServDB]]. It contains a list of cells. Each cell has a number of servers
286     which can be contacted in order to use data in the cell. However, as time
287     passed by, the AFS administrators realized they had to keep the file up to
288     date. Not only that, they also recognized they already had a database for their
289     domain; the DNS records. To simplify the job of AFS administrators, the AFS
290     community decided to read server mappings from the DNS instead. In [[OpenAFS]]
291     for Windows, it is still under development, which is why you have the option of
292     disabling it. Normally, you will not notice if the mapping is read from
293     [[CellServDB]] or DNS. (Default is **_enabled_**.)
294
295 Probably the only thing you have changed is the Default cell. All features can
296 be left enabled, unless you have previously detected a bug in one of them.
297
298 ![](http://www.e.kth.se/~tommie/openafs/screens/install/msi/7 credentials.png)
299
300 ![](http://www.e.kth.se/~tommie/openafs/screens/install/nis/6 credentials.png)
301
302 To be able to authenticate yourself to AFS, you will need to retrieve and
303 renew Kerberos tickets. These are called "tokens" in the AFS world. Tokens
304 must be renewed on regular intervals (a common setting is ten hours). In order
305 to handle this, [[OpenAFS]] for Windows ships with a Credentials Manager. A
306 credential is a common name for both tickets and tokens.
307
308 To have the program start when you login, leave the checkbox filled. If you
309 intend to authenticate with [[KerberosV]], you have two options: you either go
310 with AFS Credentials Manager, or use the Leash Credentials Manager of Kerberos
311 for Windows instead. In the latter case, you can disable automatic startup,
312 and ignore the other checkboxes. If unsure, leave it enabled.
313
314 The rest of the checkboxes are (from the Microsoft Installer):
315
316   * **Auto initialize AFS Credentials**
317
318     If you are not able to use the Integrated Logon feature (because the
319     usernames do not match, for instance), you can use this feature instead.
320     Whenever the Credentials Manager is started, or a new network address is found
321     (see below), you will be asked to get new tokens. (This is equivalent to the
322     "-A" parameter to afscreds.exe.)
323
324   * **Renew drive maps**
325
326     This option ensures all drives you have chosen to map to AFS are mapped.
327     (This is equivalent to the "-M" parameter to afscreds.exe.)
328
329   * **Detect IP address changes**
330
331     If used together with the automatic initialization, new tokens will be
332     asked for when the computer receives a new network address. This may be due to
333     a modem connection, an ISP with DHCP, or just plug-and-play computing. (This is
334     equivalent to the "-N" parameter to afscreds.exe.)
335
336   * **Quiet mode**
337
338     Normally, if the [[OpenAFS]] service is not started before the Credential
339     Manager starts, the Manager will display a little guide to help you start it.
340     Enabling this option makes the Credentials Manager silently ignore a stopped
341     service. (This is equivalent to the "-Q" parameter to afscreds.exe.)
342
343   * **Show credentials window on startup**
344
345     The Credentials Manager usually resides in the system tray (lower-right
346     corner). It shows a locked padlock if you have valid tokens, and a padlock with
347     a red cross if not. If you enable this option, [[OpenAFS]] will automatically
348     show you a screen with information about your current tokens. This can be
349     achieved later by clicking on the lock icon in the system tray. (This is
350     equivalent to the "-S" parameter to afscreds.exe.)
351
352 Default is enabled for all options except the last. The install program only
353 appends the parameters to the shortcuts of the Start Menu (under [[OpenAFS]]
354 and under Autostart, if you choose to start the Manager at startup). You may
355 alter these parameters at any time by right-clicking the menu item and choose
356 "Properties".
357
358 This is all it takes for Custom Installation. From now on, the differences
359 between the three installation types are not visible.
360
361 ### Finishing the Installation
362
363 ![](http://www.e.kth.se/~tommie/openafs/screens/install/msi/8 ready.png)
364
365 ![](http://www.e.kth.se/~tommie/openafs/screens/install/nis/7 installing.png)
366
367 Now that you have setup your [[OpenAFS]] package, [[OpenAFS]] can be copied
368 into the right directories. This will be reasonably fast, so don't go for a
369 coffee yet!
370
371 ![](http://www.e.kth.se/~tommie/openafs/screens/install/msi/11 restart.png)
372
373 The last thing you have to do is reboot your computer. Theoretically, you
374 could start [[OpenAFS]] without rebooting. This is not recommended, though.
375 With all of today's anti virus programs and synchronization drivers, you can
376 have that well-deserved coffee break now. Soon, the final adventure will
377 begin.
378
379 ## Configure the Rest
380
381 When you logged in, you may have encountered an error message from "AFS
382 Integrated Logon". This is because you enabled Integrated Logon, but did not
383 have the same username and password for both Windows and the AFS servers. In a
384 later section, we will see how we can make [[OpenAFS]] ignore these situations
385 without bothering you about it.
386
387 [[OpenAFS]] will automatically open ports as neccessary in Windows Internet
388 Connection Firewall. If you have another firewall installed, you will have to
389 open TCP and UDP ports 7000 through 7009.
390
391 Browse to "Control Panel" of your computer. You should have a new alternative
392 called "AFS Client Configuration". Double-clicking this, you should see
393 (something like) the screen below.
394
395 ![](http://www.e.kth.se/~tommie/openafs/screens/afsconfig/general.png)
396
397 Please note that this is only a starting point. If you are looking for a
398 complete configuration reference to [[OpenAFS]] for Windows, you should read
399 the [[WindowsConfigurationReferenceGuide]].
400
401 According to the Client Status, the service is started, as it should. If you
402 used the Typical Installation mode, you will now have to change the cell name
403 into something more appropriate. (No one can authenticate to openafs.org,
404 really.) Change it to whatever your network administrator told you. It is
405 usually simply the domain name of the organization.
406
407 ### Silencing the Intergrated Login
408
409 ![](http://www.e.kth.se/~tommie/openafs/screens/afsconfig/adv_login.png)
410
411 Information is good, but not in excess. To remove the message, go to the
412 "Advanced" tab. Click the "Logon..." button, and set "Fail Logins Silently" to
413 "Yes". This is shown to the right.
414
415 ### Check If You Have Kerberos 5
416
417 If everything is well, you should now be able to obtain AFS tokens for your
418 default cell. Try this by opening the Credentials Manager from the Start Menu.
419 Depending on your installation settings, you may be presented with a password
420 prompt, an information window, or nothing.
421
422 ![](http://www.e.kth.se/~tommie/openafs/screens/windows/taskbar.png)
423
424 If you get nothing, you have started the Credentials Manager in the system
425 tray. Is the padlock locked? Then you do not need [[KerberosV]]. Otherwise, if
426 there is a small red cross over it, try clicking the padlock.
427
428 ![Screenshot of AFSCreds.exe](http://lh3.ggpht.com/_v_0hCq1skrw/S89dFHP3_hI/AA
429 AAAAAACFE/dMQfa_ERaH0/s800/afscreds-sc.png)
430
431 If you get a screen like the one above, you can skip [[KerberosV]]. If it says
432 "You do not have tokens within any AFS cell", you press "Obtain New
433 Tokens...".
434
435 Finally, if you get a password prompt, enter your AFS username and password.
436 Confirm the AFS Cell name to be your default cell. Press "OK".
437
438 If you get an error at this time, you (probably) need to have [[KerberosV]]
439 installed. Often, the Credentials Manager complains the "Authentication Server
440 was unavailable", or something similar.
441
442 Optional: Kerberos for Windows To be able to use [[KerberosV]] authentication
443 servers, install MIT Kerberos for Windows. A description of how to install
444 this is outside the scope of this guide.
445
446 ## Trying It Out
447
448 Start the Credentials Manager and try to obtain new tokens. This should work.
449 You should be able to browse the lands of **_\\AFS\all_** like you were on a
450 Unix computer. Do you have write permissions in the right directories?
451
452 ## Mapping Network Drives
453
454 Many Windows users are more comfortable using drive letters instead of UNC
455 path notation such as \\AFS\openafs.org\software\openafs\1.5.73\. Windows
456 permits any UNC path to be mapped to a drive. On Windows 7 this can be done
457 from the Start Menu. Right Click on "Computer" and select "Map Network Drive".
458 Select a drive letter to map, enter the \\AFS UNC path to map, and select
459 "Reconnect at logon". To map the AFS root volume, use the UNC path \\AFS\all.
460
461 Drive mapping can also be performed using the "NET USE" command line tool.
462
463 ## From here to eternity
464
465 The next time you install [[OpenAFS]] for Windows, you are sufficiently
466 competent to go directly onto the [[WindowsAdministratorsInstallationGuide]].
467 It is more hard-core, and with less fancy screen shots. The
468 [[WindowsConfigurationReferenceGuide]] contains a complete description of the
469 configuration options of [[OpenAFS]] for Windows.
470
471 If anything goes wrong, you can hopefully look it up in
472 [[WindowsTroubleshootingGuide]], a FAQ just for [[OpenAFS]] on Windows. Happy
473 filing!
474