registry-notes-20040316
[openafs.git] / doc / txt / winnotes / afsdb-freelance-notes
1 New features for the Windows Clients
2 ------------------------------------
3
4 This file describes new features that have been added to the Windows AFS
5 clients.
6
7 DNS lookup
8 ----------
9
10 DNS lookup of cell servers is now available for the Windows AFS clients.
11 A type 1 AFSDB record is queried to determine the cell server host names.
12 These names are then resolved to IP addresses.
13
14 1. Usage
15
16 This feature is enabled at compilation with the switch "AFS_AFSDB_ENV",
17 as with the Unix clients.  It is activated by default, and can be disabled
18 at runtime by running afsd.exe with the -noafsdb flag for the Win9x client,
19 or by setting the following registry entry on the NT/2000 client:
20
21 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters\UseDNS=0
22
23 The Windows AFS clients use a configuration file named afsdns.ini (stored in
24 the same directory as the cell server database) to determine the address
25 of the DNS server.  This file has the following format:
26
27 [AFS Domain Name Servers]
28 ns1=xx.xx.xx.xx
29
30 Only one name server is actually used currently.  Support for multiple
31 name servers should be easy to add.
32
33
34 2. Design
35
36 Because of the lack of standard resolver libraries on the Win32 and DJGPP
37 platforms, it was decided to perform DNS queries by manually creating
38 packets to send to the DNS server.  The DNS response is then decoded to
39 determine the correct cell server addresses.
40
41 New files:
42
43 WINNT/afsd/cm_dns.c
44 WINNT/afsd/cm_dns.h
45 WINNT/afsd/cm_dns_private.h
46
47 Changed files:
48
49 WINNT/afsd/cm_config.c
50 WINNT/afsd/cm_cell.c
51 WINNT/afsd/cm_ioctl.c
52 WINNT/afsd/afsd_init.c
53 WINNT/afsd/afsd_init95.c
54 auth/cellconfig.c
55 kauth/user_nt.c
56
57
58 3. Future work
59
60 Support for multiple DNS servers
61 Support for resolver libraries, if available for DJGPP and/or Win32
62
63
64 Freelance AFS Client
65 --------------------
66
67 1       Introduction
68
69 The current implementation of AFS requires that all AFS clients belong to
70 a home cell. The home cell provides the client with a starting point to
71 mount the entire AFS file system. The client's top most level view of AFS
72 is determined by the home cell server's root.afs volume. Through root.afs,
73 the home cell also controls which cells clients can access.
74
75 To provide a more flexible and relevant view of the AFS file system to the
76 user, this projects aims to remove the need for a home cell and to allow
77 each client to customize its view of the AFS file system. To this end,
78 the current Windows 2000 and 9x clients for AFS have been modified into
79 a Freelance AFS Client that allows the user to mount and dismount AFS
80 cells at will, without the need of a home cell.
81
82 The new Freelance AFS Client also increases the scalability of the AFS file
83 system since administrator intervention is no longer required for clients
84 to access newly established cells. It also removes the client dependency on
85 the availability of the home cell. Previously, if the home cell were not
86 available, clients would not be able to access the AFS file system. This
87 critical dependency is not present in the Freelance AFS Client.
88
89 2    Usage
90
91 The Freelance feature is available only for the Windows NT/2000 and 9x
92 clients.  In 9x, it can be enabled by running afsd.exe manually with the
93 "-freelance" flag.  It can be enabled in NT/2000 by setting the following
94 registry key:
95
96 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters\FreelanceClient=1
97
98 (GUI support to activate this feature will be available soon.)
99
100 The Freelance client reads the available mount points from a file called
101 afs_freelance.ini.  This file will be created if not found and the list
102 of mount points will initially be empty.  New mount points can be added
103 using "fs mkmount" or the Explorer shell extension.
104
105 Specification of a home cell is unnecessary with the Freelance client
106 itself, but is still needed by programs such as klog and pts to provide
107 a default cell argument.
108
109 3       Design
110
111 This section describes the design approach and provides a high-level
112 description of the project.
113
114 3.1     Design Approach
115
116 The main aim of the project was to shift the client's view of the AFS file
117 system, root.afs, from the home cell onto the client, and thus eliminate the
118 need for a home cell. This had to be done while maintaining compatibility
119 with the existing system, so changes to the client were kept to a minimum.
120
121 My primary approach has been to trick the current system into thinking
122 that there is still a home cell by while feeding it fake information that
123 is generated from a locally stored root.afs directory whenever root.afs of
124 the home cell is requested. This is accomplished by intercepting function
125 calls that fetch data from root.afs on the home cell.
126
127 3.2     Afs_freelance.ini
128
129 The local version of root.afs is represented by a file named
130 afs_freelance.ini, typically stored in the same directory as the cell
131 database. The first line of this file is an integer that specifies the
132 number of mount points there are in this file. The rest of the file is a
133 list of entries, one on each line, in the form xxx#yyy:zzz, where xxx is the
134 name of the mount point, yyy is the cell name and zzz is the volume name.
135
136 3.3     Directory File Structure
137
138 Using the data in afs_freelance.ini, a fake directory is created in memory that
139 is identical to what an AFS directory containing those mount points. This
140 fake directory is then fed to the client when necessary. The structure
141 of the directory is as follows:
142
143 1. Each directory is made up of pages, each of a fixed size. 
144 2. Each page is divided into 32 byte chunks, which are indivisible units.
145 3. The first 13 chunks of the first page, called the directory header page,
146 are used for header information.
147 4. The first chunk of all other pages, are also used for header information.
148 5. Chunks other than those reserved for header information can be used
149 to store mount points. Mount points are stored in a struct defined as such:
150
151 typedef struct cm_localMountPoint {
152         char* namep;
153         char* mountPointStringp;
154         struct cm_localMountPoint* next;
155 } cm_localMountPoint_t;
156
157
158 3.4     Adding/removing mounts
159
160 The fs commands "mkmount" and "rmmount" can be used to add/remove mount
161 points from the afs_freelance.ini file.  These functions can also be
162 accessed from the Explorer shell extension.
163
164 4       Implementation
165
166 4.1 Files Changed/Added
167
168 Most of the changes have been made in 5 files:
169
170 afsd_init.c
171 cm_callback.c
172 cm_dcache.c
173 cm_scache.c
174 cm_vnodeops.c
175
176 Afsd_init.c was changed to include initialization code for the fake
177 directory and local mount points. Cm_callback.c was changed to handle
178 callbacks to /afs differently, since it is now local. Cm_dcache was
179 changed to feed fake information into buffers when the /afs directory is
180 read. Cm_scache.c was changed to provide fake scp information for the
181 mount points found under /afs. Finally, cm_vnodeops.c was modified to
182 make the function trybulkproc skip the fake directory entries.
183
184 In addition, the following files were added:
185
186         cm_freelance.h
187         cm_freelance.c
188
189 Cm_freelance.h and cm_freelance.c were added to provide functions that
190 create and handle the fake directory and fake mount points.
191
192
193 4.2     Functions Modified
194
195 Below is a list of the functions that have been modified. The list is
196 not exhaustive but includes most of the major changes.
197
198 4.2.1   afsd_InitCM
199
200 Several lines of code were added to this function to call the initialization
201 functions for the fake directory and fake mount points.
202
203 4.2.2   cm_HaveCallback
204
205 This function is called to check if files have changed. The /afs directory
206 and mount points on /afs need to handled differently by this function. In
207 particular, whenever this function is called on mount points on /afs,
208 the function needs to always return true. This is because local mount
209 points are only added or removed, never modified.
210
211 4.2.3 cm_GetCallBack
212
213 Because of the same reasons as in 4.2.2, this function needs to handle
214 /afs differently. This function should never be called on the local mount
215 points since the cm_HaveCallBack function always returns true on local
216 mount points. When this function is called on /afs, we need to load the
217 status information of /afs if it is the first time that /afs is accessed
218 since initialization of the fake directory. Otherwise, we simply return.
219
220 4.2.4 cm_GetBuffer
221
222 This function is used to fetch actual data from a file into memory
223 buffers. When this function is called on /afs, we need to fill the memory
224 buffers with data from the fake directory created in memory, rather than
225 by calling server functions.
226
227 4.2.5 cm_GetSCache
228
229 This function is used to fetch meta data about files. When it is called
230 on /afs, we return a hardcoded scache structure. When it is called on
231 the mount points on /afs, we return fake scache data based on the mount
232 points in afs_freelance.ini
233
234 4.2.6   cm_SyncOp
235
236 This function was modified to skip cm_HaveCallback and cm_GetCallback
237 calls on the mount points on /afs.
238
239 4.2.6 cm_MergeStatus
240
241 This function was modified to provide fake status data on /afs.
242
243 4.2.7 cm_TryBulkProc
244
245 This function was modified to skip operations on fake mount points.
246
247
248 4.3     New Functions
249
250 4.3.1   cm_InitFakeRootDir
251
252 This function uses the array cm_localMountPoints and creates in memory
253 an image of a fake directory. This directory is then used to fill buffers
254 when read requests of /afs are made.
255
256 4.3.2   cm_getNoLocalMountPoints
257
258 This function returns the number of mount points on /afs, based on
259 afs_freelance.ini.
260
261 4.3.3   cm_InitLocalMountPoints
262
263 This function reads afs_freelance.ini and creates an array of fake mount points
264 based on its contents. The array is then used by cm_InitFakeRootDir to
265 create a fake directory in memory.
266
267 4.3.4   reInitLocalMountPoints
268
269 This function clears all the fake information in memory and reconstructs
270 them from afs_freelance.ini.
271
272
273 5 Current Status
274
275 This feature is still experimental.  Please post problem reports to
276 the openafs-devel mailing list.
277
278 5.1     Future Work
279
280 GUI support for activation of the Freelance feature will be available soon.
281 An auto-mount function could be added. This would work by intercepting
282 the cm_lookup call so that when a cell is not found in /afs, it would be
283 automatically added.
284 Support for Unix clients.