From: Jeff Riegel Date: Sun, 20 Jan 2002 08:37:14 +0000 (+0000) Subject: STABLE12-windows-afsdb-freelance-notes-20020120 X-Git-Tag: openafs-stable-1_2_3~46 X-Git-Url: https://git.michaelhowe.org/gitweb/?a=commitdiff_plain;h=327e8e38609416cabd1772461f97e52a6ca594c6;p=packages%2Fo%2Fopenafs.git STABLE12-windows-afsdb-freelance-notes-20020120 notes from Jeff about AFSDB and Freelance clients --- diff --git a/doc/txt/winnotes/afsdb-freelance-notes b/doc/txt/winnotes/afsdb-freelance-notes new file mode 100644 index 000000000..af7d84286 --- /dev/null +++ b/doc/txt/winnotes/afsdb-freelance-notes @@ -0,0 +1,284 @@ +New features for the Windows Clients +------------------------------------ + +This file describes new features that have been added to the Windows AFS +clients. + +DNS lookup +---------- + +DNS lookup of cell servers is now available for the Windows AFS clients. +A type 1 AFSDB record is queried to determine the cell server host names. +These names are then resolved to IP addresses. + +1. Usage + +This feature is enabled at compilation with the switch "AFS_AFSDB_ENV", +as with the Unix clients. It is activated by default, and can be disabled +at runtime by running afsd.exe with the -noafsdb flag for the Win9x client, +or by setting the following registry entry on the NT/2000 client: + +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters\UseDNS=0 + +The Windows AFS clients use a configuration file named afsdns.ini (stored in +the same directory as the cell server database) to determine the address +of the DNS server. This file has the following format: + +[AFS Domain Name Servers] +ns1=xx.xx.xx.xx + +Only one name server is actually used currently. Support for multiple +name servers should be easy to add. + + +2. Design + +Because of the lack of standard resolver libraries on the Win32 and DJGPP +platforms, it was decided to perform DNS queries by manually creating +packets to send to the DNS server. The DNS response is then decoded to +determine the correct cell server addresses. + +New files: + +WINNT/afsd/cm_dns.c +WINNT/afsd/cm_dns.h +WINNT/afsd/cm_dns_private.h + +Changed files: + +WINNT/afsd/cm_config.c +WINNT/afsd/cm_cell.c +WINNT/afsd/cm_ioctl.c +WINNT/afsd/afsd_init.c +WINNT/afsd/afsd_init95.c +auth/cellconfig.c +kauth/user_nt.c + + +3. Future work + +Support for multiple DNS servers +Support for resolver libraries, if available for DJGPP and/or Win32 + + +Freelance AFS Client +-------------------- + +1 Introduction + +The current implementation of AFS requires that all AFS clients belong to +a home cell. The home cell provides the client with a starting point to +mount the entire AFS file system. The client's top most level view of AFS +is determined by the home cell server's root.afs volume. Through root.afs, +the home cell also controls which cells clients can access. + +To provide a more flexible and relevant view of the AFS file system to the +user, this projects aims to remove the need for a home cell and to allow +each client to customize its view of the AFS file system. To this end, +the current Windows 2000 and 9x clients for AFS have been modified into +a Freelance AFS Client that allows the user to mount and dismount AFS +cells at will, without the need of a home cell. + +The new Freelance AFS Client also increases the scalability of the AFS file +system since administrator intervention is no longer required for clients +to access newly established cells. It also removes the client dependency on +the availability of the home cell. Previously, if the home cell were not +available, clients would not be able to access the AFS file system. This +critical dependency is not present in the Freelance AFS Client. + +2 Usage + +The Freelance feature is available only for the Windows NT/2000 and 9x +clients. In 9x, it can be enabled by running afsd.exe manually with the +"-freelance" flag. It can be enabled in NT/2000 by setting the following +registry key: + +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters\FreelanceClient=1 + +(GUI support to activate this feature will be available soon.) + +The Freelance client reads the available mount points from a file called +afs_freelance.ini. This file will be created if not found and the list +of mount points will initially be empty. New mount points can be added +using "fs mkmount" or the Explorer shell extension. + +Specification of a home cell is unnecessary with the Freelance client +itself, but is still needed by programs such as klog and pts to provide +a default cell argument. + +3 Design + +This section describes the design approach and provides a high-level +description of the project. + +3.1 Design Approach + +The main aim of the project was to shift the client's view of the AFS file +system, root.afs, from the home cell onto the client, and thus eliminate the +need for a home cell. This had to be done while maintaining compatibility +with the existing system, so changes to the client were kept to a minimum. + +My primary approach has been to trick the current system into thinking +that there is still a home cell by while feeding it fake information that +is generated from a locally stored root.afs directory whenever root.afs of +the home cell is requested. This is accomplished by intercepting function +calls that fetch data from root.afs on the home cell. + +3.2 Afs_freelance.ini + +The local version of root.afs is represented by a file named +afs_freelance.ini, typically stored in the same directory as the cell +database. The first line of this file is an integer that specifies the +number of mount points there are in this file. The rest of the file is a +list of entries, one on each line, in the form xxx#yyy:zzz, where xxx is the +name of the mount point, yyy is the cell name and zzz is the volume name. + +3.3 Directory File Structure + +Using the data in afs_freelance.ini, a fake directory is created in memory that +is identical to what an AFS directory containing those mount points. This +fake directory is then fed to the client when necessary. The structure +of the directory is as follows: + +1. Each directory is made up of pages, each of a fixed size. +2. Each page is divided into 32 byte chunks, which are indivisible units. +3. The first 13 chunks of the first page, called the directory header page, +are used for header information. +4. The first chunk of all other pages, are also used for header information. +5. Chunks other than those reserved for header information can be used +to store mount points. Mount points are stored in a struct defined as such: + +typedef struct cm_localMountPoint { + char* namep; + char* mountPointStringp; + struct cm_localMountPoint* next; +} cm_localMountPoint_t; + + +3.4 Adding/removing mounts + +The fs commands "mkmount" and "rmmount" can be used to add/remove mount +points from the afs_freelance.ini file. These functions can also be +accessed from the Explorer shell extension. + +4 Implementation + +4.1 Files Changed/Added + +Most of the changes have been made in 5 files: + +afsd_init.c +cm_callback.c +cm_dcache.c +cm_scache.c +cm_vnodeops.c + +Afsd_init.c was changed to include initialization code for the fake +directory and local mount points. Cm_callback.c was changed to handle +callbacks to /afs differently, since it is now local. Cm_dcache was +changed to feed fake information into buffers when the /afs directory is +read. Cm_scache.c was changed to provide fake scp information for the +mount points found under /afs. Finally, cm_vnodeops.c was modified to +make the function trybulkproc skip the fake directory entries. + +In addition, the following files were added: + + cm_freelance.h + cm_freelance.c + +Cm_freelance.h and cm_freelance.c were added to provide functions that +create and handle the fake directory and fake mount points. + + +4.2 Functions Modified + +Below is a list of the functions that have been modified. The list is +not exhaustive but includes most of the major changes. + +4.2.1 afsd_InitCM + +Several lines of code were added to this function to call the initialization +functions for the fake directory and fake mount points. + +4.2.2 cm_HaveCallback + +This function is called to check if files have changed. The /afs directory +and mount points on /afs need to handled differently by this function. In +particular, whenever this function is called on mount points on /afs, +the function needs to always return true. This is because local mount +points are only added or removed, never modified. + +4.2.3 cm_GetCallBack + +Because of the same reasons as in 4.2.2, this function needs to handle +/afs differently. This function should never be called on the local mount +points since the cm_HaveCallBack function always returns true on local +mount points. When this function is called on /afs, we need to load the +status information of /afs if it is the first time that /afs is accessed +since initialization of the fake directory. Otherwise, we simply return. + +4.2.4 cm_GetBuffer + +This function is used to fetch actual data from a file into memory +buffers. When this function is called on /afs, we need to fill the memory +buffers with data from the fake directory created in memory, rather than +by calling server functions. + +4.2.5 cm_GetSCache + +This function is used to fetch meta data about files. When it is called +on /afs, we return a hardcoded scache structure. When it is called on +the mount points on /afs, we return fake scache data based on the mount +points in afs_freelance.ini + +4.2.6 cm_SyncOp + +This function was modified to skip cm_HaveCallback and cm_GetCallback +calls on the mount points on /afs. + +4.2.6 cm_MergeStatus + +This function was modified to provide fake status data on /afs. + +4.2.7 cm_TryBulkProc + +This function was modified to skip operations on fake mount points. + + +4.3 New Functions + +4.3.1 cm_InitFakeRootDir + +This function uses the array cm_localMountPoints and creates in memory +an image of a fake directory. This directory is then used to fill buffers +when read requests of /afs are made. + +4.3.2 cm_getNoLocalMountPoints + +This function returns the number of mount points on /afs, based on +afs_freelance.ini. + +4.3.3 cm_InitLocalMountPoints + +This function reads afs_freelance.ini and creates an array of fake mount points +based on its contents. The array is then used by cm_InitFakeRootDir to +create a fake directory in memory. + +4.3.4 reInitLocalMountPoints + +This function clears all the fake information in memory and reconstructs +them from afs_freelance.ini. + + +5 Current Status + +This feature is still experimental. Please post problem reports to +the openafs-devel mailing list. + +5.1 Future Work + +GUI support for activation of the Freelance feature will be available soon. +An auto-mount function could be added. This would work by intercepting +the cm_lookup call so that when a cell is not found in /afs, it would be +automatically added. +Support for Unix clients.