doc/txt/winnotes/afs-integration.txt

   1 How to determine if OpenAFS is installed?
   2
   3 When the OpenAFS Client Service is installed there will be several
   4 registry keys created:
   5
   6   HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon
   7      "ImagePath" = "path to afsd_service.exe"
   8
   9   HKLM\SOFTWARE\TransarcCorporation\AFS Client\CurrentVersion
  10      "PathName" = "the path to the client installation directory"
  11      "MajorVersion"
  12      "MinorVersion"
  13      "VersionString"
  14
  15 BOOL IsAFSServerInstalled (void)
  16 {
  17    BOOL fInstalled = FALSE;
  18    TCHAR szKey[] = TEXT("HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon");
  19    LPCTSTR pch = lstrchr (szKey, TEXT('\\'));
  20    HKEY hk;
  21
  22    if (RegOpenKey (HKEY_LOCAL_MACHINE, &pch[1], &hk) == 0)
  23    {
  24       fInstalled = TRUE;
  25       RegCloseKey (hk);
  26    }
  27
  28    return fInstalled;
  29 }
  30
  31 How to determine if OpenAFS is active?
  32
  33 The AFS Client Service is normally started automatically at system boot.
  34 The state of the service may be queried by asking the Windows Service
  35 Manager.
  36
  37 BOOL IsAFSServiceRunning (void)
  38 {
  39     SERVICE_STATUS Status;
  40     memset (&Status, 0x00, sizeof(Status));
  41     Status.dwCurrentState = SERVICE_STOPPED;
  42
  43     SC_HANDLE hManager;
  44     if ((hManager = OpenSCManager (NULL, NULL, GENERIC_READ)) != NULL)
  45     {
  46         SC_HANDLE hService;
  47         if ((hService = OpenService (hManager, TEXT("TransarcAFSDaemon"), GENERIC_READ)) != NULL)
  48         {
  49             QueryServiceStatus (hService, &Status);
  50             CloseServiceHandle (hService);
  51         }
  52         CloseServiceHandle (hManager);
  53     }
  54     return (Status.dwCurrentState == SERVICE_RUNNING);
  55 }
  56
  57 How to determine the AFS UNC Service Name?
  58
  59 The local UNC service name registered by the OpenAFS Client Service SMB/CIFS
  60 Server depends on whether or not a Microsoft Loopback Adapter has been
  61 installed and the contents of a registry value.  The loopback adapter is
  62 important because if the service cannot bind itself to a loopback adapter
  63 then the registered SMB/CIFS service name must be unique to the WINS name
  64 space.  When the loopback adapter is installed, a globally common name such
  65 as "AFS" can be used.
  66
  67 If the loopback adapter is installed the UNC server name will be the value at:
  68
  69   HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters
  70     REG_SZ/REG_EXPAND_SZ  "NetbiosName"
  71
  72 If this value is not present, the default is "AFS".
  73
  74 When the loopback adapter is not installed the UNC name will be:
  75
  76   %COMPUTERNAME%-%NetbiosName%
  77
  78 if the Computer Name is "MYHOST" and the Netbios Name is "AFS" then
  79 the UNC server name will be:
  80
  81   MYHOST-AFS
  82
  83 At the moment there is no readily available code exported by a library to
  84 determine if the loopback adapter is installed or not.  What I will do if
  85 someone requests it is add a new AFS pioctl operation which will return
  86 the in use UNC Server Name.
  87
  88
  89 How to determine the AFS unix mount point path?
  90
  91 On Unix systems the local mount point of the AFS file system is usually "/afs".
  92 Some organizations have their own custom local mount point locations.  To
  93 determine what the locally configured unix mount point is for interpretting
  94 Unix style paths there is a registry value:
  95
  96   HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters
  97     REG_SZ "MountRoot"
  98
  99 If this value does not exist the default value is "/afs".
 100
 101 What are AFS pioctl() operations and how do I call them?
 102
 103 AFS pioctl() operations are IPCs which can be used to communicate with the
 104 AFS Client Service for the purposes of querying or changing the state of
 105 the service.
 106
 107 The pioctl() function has a prototype of:
 108
 109 struct ViceIoctl {
 110     long in_size;
 111     long out_size;
 112     void *in;
 113     void *out;
 114 };
 115
 116 long pioctl(char *pathp, long opcode, struct ViceIoctl *blobp, int follow);
 117
 118 and can be loaded from the library "afsauthent.dll" at runtime.  The default
 119 calling convention is used.
 120
 121
 122 How to test to see if a PATH is within AFS?
 123
 124 Given an arbitrary file path, you can test to see if the path is in the AFS
 125 file system with the following function.  It asks the AFS Client Service to
 126 return the name of the cell in which the path exists.  If the cell name cannot
 127 be found, the path is not in the AFS file space.
 128
 129 BOOL IsPathInAFS(const CHAR *strPath)
 130 {
 131     struct ViceIoctl blob;
 132     char cellname[256];
 133     int code;
 134
 135     blob.in_size = 0;
 136     blob.out_size = sizeof(cellname);
 137     blob.out = cellname;
 138
 139     code = pioctl((LPTSTR)((LPCTSTR)strPath), VIOC_FILE_CELL_NAME, &blob, 1);
 140     if (code)
 141         return FALSE;
 142     return TRUE;
 143 }
 144
 145
 146 What are AFS cells, volumes and mount points?
 147
 148 The AFS file system consists of a series of administrative domains called
 149 "cells" each of which contain two or more volumes.  A volume is a file system
 150 unit which contains files, directories, mount points, symlinks and hard
 151 links.
 152
 153 Each cell has a minimum of two volumes.  When an AFS client connects to a
 154 cell it mounts the cell's "root.afs" volume at the local afs mount point path.
 155 Each "root.afs" volume contains one or more mount points which allow the
 156 AFS client to other volumes in both in the current cell as well as other
 157 cells.  There are two types of mount points: read-only and read-write.
 158 By following a read-only mount point the client can obtain data from any
 159 of the equivalent read-only volume replicas.  By following a read-write mount
 160 point the client is restricted to the one and only read-write copy of the
 161 volume.  Periodically replicated volumes have their read-write copy "released"
 162 which results in a synchronization with the read-only copies.
 163
 164 By convention the first volume of every cell to contain real data is called
 165 "root.cell".  The name of the read-only mount point which joins the "root.afs"
 166 volume to the "root.cell" volume is the name of the cell.  The name of the
 167 read-write mount point is the name of the cell prefaced by a dot.  For
 168 example, the "athena.mit.edu" cell's "root.afs" volume will contain mount points
 169 such as
 170
 171         "athena.mit.edu"  -> "#athena.mit.edu:root.cell"
 172         ".athena.mit.edu" -> "%athena.mit.edu:root.cell"
 173
 174 The '#' indicates a read-only mount point and the '%' indicates a read-write
 175 mount point.  The mount points are not limited to the local cell so additional
 176 mount points might be included such as:
 177
 178         "andrew.cmu.edu" -> "#andrew.cmu.edu:root.cell"
 179         "sipb.mit.edu"   -> "#sipb.mit.edu:root.cell"
 180
 181 The mount points appear as directory entries to the operating system.
 182
 183 Volumes can also store files, hard links to files, and symlinks to files.
 184
 185 On Windows, hardlinks can be created and destroyed using the CreateHardLink()
 186 and DeleteFile() Win32 APIs.
 187
 188 Creating, Listing and Destroying symlinks and mount points is performed by
 189 the user via the OpenAFS provided command line tools: fs.exe and symlink.exe.
 190
 191   symlink make <name> <to>
 192   symlink list <name>
 193   symlink rm <name>
 194
 195   fs mkmount <dir> <vol> [<cell>] [-rw]
 196   fs lsmount <dir>+
 197   fs rmmount <dir>+
 198
 199 These operations are performed via pioctl calls.
 200