doc/txt/winnotes/afsdb-freelance-notes

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