windows-notes-20050509
[openafs.git] / 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