Commit | Line | Data |
---|---|---|
805e021f CE |
1 | /*! |
2 | ||
3 | \page title AFS-3 Programmer's Reference: File Server/Cache Manager | |
4 | Interface | |
5 | ||
6 | \author Edward R. Zayas | |
7 | Transarc Corporation | |
8 | \version 1.1 | |
9 | \date 20 Aug 1991 9:38 Copyright 1991 Transarc Corporation All Rights Reserved | |
10 | FS-00-D162 | |
11 | ||
12 | \page chap1 Chapter 1: Overview | |
13 | ||
14 | \section sec1-1 Section 1.1: Introduction | |
15 | ||
16 | \subsection sec1-1-1 Section 1.1.1: The AFS 3.1 Distributed File System | |
17 | ||
18 | \par | |
19 | AFS 3.1 is a distributed file system (DFS) designed to meet the following set | |
20 | of requirements: | |
21 | \li Server-client model: Permanent file storage for AFS is maintained by a | |
22 | collection of file server machines. This centralized storage is accessed by | |
23 | individuals running on client machines, which also serve as the computational | |
24 | engines for those users. A single machine may act as both an AFS file server | |
25 | and client simultaneously. However, file server machines are generally assumed | |
26 | to be housed in a secure environment, behind locked doors. | |
27 | \li Scale: Unlike other existing DFSs, AFS was designed with the specific goal | |
28 | of supporting a very large user community. Unlike the rule-of-thumb ratio of 20 | |
29 | client machines for every server machine (20:1) used by Sun Microsystem's NFS | |
30 | distributed file system [4][5], the AFS architecture aims at smoothly | |
31 | supporting client/server ratios more along the lines of 200:1 within a single | |
32 | installation. | |
33 | \par | |
34 | AFS also provides another, higher-level notion of scalability. Not only can | |
35 | each independently-administered AFS site, or cell, grow very large (on the | |
36 | order of tens of thousands of client machines), but individual cells may easily | |
37 | collaborate to form a single, unified file space composed of the union of the | |
38 | individual name spaces. Thus, users have the image of a single unix file system | |
39 | tree rooted at the /afs directory on their machine. Access to files in this | |
40 | tree is performed with the standard unix commands, editors, and tools, | |
41 | regardless of a file's location. | |
42 | \par | |
43 | These cells and the files they export may be geographically dispersed, thus | |
44 | requiring client machines to access remote file servers across network pathways | |
45 | varying widely in speed, latency, and reliability. The AFS architecture | |
46 | encourages this concept of a single, wide-area file system. As of this writing, | |
47 | the community AFS filespace includes sites spanning the continental United | |
48 | States and Hawaii, and also reaches overseas to various installations in | |
49 | Europe, Japan, and Australia. | |
50 | \li Performance: This is a critical consideration given the scalability and | |
51 | connectivity requirements described above. A high-performance system in the | |
52 | face of high client/server ratios and the existence of low-bandwidth, | |
53 | high-latency network connections as well as the normal high-speed ones is | |
54 | achieved by two major mechanisms: | |
55 | \li Caching: Client machines make extensive use of caching techniques wherever | |
56 | possible. One important application of this methodology is that each client is | |
57 | required to maintain a cache of files it has accessed from AFS file servers, | |
58 | performing its operations exclusively on these local copies. This file cache is | |
59 | organized in a least-recently-used (LRU) fashion. Thus, each machine will build | |
60 | a local working set of objects being referenced by its users. As long as the | |
61 | cached images remain 'current' (i.e., compatible with the central version | |
62 | stored at the file servers), operations may be performed on these files without | |
63 | further communication with the central servers. This results in significant | |
64 | reductions in network traffic and server loads, paving the way for the target | |
65 | client/server ratios. | |
66 | \par | |
67 | This file cache is typically located on the client's local hard disk, although | |
68 | a strictly in-memory cache is also supported. The disk cache has the advantage | |
69 | that its contents will survive crashes and reboots, with the expectation that | |
70 | the majority of cached objects will remain current. The local cache parameters, | |
71 | including the maximum number of blocks it may occupy on the local disk, may be | |
72 | changed on the fly. In order to avoid having the size of the client file cache | |
73 | become a limit on the length of an AFS file, caching is actually performed on | |
74 | chunks of the file. These chunks are typically 64 Kbytes in length, although | |
75 | the chunk size used by the client is settable when the client starts up. | |
76 | \li Callbacks: The use of caches by the file system, as described above, raises | |
77 | the thorny issue of cache consistency. Each client must efficiently determine | |
78 | whether its cached file chunks are identical to the corresponding sections of | |
79 | the file as stored at the server machine before allowing a user to operate on | |
80 | those chunks. AFS employs the notion of a callback as the backbone of its cache | |
81 | consistency algorithm. When a server machine delivers one or more chunks of a | |
82 | file to a client, it also includes a callback 'promise' that the client will be | |
83 | notified if any modifications are made to the data in the file. Thus, as long | |
84 | as the client machine is in possession of a callback for a file, it knows it is | |
85 | correctly synchronized with the centrally-stored version, and allows its users | |
86 | to operate on it as desired without any further interaction with the server. | |
87 | Before a file server stores a more recent version of a file on its own disks, | |
88 | it will first break all outstanding callbacks on this item. A callback will | |
89 | eventually time out, even if there are no changes to the file or directory it | |
90 | covers. | |
91 | \li Location transparency: The typical AFS user does not know which server or | |
92 | servers houses any of his or her files. In fact, the user's storage may be | |
93 | distributed among several servers. This location transparency also allows user | |
94 | data to be migrated between servers without users having to take corrective | |
95 | actions, or even becoming aware of the shift. | |
96 | \li Reliability: The crash of a server machine in any distributed file system | |
97 | will cause the information it hosts to become unavailable to the user | |
98 | community. The same effect is caused when server and client machines are | |
99 | isolated across a network partition. AFS addresses this situation by allowing | |
100 | data to be replicated across two or more servers in a read-only fashion. If the | |
101 | client machine loses contact with a particular server from which it is | |
102 | attempting to fetch data, it hunts among the remaining machines hosting | |
103 | replicas, looking for one that is still in operation. This search is performed | |
104 | without the user's knowledge or intervention, smoothly masking outages whenever | |
105 | possible. Each client machine will automatically perform periodic probes of | |
106 | machines on its list of known servers, updating its internal records concerning | |
107 | their status. Consequently, server machines may enter and exit the pool without | |
108 | administrator intervention. | |
109 | \par | |
110 | Replication also applies to the various databases employed by the AFS server | |
111 | processes. These system databases are read/write replicated with a single | |
112 | synchronization site at any instant. If a synchronization site is lost due to | |
113 | failure, the remaining database sites elect a new synchronization site | |
114 | automatically without operator intervention. | |
115 | \li Security: A production file system, especially one which allows and | |
116 | encourages transparent access between administrative domains, must be conscious | |
117 | of security issues. AFS considers the server machines as 'trusted', being kept | |
118 | behind locked doors and only directly manipulated by administrators. On the | |
119 | other hand, client machines are, by definition, assumed to exist in inherently | |
120 | insecure environments. These client machines are recognized to be fully | |
121 | accessible to their users, making AFS servers open to attacks mounted by | |
122 | possibly modified hardware, operating systems, and software from its clients. | |
123 | \li To provide credible file system security, AFS employs an authentication | |
124 | system based on the Kerberos facility developed by Project Athena at MIT | |
125 | [6][7]. Users operating from client machines are required to interact with | |
126 | Authentication Server agents running on the secure server machines to generate | |
127 | secure tokens of identity. These tokens express the user's identity in an | |
128 | encrypted fashion, and are stored in the kernel of the client machine. When the | |
129 | user attempts to fetch or store files, the server may challenge the user to | |
130 | verify his or her identity. This challenge, hidden from the user and handled | |
131 | entirely by the RPC layer, will transmit this token to the file server involved | |
132 | in the operation. The server machine, upon decoding the token and thus | |
133 | discovering the user's true identity, will allow the caller to perform the | |
134 | operation if permitted. Access control: The standard unix access control | |
135 | mechanism associates mode bits with every file and directory, applying them | |
136 | based on the user's numerical identifier and the user's membership in various | |
137 | groups. AFS has augmented this traditional access control mechanism with Access | |
138 | Control Lists (ACLs). Every AFS directory has an associated ACL which defines | |
139 | the principals or parties that may operate on all files contained in the | |
140 | directory, and which operations these principals may perform. Rights granted by | |
141 | these ACLs include read, write, delete, lookup, insert (create new files, but | |
142 | don't overwrite old files), and administer (change the ACL). Principals on | |
143 | these ACLs include individual users and groups of users. These groups may be | |
144 | defined by AFS users without administrative intervention. AFS ACLs provide for | |
145 | much finer-grained access control for its files. | |
146 | \li Administrability: Any system with the scaling goals of AFS must pay close | |
147 | attention to its ease of administration. The task of running an AFS | |
148 | installation is facilitated via the following mechanisms: | |
149 | \li Pervasive RPC interfaces: Access to AFS server agents is performed mostly | |
150 | via RPC interfaces. Thus, servers may be queried and operated upon regardless | |
151 | of their location. In combination with the security system outlined above, even | |
152 | administrative functions such as instigating backups, reconfiguring server | |
153 | machines, and stopping and restarting servers may be performed by an | |
154 | administrator sitting in front of any AFS-capable machine, as long as the | |
155 | administrator holds the proper tokens. | |
156 | \li Replication: As AFS supports read-only replication for user data and | |
157 | read-write replication for system databases, much of the system reconfiguration | |
158 | work in light of failures is performed transparently and without human | |
159 | intervention. Administrators thus typically have more time to respond to many | |
160 | common failure situations. | |
161 | \li Data mobility: Improved and balanced utilization of disk resources is | |
162 | facilitated by the fact that AFS supports transparent relocation of user data | |
163 | between partitions on a single file server machine or between two different | |
164 | machines. In a situation where a machine must be brought down for an extended | |
165 | period, all its storage may be migrated to other servers so that users may | |
166 | continue their work completely unaffected. | |
167 | \li Automated 'nanny' services: Each file server machine runs a BOS Server | |
168 | process, which assists in the machine's administration. This server is | |
169 | responsible for monitoring the health of the AFS agents under its care, | |
170 | bringing them up in the proper order after a system reboot, answering requests | |
171 | as to their status and restarting them when they fail. It also accepts commands | |
172 | to start, suspend, or resume these processes, and install new server binaries. | |
173 | Accessible via an RPC interface, this supervisory process relieves | |
174 | administrators of some oversight responsibilities and also allows them to | |
175 | perform their duties from any machine running AFS, regardless of location or | |
176 | geographic distance from the targeted file server machine. | |
177 | \li On-line backup: Backups may be performed on the data stored by the AFS file | |
178 | server machines without bringing those machines down for the duration. | |
179 | Copy-on-write 'snapshots' are taken of the data to be preserved, and tape | |
180 | backup is performed from these clones. One added benefit is that these backup | |
181 | clones are on-line and accessible by users. Thus, if someone accidentally | |
182 | deletes a file that is contained in their last snapshot, they may simply copy | |
183 | its contents as of the time the snapshot was taken back into their active | |
184 | workspace. This facility also serves to improve the administrability of the | |
185 | system, greatly reducing the number of requests to restore data from tape. | |
186 | \li On-line help: The set of provided program tools used to interact with the | |
187 | active AFS agents are self-documenting in that they will accept command-line | |
188 | requests for help, displaying descriptive text in response. | |
189 | \li Statistics: Each AFS agent facilitates collection of statistical data on | |
190 | its performance, configuration, and status via its RPC interface. Thus, the | |
191 | system is easy to monitor. One tool that takes advantage of this facility is | |
192 | the scout program. Scout polls file server machines periodically, displaying | |
193 | usage statistics, current disk capacities, and whether the server is | |
194 | unavailable. Administrators monitoring this information can thus quickly react | |
195 | to correct overcrowded disks and machine crashes. | |
196 | \li Coexistence: Many organizations currently employ other distributed file | |
197 | systems, most notably NFS. AFS was designed to run simultaneously with other | |
198 | DFSs without interfering in their operation. In fact, an NFS-AFS translator | |
199 | agent exists that allows pure-NFS client machines to transparently access files | |
200 | in the AFS community. | |
201 | \li Portability: Because AFS is implemented using the standard VFS and vnode | |
202 | interfaces pioneered and advanced by Sun Microsystems, AFS is easily portable | |
203 | between different platforms from a single vendor or from different vendors. | |
204 | ||
205 | \subsection sec1-1-2 Section 1.1.2: Scope of this Document | |
206 | ||
207 | \par | |
208 | This document is a member of a documentation suite providing specifications of | |
209 | the operations and interfaces offered by the various AFS servers and agents. | |
210 | Specifically, this document will focus on two of these system agents: | |
211 | \li File Server: This AFS entity is responsible for providing a central disk | |
212 | repository for a particular set of files and for making these files accessible | |
213 | to properly-authorized users running on client machines. The File Server is | |
214 | implemented as a user-space process | |
215 | \li Cache Manager: This code, running within the kernel of an AFS client | |
216 | machine, is a user's representative in communicating with the File Servers, | |
217 | fetching files back and forth into the local cache as needed. The Cache Manager | |
218 | also keeps information as to the composition of its own cell as well as the | |
219 | other AFS cells in existence. It resolves file references and operations, | |
220 | determining the proper File Server (or group of File Servers) that may satisfy | |
221 | the request. In addition, it is also a reliable repository for the user's | |
222 | authentication information, holding on to their tokens and wielding them as | |
223 | necessary when challenged. | |
224 | ||
225 | \subsection sec1-1-3 Section 1.1.3: Related Documents | |
226 | ||
227 | \par | |
228 | The full AFS specification suite of documents is listed below: | |
229 | \li AFS-3 Programmer's Reference: Architectural Overview: This paper provides | |
230 | an architectual overview of the AFS distributed file system, describing the | |
231 | full set of servers and agents in a coherent way, illustrating their | |
232 | relationships to each other and examining their interactions. | |
233 | \li AFS-3 Programmer's Reference:Volume Server/Volume Location Server | |
234 | Interface: This document describes the services through which 'containers' of | |
235 | related user data are located and managed. | |
236 | \li AFS-3 Programmer's Reference: Protection Server Interface: This paper | |
237 | describes the server responsible for providing two-way mappings between | |
238 | printable usernames and their internal AFS identifiers. The Protection Server | |
239 | also allows users to create, destroy, and manipulate 'groups' of users, which | |
240 | are suitable for placement on ACLs. AFS-3 Programmer's Reference: BOS Server | |
241 | Interface: This paper explicates the 'nanny' service described above, which | |
242 | assists in the administrability of the AFS environment. | |
243 | \li AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure | |
244 | Call Facility: This document specifies the design and operation of the remote | |
245 | procedure call and lightweight process packages used by AFS. | |
246 | \par | |
247 | In addition to these papers, the AFS 3.1 product is delivered with its own | |
248 | user, administrator, installation, and command reference documents. | |
249 | ||
250 | \section sec1-2 Section 1.2: Basic Concepts | |
251 | ||
252 | \par | |
253 | To properly understand AFS operation, specifically the tasks and objectives of | |
254 | the File Server and Cache Manager, it is necessary to introduce and explain the | |
255 | following concepts: | |
256 | \li Cell: A cell is the set of server and client machines operated by an | |
257 | administratively independent organization. The cell administrators make | |
258 | decisions concerning such issues as server deployment and configuration, user | |
259 | backup schedules, and replication strategies on their own hardware and disk | |
260 | storage completely independently from those implemented by other cell | |
261 | administrators regarding their own domains. Every client machine belongs to | |
262 | exactly one cell, and uses that information to determine the set of database | |
263 | servers it uses to locate system resources and generate authentication | |
264 | information. | |
265 | \li Volume: AFS disk partitions do not directly host individual user files or | |
266 | directories. Rather, connected subtrees of the system's directory structure are | |
267 | placed into containers called volumes. Volumes vary in size dynamically as | |
268 | objects are inserted, overwritten, and deleted. Each volume has an associated | |
269 | quota, or maximum permissible storage. A single unix disk partition may host | |
270 | one or more volumes, and in fact may host as many volumes as physically fit in | |
271 | the storage space. However, a practical maximum is 3,500 volumes per disk | |
272 | partition, since this is the highest number currently handled by the salvager | |
273 | program. The salvager is run on occasions where the volume structures on disk | |
274 | are inconsistent, repairing the damage. A compile-time constant within the | |
275 | salvager imposes the above limit, causing it to refuse to repair any | |
276 | inconsistent partition with more than 3,500 volumes. Volumes serve many | |
277 | purposes within AFS. First, they reduce the number of objects with which an | |
278 | administrator must be concerned, since operations are normally performed on an | |
279 | entire volume at once (and thus on all files and directories contained within | |
280 | the volume). In addition, volumes are the unit of replication, data mobility | |
281 | between servers, and backup. Disk utilization may be balanced by transparently | |
282 | moving volumes between partitions. | |
283 | \li Mount Point: The connected subtrees contained within individual volumes | |
284 | stored at AFS file server machines are 'glued' to their proper places in the | |
285 | file space defined by a site, forming a single, apparently seamless unix tree. | |
286 | These attachment points are referred to as mount points. Mount points are | |
287 | persistent objects, implemented as symbolic links whose contents obey a | |
288 | stylized format. Thus, AFS mount points differ from NFS-style mounts. In the | |
289 | NFS environment, the user dynamically mounts entire remote disk partitions | |
290 | using any desired name. These mounts do not survive client restarts, and do not | |
291 | insure a uniform namespace between different machines. | |
292 | \par | |
293 | As a Cache Manager resolves an AFS pathname as part of a file system operation | |
294 | initiated by a user process, it recognizes mount points and takes special | |
295 | action to resolve them. The Cache Manager consults the appropriate Volume | |
296 | Location Server to discover the File Server (or set of File Servers) hosting | |
297 | the indicated volume. This location information is cached, and the Cache | |
298 | Manager then proceeds to contact the listed File Server(s) in turn until one is | |
299 | found that responds with the contents of the volume's root directory. Once | |
300 | mapped to a real file system object, the pathname resolution proceeds to the | |
301 | next component. | |
302 | \li Database Server: A set of AFS databases is required for the proper | |
303 | functioning of the system. Each database may be replicated across two or more | |
304 | file server machines. Access to these databases is mediated by a database | |
305 | server process running at each replication site. One site is declared to be the | |
306 | synchronization site, the sole location accepting requests to modify the | |
307 | databases. All other sites are read-only with respect to the set of AFS users. | |
308 | When the synchronization site receives an update to its database, it | |
309 | immediately distributes it to the other sites. Should a synchronization site go | |
310 | down through either a hard failure or a network partition, the remaining sites | |
311 | will automatically elect a new synchronization site if they form a quorum, or | |
312 | majority. This insures that multiple synchronization sites do not become active | |
313 | in the network partition scenario. | |
314 | \par | |
315 | The classes of AFS database servers are listed below: | |
316 | \li Authentication Server: This server maintains the authentication database | |
317 | used to generate tokens of identity. | |
318 | \li Protection Server: This server maintains mappings between human-readable | |
319 | user account names and their internal numerical AFS identifiers. It also | |
320 | manages the creation, manipulation, and update of user-defined groups suitable | |
321 | for use on ACLs. | |
322 | \li Volume Location Server: This server exports information concerning the | |
323 | location of the individual volumes housed within the cell. | |
324 | ||
325 | \section sec1-3 Section 1.3: Document Layout | |
326 | ||
327 | \par | |
328 | Following this introduction and overview, Chapter 2 describes the architecture | |
329 | of the File Server process design. Similarly, Chapter 3 describes the | |
330 | architecture of the in-kernel Cache Manager agent. Following these | |
331 | architectural examinations, Chapter 4 provides a set of basic coding | |
332 | definitions common to both the AFS File Server and Cache Manager, required to | |
333 | properly understand the interface specifications which follow. Chapter 5 then | |
334 | proceeds to specify the various File Server interfaces. The myriad Cache | |
335 | Manager interfaces are presented in Chapter 6, thus completing the document. | |
336 | ||
337 | \page chap2 Chapter 2: File Server Architecture | |
338 | ||
339 | \section sec2-1 Section 2.1: Overview | |
340 | ||
341 | \par | |
342 | The AFS File Server is a user-level process that presides over the raw disk | |
343 | partitions on which it supports one or more volumes. It provides 'half' of the | |
344 | fundamental service of the system, namely exporting and regimenting access to | |
345 | the user data entrusted to it. The Cache Manager provides the other half, | |
346 | acting on behalf of its human users to locate and access the files stored on | |
347 | the file server machines. | |
348 | \par | |
349 | This chapter examines the structure of the File Server process. First, the set | |
350 | of AFS agents with which it must interact are discussed. Next, the threading | |
351 | structure of the server is examined. Some details of its handling of the race | |
352 | conditions created by the callback mechanism are then presented. This is | |
353 | followed by a discussion of the read-only volume synchronization mechanism. | |
354 | This functionality is used in each RPC interface call and intended to detect | |
355 | new releases of read-only volumes. File Servers do not generate callbacks for | |
356 | objects residing in read-only volumes, so this synchronization information is | |
357 | used to implement a 'whole-volume' callback. Finally, the fact that the File | |
358 | Server may drop certain information recorded about the Cache Managers with | |
359 | which it has communicated and yet guarantee correctness of operation is | |
360 | explored. | |
361 | ||
362 | \section sec2-2 Section 2.2: Interactions | |
363 | ||
364 | \par | |
365 | By far the most frequent partner in File Server interactions is the set of | |
366 | Cache Managers actively fetching and storing chunks of data files for which the | |
367 | File Server provides central storage facilities. The File Server also | |
368 | periodically probes the Cache Managers recorded in its tables with which it has | |
369 | recently dealt, determining if they are still active or whether their records | |
370 | might be garbage-collected. | |
371 | \par | |
372 | There are two other server entities with which the File Server interacts, | |
373 | namely the Protection Server and the BOS Server. Given a fetch or store request | |
374 | generated by a Cache Manager, the File Server needs to determine if the caller | |
375 | is authorized to perform the given operation. An important step in this process | |
376 | is to determine what is referred to as the caller's Current Protection | |
377 | Subdomain, or CPS. A user's CPS is a list of principals, beginning with the | |
378 | user's internal identifier, followed by the the numerical identifiers for all | |
379 | groups to which the user belongs. Once this CPS information is determined, the | |
380 | File Server scans the ACL controlling access to the file system object in | |
381 | question. If it finds that the ACL contains an entry specifying a principal | |
382 | with the appropriate rights which also appears in the user's CPS, then the | |
383 | operation is cleared. Otherwise, it is rejected and a protection violation is | |
384 | reported to the Cache Manager for ultimate reflection back to the caller. | |
385 | \par | |
386 | The BOS Server performs administrative operations on the File Server process. | |
387 | Thus, their interactions are quite one-sided, and always initiated by the BOS | |
388 | Server. The BOS Server does not utilize the File Server's RPC interface, but | |
389 | rather generates unix signals to achieve the desired effect. | |
390 | ||
391 | \section sec2-3 Section 2.3: Threading | |
392 | ||
393 | \par | |
394 | The File Server is organized as a multi-threaded server. Its threaded behavior | |
395 | within a single unix process is achieved by use of the LWP lightweight process | |
396 | facility, as described in detail in the companion "AFS-3 Programmer's | |
397 | Reference: Specification for the Rx Remote Procedure Call Facility" document. | |
398 | The various threads utilized by the File Server are described below: | |
399 | \li WorkerLWP: This lightweight process sleeps until a request to execute one | |
400 | of the RPC interface functions arrives. It pulls the relevant information out | |
401 | of the request, including any incoming data delivered as part of the request, | |
402 | and then executes the server stub routine to carry out the operation. The | |
403 | thread finishes its current activation by feeding the return code and any | |
404 | output data back through the RPC channel back to the calling Cache Manager. The | |
405 | File Server initialization sequence specifies that at least three but no more | |
406 | than six of these WorkerLWP threads are to exist at any one time. It is | |
407 | currently not possible to configure the File Server process with a different | |
408 | number of WorkerLWP threads. | |
409 | \li FiveMinuteCheckLWP: This thread runs every five minutes, performing such | |
410 | housekeeping chores as cleaning up timed-out callbacks, setting disk usage | |
411 | statistics, and executing the special handling required by certain AIX | |
412 | implementations. Generally, this thread performs activities that do not take | |
413 | unbounded time to accomplish and do not block the thread. If reassurance is | |
414 | required, FiveMinuteCheckLWP can also be told to print out a banner message to | |
415 | the machine's console every so often, stating that the File Server process is | |
416 | still running. This is not strictly necessary and an artifact from earlier | |
417 | versions, as the File Server's status is now easily accessible at any time | |
418 | through the BOS Server running on its machine. | |
419 | \li HostCheckLWP: This thread, also activated every five minutes, performs | |
420 | periodic checking of the status of Cache Managers that have been previously | |
421 | contacted and thus appear in this File Server's internal tables. It generates | |
422 | RXAFSCB Probe() calls from the Cache Manager interface, and may find itself | |
423 | suspended for an arbitrary amount of time when it enounters unreachable Cache | |
424 | Managers. | |
425 | ||
426 | \section sec2-4 Section 2.4: Callback Race Conditions | |
427 | ||
428 | \par | |
429 | Callbacks serve to implement the efficient AFS cache consistency mechanism, as | |
430 | described in Section 1.1.1. Because of the asynchronous nature of callback | |
431 | generation and the multi-threaded operation and organization of both the File | |
432 | Server and Cache Manager, race conditions can arise in their use. As an | |
433 | example, consider the case of a client machine fetching a chunk of file X. The | |
434 | File Server thread activated to carry out the operation ships the contents of | |
435 | the chunk and the callback information over to the requesting Cache Manager. | |
436 | Before the corresponding Cache Manager thread involved in the exchange can be | |
437 | scheduled, another request arrives at the File Server, this time storing a | |
438 | modified image of the same chunk from file X. Another worker thread comes to | |
439 | life and completes processing of this second request, including execution of an | |
440 | RXAFSCB CallBack() to the Cache Manager who still hasn't picked up on the | |
441 | results of its fetch operation. If the Cache Manager blindly honors the RXAFSCB | |
442 | CallBack() operation first and then proceeds to process the fetch, it will wind | |
443 | up believing it has a callback on X when in reality it is out of sync with the | |
444 | central copy on the File Server. To resolve the above class of callback race | |
445 | condition, the Cache Manager effectively doublechecks the callback information | |
446 | received from File Server calls, making sure they haven't already been | |
447 | nullified by other file system activity. | |
448 | ||
449 | \section sec2-5 Section 2.5: Read-Only Volume Synchronization | |
450 | ||
451 | \par | |
452 | The File Server issues a callback for each file chunk it delivers from a | |
453 | read-write volume, thus allowing Cache Managers to efficiently synchronize | |
454 | their local caches with the authoritative File Server images. However, no | |
455 | callbacks are issued when data from read-only volumes is delivered to clients. | |
456 | Thus, it is possible for a new snapshot of the read-only volume to be | |
457 | propagated to the set of replication sites without Cache Managers becoming | |
458 | aware of the event and marking the appropriate chunks in their caches as stale. | |
459 | Although the Cache Manager refreshes its volume version information | |
460 | periodically (once an hour), there is still a window where a Cache Manager will | |
461 | fail to notice that it has outdated chunks. | |
462 | \par | |
463 | The volume synchronization mechanism was defined to close this window, | |
464 | resulting in what is nearly a 'whole-volume' callback device for read-only | |
465 | volumes. Each File Server RPC interface function handling the transfer of file | |
466 | data is equipped with a parameter (a volSyncP), which carries this volume | |
467 | synchronization information. This parameter is set to a non-zero value by the | |
468 | File Server exclusively when the data being fetched is coming from a read-only | |
469 | volume. Although the struct AFSVolSync defined in Section 5.1.2.2 passed via a | |
470 | volSyncP consists of six longwords, only the first one is set. This leading | |
471 | longword carries the creation date of the read-only volume. The Cache Manager | |
472 | immediately compares the synchronization value stored in its cached volume | |
473 | information against the one just received. If they are identical, then the | |
474 | operation is free to complete, secure in the knowledge that all the information | |
475 | and files held from that volume are still current. A mismatch, though, | |
476 | indicates that every file chunk from this volume is potentially out of date, | |
477 | having come from a previous release of the read-only volume. In this case, the | |
478 | Cache Manager proceeds to mark every chunk from this volume as suspect. The | |
479 | next time the Cache Manager considers accessing any of these chunks, it first | |
480 | checks with the File Server it came from which the chunks were obtained to see | |
481 | if they are up to date. | |
482 | ||
483 | \section sec2-6 Section 2.6: Disposal of Cache Manager Records | |
484 | ||
485 | \par | |
486 | Every File Server, when first starting up, will, by default, allocate enough | |
487 | space to record 20,000 callback promises (see Section 5.3 for how to override | |
488 | this default). Should the File Server fully populate its callback records, it | |
489 | will not allocate more, allowing its memory image to possibly grow in an | |
490 | unbounded fashion. Rather, the File Server chooses to break callbacks until it | |
491 | acquires a free record. All reachable Cache Managers respond by marking their | |
492 | cache entries appropriately, preserving the consistency guarantee. In fact, a | |
493 | File Server may arbitrarily and unilaterally purge itself of all records | |
494 | associated with a particular Cache Manager. Such actions will reduce its | |
495 | performance (forcing these Cache Managers to revalidate items cached from that | |
496 | File Server) without sacrificing correctness. | |
497 | ||
498 | \page chap3 Chapter 3: Cache Manager Architecture | |
499 | ||
500 | \section sec3-1 Section 3.1: Overview | |
501 | ||
502 | \par | |
503 | The AFS Cache Manager is a kernel-resident agent with the following duties and | |
504 | responsibilities: | |
505 | \li Users are to be given the illusion that files stored in the AFS distributed | |
506 | file system are in fact part of the local unix file system of their client | |
507 | machine. There are several areas in which this illusion is not fully realized: | |
508 | \li Semantics: Full unix semantics are not maintained by the set of agents | |
509 | implementing the AFS distributed file system. The largest deviation involves | |
510 | the time when changes made to a file are seen by others who also have the file | |
511 | open. In AFS, modifications made to a cached copy of a file are not necessarily | |
512 | reflected immediately to the central copy (the one hosted by File Server disk | |
513 | storage), and thus to other cache sites. Rather, the changes are only | |
514 | guaranteed to be visible to others who simultaneously have their own cached | |
515 | copies open when the modifying process executes a unix close() operation on the | |
516 | file. | |
517 | \par | |
518 | This differs from the semantics expected from the single-machine, local unix | |
519 | environment, where writes performed on one open file descriptor are immediately | |
520 | visible to all processes reading the file via their own file descriptors. Thus, | |
521 | instead of the standard "last writer wins" behavior, users see "last closer | |
522 | wins" behavior on their AFS files. Incidentally, other DFSs, such as NFS, do | |
523 | not implement full unix semantics in this case either. | |
524 | \li Partial failures: A panic experienced by a local, single-machine unix file | |
525 | system will, by definition, cause all local processes to terminate immediately. | |
526 | On the other hand, any hard or soft failure experienced by a File Server | |
527 | process or the machine upon which it is executing does not cause any of the | |
528 | Cache Managers interacting with it to crash. Rather, the Cache Managers will | |
529 | now have to reflect their failures in getting responses from the affected File | |
530 | Server back up to their callers. Network partitions also induce the same | |
531 | behavior. From the user's point of view, part of the file system tree has | |
532 | become inaccessible. In addition, certain system calls (e.g., open() and | |
533 | read()) may return unexpected failures to their users. Thus, certain coding | |
534 | practices that have become common amongst experienced (single-machine) unix | |
535 | programmers (e.g., not checking error codes from operations that "can't" fail) | |
536 | cause these programs to misbehave in the face of partial failures. | |
537 | \par | |
538 | To support this transparent access paradigm, the Cache Manager proceeds to: | |
539 | \li Intercept all standard unix operations directed towards AFS objects, | |
540 | mapping them to references aimed at the corresponding copies in the local | |
541 | cache. | |
542 | \li Keep a synchronized local cache of AFS files referenced by the client | |
543 | machine's users. If the chunks involved in an operation reading data from an | |
544 | object are either stale or do not exist in the local cache, then they must be | |
545 | fetched from the File Server(s) on which they reside. This may require a query | |
546 | to the volume location service in order to locate the place(s) of residence. | |
547 | Authentication challenges from File Servers needing to verify the caller's | |
548 | identity are handled by the Cache Manager, and the chunk is then incorporated | |
549 | into the cache. | |
550 | \li Upon receipt of a unix close, all dirty chunks belonging to the object will | |
551 | be flushed back to the appropriate File Server. | |
552 | \li Callback deliveries and withdrawals from File Servers must be processed, | |
553 | keeping the local cache in close synchrony with the state of affairs at the | |
554 | central store. | |
555 | \li Interfaces are also be provided for those principals who wish to perform | |
556 | AFS-specific operations, such as Access Control List (ACL) manipulations or | |
557 | changes to the Cache Manager's configuration. | |
558 | \par | |
559 | This chapter takes a tour of the Cache Manager's architecture, and examines how | |
560 | it supports these roles and responsibilities. First, the set of AFS agents with | |
561 | which it must interact are discussed. Next, some of the Cache Manager's | |
562 | implementation and interface choices are examined. Finally, the server's | |
563 | ability to arbitrarily dispose of callback information without affecting the | |
564 | correctness of the cache consistency algorithm is explained. | |
565 | ||
566 | \section sec3-2 Section 3.2: Interactions | |
567 | ||
568 | \par | |
569 | The main AFS agent interacting with a Cache Manager is the File Server. The | |
570 | most common operation performed by the Cache Manager is to act as its users' | |
571 | agent in fetching and storing files to and from the centralized repositories. | |
572 | Related to this activity, a Cache Manager must be prepared to answer queries | |
573 | from a File Server concerning its health. It must also be able to accept | |
574 | callback revocation notices generated by File Servers. Since the Cache Manager | |
575 | not only engages in data transfer but must also determine where the data is | |
576 | located in the first place, it also directs inquiries to Volume Location Server | |
577 | agents. There must also be an interface allowing direct interactions with both | |
578 | common and administrative users. Certain AFS-specific operations must be made | |
579 | available to these parties. In addition, administrative users may desire to | |
580 | dynamically reconfigure the Cache Manager. For example, information about a | |
581 | newly-created cell may be added without restarting the client's machine. | |
582 | ||
583 | \section sec3-3 Section 3.3: Implementation Techniques | |
584 | ||
585 | \par | |
586 | The above roles and behaviors for the Cache Manager influenced the | |
587 | implementation choices and methods used to construct it, along with the desire | |
588 | to maximize portability. This section begins by showing how the VFS/vnode | |
589 | interface, pioneered and standardized by Sun Microsystems, provides not only | |
590 | the necessary fine-grain access to user file system operations, but also | |
591 | facilitates Cache Manager ports to new hardware and operating system platforms. | |
592 | Next, the use of unix system calls is examined. Finally, the threading | |
593 | structure employed is described. | |
594 | ||
595 | \subsection sec3-3-1 Section 3.3.1: VFS Interface | |
596 | ||
597 | \par | |
598 | As mentioned above, Sun Microsystems has introduced and propagated an important | |
599 | concept in the file system world, that of the Virtual File System (VFS) | |
600 | interface. This abstraction defines a core collection of file system functions | |
601 | which cover all operations required for users to manipulate their data. System | |
602 | calls are written in terms of these standardized routines. Also, the associated | |
603 | vnode concept generalizes the original unix inode idea and provides hooks for | |
604 | differing underlying environments. Thus, to port a system to a new hardware | |
605 | platform, the system programmers have only to construct implementations of this | |
606 | base array of functions consistent with the new underlying machine. | |
607 | \par | |
608 | The VFS abstraction also allows multiple file systems (e.g., vanilla unix, DOS, | |
609 | NFS, and AFS) to coexist on the same machine without interference. Thus, to | |
610 | make a machine AFS-capable, a system designer first extends the base vnode | |
611 | structure in well-defined ways in order to store AFS-specific operations with | |
612 | each file description. Then, the base function array is coded so that calls | |
613 | upon the proper AFS agents are made to accomplish each function's standard | |
614 | objectives. In effect, the Cache Manager consists of code that interprets the | |
615 | standard set of unix operations imported through this interface and executes | |
616 | the AFS protocols to carry them out. | |
617 | ||
618 | \subsection sec3-3-2 Section 3.3.2: System Calls | |
619 | ||
620 | \par | |
621 | As mentioned above, many unix system calls are implemented in terms of the base | |
622 | function array of vnode-oriented operations. In addition, one existing system | |
623 | call has been modified and two new system calls have been added to perform | |
624 | AFS-specific operations apart from the Cache Manager's unix 'emulation' | |
625 | activities. The standard ioctl() system call has been augmented to handle | |
626 | AFS-related operations on objects accessed via open unix file descriptors. One | |
627 | of the brand-new system calls is pioctl(), which is much like ioctl() except it | |
628 | names targeted objects by pathname instead of file descriptor. Another is afs | |
629 | call(), which is used to initialize the Cache Manager threads, as described in | |
630 | the section immediately following. | |
631 | ||
632 | \subsection sec3-3-3 Section 3.3.3: Threading | |
633 | ||
634 | \par | |
635 | In order to execute its many roles, the Cache Manager is organized as a | |
636 | multi-threaded entity. It is implemented with (potentially multiple | |
637 | instantiations of) the following three thread classes: | |
638 | \li CallBack Listener: This thread implements the Cache Manager callback RPC | |
639 | interface, as described in Section 6.5. | |
640 | \li Periodic Maintenance: Certain maintenance and checkup activities need to be | |
641 | performed at five set intervals. Currently, the frequency of each of these | |
642 | operations is hard-wired. It would be a simple matter, though, to make these | |
643 | times configurable by adding command-line parameters to the Cache Manager. | |
644 | \li Thirty seconds: Flush pending writes for NFS clients coming in through the | |
645 | NFS-AFS Translator facility. | |
646 | \li One minute: Make sure local cache usage is below the assigned quota, write | |
647 | out dirty buffers holding directory data, and keep flock()s alive. | |
648 | \li Three minutes: Check for the resuscitation of File Servers previously | |
649 | determined to be down, and check the cache of previously computed access | |
650 | information in light of any newly expired tickets. | |
651 | \li Ten minutes: Check health of all File Servers marked as active, and | |
652 | garbage-collect old RPC connections. | |
653 | \li One hour: Check the status of the root AFS volume as well as all cached | |
654 | information concerning read-only volumes. | |
655 | \li Background Operations: The Cache Manager is capable of prefetching file | |
656 | system objects, as well as carrying out delayed stores, occurring sometime | |
657 | after a close() operation. At least two threads are created at Cache Manager | |
658 | initialization time and held in reserve to carry out these objectives. This | |
659 | class of background threads implements the following three operations: | |
660 | \li Prefetch operation: Fetches particular file system object chunks in the | |
661 | expectation that they will soon be needed. | |
662 | \li Path-based prefetch operation: The prefetch daemon mentioned above operates | |
663 | on objects already at least partly resident in the local cache, referenced by | |
664 | their vnode. The path-based prefetch daemon performs the same actions, but on | |
665 | objects named solely by their unix pathname. | |
666 | \li Delayed store operation: Flush all modified chunks from a file system | |
667 | object to the appropriate File Server's disks. | |
668 | ||
669 | \section sec3-4 Section 3.4: Disposal of Cache Manager Records | |
670 | ||
671 | \par | |
672 | The Cache Manager is free to throw away any or all of the callbacks it has | |
673 | received from the set of File Servers from which it has cached files. This | |
674 | housecleaning does not in any way compromise the correctness of the AFS cache | |
675 | consistency algorithm. The File Server RPC interface described in this paper | |
676 | provides a call to allow a Cache Manager to advise of such unilateral | |
677 | jettisoning. However, failure to use this routine still leaves the machine's | |
678 | cache consistent. Let us examine the case of a Cache Manager on machine C | |
679 | disposing of its callback on file X from File Server F. The next user access on | |
680 | file X on machine C will cause the Cache Manager to notice that it does not | |
681 | currently hold a callback on it (although the File Server will think it does). | |
682 | The Cache Manager on C attempts to revalidate its entry when it is entirely | |
683 | possible that the file is still in sync with the central store. In response, | |
684 | the File Server will extend the existing callback information it has and | |
685 | deliver the new promise to the Cache Manager on C. Now consider the case where | |
686 | file X is modified by a party on a machine other than C before such an access | |
687 | occurs on C. Under these circumstances, the File Server will break its callback | |
688 | on file X before performing the central update. The Cache Manager on C will | |
689 | receive one of these "break callback" messages. Since it no longer has a | |
690 | callback on file X, the Cache Manager on C will cheerfully acknowledge the File | |
691 | Server's notification and move on to other matters. In either case, the | |
692 | callback information for both parties will eventually resynchronize. The only | |
693 | potential penalty paid is extra inquiries by the Cache Manager and thus | |
694 | providing for reduced performance instead of failure of operation. | |
695 | ||
696 | \page chap4 Chapter 4: Common Definitions and Data Structures | |
697 | ||
698 | \par | |
699 | This chapter discusses the definitions used in common by the File Server and | |
700 | the Cache Manager. They appear in the common.xg file, used by Rxgen to generate | |
701 | the C code instantiations of these definitions. | |
702 | ||
703 | \section sec4-1 Section 4.1: File-Related Definitions | |
704 | ||
705 | \subsection sec4-1-1 Section 4.1.1: struct AFSFid | |
706 | ||
707 | \par | |
708 | This is the type for file system objects within AFS. | |
709 | \n \n Fields | |
710 | \li unsigned long Volume - This provides the identifier for the volume in which | |
711 | the object resides. | |
712 | \li unsigned long Vnode - This specifies the index within the given volume | |
713 | corresponding to the object. | |
714 | \li unsigned long Unique - This is a 'uniquifier' or generation number for the | |
715 | slot identified by the Vnode field. | |
716 | ||
717 | \section sec4-2 Section 4.2: Callback-related Definitions | |
718 | ||
719 | \subsection sec4-2-1 Section 4.2.1: Types of Callbacks | |
720 | ||
721 | \par | |
722 | There are three types of callbacks defined by AFS-3: | |
723 | ||
724 | \li EXCLUSIVE: This version of callback has not been implemented. Its intent | |
725 | was to allow a single Cache Manager to have exclusive rights on the associated | |
726 | file data. | |
727 | \li SHARED: This callback type indicates that the status information kept by a | |
728 | Cache Manager for the associated file is up to date. All cached chunks from | |
729 | this file whose version numbers match the status information are thus | |
730 | guaranteed to also be up to date. This type of callback is non-exclusive, | |
731 | allowing any number of other Cache Managers to have callbacks on this file and | |
732 | cache chunks from the file. | |
733 | \li DROPPED: This is used to indicate that the given callback promise has been | |
734 | cancelled by the issuing File Server. The Cache Manager is forced to mark the | |
735 | status of its cache entry as unknown, forcing it to stat the file the next time | |
736 | a user attempts to access any chunk from it. | |
737 | ||
738 | \subsection sec4-2-2 Section 4.2.2: struct AFSCallBack | |
739 | ||
740 | \par | |
741 | This is the canonical callback structure passed in many File Server RPC | |
742 | interface calls. | |
743 | \n \b Fields | |
744 | \li unsigned long CallBackVersion - Callback version number. | |
745 | \li unsigned long ExpirationTime - Time when the callback expires, measured in | |
746 | seconds. | |
747 | \li unsigned long CallBackType - The type of callback involved, one of | |
748 | EXCLUSIVE, SHARED, or DROPPED. | |
749 | ||
750 | \subsection sec4-2-3 Section 4.2.3: Callback Arrays | |
751 | ||
752 | \par | |
753 | AFS-3 sometimes does callbacks in bulk. Up to AFSCBMAX (50) callbacks can be | |
754 | handled at once. Layouts for the two related structures implementing callback | |
755 | arrays, struct AFSCBFids and struct AFSCBs, follow below. Note that the | |
756 | callback descriptor in slot i of the array in the AFSCBs structure applies to | |
757 | the file identifier contained in slot i in the fid array in the matching | |
758 | AFSCBFids structure. | |
759 | ||
760 | \subsubsection sec4-2-3-1 Section 4.2.3.1: struct AFSCBFids | |
761 | ||
762 | \n \b Fields | |
763 | \li u int AFSCBFids len - Number of AFS file identifiers stored in the | |
764 | structure, up to a maximum of AFSCBMAX. | |
765 | \li AFSFid *AFSCBFids val - Pointer to the first element of the array of file | |
766 | identifiers. | |
767 | ||
768 | \subsubsection sec4-2-3-2 Section 4.2.3.2: struct AFSCBs | |
769 | ||
770 | \n \b Fields | |
771 | \li u int AFSCBs len - Number of AFS callback descriptors stored in the | |
772 | structure, up to a maximum of AFSCBMAX. | |
773 | \li AFSCallBack *AFSCBs val - Pointer to the actual array of callback | |
774 | descriptors | |
775 | ||
776 | \section sec4-3 Section 4.3: Locking Definitions | |
777 | ||
778 | \subsection sec4-3-1 Section 4.3.1: struct AFSDBLockDesc | |
779 | ||
780 | \par | |
781 | This structure describes the state of an AFS lock. | |
782 | \n \b Fields | |
783 | \li char waitStates - Types of lockers waiting for the lock. | |
784 | \li char exclLocked - Does anyone have a boosted, shared or write lock? (A | |
785 | boosted lock allows the holder to have data read-locked and then 'boost' up to | |
786 | a write lock on the data without ever relinquishing the lock.) | |
787 | \li char readersReading - Number of readers that actually hold a read lock on | |
788 | the associated object. | |
789 | \li char numWaiting - Total number of parties waiting to acquire this lock in | |
790 | some fashion. | |
791 | ||
792 | \subsection sec4-3-2 Section 4.3.2: struct AFSDBCacheEntry | |
793 | ||
794 | \par | |
795 | This structure defines the description of a Cache Manager local cache entry, as | |
796 | made accessible via the RXAFSCB GetCE() callback RPC call. Note that File | |
797 | Servers do not make the above call. Rather, client debugging programs (such as | |
798 | cmdebug) are the agents which call RXAFSCB GetCE(). | |
799 | \n \b Fields | |
800 | \li long addr - Memory location in the Cache Manager where this description is | |
801 | located. | |
802 | \li long cell - Cell part of the fid. | |
803 | \li AFSFid netFid - Network (standard) part of the fid | |
804 | \li long Length - Number of bytes in the cache entry. | |
805 | \li long DataVersion - Data version number for the contents of the cache entry. | |
806 | \li struct AFSDBLockDesc lock - Status of the lock object controlling access to | |
807 | this cache entry. | |
808 | \li long callback - Index in callback records for this object. | |
809 | \li long cbExpires - Time when the callback expires. | |
810 | \li short refCount - General reference count. | |
811 | \li short opens - Number of opens performed on this object. | |
812 | \li short writers - Number of writers active on this object. | |
813 | \li char mvstat - The file classification, indicating one of normal file, mount | |
814 | point, or volume root. | |
815 | \li char states - Remembers the state of the given file with a set of | |
816 | bits indicating, from lowest-order to highest order: stat info valid, read-only | |
817 | file, mount point valid, pending core file, wait-for-store, and mapped file. | |
818 | ||
819 | \subsection sec4-3-3 Section 4.3.3: struct AFSDBLock | |
820 | ||
821 | \par | |
822 | This is a fuller description of an AFS lock, including a string name used to | |
823 | identify it. | |
824 | \n \b Fields | |
825 | \li char name[16] - String name of the lock. | |
826 | \li struct AFSDBLockDesc lock - Contents of the lock itself. | |
827 | ||
828 | \section sec4-4 Section 4.4: Miscellaneous Definitions | |
829 | ||
830 | \subsection sec4-4-1 Section 4.4.1: Opaque structures | |
831 | ||
832 | \par | |
833 | A maximum size for opaque structures passed via the File Server interface is | |
834 | defined as AFSOPAQUEMAX. Currently, this is set to 1,024 bytes. The AFSOpaque | |
835 | typedef is defined for use by those parameters that wish their contents to | |
836 | travel completely uninterpreted across the network. | |
837 | ||
838 | \subsection sec4-4-2 Section 4.4.2: String Lengths | |
839 | ||
840 | \par | |
841 | Two common definitions used to specify basic AFS string lengths are AFSNAMEMAX | |
842 | and AFSPATHMAX. AFSNAMEMAX places an upper limit of 256 characters on such | |
843 | things as file and directory names passed as parameters. AFSPATHMAX defines the | |
844 | longest pathname expected by the system, composed of slash-separated instances | |
845 | of the individual directory and file names mentioned above. The longest | |
846 | acceptable pathname is currently set to 1,024 characters. | |
847 | ||
848 | \page chap5 Chapter 5: File Server Interfaces | |
849 | ||
850 | \par | |
851 | There are several interfaces offered by the File Server, allowing it to export | |
852 | the files stored within the set of AFS volumes resident on its disks to the AFS | |
853 | community in a secure fashion and to perform self-administrative tasks. This | |
854 | chapter will cover the three File Server interfaces, summarized below. There is | |
855 | one File Server interface that will not be discussed in this document, namely | |
856 | that used by the Volume Server. It will be fully described in the companion | |
857 | AFS-3 Programmer's Reference:Volume Server/Volume Location Server Interface. | |
858 | \li RPC: This is the main File Server interface, supporting all of the Cache | |
859 | Manager's needs for providing its own clients with appropriate access to file | |
860 | system objects stored within AFS. It is closedly tied to the callback interface | |
861 | exported by the Cache Manager as described in Section 6.5, which has special | |
862 | implications for any application program making direct calls to this interface. | |
863 | \li Signals: Certain operations on a File Server must be performed by it | |
864 | sending unix signals on the machine on which it is executing. These operations | |
865 | include performing clean shutdowns and adjusting debugging output levels. | |
866 | Properly-authenticated administrative users do not have to be physically logged | |
867 | into a File Server machine to generate these signals. Rather, they may use the | |
868 | RPC interface exported by that machine's BOS Server process to generate them | |
869 | from any AFS-capable machine. | |
870 | \li Command Line: Many of the File Server's operating parameters may be set | |
871 | upon startup via its command line interface. Such choices as the number of data | |
872 | buffers and callback records to hold in memory may be made here, along with | |
873 | various other decisions such as lightweight thread stack size. | |
874 | ||
875 | \section sec5-1 Section 5.1: RPC Interface | |
876 | ||
877 | \subsection sec5-1-1 Section 5.1.1: Introduction and Caveats | |
878 | ||
879 | \par | |
880 | The documentation for the AFS-3 File Server RPC interface commences with some | |
881 | basic definitions and data structures used in conjunction with the function | |
882 | calls. This is followed by an examination of the set of non-streamed RPC | |
883 | functions, namely those routines whose parameters are all fixed in size. Next, | |
884 | the streamed RPC functions, those with parameters that allow an arbitrary | |
885 | amount of data to be delivered, are described. A code fragment and accompanying | |
886 | description and analysis are offered as an example of how to use the streamed | |
887 | RPC calls. Finally, a description of the special requirements on any | |
888 | application program making direct calls to this File Server interface appears. | |
889 | The File Server assumes that any entity making calls to its RPC functionality | |
890 | is a bona fide and full-fledged Cache Manager. Thus, it expects this caller to | |
891 | export the Cache Manager's own RPC interface, even if the application simply | |
892 | uses File Server calls that don't transfer files and thus generate callbacks. | |
893 | \par | |
894 | Within those sections describing the RPC functions themselves, the purpose of | |
895 | each call is detailed, and the nature and use of its parameters is documented. | |
896 | Each of these RPC interface routines returns an integer error code, and a | |
897 | subset of the possible values are described. A complete and systematic list of | |
898 | potential error returns for each function is difficult to construct and | |
899 | unwieldy to examine. This is due to fact that error codes from many different | |
900 | packages and from many different levels may arise. Instead of attempting | |
901 | completeness, the error return descriptions discuss error codes generated | |
902 | within the functions themselves (or a very small number of code levels below | |
903 | them) within the File Server code itself, and not from such associated packages | |
904 | as the Rx, volume, and protection modules. Many of these error code are defined | |
905 | in the companion AFS-3 documents. | |
906 | \par | |
907 | By convention, a return value of zero reveals that the function call was | |
908 | successful and that all of its OUT parameters have been set by the File Server. | |
909 | ||
910 | \subsection sec5-1-2 Section 5.1.2: Definitions and Structures | |
911 | ||
912 | \subsubsection sec5-1-2-1 Section 5.1.2.1: Constants and Typedefs | |
913 | ||
914 | \par | |
915 | The following constants and typedefs are required to properly use the File | |
916 | Server RPC interface, both to provide values and to interpret information | |
917 | returned by the calls. The constants appear first, followed by the list of | |
918 | typedefs, which sometimes depend on the constants above. Items are alphabetized | |
919 | within each group. | |
920 | \par | |
921 | All of the constants appearing below whose names contain the XSTAT string are | |
922 | used in conjuction with the extended data collection facility supported by the | |
923 | File Server. The File Server defines some number of data collections, each of | |
924 | which consists of an array of longword values computed by the File Server. | |
925 | \par | |
926 | There are currently two data collections defined for the File Server. The first | |
927 | is identified by the AFS XSTATSCOLL CALL INFO constant. This collection of | |
928 | longwords relates the number of times each internal function within the File | |
929 | Server code has been executed, thus providing profiling information. The second | |
930 | File Server data collection is identified by the AFS XSTATSCOLL PERF INFO | |
931 | constant. This set of longwords contains information related to the File | |
932 | Server's performance. | |
933 | ||
934 | \par Section 5.1.2.1.1 AFS DISKNAMESIZE [Value = 32] | |
935 | Specifies the maximum length for an AFS disk partition, used directly in the | |
936 | definition for the DiskName typedef. A DiskName appears as part of a struct | |
937 | ViceDisk, a group of which appear inside a struct ViceStatistics, used for | |
938 | carrying basic File Server statistics information. | |
939 | ||
940 | \par Section 5.1.2.1.2 AFS MAX XSTAT LONGS [Value = 1,024] | |
941 | Defines the maximum size for a File Server data collection, as exported via the | |
942 | RXAFS GetXStats() RPC call. It is used directly in the AFS CollData typedef. | |
943 | ||
944 | \par Section 5.1.2.1.3 AFS XSTATSCOLL CALL INFO [Value = 0] | |
945 | This constant identifies the File Server's data collection containing profiling | |
946 | information on the number of times each of its internal procedures has been | |
947 | called. | |
948 | \par | |
949 | Please note that this data collection is not supported by the File Server at | |
950 | this time. A request for this data collection will result the return of a | |
951 | zero-length array. | |
952 | ||
953 | \par Section 5.1.2.1.4 AFS XSTATSCOLL PERF INFO [Value = 1] | |
954 | This constant identifies the File Server's data collection containing | |
955 | performance-related information. | |
956 | ||
957 | \par Section 5.1.2.1.5 AFS CollData [typedef long AFS CollData<AFS MAX XSTAT | |
958 | LONGS>;] | |
959 | This typedef is used by Rxgen to create a structure used to pass File Server | |
960 | data collections to the caller. It resolves into a C typedef statement defining | |
961 | a structure of the same name with the following fields: | |
962 | \n \b Fields | |
963 | \li u int AFS CollData len - The number of longwords contained within the data | |
964 | pointed to by the next field. | |
965 | \li long *AFS CollData val - A pointer to a sequence of AFS CollData len | |
966 | long-words. | |
967 | ||
968 | \par Section 5.1.2.1.6 AFSBulkStats [typedef AFSFetchStatus | |
969 | AFSBulkStats<AFSCBMAX>;] | |
970 | This typedef is used by Rxgen to create a structure used to pass a set of | |
971 | statistics structures, as described in the RXAFS BulkStatus documentation in | |
972 | Section 5.1.3.21. It resolves into a C typedef statement defining a structure | |
973 | of the same name with the following fields: | |
974 | \n \b Fields | |
975 | \li u int AFSBulkStats len - The number of struct AFSFetchStatus units | |
976 | contained within the data to which the next field points. | |
977 | \li AFSFetchStatus *AFSBulkStats val - This field houses pointer to a sequence | |
978 | of AFSBulkStats len units of type struct AFSFetchStatus. | |
979 | ||
980 | \par Section 5.1.2.1.7 DiskName [typedef opaque DiskName[AFS DISKNAMESIZE];] | |
981 | The name of an AFS disk partition. This object appears as a field within a | |
982 | struct ViceDisk,a group of which appear inside a struct ViceStatistics, used | |
983 | for carrying basic File Server statistics information. The term opaque | |
984 | appearing above inidcates that the object being defined will be treated as an | |
985 | undifferentiated string of bytes. | |
986 | ||
987 | \par Section 5.1.2.1.8 ViceLockType [typedef long ViceLockType;] | |
988 | This defines the format of a lock used internally by the Cache Manager. The | |
989 | content of these locks is accessible via the RXAFSCB GetLock() RPC function. An | |
990 | isomorphic and more refined version of the lock structure used by the Cache | |
991 | Manager, mapping directly to this definition, is struct AFSDBLockDesc, defined | |
992 | in Section 4.3.1. | |
993 | ||
994 | \subsubsection sec5-1-2-2 Section 5.1.2.2: struct AFSVolSync | |
995 | ||
996 | \par | |
997 | This structure conveys volume synchronization information across many of the | |
998 | File Server RPC interface calls, allowing something akin to a "whole-volume | |
999 | callback" on read-only volumes. | |
1000 | \n \b Fields | |
1001 | \li unsigned long spare1 ... spare6 - The first longword, spare1, contains the | |
1002 | volume's creation date. The rest are currently unused. | |
1003 | ||
1004 | \subsubsection sec5-1-2-3 Section 5.1.2.3: struct AFSFetchStatus | |
1005 | ||
1006 | \par | |
1007 | This structure defines the information returned when a file system object is | |
1008 | fetched from a File Server. | |
1009 | \n \b Fields | |
1010 | \li unsigned long InterfaceVersion - RPC interface version, defined to be 1. | |
1011 | \li unsigned long FileType - Distinguishes the object as either a file, | |
1012 | directory, symlink, or invalid. | |
1013 | \li unsigned long LinkCount - Number of links to this object. | |
1014 | \li unsigned long Length - Length in bytes. | |
1015 | \li unsigned long DataVersion - Object's data version number. | |
1016 | \li unsigned long Author - Identity of the object's author. | |
1017 | \li unsigned long Owner - Identity of the object's owner. | |
1018 | \li unsigned long CallerAccess - The set of access rights computed for the | |
1019 | caller on this object. | |
1020 | \li unsigned long AnonymousAccess - The set of access rights computed for any | |
1021 | completely unauthenticated principal. | |
1022 | \li unsigned long UnixModeBits - Contents of associated unix mode bits. | |
1023 | \li unsigned long ParentVnode - Vnode for the object's parent directory. | |
1024 | \li unsigned long ParentUnique - Uniquifier field for the parent object. | |
1025 | \li unsigned long SegSize - (Not implemented). | |
1026 | \li unsigned long ClientModTime - Time when the caller last modified the data | |
1027 | within the object. | |
1028 | \li unsigned long ServerModTime - Time when the server last modified the data | |
1029 | within the object. | |
1030 | \li unsigned long Group - (Not implemented). | |
1031 | \li unsigned long SyncCounter - (Not implemented). | |
1032 | \li unsigned long spare1 ... spare4 - Spares. | |
1033 | ||
1034 | \subsubsection sec5-1-2-4 Section 5.1.2.4: struct AFSStoreStatus | |
1035 | ||
1036 | \par | |
1037 | This structure is used to convey which of a file system object's status fields | |
1038 | should be set, and their new values. Several File Server RPC calls, including | |
1039 | RXAFS StoreStatus(), RXAFS CreateFile(), RXAFS SymLink(), RXAFS MakeDir(), and | |
1040 | the streamed call to store file data onto the File Server. | |
1041 | \n \b Fields | |
1042 | \li unsigned long Mask - Bit mask, specifying which of the following fields | |
1043 | should be assigned into the File Server's status block on the object. | |
1044 | \li unsigned long ClientModTime - The time of day that the object was last | |
1045 | modified. | |
1046 | \li unsigned long Owner - The principal identified as the owner of the file | |
1047 | system object. | |
1048 | \li unsigned long Group - (Not implemented). | |
1049 | \li unsigned long UnixModeBits - The set of associated unix mode bits. | |
1050 | \li unsigned long SegSize - (Not implemented). | |
1051 | ||
1052 | \subsubsection sec5-1-2-5 Section 5.1.2.5: struct ViceDisk | |
1053 | ||
1054 | \par | |
1055 | This structure occurs in struct ViceStatistics, and describes the | |
1056 | characteristics and status of a disk partition used for AFS storage. | |
1057 | \n \b Fields | |
1058 | \li long BlocksAvailable - Number of 1 Kbyte disk blocks still available on the | |
1059 | partition. | |
1060 | \li long TotalBlocks - Total number of disk blocks in the partition. | |
1061 | \li DiskName Name - The human-readable character string name of the disk | |
1062 | partition (e.g., /vicepa). | |
1063 | ||
1064 | \subsubsection sec5-1-2-6 Section 5.1.2.6: struct ViceStatistics | |
1065 | ||
1066 | \par | |
1067 | This is the File Server statistics structure returned by the RXAFS | |
1068 | GetStatistics() RPC call. | |
1069 | \n \b Fields | |
1070 | \li unsigned long CurrentMsgNumber - Not used. | |
1071 | \li unsigned long OldestMsgNumber - Not used. | |
1072 | \li unsigned long CurrentTime - Time of day, as understood by the File Server. | |
1073 | \li unsigned long BootTime - Kernel's boot time. | |
1074 | \li unsigned long StartTime - Time when the File Server started up. | |
1075 | \li long CurrentConnections - Number of connections to Cache Manager instances. | |
1076 | \li unsigned long TotalViceCalls - Count of all calls made to the RPC | |
1077 | interface. | |
1078 | \li unsigned long TotalFetchs - Total number of fetch operations, either status | |
1079 | or data, performed. | |
1080 | \li unsigned long FetchDatas - Total number of data fetch operations | |
1081 | exclusively. | |
1082 | \li unsigned long FetchedBytes - Total number of bytes fetched from the File | |
1083 | Server since it started up. | |
1084 | \li long FetchDataRate - Result of dividing the FetchedBytes field by the | |
1085 | number of seconds the File Server has been running. | |
1086 | \li unsigned long TotalStores - Total number of store operations, either status | |
1087 | or data, performed. | |
1088 | \li unsigned long StoreDatas - Total number of data store operations | |
1089 | exclusively. | |
1090 | \li unsigned long StoredBytes - Total number of bytes stored to the File Server | |
1091 | since it started up. | |
1092 | \li long StoreDataRate - The result of dividing the StoredBytes field by the | |
1093 | number of seconds the File Server has been running. | |
1094 | \li unsigned long TotalRPCBytesSent - Outdated | |
1095 | \li unsigned long TotalRPCBytesReceived - Outdated | |
1096 | \li unsigned long TotalRPCPacketsSent - Outdated | |
1097 | \li unsigned long TotalRPCPacketsReceived - Outdated | |
1098 | \li unsigned long TotalRPCPacketsLost - Outdated | |
1099 | \li unsigned long TotalRPCBogusPackets - Outdated | |
1100 | \li long SystemCPU - Result of reading from the kernel the usage times | |
1101 | attributed to system activities. | |
1102 | \li long UserCPU - Result of reading from the kernel the usage times attributed | |
1103 | to user-level activities. | |
1104 | \li long NiceCPU - Result of reading from the kernel the usage times attributed | |
1105 | to File Server activities that have been nice()d (i.e., run at a lower | |
1106 | priority). | |
1107 | \li long IdleCPU - Result of reading from the kernel the usage times attributed | |
1108 | to idling activities. | |
1109 | \li long TotalIO - Summary of the number of bytes read/written from the disk. | |
1110 | \li long ActiveVM - Amount of virtual memory used by the File Server. | |
1111 | \li long TotalVM - Total space available on disk for virtual memory activities. | |
1112 | \li long EtherNetTotalErrors - Not used. | |
1113 | \li long EtherNetTotalWrites - Not used. | |
1114 | \li long EtherNetTotalInterupts - Not used. | |
1115 | \li long EtherNetGoodReads - Not used. | |
1116 | \li long EtherNetTotalBytesWritten - Not used. | |
1117 | \li long EtherNetTotalBytesRead - Not used. | |
1118 | \li long ProcessSize - The size of the File Server's data space in 1 Kbyte | |
1119 | chunks. | |
1120 | \li long WorkStations - The total number of client Cache Managers | |
1121 | (workstations) for which information is held by the File Server. | |
1122 | \li long ActiveWorkStations - The total number of client Cache Managers | |
1123 | (workstations) that have recently interacted with the File Server. This number | |
1124 | is strictly less than or equal to the WorkStations field. | |
1125 | \li long Spare1 ... Spare8 - Not used. | |
1126 | \li ViceDisk Disk1 ... Disk10 - Statistics concerning up to 10 disk partitions | |
1127 | used by the File Server. These records keep information on all partitions, not | |
1128 | just partitions reserved for AFS storage. | |
1129 | ||
1130 | \subsubsection sec5-1-2-7 Section 5.1.2.7: struct afs PerfStats | |
1131 | ||
1132 | \par | |
1133 | This is the structure corresponding to the AFS XSTATSCOLL PERF INFO data | |
1134 | collection that is defined by the File Server (see Section 5.1.2.1.4). It is | |
1135 | accessible via the RXAFS GetXStats() interface routine, as defined in Section | |
1136 | 5.1.3.26. | |
1137 | The fields within this structure fall into the following classifications: | |
1138 | \li Number of requests for the structure. | |
1139 | \li Vnode cache information. | |
1140 | \li Directory package numbers. | |
1141 | \li Rx information. | |
1142 | \li Host module fields | |
1143 | \li Spares. | |
1144 | ||
1145 | \par | |
1146 | Please note that the Rx fields represent the contents of the rx stats structure | |
1147 | maintained by Rx RPC facility itself. Also, a full description of all the | |
1148 | structure's fields is not possible here. For example, the reader is referred to | |
1149 | the companion Rx document for further clarification on the Rx-related fields | |
1150 | within afs PerfStats. | |
1151 | \n \b Fields | |
1152 | \li long numPerfCalls - Number of performance collection calls received. | |
1153 | \li long vcache L Entries - Number of entries in large (directory) vnode cache. | |
1154 | \li long vcache L Allocs - Number of allocations for the large vnode cache. | |
1155 | \li long vcache L Gets - Number of get operations for the large vnode cache. | |
1156 | \li long vcache L Reads - Number of reads performed on the large vnode cache. | |
1157 | \li long vcache L Writes - Number of writes executed on the large vnode.cache. | |
1158 | \li long vcache S Entries - Number of entries in the small (file) vnode cache. | |
1159 | \li long vcache S Allocs - Number of allocations for the small vnode cache. | |
1160 | \li long vcache S Gets - Number of get operations for the small vnode cache. | |
1161 | \li long vcache S Reads - Number of reads performed on the small vnode cache. | |
1162 | \li long vcache S Writes - Number of writes executed on the small vnode cache. | |
1163 | \li long vcache H Entries - Number of entries in the header of the vnode cache. | |
1164 | \li long vcache H Gets - Number of get operations on the header of the vnode | |
1165 | cache. | |
1166 | \li long vcache H Replacements - Number of replacement operations on the header | |
1167 | of the vnode cache. | |
1168 | \li long dir Buffers - Number of directory package buffers in use. | |
1169 | \li long dir Calls - Number of read calls made to the directory package. | |
1170 | \li long dir IOs - Number of directory I/O operations performed. | |
1171 | \li long rx packetRequests - Number of Rx packet allocation requests. | |
1172 | \li long rx noPackets RcvClass - Number of failed packet reception requests. | |
1173 | \li long rx noPackets SendClass - Number of failed packet transmission | |
1174 | requests. | |
1175 | \li long rx noPackets SpecialClass - Number of 'special' Rx packet rquests. | |
1176 | \li long rx socketGreedy - Did setting the Rx socket to SO GREEDY succeed? | |
1177 | \li long rx bogusPacketOnRead - Number of short packets received. | |
1178 | \li long rx bogusHost - Latest host address from bogus packets. | |
1179 | \li long rx noPacketOnRead - Number of attempts to read a packet when one was | |
1180 | not physically available. | |
1181 | \li long rx noPacketBuffersOnRead - Number of packets dropped due to buffer | |
1182 | shortages. | |
1183 | \li long rx selects - Number of selects performed, waiting for a packet arrival | |
1184 | or a timeout. | |
1185 | \li long rx sendSelects - Number of selects forced upon a send. | |
1186 | \li long rx packetsRead RcvClass - Number of packets read belonging to the | |
1187 | 'Rcv' class. | |
1188 | \li long rx packetsRead SendClass - Number of packets read that belong to the | |
1189 | 'Send' class. | |
1190 | \li long rx packetsRead SpecialClass - Number of packets read belonging to the | |
1191 | 'Special' class. | |
1192 | \li long rx dataPacketsRead - Number of unique data packets read off the wire. | |
1193 | \li long rx ackPacketsRead - Number of acknowledgement packets read. | |
1194 | \li long rx dupPacketsRead - Number of duplicate data packets read. | |
1195 | \li long rx spuriousPacketsRead - Number of inappropriate packets read. | |
1196 | \li long rx packetsSent RcvClass - Number of packets sent belonging to the | |
1197 | 'Rcv' class. | |
1198 | \li long rx packetsSent SendClass - Number of packets sent belonging to the | |
1199 | 'Send' class. | |
1200 | \li long rx packetsSent SpecialClass - Number of packets sent belonging to the | |
1201 | 'Special' class. | |
1202 | \li long rx ackPacketsSent - Number of acknowledgement packets sent. | |
1203 | \li long rx pingPacketsSent - Number of ping packets sent. | |
1204 | \li long rx abortPacketsSent - Number of abort packets sent. | |
1205 | \li long rx busyPacketsSent - Number of busy packets sent. | |
1206 | \li long rx dataPacketsSent - Number of unique data packets sent. | |
1207 | \li long rx dataPacketsReSent - Number of retransmissions sent. | |
1208 | \li long rx dataPacketsPushed - Number of retransmissions pushed by a NACK. | |
1209 | \li long rx ignoreAckedPacket - Number of packets whose acked flag was set at | |
1210 | rxi Start() time. | |
1211 | \li long rx totalRtt Sec - Total round trip time in seconds. | |
1212 | \li long rx totalRtt Usec - Microsecond portion of the total round trip time, | |
1213 | \li long rx minRtt Sec - Minimum round trip time in seconds. | |
1214 | \li long rx minRtt Usec - Microsecond portion of minimal round trip time. | |
1215 | \li long rx maxRtt Sec - Maximum round trip time in seconds. | |
1216 | \li long rx maxRtt Usec - Microsecond portion of maximum round trip time. | |
1217 | \li long rx nRttSamples - Number of round trip samples. | |
1218 | \li long rx nServerConns - Total number of server connections. | |
1219 | \li long rx nClientConns - Total number of client connections. | |
1220 | \li long rx nPeerStructs - Total number of peer structures. | |
1221 | \li long rx nCallStructs - Total number of call structures. | |
1222 | \li long rx nFreeCallStructs - Total number of call structures residing on the | |
1223 | free list. | |
1224 | \li long host NumHostEntries - Number of host entries. | |
1225 | \li long host HostBlocks - Number of blocks in use for host entries. | |
1226 | \li long host NonDeletedHosts - Number of non-deleted host entries. | |
1227 | \li long host HostsInSameNetOrSubnet - Number of host entries in the same | |
1228 | [sub]net as the File Server. | |
1229 | \li long host HostsInDiffSubnet - Number of host entries in a different subnet | |
1230 | as the File Server. | |
1231 | \li long host HostsInDiffNetwork - Number of host entries in a different | |
1232 | network entirely as the File Server. | |
1233 | \li long host NumClients - Number of client entries. | |
1234 | \li long host ClientBlocks - Number of blocks in use for client entries. | |
1235 | \li long spare[32] - Spare fields, reserved for future use. | |
1236 | ||
1237 | \subsubsection sec5-1-2-8 Section 5.1.2.8: struct AFSFetchVolumeStatus | |
1238 | ||
1239 | \par | |
1240 | The results of asking the File Server for status information concerning a | |
1241 | particular volume it hosts. | |
1242 | \n \b Fields | |
1243 | \li long Vid - Volume ID. | |
1244 | \li long ParentId - Volume ID in which the given volume is 'primarily' mounted. | |
1245 | \li This is used to properly resolve pwd operations, as a volume may be mounted | |
1246 | simultaneously at multiple locations. | |
1247 | \li char Online - Is the volume currently online and fully available? | |
1248 | \li char InService - This field records whether the volume is currently in | |
1249 | service. It is indistinguishable from the Blessed field, | |
1250 | \li char Blessed - See the description of the InService field immediately | |
1251 | above. | |
1252 | \li char NeedsSalvage -Should this volume be salvaged (run through a | |
1253 | consistency- checking procedure)? | |
1254 | \li long Type - The classification of this volume, namely a read/write volume | |
1255 | (RWVOL = 0), read-only volume (ROVOL = 1), or backup volume (BACKVOL = 2). | |
1256 | \li long MinQuota - Minimum number of 1 Kbyte disk blocks to be set aside for | |
1257 | this volume. Note: this field is not currently set or accessed by any AFS | |
1258 | agents. | |
1259 | \li long MaxQuota - Maximum number of 1 Kbyte disk blocks that may be occupied | |
1260 | by this volume. | |
1261 | \li long BlocksInUse - Number of 1 Kbyte disk blocks currently in use by this | |
1262 | volume. | |
1263 | \li long PartBlocksAvail - Number of available 1 Kbyte blocks currently unused | |
1264 | in the volume's partition. | |
1265 | \li long PartMaxBlocks - Total number of blocks, in use or not, for the | |
1266 | volume's partition. | |
1267 | ||
1268 | \subsubsection sec5-1-2-9 Section 5.1.2.9: struct AFSStoreVolumeStatus | |
1269 | ||
1270 | \par | |
1271 | This structure is used to convey which of a file system object's status fields | |
1272 | should be set, and their new values. The RXAFS SetVolumeStatus() RPC call is | |
1273 | the only user of this structure. | |
1274 | \n \b Fields | |
1275 | \li long Mask - Bit mask to determine which of the following two fields should | |
1276 | be stored in the centralized status for a given volume. | |
1277 | \li long MinQuota - Minimum number of 1 Kbyte disk blocks to be set aside for | |
1278 | this volume. | |
1279 | \li long MaxQuota - Maximum number of 1 Kbyte disk blocks that may be occupied | |
1280 | by this volume. | |
1281 | ||
1282 | \subsubsection sec5-1-2-10 Section 5.1.2.10: struct AFSVolumeInfo | |
1283 | ||
1284 | \par | |
1285 | This field conveys information regarding a particular volume through certain | |
1286 | File Server RPC interface calls. For information regarding the different volume | |
1287 | types that exist, please consult the companion document, AFS-3 Programmer's | |
1288 | Reference:Volume Server/Volume Location Server Interface. | |
1289 | \n \b Fields | |
1290 | \li unsigned long Vid - Volume ID. | |
1291 | \li long Type - Volume type (see struct AFSFetchVolumeStatus in Section 5.1.2.8 | |
1292 | above). | |
1293 | \li unsigned long Type0 ... Type4 - The volume IDs for the possible volume | |
1294 | types in existance for this volume. | |
1295 | \li unsigned long ServerCount - The number of File Server machines on which an | |
1296 | instance of this volume is located. | |
1297 | \li unsigned long Server0 ... Server7 - Up to 8 IP addresses of File Server | |
1298 | machines hosting an instance on this volume. The first ServerCount of these | |
1299 | fields hold valid server addresses. | |
1300 | \li unsigned short Port0 ... Port7 - Up to 8 UDP port numbers on which | |
1301 | operations on this volume should be directed. The first ServerCount of these | |
1302 | fields hold valid port identifiers. | |
1303 | ||
1304 | \subsection sec5-1-3 Section 5.1.3: Non-Streamed Function Calls | |
1305 | ||
1306 | \par | |
1307 | The following is a description of the File Server RPC interface routines that | |
1308 | utilize only parameters with fixed maximum lengths. The majority of the File | |
1309 | Server calls fall into this suite, with only a handful using streaming | |
1310 | techniques to pass objects of unbounded size between a File Server and Cache | |
1311 | Manager. | |
1312 | \par | |
1313 | Each function is labeled with an opcode number. This is the low-level numerical | |
1314 | identifier for the function, and appears in the set of network packets | |
1315 | constructed for the RPC call. | |
1316 | ||
1317 | \subsubsection sec5-1-3-1 Section 5.1.3.1: RXAFS FetchACL - Fetch the | |
1318 | ACL associated with the given AFS file identifier | |
1319 | ||
1320 | \code | |
1321 | int RXAFS FetchACL(IN struct rx connection *a rxConnP, | |
1322 | IN AFSFid *a dirFidP, | |
1323 | OUT AFSOpaque *a ACLP, | |
1324 | OUT AFSFetchStatus *a dirNewStatP, | |
1325 | OUT AFSVolSync *a volSyncP) | |
1326 | \endcode | |
1327 | \par Description | |
1328 | [Opcode 131] Fetch the ACL for the directory identified by a dirFidP, placing | |
1329 | it in the space described by the opaque structure to which a ACLP points. Also | |
1330 | returned is the given directory's status, written to a dirNewStatP. An ACL may | |
1331 | thus take up at most AFSOPAQUEMAX (1,024) bytes, since this is the maximum size | |
1332 | of an AFSOpaque. | |
1333 | \par | |
1334 | Rx connection information for the related File Server is contained in a | |
1335 | rxConnP. Volume version information is returned for synchronization purposes in | |
1336 | a volSyncP. | |
1337 | \par Error Codes | |
1338 | EACCES The caller is not permitted to perform this operation. EINVAL An | |
1339 | internal error in looking up the client record was encountered, or an invalid | |
1340 | fid was provided. VICETOKENDEAD Caller's authentication token has expired. | |
1341 | ||
1342 | \subsubsection sec5-1-3-2 Section 5.1.3.2: RXAFS FetchStatus - Fetch | |
1343 | the status information regarding a given file system object | |
1344 | ||
1345 | \code | |
1346 | int RXAFS FetchStatus(IN struct rx connection *a rxConnP, | |
1347 | IN AFSFid *a fidToStatP, | |
1348 | OUT AFSFetchStatus *a currStatP, | |
1349 | OUT AFSCallBack *a callBackP, | |
1350 | OUT AFSVolSync *a volSyncP) | |
1351 | \endcode | |
1352 | \par Description | |
1353 | [Opcode 132] Fetch the current status information for the file or directory | |
1354 | identified by a fidToStatP, placing it into the area to which a currStatP | |
1355 | points. If the object resides in a read/write volume, then the related callback | |
1356 | information is returned in a callBackP. | |
1357 | \par | |
1358 | Rx connection information for the related File Server is contained in a | |
1359 | rxConnP. Volume version information is returned for synchronization purposes in | |
1360 | a volSyncP. | |
1361 | \par Error Codes | |
1362 | EACCES The caller is not permitted to perform this operation. EINVAL An | |
1363 | internal error in looking up the client record was encountered, or an invalid | |
1364 | fid was provided. VICETOKENDEAD Caller's authentication token has expired. | |
1365 | ||
1366 | \subsubsection sec5-1-3-3 Section 5.1.3.3: RXAFS StoreACL - Associate | |
1367 | the given ACL with the named directory | |
1368 | ||
1369 | \code | |
1370 | int RXAFS StoreACL(IN struct rx connection *a rxConnP, | |
1371 | IN AFSOpaque *a ACLToStoreP, | |
1372 | IN AFSFid *a dirFidP, | |
1373 | OUT AFSFetchStatus *a dirNewStatP, | |
1374 | OUT AFSVolSync *a volSyncP) | |
1375 | \endcode | |
1376 | \par Description | |
1377 | [Opcode 134] Store the ACL information to which a ACLToStoreP points to the | |
1378 | File Server, associating it with the directory identified by a dirFidP. The | |
1379 | resulting status information for the a dirFidP directory is returned in a | |
1380 | dirNewStatP. Note that the ACL supplied via a ACLToStoreP may be at most | |
1381 | AFSOPAQUEMAX (1,024) bytes long, since this is the maximum size accommodated by | |
1382 | an AFSOpaque. | |
1383 | \par | |
1384 | Rx connection information for the related File Server is contained in a | |
1385 | rxConnP. Volume version information is returned for synchronization purposes in | |
1386 | a volSyncP. | |
1387 | \par Error Codes | |
1388 | EACCES The caller is not permitted to perform this operation. | |
1389 | \n E2BIG The given ACL is too large. | |
1390 | \n EINVAL The given ACL could not translated to its on-disk format. | |
1391 | ||
1392 | \subsubsection sec5-1-3-4 Section 5.1.3.4: RXAFS StoreStatus - Store | |
1393 | the given status information for the specified file | |
1394 | ||
1395 | \code | |
1396 | int RXAFS StoreStatus(IN struct rx connection *a rxConnP, | |
1397 | IN AFSFid *a fidP, | |
1398 | IN AFSStoreStatus *a currStatusP, | |
1399 | OUT AFSFetchStatus *a srvStatusP, | |
1400 | OUT AFSVolSync *a volSyncP) | |
1401 | \endcode | |
1402 | \par Description | |
1403 | [Opcode 135] Store the status information to which a currStatusP points, | |
1404 | associating it with the file identified by a fidP. All outstanding callbacks on | |
1405 | this object are broken. The resulting status structure stored at the File | |
1406 | Server is returned in a srvStatusP. | |
1407 | \par | |
1408 | Rx connection information for the related File Server is contained in a | |
1409 | rxConnP. Volume version information is returned for synchronization purposes in | |
1410 | a volSyncP. | |
1411 | \par Error Codes | |
1412 | EACCES The caller is not permitted to perform this operation. | |
1413 | \n EINVAL An internal error in looking up the client record was encountered, or | |
1414 | an invalid fid was provided, or an attempt was made to change the mode of a | |
1415 | symbolic link. | |
1416 | \n VICETOKENDEAD Caller's authentication token has expired. | |
1417 | ||
1418 | \subsubsection sec5-1-3-5 Section 5.1.3.5: RXAFS RemoveFile - Delete | |
1419 | the given file | |
1420 | ||
1421 | \code | |
1422 | int RXAFS RemoveFile(IN struct rx connection *a rxConnP, | |
1423 | IN AFSFid *a dirFidP, | |
1424 | IN char *a name<AFSNAMEMAX>, | |
1425 | OUT AFSFetchStatus *a srvStatusP, | |
1426 | OUT AFSVolSync *a volSyncP) | |
1427 | \endcode | |
1428 | \par Description | |
1429 | [Opcode 136] Destroy the file named a name within the directory identified by a | |
1430 | dirFidP. All outstanding callbacks on this object are broken. The resulting | |
1431 | status structure stored at the File Server is returned in a srvStatusP. | |
1432 | \par | |
1433 | Rx connection information for the related File Server is contained in a | |
1434 | rxConnP. Volume version information is returned for synchronization purposes in | |
1435 | a volSyncP. | |
1436 | \par Error Codes | |
1437 | EACCES The caller is not permitted to perform this operation. | |
1438 | \n EINVAL An internal error in looking up the client record was encountered, or | |
1439 | an invalid fid was provided, or an attempt was made to remove "." or "..". | |
1440 | \n EISDIR The target of the deletion was supposed to be a file, but it is | |
1441 | really a directory. | |
1442 | \n ENOENT The named file was not found. | |
1443 | \n ENOTDIR The a dirFidP parameter references an object which is not a | |
1444 | directory, or the deletion target is supposed to be a directory but is not. | |
1445 | \n ENOTEMPTY The target directory being deleted is not empty. | |
1446 | \n VICETOKENDEAD Caller's authentication token has expired. | |
1447 | ||
1448 | \subsubsection sec5-1-3-6 Section 5.1.3.6: RXAFS CreateFile - Create | |
1449 | the given file | |
1450 | ||
1451 | \code | |
1452 | int RXAFS CreateFile(IN struct rx connection *a rxConnP, | |
1453 | IN AFSFid *DirFid, | |
1454 | IN char *Name, | |
1455 | IN AFSStoreStatus *InStatus, | |
1456 | OUT AFSFid *OutFid, | |
1457 | OUT AFSFetchStatus *OutFidStatus, | |
1458 | OUT AFSFetchStatus *OutDirStatus, | |
1459 | OUT AFSCallBack *CallBack, | |
1460 | OUT AFSVolSync *a volSyncP) | |
1461 | /* associated with the new file. */ | |
1462 | \endcode | |
1463 | \par Description | |
1464 | [Opcode 137] This call is used to create a file, but not for creating a | |
1465 | directory or a symbolic link. If this call succeeds, it is the Cache Manager's | |
1466 | responsibility to either create an entry locally in the directory specified by | |
1467 | DirFid or to invalidate this directory's cache entry. | |
1468 | \par | |
1469 | Rx connection information for the related File Server is contained in a | |
1470 | rxConnP. Volume version information is returned for synchronization purposes in | |
1471 | a volSyncP. | |
1472 | \par Error Codes | |
1473 | EACCES The caller is not permitted to perform this operation. | |
1474 | \n EINVAL An internal error in looking up the client record was encountered, or | |
1475 | an invalid fid or name was provided. | |
1476 | \n ENOTDIR The DirFid parameter references an object which is not a directory. | |
1477 | \n VICETOKENDEAD Caller's authentication token has expired. | |
1478 | ||
1479 | \subsubsection sec5-1-3-7 Section 5.1.3.7: RXAFS Rename - Rename the | |
1480 | specified file in the given directory | |
1481 | ||
1482 | \code | |
1483 | int RXAFS Rename(IN struct rx connection *a rxConnP, | |
1484 | IN AFSFid *a origDirFidP, | |
1485 | IN char *a origNameP, | |
1486 | IN AFSFid *a newDirFidP, | |
1487 | IN char *a newNameP, | |
1488 | OUT AFSFetchStatus *a origDirStatusP, | |
1489 | OUT AFSFetchStatus *a newDirStatusP, | |
1490 | OUT AFSVolSync *a volSyncP) | |
1491 | \endcode | |
1492 | \par Description | |
1493 | [Opcode 138] Rename file a origNameP in the directory identified by a | |
1494 | origDirFidP. Its new name is to be a newNameP, and it will reside in the | |
1495 | directory identified by a newDirFidP. Each of these names must be no more than | |
1496 | AFSNAMEMAX (256) characters long. The status of the original and new | |
1497 | directories after the rename operation completes are deposited in a | |
1498 | origDirStatusP and a newDirStatusP respectively. Existing callbacks are broken | |
1499 | for all files and directories involved in the operation. | |
1500 | \par | |
1501 | Rx connection information for the related File Server is contained in a | |
1502 | rxConnP. Volume version information is returned for synchronization purposes in | |
1503 | a volSyncP. | |
1504 | \par Error Codes | |
1505 | EACCES New file exists but user doesn't have Delete rights in the directory. | |
1506 | \n EINVAL Name provided is invalid. | |
1507 | \n EISDIR Original object is a file and new object is a directory. | |
1508 | \n ENOENT The object to be renamed doesn't exist in the parent directory. | |
1509 | \n ENOTDIR Original object is a directory and new object is a file. | |
1510 | \n EXDEV Rename attempted across a volume boundary, or create a pathname loop, | |
1511 | or hard links exist to the file. | |
1512 | ||
1513 | \subsubsection sec5-1-3-8 Section 5.1.3.8: RXAFS Symlink - Create a | |
1514 | symbolic link | |
1515 | ||
1516 | \code | |
1517 | int RXAFS Symlink(IN struct rx connection *a rxConnP, | |
1518 | IN AFSFid *a dirFidP, | |
1519 | IN char *a nameP, | |
1520 | IN char *a linkContentsP, | |
1521 | IN AFSStoreStatus *a origDirStatP, | |
1522 | OUT AFSFid *a newFidP, | |
1523 | OUT AFSFetchStatus *a newFidStatP, | |
1524 | OUT AFSFetchStatus *a newDirStatP, | |
1525 | OUT AFSVolSync *a volSyncP) | |
1526 | \endcode | |
1527 | \par Description | |
1528 | [Opcode 139] Create a symbolic link named a nameP in the directory identified | |
1529 | by a dirFidP. The text of the symbolic link is provided in a linkContentsP, and | |
1530 | the desired status fields for the symbolic link given by a origDirStatP. The | |
1531 | name offered in a nameP must be less than AFSNAMEMAX (256) characters long, and | |
1532 | the text of the link to which a linkContentsP points must be less than | |
1533 | AFSPATHMAX (1,024) characters long. Once the symbolic link has been | |
1534 | successfully created, its file identifier is returned in a newFidP. Existing | |
1535 | callbacks to the a dirFidP directory are broken before the symbolic link | |
1536 | creation completes. The status fields for the symbolic link itself and its | |
1537 | parent's directory are returned in a newFidStatP and a newDirStatP | |
1538 | respectively. | |
1539 | \par | |
1540 | Rx connection information for the related File Server is contained in a | |
1541 | rxConnP. Volume version information is returned for synchronization purposes in | |
1542 | a volSyncP. | |
1543 | \par Error Codes | |
1544 | EACCES The caller does not have the necessary access rights. | |
1545 | \n EINVAL Illegal symbolic link name provided. | |
1546 | ||
1547 | \subsubsection sec5-1-3-9 Section 5.1.3.9: RXAFS Link - Create a hard | |
1548 | link | |
1549 | ||
1550 | \code | |
1551 | int RXAFS Link(IN struct rx connection *a rxConnP, | |
1552 | IN AFSFid *a dirFidP, | |
1553 | IN char *a nameP, | |
1554 | IN AFSFid *a existingFidP, | |
1555 | OUT AFSFetchStatus *a newFidStatP, | |
1556 | OUT AFSFetchStatus *a newDirStatP, | |
1557 | OUT AFSVolSync *a volSyncP) | |
1558 | \endcode | |
1559 | \par Description | |
1560 | [Opcode 140] Create a hard link named a nameP in the directory identified by a | |
1561 | dirFidP. The file serving as the basis for the hard link is identified by | |
1562 | existingFidP. The name offered in a nameP must be less than AFSNAMEMAX (256) | |
1563 | characters long. Existing callbacks to the a dirFidP directory are broken | |
1564 | before the hard link creation completes. The status fields for the file itself | |
1565 | and its parent's directory are returned in a newFidStatP and a newDirStatP | |
1566 | respectively. | |
1567 | Rx connection information for the related File Server is contained in a | |
1568 | rxConnP. Volume version information is returned for synchronization purposes in | |
1569 | a volSyncP. | |
1570 | \par Error Codes | |
1571 | EACCES The caller does not have the necessary access rights. | |
1572 | \n EISDIR An attempt was made to create a hard link to a directory. | |
1573 | \n EXDEV Hard link attempted across directories. | |
1574 | ||
1575 | \subsubsection sec5-1-3-10 Section 5.1.3.10: RXAFS MakeDir - Create a | |
1576 | directory | |
1577 | ||
1578 | \code | |
1579 | int RXAFS MakeDir(IN struct rx connection *a rxConnP, | |
1580 | IN AFSFid *a parentDirFid,P | |
1581 | IN char *a newDirNameP, | |
1582 | IN AFSStoreStatus *a currStatP, | |
1583 | OUT AFSFid *a newDirFidP, | |
1584 | OUT AFSFetchStatus *a dirFidStatP, | |
1585 | OUT AFSFetchStatus *a parentDirStatP, | |
1586 | OUT AFSCallBack *a newDirCallBackP, | |
1587 | OUT AFSVolSync *a volSyncP) | |
1588 | \endcode | |
1589 | \par Description | |
1590 | [Opcode 141] Create a directory named a newDirNameP within the directory | |
1591 | identified by a parentDirFidP. The initial status fields for the new directory | |
1592 | are provided in a currStatP. The new directory's name must be less than | |
1593 | AFSNAMEMAX (256) characters long. The new directory's ACL is inherited from its | |
1594 | parent. Existing callbacks on the parent directory are broken before the | |
1595 | creation completes. Upon successful directory creation, the new directory's | |
1596 | file identifier is returned in a newDirFidP, and the resulting status | |
1597 | information for the new and parent directories are stored in a dirFidStatP and | |
1598 | a parentDirStatP respectively. In addition, a callback for the new directory is | |
1599 | returned in a newDirCallBackP. | |
1600 | \par | |
1601 | Rx connection information for the related File Server is contained in a | |
1602 | rxConnP. Volume version information is returned for synchronization purposes in | |
1603 | a volSyncP. | |
1604 | \par Error Codes | |
1605 | EACCES The caller does not have the necessary access rights. | |
1606 | \n EINVAL The directory name provided is unacceptable. | |
1607 | ||
1608 | \subsubsection sec5-1-3-11 Section 5.1.3.11: RXAFS RemoveDir - Remove a | |
1609 | directory | |
1610 | ||
1611 | \code | |
1612 | int RXAFS RemoveDir(IN struct rx connection *a rxConnP, | |
1613 | IN AFSFid *a parentDirFidP, | |
1614 | IN char *a dirNameP, | |
1615 | OUT AFSFetchStatus *a newParentDirStatP, | |
1616 | OUT AFSVolSync *a volSyncP) | |
1617 | \endcode | |
1618 | \par Description | |
1619 | [Opcode 142] Remove the directory named a dirNameP from within its parent | |
1620 | directory, identified by a parentDirFid. The directory being removed must be | |
1621 | empty, and its name must be less than AFSNAMEMAX (256) characters long. | |
1622 | Existing callbacks to the directory being removed and its parent directory are | |
1623 | broken before the deletion completes. Upon successful deletion, the status | |
1624 | fields for the parent directory are returned in a newParentDirStatP. | |
1625 | \par | |
1626 | Rx connection information for the related File Server is contained in a | |
1627 | rxConnP. Volume version information is returned for synchronization purposes in | |
1628 | a volSyncP. | |
1629 | \par Error Codes | |
1630 | EACCES The caller does not have the necessary access rights. | |
1631 | ||
1632 | \subsubsection sec5-1-3-12 Section 5.1.3.12: RXAFS GetStatistics - Get | |
1633 | common File Server statistics | |
1634 | ||
1635 | \code | |
1636 | int RXAFS GetStatistics(IN struct rx connection *a rxConnP, | |
1637 | OUT ViceStatistics *a FSInfoP) | |
1638 | \endcode | |
1639 | \par Description | |
1640 | [Opcode 146] Fetch the structure containing a set of common File Server | |
1641 | statistics. These numbers represent accumulated readings since the time the | |
1642 | File Server last restarted. For a full description of the individual fields | |
1643 | contained in this structure, please see Section 5.1.2.6. | |
1644 | \par | |
1645 | Rx connection information for the related File Server is contained in a | |
1646 | rxConnP. | |
1647 | \par Error Codes | |
1648 | ---No error codes generated. | |
1649 | ||
1650 | \subsubsection sec5-1-3-13 Section 5.1.3.13: RXAFS GiveUpCallBacks - | |
1651 | Ask the File Server to break the given set of callbacks on the corresponding | |
1652 | set of file identifiers | |
1653 | ||
1654 | \code | |
1655 | int RXAFS GiveUpCallBacks(IN struct rx connection *a rxConnP, | |
1656 | IN AFSCBFids *a fidArrayP, | |
1657 | IN AFSCBs *a callBackArrayP) | |
1658 | \endcode | |
1659 | \par Description | |
1660 | [Opcode 147] Given an array of up to AFSCBMAX file identifiers in a fidArrayP | |
1661 | and a corresponding number of callback structures in a callBackArrayP, ask the | |
1662 | File Server to remove these callbacks from its register. Note that this routine | |
1663 | only affects callbacks outstanding on the given set of files for the host | |
1664 | issuing the RXAFS GiveUpCallBacks call. Callback promises made to other | |
1665 | machines on any or all of these files are not affected. | |
1666 | \par | |
1667 | Rx connection information for the related File Server is contained in a | |
1668 | rxConnP. | |
1669 | \par Error Codes | |
1670 | EINVAL More file identifiers were provided in the a fidArrayP than callbacks in | |
1671 | the a callBackArray. | |
1672 | ||
1673 | \subsubsection sec5-1-3-14 Section 5.1.3.14: RXAFS GetVolumeInfo - Get | |
1674 | information about a volume given its name | |
1675 | ||
1676 | \code | |
1677 | int RXAFS GetVolumeInfo(IN struct rx connection *a rxConnP, | |
1678 | IN char *a volNameP, | |
1679 | OUT VolumeInfo *a volInfoP) | |
1680 | \endcode | |
1681 | \par Description | |
1682 | [Opcode 148] Ask the given File Server for information regarding a volume whose | |
1683 | name is a volNameP. The volume name must be less than AFSNAMEMAX characters | |
1684 | long, and the volume itself must reside on the File Server being probed. | |
1685 | \par | |
1686 | Rx connection information for the related File Server is contained in a | |
1687 | rxConnP. Please note that definitions for the error codes with VL prefixes may | |
1688 | be found in the vlserver.h include file | |
1689 | \par Error Codes | |
1690 | Could not contact any of the corresponding Volume Location Servers. | |
1691 | VL BADNAME An improperly-formatted volume name provided. | |
1692 | \n VL ENTDELETED An entry was found for the volume, reporting that the volume | |
1693 | has been deleted. | |
1694 | \n VL NOENT The given volume was not found. | |
1695 | ||
1696 | \subsubsection sec5-1-3-15 Section 5.1.3.15: RXAFS GetVolumeStatus - | |
1697 | Get basic status information for the named volume | |
1698 | ||
1699 | \code | |
1700 | int RXAFS GetVolumeStatus(IN struct rx connection *a rxConnP, | |
1701 | IN long a volIDP, | |
1702 | OUT AFSFetchVolumeStatus *a volFetchStatP, | |
1703 | OUT char *a volNameP, | |
1704 | OUT char *a offLineMsgP, | |
1705 | OUT char *a motdP) | |
1706 | \endcode | |
1707 | \par Description | |
1708 | [Opcode 149] Given the numeric volume identifier contained in a volIDP, fetch | |
1709 | the basic status information corresponding to that volume. This status | |
1710 | information is stored into a volFetchStatP. A full description of this status | |
1711 | structure is found in Section 5.1.2.8. In addition, three other facts about the | |
1712 | volume are returned. The volume's character string name is placed into a | |
1713 | volNameP. This name is guaranteed to be less than AFSNAMEMAX characters long. | |
1714 | The volume's offline message, namely the string recording why the volume is | |
1715 | off-line (if it is), is stored in a offLineMsgP . Finally, the volume's | |
1716 | "Message of the Day" is placed in a motdP. Each of the character strings | |
1717 | deposited into a offLineMsgP and a motdP is guaranteed to be less than | |
1718 | AFSOPAQUEMAX (1,024) characters long. | |
1719 | \par | |
1720 | Rx connection information for the related File Server is contained in a | |
1721 | rxConnP. | |
1722 | \par Error Codes | |
1723 | EACCES The caller does not have the necessary access rights. | |
1724 | \n EINVAL A volume identifier of zero was specified. | |
1725 | ||
1726 | \subsubsection sec5-1-3-16 Section 5.1.3.16: RXAFS SetVolumeStatus - | |
1727 | Set the basic status information for the named volume | |
1728 | ||
1729 | \code | |
1730 | int RXAFS SetVolumeStatus(struct rx connection *a rxConnP, | |
1731 | long avolIDP, | |
1732 | AFSStoreVolumeStatus *a volStoreStatP, | |
1733 | char *a volNameP, | |
1734 | char *a offLineMsgP, | |
1735 | char *a motdP) | |
1736 | /* for the named volume */ | |
1737 | \endcode | |
1738 | \par Description | |
1739 | [Opcode 150] Given the numeric volume identifier contained in a volIDP, set | |
1740 | that volume's basic status information to the values contained in a | |
1741 | volStoreStatP. A full description of the fields settable by this call, | |
1742 | including the necessary masking, is found in Section 5.1.2.9. In addition, | |
1743 | three other items relating to the volume may be set. Non-null character strings | |
1744 | found in a volNameP, a offLineMsgP, and a motdP will be stored in the volume's | |
1745 | printable name, off-line message, and "Message of the Day" fields respectively. | |
1746 | The volume name provided must be less than AFSNAMEMAX (256) characters long, | |
1747 | and the other two strings must be less than AFSOPAQUEMAX (1,024) characters | |
1748 | long each. | |
1749 | \par | |
1750 | Rx connection information for the related File Server is contained in a | |
1751 | rxConnP. | |
1752 | \par Error Codes | |
1753 | EACCES The caller does not have the necessary access rights. | |
1754 | \n EINVAL A volume identifier of zero was specified. | |
1755 | ||
1756 | \subsubsection sec5-1-3-17 Section 5.1.3.17: RXAFS GetRootVolume - | |
1757 | Return the name of the root volume for the file system | |
1758 | ||
1759 | \code | |
1760 | int RXAFS GetRootVolume(IN struct rx connection *a rxConnP, | |
1761 | OUT char *a rootVolNameP) | |
1762 | \endcode | |
1763 | \par Description | |
1764 | [Opcode 151] Fetch the name of the volume which serves as the root of the AFS | |
1765 | file system and place it into a rootVolNameP. This name will always be less | |
1766 | than AFSNAMEMAX characters long. Any File Server will respond to this call, not | |
1767 | just the one hosting the root volume. The queried File Server first tries to | |
1768 | discover the name of the root volume by reading from the | |
1769 | /usr/afs/etc/RootVolume file on its local disks. If that file doesn't exist, | |
1770 | then it will return the default value, namely "root.afs". | |
1771 | \par | |
1772 | Rx connection information for the related File Server is contained in a | |
1773 | rxConnP. Volume version information is returned for synchronization purposes in | |
1774 | a volSyncP. | |
1775 | \par Error Codes | |
1776 | ---No error codes generated. | |
1777 | ||
1778 | \subsubsection sec5-1-3-18 5.1.3.18: RXAFS CheckToken - (Obsolete) | |
1779 | Check that the given user identifier matches the one in the supplied | |
1780 | authentication token | |
1781 | ||
1782 | \code | |
1783 | int RXAFS CheckToken(IN struct rx connection *a rxConnP, | |
1784 | IN long ViceId, | |
1785 | IN AFSOpaque *token) | |
1786 | \endcode | |
1787 | \par Description | |
1788 | [Opcode 152] This function only works for the now-obsolete RPC facility used by | |
1789 | AFS, R. For modern systems using the Rx RPC mechanism, we always get an error | |
1790 | return from this routine. | |
1791 | \par | |
1792 | Rx connection information for the related File Server is contained in a | |
1793 | rxConnP. | |
1794 | \par Error Codes | |
1795 | ECONNREFUSED Always returned on Rx connections. | |
1796 | ||
1797 | \subsubsection sec5-1-3-19 Section 5.1.3.19: RXAFS GetTime - Get the | |
1798 | File Server's time of day | |
1799 | ||
1800 | \code | |
1801 | int RXAFS GetTime(IN struct rx connection *a rxConnP, | |
1802 | OUT unsigned long *a secondsP, | |
1803 | OUT unsigned long *a uSecondsP) | |
1804 | \endcode | |
1805 | \par Description | |
1806 | [Opcode 153] Get the current time of day from the File Server specified in the | |
1807 | Rx connection information contained in a rxConnP. The time is returned in | |
1808 | elapsed seconds (a secondsP) and microseconds (a uSecondsP) since that standard | |
1809 | unix "start of the world". | |
1810 | \par Error Codes | |
1811 | ---No error codes generated. | |
1812 | ||
1813 | \subsubsection sec5-1-3-20 Section 5.1.3.20: RXAFS NGetVolumeInfo - Get | |
1814 | information about a volume given its name | |
1815 | ||
1816 | \code | |
1817 | int RXAFS NGetVolumeInfo(IN struct rx connection *a rxConnP, | |
1818 | IN char *a volNameP, | |
1819 | OUT AFSVolumeInfo *a volInfoP) | |
1820 | \endcode | |
1821 | \par Description | |
1822 | [Opcode 154] This function is identical to RXAFS GetVolumeInfo() (see Section | |
1823 | 5.1.3.14), except that it returns a struct AFSVolumeInfo instead of a struct | |
1824 | VolumeInfo. The basic difference is that struct AFSVolumeInfo also carries an | |
1825 | accompanying UDP port value for each File Server listed in the record. | |
1826 | ||
1827 | \subsubsection sec5-1-3-21 Section 5.1.3.21: RXAFS BulkStatus - Fetch | |
1828 | the status information regarding a set of given file system objects | |
1829 | ||
1830 | \code | |
1831 | int RXAFS BulkStatus(IN struct rx connection *a rxConnP, | |
1832 | IN AFSCBFids *a fidToStatArrayP, | |
1833 | OUT AFSBulkStats *a currStatArrayP, | |
1834 | OUT AFSCBs *a callBackArrayP, | |
1835 | OUT AFSVolSync *a volSyncP) | |
1836 | \endcode | |
1837 | \par Description | |
1838 | [Opcode 155] This routine is identical to RXAFS FetchStatus() as described in | |
1839 | Section 5.1.3.2, except for the fact that it allows the caller to ask for the | |
1840 | current status fields for a set of up to AFSCBMAX (50) file identifiers at | |
1841 | once. | |
1842 | \par | |
1843 | Rx connection information for the related File Server is contained in a | |
1844 | rxConnP. Volume version information is returned for synchronization purposes in | |
1845 | a volSyncP. | |
1846 | \par Error Codes | |
1847 | EACCES The caller does not have the necessary access rights. | |
1848 | \n EINVAL The number of file descriptors for which status information was | |
1849 | requested is illegal. | |
1850 | ||
1851 | \subsubsection sec5-1-3-22 Section 5.1.3.22: RXAFS SetLock - Set an | |
1852 | advisory lock on the given file identifier | |
1853 | ||
1854 | \code | |
1855 | int RXAFS SetLock(IN struct rx connection *a rxConnP, | |
1856 | IN AFSFid *a fidToLockP, | |
1857 | IN ViceLockType a lockType, | |
1858 | OUT AFSVolSync *a volSyncP) | |
1859 | \endcode | |
1860 | \par Description | |
1861 | [Opcode 156] Set an advisory lock on the file identified by a fidToLockP. There | |
1862 | are two types of locks that may be specified via a lockType: LockRead and | |
1863 | LockWrite. An advisory lock times out after AFS LOCKWAIT (5) minutes, and must | |
1864 | be extended in order to stay in force (see RXAFS ExtendLock(), Section | |
1865 | 5.1.3.23). | |
1866 | \par | |
1867 | Rx connection information for the related File Server is contained in a | |
1868 | rxConnP. Volume version information is returned for synchronization purposes in | |
1869 | a volSyncP. | |
1870 | \par Error Codes | |
1871 | EACCES The caller does not have the necessary access rights. | |
1872 | \n EINVAL An illegal lock type was specified. | |
1873 | \n EWOULDBLOCK The lock was already incompatibly granted to another party. | |
1874 | ||
1875 | \subsubsection sec5-1-3-23 Section 5.1.3.23: RXAFS ExtendLock - Extend | |
1876 | an advisory lock on a file | |
1877 | ||
1878 | \code | |
1879 | int RXAFS ExtendLock(IN struct rx connection *a rxConnP, | |
1880 | IN AFSFid *a fidToBeExtendedP, | |
1881 | OUT AFSVolSync *a volSyncP) | |
1882 | \endcode | |
1883 | \par Description | |
1884 | [Opcode 157] Extend the advisory lock that has already been granted to the | |
1885 | caller on the file identified by a fidToBeExtendedP. | |
1886 | \par | |
1887 | Rx connection information for the related File Server is contained in a | |
1888 | rxConnP. Volume version information is returned for synchronization purposes in | |
1889 | a volSyncP. | |
1890 | \par Error Codes | |
1891 | EINVAL The caller does not already have the given file locked. | |
1892 | ||
1893 | \subsubsection sec5-1-3-24 Section 5.1.3.24: RXAFS ReleaseLock - | |
1894 | Release the advisory lock on a file | |
1895 | ||
1896 | \code | |
1897 | int RXAFS ReleaseLock(IN struct rx connection *a rxConnP, | |
1898 | IN AFSFid *a fidToUnlockP, | |
1899 | OUT AFSVolSync *a volSyncP) | |
1900 | \endcode | |
1901 | \par Description | |
1902 | [Opcode 158] Release the advisory lock held on the file identified by a | |
1903 | fidToUnlockP. If this was the last lock on this file, the File Server will | |
1904 | break all existing callbacks to this file. | |
1905 | \par | |
1906 | Rx connection information for the related File Server is contained in a | |
1907 | rxConnP. Volume version information is returned for synchronization purposes in | |
1908 | a volSyncP. | |
1909 | \par Error Codes | |
1910 | EACCES The caller does not have the necessary access rights. | |
1911 | ||
1912 | \subsubsection sec5-1-3-25 Section 5.1.3.25: RXAFS XStatsVersion - Get | |
1913 | the version number associated with the File Server's extended statistics | |
1914 | structure | |
1915 | ||
1916 | \code | |
1917 | int RXAFS XStatsVersion(IN struct rx connection *a rxConnP, | |
1918 | OUT long *a versionNumberP) | |
1919 | \endcode | |
1920 | \par Description | |
1921 | [Opcode 159] This call asks the File Server for the current version number of | |
1922 | the extended statistics structures it exports (see RXAFS GetXStats(), Section | |
1923 | 5.1.3.26). The version number is placed into a versionNumberP. | |
1924 | \par | |
1925 | Rx connection information for the related File Server is contained in a | |
1926 | rxConnP. | |
1927 | \par Error Codes | |
1928 | ---No error codes generated. | |
1929 | ||
1930 | \subsubsection sec5-1-3-26 Section 5.1.3.26: RXAFS GetXStats - Get the | |
1931 | current contents of the specified extended statistics structure | |
1932 | ||
1933 | \code | |
1934 | int RXAFS GetXStats(IN struct rx connection *a rxConnP, | |
1935 | IN long a clientVersionNumber, | |
1936 | IN long a collectionNumber, | |
1937 | OUT long *a srvVersionNumberP, | |
1938 | OUT long *a timeP, | |
1939 | OUT AFS CollData *a dataP) | |
1940 | \endcode | |
1941 | \par Description | |
1942 | [Opcode 160] This function fetches the contents of the specified File Server | |
1943 | extended statistics structure. The caller provides the version number of the | |
1944 | data it expects to receive in a clientVersionNumber. Also provided in a | |
1945 | collectionNumber is the numerical identifier for the desired data collection. | |
1946 | There are currently two of these data collections defined: AFS XSTATSCOLL CALL | |
1947 | INFO, which is the list of tallies of the number of invocations of internal | |
1948 | File Server procedure calls, and AFS XSTATSCOLL PERF INFO, which is a list of | |
1949 | performance-related numbers. The precise contents of these collections are | |
1950 | described in Sections 5.1.2.7. The current version number of the File Server | |
1951 | collections is returned in a srvVersionNumberP, and is always set upon return, | |
1952 | even if the caller has asked for a difierent version. If the correct version | |
1953 | number has been specified, and a supported collection number given, then the | |
1954 | collection data is returned in a dataP. The time of collection is also | |
1955 | returned, being placed in a timeP. | |
1956 | \par | |
1957 | Rx connection information for the related File Server is contained in a | |
1958 | rxConnP. | |
1959 | \par Error Codes | |
1960 | ---No error codes are generated. | |
1961 | ||
1962 | \subsection sec5-1-4 Section 5.1.4: Streamed Function Calls | |
1963 | ||
1964 | \par | |
1965 | There are two streamed functions in the File Server RPC interface, used to | |
1966 | fetch and store arbitrary amounts of data from a file. While some non-streamed | |
1967 | calls pass such variable-length objects as struct AFSCBFids, these objects have | |
1968 | a pre-determined maximum size. | |
1969 | \par | |
1970 | The two streamed RPC functions are also distinctive in that their single Rxgen | |
1971 | declarations generate not one but two client-side stub routines. The first is | |
1972 | used to ship the IN parameters off to the designated File Server, and the | |
1973 | second to gather the OUT parameters and the error code. If a streamed | |
1974 | definition declares a routine named X YZ(), the two resulting stubs will be | |
1975 | named StartX YZ() and EndX YZ(). It is the application programmer's job to | |
1976 | first invoke StartX YZ(), then manage the unbounded data transfer, then finish | |
1977 | up by calling EndX YZ(). The first longword in the unbounded data stream being | |
1978 | fetched from a File Server contains the number of data bytes to follow. The | |
1979 | application then reads the specified number of bytes from the stream. | |
1980 | \par | |
1981 | The following sections describe the four client-side functions resulting from | |
1982 | the Fetch-Data() and StoreData() declarations in the Rxgen interface definition | |
1983 | file. These are the actual routines the application programmer will include in | |
1984 | the client code. For reference, here are the interface definitions that | |
1985 | generate these functions. Note that the split keyword is what causes Rxgen to | |
1986 | generate the separate start and end routines. In each case, the number after | |
1987 | the equal sign specifies the function's identifying opcode number. The opcode | |
1988 | is passed to the File Server by the StartRXAFS FetchData() and StartRXAFS | |
1989 | StoreData() stub routines. | |
1990 | ||
1991 | \code | |
1992 | FetchData(IN AFSFid *a_fidToFetchP, | |
1993 | IN long a_offset, | |
1994 | IN long a_lenInBytes, | |
1995 | OUT AFSFetchStatus *a_fidStatP, | |
1996 | OUT AFSCallBack *a_callBackP, | |
1997 | OUT AFSVolSync *a_volSyncP) split = 130; | |
1998 | ||
1999 | StoreData(IN AFSFid *Fid, | |
2000 | IN AFSStoreStatus *InStatus, | |
2001 | IN long Pos, | |
2002 | IN long Length, | |
2003 | IN long FileLength, | |
2004 | OUT AFSFetchStatus *OutStatus, | |
2005 | OUT AFSVolSync *a_volSyncP) split = 133; | |
2006 | \endcode | |
2007 | ||
2008 | \subsubsection sec5-1-4-1 Section 5.1.4.1: StartRXAFS FetchData - Begin | |
2009 | a request to fetch file data | |
2010 | ||
2011 | \code | |
2012 | int StartRXAFS FetchData(IN struct rx call *a rxCallP, | |
2013 | IN AFSFid *a fidToFetchP, | |
2014 | IN long a offset, | |
2015 | IN long a lenInBytes) | |
2016 | \endcode | |
2017 | ||
2018 | \par Description | |
2019 | Begin a request for a lenInBytes bytes of data starting at byte offset a offset | |
2020 | from the file identified by a fidToFetchP. After successful completion of this | |
2021 | call, the data stream will make the desired bytes accessible. The first | |
2022 | longword in the stream contains the number of bytes to actually follow. | |
2023 | \par | |
2024 | Rx call information to the related File Server is contained in a rxCallP. | |
2025 | \par Error Codes | |
2026 | ---No error codes generated. | |
2027 | ||
2028 | \subsubsection sec5-1-4-2 Section 5.1.4.2: EndRXAFS FetchData - | |
2029 | Conclude a request to fetch file data | |
2030 | ||
2031 | \code | |
2032 | int EndRXAFS FetchData(IN struct rx call *a rxCallP, | |
2033 | OUT AFSFetchStatus *a fidStatP, | |
2034 | OUT AFSCallBack *a callBackP, | |
2035 | OUT AFSVolSync *a volSyncP) | |
2036 | \endcode | |
2037 | \par Description | |
2038 | Conclude a request to fetch file data, as commenced by an StartRXAFS | |
2039 | FetchData() invocation. By the time this routine has been called, all of the | |
2040 | desired data has been read off the data stream. The status fields for the file | |
2041 | from which the data was read are stored in a fidStatP. If the file was from a | |
2042 | read/write volume, its callback information is placed in a callBackP. | |
2043 | \par | |
2044 | Rx call information to the related File Server is contained in a rxCallP. | |
2045 | Volume version information is returned for synchronization purposes in a | |
2046 | volSyncP. | |
2047 | \par Error Codes | |
2048 | EACCES The caller does not have the necessary access rights. EIO Given file | |
2049 | could not be opened or statted on the File Server, or there was an error | |
2050 | reading the given data off the File Server's disk. | |
2051 | \n -31 An Rx write into the stream ended prematurely. | |
2052 | ||
2053 | \subsubsection sec5-1-4-3 Section 5.1.4.3: StartRXAFS StoreData - Begin | |
2054 | a request to store file data | |
2055 | ||
2056 | \code | |
2057 | int StartRXAFS StoreData(IN struct rx call *a rxCallP, | |
2058 | IN AFSFid *a fidToStoreP, | |
2059 | IN reStatus *a fidStatusP, | |
2060 | IN AFSStolong a offset, | |
2061 | IN long a lenInBytes, | |
2062 | IN long a fileLenInBytes) | |
2063 | \endcode | |
2064 | \par Description | |
2065 | Begin a request to write a lenInBytes of data starting at byte offset a offset | |
2066 | to the file identified by a fidToStoreP, causing that file's length to become a | |
2067 | fileLenInBytes bytes. After successful completion of this call, the data stream | |
2068 | will be ready to begin accepting the actual data being written. | |
2069 | \par | |
2070 | Rx call information to the related File Server is contained in a rxCallP. | |
2071 | \par Error Codes | |
2072 | ---No error codes generated. | |
2073 | ||
2074 | \subsubsection sec5-1-4-4 Section 5.1.4.4: EndRXAFS StoreData - | |
2075 | Conclude a request to store file data | |
2076 | ||
2077 | \code | |
2078 | int EndRXAFS StoreData(IN struct rx call *a rxCallP, | |
2079 | OUT AFSFetchStatus *a fidStatP, | |
2080 | OUT AFSCallBack *a callBackP, | |
2081 | OUT AFSVolSync *a volSyncP) | |
2082 | \endcode | |
2083 | \par Description | |
2084 | Conclude a request to store file data, as commenced by a StartRXAFS StoreData() | |
2085 | invocation. By the time this routine has been called, all of the file data has | |
2086 | been inserted into the data stream. The status fields for the file to which the | |
2087 | data was written are stored in a fidStatP. All existing callbacks to the given | |
2088 | file are broken before the store concludes. | |
2089 | \par | |
2090 | Rx call information to the related File Server is contained in a rxCallP. | |
2091 | Volume version information is returned for synchronization purposes in a | |
2092 | volSyncP. | |
2093 | \par Error Codes | |
2094 | EACCES The caller does not have the necessary access rights. | |
2095 | \n EISDIR The file being written to is a symbolic link. | |
2096 | \n ENOSPEC A write to the File Server's file on local disk failed. | |
2097 | \n -32 A short read was encountered by the File Server on the data stream. | |
2098 | ||
2099 | \subsection sec5-1-5 Section 5.1.5: Example of Streamed Function Call | |
2100 | Usage | |
2101 | ||
2102 | \subsubsection sec5-1-5-1 Section 5.1.5.1: Preface | |
2103 | ||
2104 | \par | |
2105 | The following code fragment is offered as an example of how to use the streamed | |
2106 | File Server RPC calls. In this case, a client fetches some amount of data from | |
2107 | the given File Server and writes it to a local file it uses to cache the | |
2108 | information. For simplicity, many issues faced by a true application programmer | |
2109 | are not addressed here. These issues include locking, managing file chunking, | |
2110 | data version number mismatches, volume location, Rx connection management, | |
2111 | defensive programming (e.g., checking parameters before using them), | |
2112 | client-side cache management algorithms, callback management, and full error | |
2113 | detection and recovery. Pseudocode is incorporated when appropriate to keep the | |
2114 | level of detail reasonable. For further descriptions of some of these details | |
2115 | and issues, the reader is referred to such companion documents as AFS-3 | |
2116 | Programmer's Reference: Specification for the Rx Remote Procedure Call | |
2117 | Facility, AFS-3 Programmer's Reference:Volume Server/Volume Location Server | |
2118 | Interface, and AFS-3 Programmer's Reference: Architectural Overview. | |
2119 | \par | |
2120 | A discussion of the methods used within the example code fragment follows | |
2121 | immediately afterwards in Section 5.1.5.3. | |
2122 | ||
2123 | \subsubsection sec5-1-5-2 Section 5.1.5.2: Code Fragment Illustrating | |
2124 | Fetch Operation | |
2125 | ||
2126 | \code | |
2127 | int code; /*Return code*/ | |
2128 | long bytesRead; /*Num bytes read from Rx*/ | |
2129 | struct myConnInfo *connP; /*Includes Rx conn info*/ | |
2130 | struct rx_call *rxCallP; /*Rx call ptr*/ | |
2131 | struct AFSFid *afsFidP; /*Fid for file to fetch*/ | |
2132 | int lclFid; /*Fid for local cache file*/ | |
2133 | long offsetBytes; /*Starting fetch offset*/ | |
2134 | long bytesToFetch; /*Num bytes to fetch*/ | |
2135 | long bytesFromFS; /*Num bytes FileServer returns*/ | |
2136 | char *fetchBuffP; /*Buffer to hold stream data*/ | |
2137 | int currReadBytes; /*Num bytes for current read*/ | |
2138 | /* | |
2139 | * Assume that connP, afsFidP, offsetBytes, lclFid,and | |
2140 | * bytesToFetch have all been given their desired values. | |
2141 | */ . . . | |
2142 | rxCallP = rx_NewCall(connP->rxConnP); | |
2143 | code = StartRXAFS_FetchData( rxCallP, /*Rx call to use*/ | |
2144 | afsFidP, /*Fid being fetched from*/ | |
2145 | offsetBytes, /*Offset in bytes*/ | |
2146 | bytesToFetch); /*Num bytes wanted*/ | |
2147 | if (code == 0) | |
2148 | { | |
2149 | bytesRead = rx_Read(rxCallP, &bytesFromFS, sizeof(long)); | |
2150 | if (bytesRead != sizeof(long)) ExitWithError(SHORT_RX_READ); | |
2151 | bytesFromFS = ntohl(bytesFromFS); | |
2152 | xmitBuffer = malloc(FETCH_BUFF_BYTES); | |
2153 | lclFid = open(CacheFileName, O_RDWR, mode); | |
2154 | pos = lseek(lclFid, offsetBytes, L_SET); | |
2155 | while (bytesToFetch > 0) { | |
2156 | currReadBytes = (bytesToFetch > FETCH_BUFF_BYTES) ? | |
2157 | FETCH_BUFF_BYTES : bytesToFetch; | |
2158 | bytesRead = rx_Read(rxCallP, fetchBuffP, currReadBytes); | |
2159 | if (bytesRead != currReadBytes) ExitWithError(SHORT_RX_READ); | |
2160 | code = write(lclFid, fetchBuffP, currReadBytes); | |
2161 | if (code) ExitWithError(LCL_WRITE_FAILED); | |
2162 | bytesToFetch -= bytesRead; | |
2163 | } /*Read from the Rx stream*/ | |
2164 | close(lclFid); | |
2165 | } else ExitWithError(code); | |
2166 | code = EndRXAFS_FetchData( rxCallP, /*Rx call to use*/ | |
2167 | fidStatP, /*Resulting stat fields*/ | |
2168 | fidCallBackP, /*Resulting callback info*/ | |
2169 | volSynchP); /*Resulting volume sync info*/ | |
2170 | code = rx_EndCall(rxCallP, code); | |
2171 | return(code); . . . | |
2172 | \endcode | |
2173 | ||
2174 | \subsubsection sec5-1-5-3 Section 5.1.5.3: Discussion and Analysis | |
2175 | ||
2176 | \par | |
2177 | The opening assumption in this discussion is that all the information required | |
2178 | to do the fetch has already been set up. These mandatory variables are the | |
2179 | client-side connection information for the File Server hosting the desired | |
2180 | file, the corresponding AFS file identifier, the byte offset into the file, the | |
2181 | number of bytes to fetch, and the identifier for the local file serving as a | |
2182 | cached copy. | |
2183 | \par | |
2184 | Given the Rx connection information stored in the client's connP record, rx | |
2185 | NewCall() is used to create a new Rx call to handle this fetch operation. The | |
2186 | structure containing this call handle is placed into rxCallP. This call handle | |
2187 | is used immediately in the invocation of StartRXAFS FetchData(). If this setup | |
2188 | call fails, the fragment exits. Upon success, though, the File Server will | |
2189 | commence writing the desired data into the Rx data stream. The File Server | |
2190 | first writes a single longword onto the stream announcing to the client how | |
2191 | many bytes of data will actually follow. The fragment reads this number with | |
2192 | its first rx Read() call. Since all Rx stream data is written in network byte | |
2193 | order, the fragment translates the byte count to its own host byte order first | |
2194 | to properly interpret it. Once the number of bytes to appear on the stream is | |
2195 | known, the client code proceeds to open the appropriate cache file on its own | |
2196 | local disk and seeks to the appropriate spot within it. A buffer into which the | |
2197 | stream data will be placed is also created at this time. | |
2198 | \par | |
2199 | The example code then falls into a loop where it reads all of the data from the | |
2200 | File Server and stores it in the corresponding place in the local cache file. | |
2201 | For each iteration, the code decides whether to read a full buffer's worth or | |
2202 | the remaining number of bytes, whichever is smaller. After all the data is | |
2203 | pulled off the Rx stream, the local cache file is closed. At this point, the | |
2204 | example finishes off the RPC by calling EndRXAFS FetchData(). This gathers in | |
2205 | the required set of OUT parameters, namely the status fields for the file just | |
2206 | fetched, callback and volume synchronization information, and the overall error | |
2207 | code for the streamed routine. The Rx call created to perform the fetch is then | |
2208 | terminated and cleaned up by invoking rx EndCall(). | |
2209 | ||
2210 | \subsection sec5-1-6 Section 5.1.6: Required Caller Functionality | |
2211 | ||
2212 | \par | |
2213 | The AFS File Server RPC interface was originally designed to interact only with | |
2214 | Cache Manager agents, and thus made some assumptions about its callers. In | |
2215 | particular, the File Server expected that the agents calling it would | |
2216 | potentially have stored callback state on file system objects, and would have | |
2217 | to be periodically pinged in order to garbage-collect its records, removing | |
2218 | information on dead client machines. Thus, any entity making direct calls to | |
2219 | this interface must mimic certain Cache Manager actions, and respond to certain | |
2220 | Cache Manager RPC interface calls. | |
2221 | \par | |
2222 | To be safe, any application calling the File Server RPC interface directly | |
2223 | should export the entire Cache Manager RPC interface. Realistically, though, it | |
2224 | will only need to provide stubs for the three calls from this interface that | |
2225 | File Servers know how to make: RXAFSCB InitCallBackState(), RXAFSCB Probe() and | |
2226 | RXAFSCB CallBack(). The very first File Server call made by this application | |
2227 | will prompt the given File Server to call RXAFSCB InitCallBackState(). This | |
2228 | informs the application that the File Server has no record of its existence and | |
2229 | hence this "Cache Manager" should clear all callback information for that | |
2230 | server. Once the application responds positively to the inital RXAFSCB | |
2231 | InitCallBackState(), the File Server will treat it as a bona fide, | |
2232 | fully-fledged Cache Manager, and probe it every so often with RXAFSCB Probe() | |
2233 | calls to make sure it is still alive. | |
2234 | ||
2235 | \section sec5-2 Section 5.2: Signal Interface | |
2236 | ||
2237 | \par | |
2238 | While the majority of communication with AFS File Servers occurs over the RPC | |
2239 | interface, some important operations are invoked by sending unix signals to the | |
2240 | process. This section describes the set of signals recognized by the File | |
2241 | Server and the actions they trigger upon receipt, as summarized below: | |
2242 | \li SIGQUIT: Shut down a File Server. | |
2243 | \li SIGTSTP: Upgrade debugging output level. | |
2244 | \li SIGHUP: Reset debugging output level. | |
2245 | \li SIGTERM: Generate debugging output specifically concerning open files | |
2246 | within the File Server process. | |
2247 | ||
2248 | \subsection sec5-2-1 Section 5.2.1: SIGQUIT: Server Shutdown | |
2249 | ||
2250 | \par | |
2251 | Upon receipt of this signal, the File Server shuts itself down in an orderly | |
2252 | fashion. It first writes a message to the console and to its log file | |
2253 | (/usr/afs/logs/FileLog) stating that a shutdown has commenced. The File Server | |
2254 | then flushes all modified buffers and prints out a set of internal statistics, | |
2255 | including cache and disk numbers. Finally, each attached volume is taken | |
2256 | offline, which means the volume header is written to disk with the appropriate | |
2257 | bits set. | |
2258 | \par | |
2259 | In typical usage, human operators do not send the SIGQUIT signal directly to | |
2260 | the File Server in order to affect an orderly shutdown. Rather, the BOS Server | |
2261 | managing the server processes on that machine issues the signal upon receipt of | |
2262 | a properly-authorized shutdown RPC request. | |
2263 | ||
2264 | \subsection sec5-2-2 Section 5.2.2: SIGTSTP: Upgrade Debugging Level | |
2265 | ||
2266 | \par | |
2267 | Arrival of a SIGTSTP signal results in an increase of the debugging level used | |
2268 | by the File Server. The routines used for writing to log files are sensitive to | |
2269 | this debugging level, as recorded in the global LogLevel variable. | |
2270 | Specifically, these routines will only generate output if the value of LogLevel | |
2271 | is greater than or equal to the value of its threshold parameter. By default, | |
2272 | the File Server sets LogLevel to zero upon startup. If a SIGTSTP signal is | |
2273 | received when the debugging level is zero, it will be bumped to 1. If the | |
2274 | signal arrives when the debugging level is positive, its value will be | |
2275 | multiplied by 5. Thus, as more SIGTSTPs are received, the set of debugging | |
2276 | messages eligible to be delivered to log files grows. | |
2277 | \par | |
2278 | Since the SIGTSTP signal is not supported under IBM's AIX 2.2.1 operating | |
2279 | system, this form of debugging output manipulation is not possible on those | |
2280 | platforms. | |
2281 | ||
2282 | \subsection sec5-2-3 Section 5.2.3: SIGHUP: Reset Debugging Level | |
2283 | ||
2284 | \par | |
2285 | Receiving a SIGHUP signal causes a File Server to reset its debugging level to | |
2286 | zero. This effectively reduces the set of debugging messages eligible for | |
2287 | delivery to log files to a bare minimum. This signal is used in conjunction | |
2288 | with SIGTSTP to manage the verbosity of log information. | |
2289 | \par | |
2290 | Since the SIGHUP signal is not supported under IBM's AIX 2.2.1 operating | |
2291 | system, this form of debugging output manipulation is not possible on those | |
2292 | platforms. | |
2293 | ||
2294 | \subsection sec5-2-4 Section 5.2.4: SIGTERM: File Descriptor Check | |
2295 | ||
2296 | \par | |
2297 | Receipt of a SIGTERM signal triggers a routine which sweeps through the given | |
2298 | File Server's unix file descriptors. For each possible unix fid slot, an | |
2299 | fstat() is performed on that descriptor, and the particulars of each open file | |
2300 | are printed out. This action is designed solely for debugging purposes. | |
2301 | ||
2302 | \section sec5-3 Section 5.3: Command Line Interface | |
2303 | ||
2304 | \par | |
2305 | Another interface exported by the File Server is the set of command line | |
2306 | switches it accepts. Using these switches, many server parameters and actions | |
2307 | can be set. Under normal conditions, the File Server process is started up by | |
2308 | the BOS Server on that machine, as described in AFS-3 Programmer's Reference: | |
2309 | BOS Server Interface. So, in order to utilize any combination of these | |
2310 | command-line options, the system administrator must define the File Server | |
2311 | bnode in such a way that these parameters are properly included. Note that the | |
2312 | switch names must be typed exactly as listed, and that abbreviations are not | |
2313 | allowed. Thus, specifying -b 300 on the command line is unambiguous, directing | |
2314 | that 300 buffers are to be allocated. It is not an abbreviation for the -banner | |
2315 | switch, asking that a message is to be printed to the console periodically. | |
2316 | \par | |
2317 | A description of the set of currently-supported command line switches follows. | |
2318 | \li -b <# buffers> Choose the number of 2,048-byte data buffers to allocate at | |
2319 | system startup. If this switch is not provided, the File Server will operate | |
2320 | with 70 such buffers by default. | |
2321 | \li -banner This switch instructs the File Server to print messages to the | |
2322 | console every 10 minutes to demonstrate it is still running correctly. The text | |
2323 | of the printed message is: File Server is running at <time>. | |
2324 | \li -cb <# callbacks stored> Specify the maximum number of callback records | |
2325 | stored simultaneously by the File Server. The default pool size is 20,000 | |
2326 | records. | |
2327 | \li -d <debug level> Set the debugging output level at which File Server runs | |
2328 | to the value provided. Specifically, the LogLevel global variable is set to the | |
2329 | given value (See Section 5.2.2). If this switch is not provided, the default | |
2330 | initial File Server debugging level is set to zero, producing the minimal | |
2331 | debugging output to the log files. | |
2332 | \li -k <stack size> Set the stack size to provide server LWPs upon creation, | |
2333 | measured in 1,024-byte blocks. The default LWP stack size is 24 blocks, or | |
2334 | 24,576 bytes. | |
2335 | \li -l <large (directory) vnodes> Select the number of "large" vnodes the File | |
2336 | Server will cache. These vnodes are suitable for recording information about | |
2337 | AFS directories. The extra space in the vnode allows ACL information to be | |
2338 | stored along with the directory. The default allocation value is 200 directory | |
2339 | vnodes. | |
2340 | \li -pctspare <percent overrun blocks past quota> Similar to the -spare switch, | |
2341 | except that the number of allowable overrun blocks is expressed as a percentage | |
2342 | of the given volume's quota. Note: this switch cannot be used in combination | |
2343 | with the -spare switch. | |
2344 | \li -rxdbg Instruct the File Server to open a file named rx dbg in the current | |
2345 | directory, into which the Rx package will write general debugging information. | |
2346 | If the file is already open (due to the appearance of the -rxdbge switch | |
2347 | earlier in the command line), this results in a no-op. | |
2348 | \li -rxdbge Instruct the File Server to open a file named rx dbg in the current | |
2349 | directory, into which the Rx package will write debugging information related | |
2350 | to its event-scheduling activities. If the file is already open (due to the | |
2351 | appearance of the -rxdbg switch earlier in the command line), this results in a | |
2352 | no-op. | |
2353 | \li -rxpck <# packets> Set the number of extra Rx packet buffers to hold in | |
2354 | reserve. These pre-allocated buffers assist in responding to spikes in network | |
2355 | traffic demands. By default, 100 such packet buffers are maintained. | |
2356 | \li -s <small (file) vnodes> Select the number of "small" vnodes the File | |
2357 | Server will cache. These vnodes are suitable for recording information about | |
2358 | non-directory files. As with directory vnodes, the File Server will allocate | |
2359 | 200 small vnodes by default. | |
2360 | \li -spare <# overrun blocks to allow> Tell the File Server to allow users | |
2361 | performing a store operation to overrun the host volume's disk quota by a | |
2362 | certain number of (1,024-byte) blocks. In other words, the first store | |
2363 | resulting in a quota overrun will be allowed to succeed if and only if it uses | |
2364 | no more than these many blocks beyond the quota. Further store operations will | |
2365 | be rejected until the volume's storage is once again reduced below quota. By | |
2366 | default, overruns of 1,024 blocks of 1,024 bytes each (1 megabyte total) are | |
2367 | tolerated. Note: this switch cannot be used in combination with the -pctspare | |
2368 | switch. | |
2369 | \li -w <callback wait interval in seconds> This switch determines how often the | |
2370 | File Server periodic daemon lightweight processes run. Among other things, | |
2371 | these daemon LWPs check on the validity of callback records, keep disk usage | |
2372 | statistics up to date, and check the health of the various client machines that | |
2373 | have previously interacted with the File Server. For a full description of | |
2374 | these daemon LWPs, consult Section 2.3. The associated argument specifies the | |
2375 | number of seconds to sleep between daemon invocations. By default, these | |
2376 | periodic daemons run every 300 seconds (5 minutes). | |
2377 | ||
2378 | \page chap6 Chapter 6: Cache Manager Interfaces | |
2379 | ||
2380 | \section sec6-1 Section 6.1: Overview | |
2381 | ||
2382 | \par | |
2383 | There are several interfaces offered by the Cache Manager, allowing clients to | |
2384 | access the files stored by the community of AFS File Servers, to configure the | |
2385 | Cache Manager's behavior and resources, to store and retrieve authentication | |
2386 | information, to specify the location of community Authentication Server and | |
2387 | Volume Location Server services, and to observe and debug the Cache Manager's | |
2388 | state and actions. This chapter will cover the following five interfaces to the | |
2389 | Cache Manager: | |
2390 | \li ioctl(): The standard unix ioctl() system call has been extended to | |
2391 | include more operations, namely waiting until data stores to a File Server | |
2392 | complete before returning to the caller (VIOCCLOSEWAIT) and getting the name of | |
2393 | the cell in which an open file resides (VIOCIGETCELL). | |
2394 | \li pioctl(): An additional system call is provided through which | |
2395 | applications can access operations specific to AFS, which are often tied to a | |
2396 | particular pathname. These operations include Access Control List (ACL) and | |
2397 | mount point management, Kerberos ticket management, cache configuration, cell | |
2398 | configuration, and status of File Servers. | |
2399 | \li RPC: Interface by which outside servers and investigators can | |
2400 | manipulate the Cache Manager. There are two main categories of routines: | |
2401 | callback management, typically called by the File Server, and | |
2402 | debugging/statistics, called by programs such as cmdebug and via the xstat | |
2403 | user-level library for collection of extended statistics. | |
2404 | \li Files: Much of the Cache Manager's configuration information, as well | |
2405 | as its view of the AFS services available from the outside world, is obtained | |
2406 | from parsing various files. One set of these files is typically located in | |
2407 | /usr/vice/etc, and includes CellServDB, ThisCell, and cacheinfo. Another set is | |
2408 | usually found in /usr/vice/cache, namely CacheItems, VolumeItems, and AFSLog. | |
2409 | \li Mariner: This is the interface by which file transfer activity between | |
2410 | the Cache Manager and File Servers may be monitored. Specifically, it is used | |
2411 | to monitor the names of the files and directories being fetched and/or stored | |
2412 | over the network. | |
2413 | \par | |
2414 | Another important component not described in this document is the afsd program. | |
2415 | It is afsd's job to initialize the Cache Manager on a given machine and to | |
2416 | start up its related daemon threads. It accepts a host of configuration | |
2417 | decisions via its command-line interface. In addition, it parses some of the | |
2418 | information kept in the configuration files mentioned above and passes that | |
2419 | information to the Cache Manager. The reader may find a full description of | |
2420 | afsd in the AFS 3.0 Command Reference Manual[2]. | |
2421 | ||
2422 | \section sec6-2 Section 6.2: Definitions | |
2423 | ||
2424 | \par | |
2425 | This section defines data structures that are used by the pioctl() calls. | |
2426 | ||
2427 | \subsection sec6-2-1 Section 6.2.1: struct VenusFid | |
2428 | ||
2429 | \par | |
2430 | The Cache Manager is the sole active AFS agent aware of the cellular | |
2431 | architecture of the system. Since AFS file identifiers are not guaranteed to be | |
2432 | unique across cell boundaries, it must further qualify them for its own | |
2433 | internal bookkeeping. The struct VenusFid provides just such additional | |
2434 | qualification, attaching the Cache Manager's internal cell identifier to the | |
2435 | standard AFS fid. | |
2436 | \n \b Fields | |
2437 | \li long Cell - The internal identifier for the cell in which the file resides. | |
2438 | \li struct ViceFid Fid - The AFS file identifier within the above cell. | |
2439 | ||
2440 | \subsection sec6-2-2 Section 6.2.2: struct ClearToken | |
2441 | ||
2442 | \par | |
2443 | This is the clear-text version of an AFS token of identity. Its fields are | |
2444 | encrypted into the secret token format, and are made easily available to the | |
2445 | Cache Manager in this structure. | |
2446 | \n \b Fields | |
2447 | \li long AuthHandle - Key version number. | |
2448 | \li char HandShakeKey[8] - Session key. | |
2449 | \li long ViceId - Identifier for the AFS principal represented by this token. | |
2450 | \li long BeginTimestamp - Timestamp of when this token was minted, and hence | |
2451 | came into effect. | |
2452 | \li long EndTimestamp - Timestamp of when this token is considered to be | |
2453 | expired, and thus disregarded. | |
2454 | ||
2455 | \section sec6-3 Section 6.3: ioctl() Interface | |
2456 | ||
2457 | \par | |
2458 | The standard unix ioctl() system call performs operations on file system | |
2459 | objects referenced with an open file descriptor. AFS has augmented this system | |
2460 | call with two additional operations, one to perform "safe stores", and one to | |
2461 | get the name of the cell in which a file resides. A third ioctl() extension is | |
2462 | now obsolete, namely aborting a store operation currently in progress. | |
2463 | ||
2464 | \subsection sec6-3-1 Section 6.3.1: VIOCCLOSEWAIT | |
2465 | ||
2466 | \par | |
2467 | [Opcode 1] Normally, a client performing a unix close() call on an AFS file | |
2468 | resumes once the store operation on the given file data to the host File Server | |
2469 | has commenced but before it has completed. Thus, it is possible that the store | |
2470 | could actually fail (say, because of network partition or server crashes) | |
2471 | without the client's knowledge. This new ioctl opcode specifies to the Cache | |
2472 | Manager that all future close() operations will wait until the associated store | |
2473 | operation to the File Server has completed fully before returning. | |
2474 | ||
2475 | \subsection sec6-3-2 Section 6.3.2: VIOCABORT | |
2476 | ||
2477 | \par | |
2478 | [Opcode 2] This ioctl() extension is now obsolete. This call results in a noop. | |
2479 | The original intention of this call was to allow a store operation currently in | |
2480 | progress to a File Server on the named fid to be aborted. | |
2481 | ||
2482 | \subsection sec6-3-3 Section 6.3.3: VIOIGETCELL | |
2483 | ||
2484 | \par | |
2485 | [Opcode 3] Get the name of the cell in which the given fid resides. If the file | |
2486 | is not an AFS file, then ENOTTY is returned. The output buffer specified in the | |
2487 | data area must be large enough to hold the null-terminated string representing | |
2488 | the file's cell, otherwise EFAULT is returned. However, an out size value of | |
2489 | zero specifies that the cell name is not to be copied into the output buffer. | |
2490 | In this case, the caller is simply interested in whether the file is in AFS, | |
2491 | and not its exact cell of residence. | |
2492 | ||
2493 | \section sec6-4 Section 6.4: pioctl() Interface | |
2494 | ||
2495 | \subsection sec6-4-1 Section 6.4.1: Introduction | |
2496 | ||
2497 | \par | |
2498 | There is a new unix system call, pioctl(), which has been defined especially to | |
2499 | support the AFS Cache Manager. Its functional definition is as follows: | |
2500 | \code | |
2501 | int afs syscall pioctl(IN char *a pathP, | |
2502 | IN int a opcode, | |
2503 | IN struct ViceIoctl *a paramsP, | |
2504 | IN int a followSymLinks) | |
2505 | \endcode | |
2506 | \par | |
2507 | This new call is much like the standard ioctl() call, but differs in that the | |
2508 | affected file (when applicable) is specified by its path, not by a file | |
2509 | descriptor. Another difference is the fourth parameter, a followSymLinks, | |
2510 | determines which file should be used should a pathP be a symbolic link. If a | |
2511 | followSymLinks be set to 1, then the symbolic link is followed to its target, | |
2512 | and the pioctl() is applied to that resulting file. If a followSymLinks is set | |
2513 | to 0, then the pioctl() applies to the symbolic link itself. | |
2514 | \par | |
2515 | Not all pioctl() calls affect files. In those cases, the a pathP parameter | |
2516 | should be set to a null pointer. The second parameter to pioctl(), a opcode, | |
2517 | specifies which operation is to be performed. The opcode for each of these | |
2518 | operations is included in the text of the description. Note that not all | |
2519 | pioctl() opcodes are in use. These unused values correspond to obsolete | |
2520 | operations. | |
2521 | \par | |
2522 | The descriptions that follow identify some of the possible error codes for each | |
2523 | pioctl() opcode, but do not offer a comprehensive lists. All pioctl() calls | |
2524 | return 0 upon success. | |
2525 | \par | |
2526 | The rest of this section proceeds to describe the individual opcodes available. | |
2527 | First, though, one asymmetry in this opcode set is pointed out, namely that | |
2528 | while various operations are defined on AFS mount points, there is no direct | |
2529 | way to create a mount point. | |
2530 | \par | |
2531 | This documentation partitions the pioctl() into several groups: | |
2532 | \li Volume operations | |
2533 | \li File Server operations | |
2534 | \li Cell Operations | |
2535 | \li Authentication Operations | |
2536 | \li ACL Operations | |
2537 | \li Cache operations | |
2538 | \li Miscellaneous operations | |
2539 | ||
2540 | \par | |
2541 | For all pioctl()s, the fields within the a paramsP parameter will be referred | |
2542 | to directly. Thus, the values of in, in size, out, and out size are discussed, | |
2543 | rather than the settings for a paramsP->in, a paramsP->in size, a paramsP->out, | |
2544 | and a paramsP->out size. | |
2545 | \par | |
2546 | For convenience of reference, a list of the actively-supported pioctl()s, their | |
2547 | opcodes, and brief description appears (in opcode order) below. | |
2548 | \li [1] VIOCSETAL : Set the ACL on a directory | |
2549 | \li [2] VIOCGETAL : Get the ACL for a directory | |
2550 | \li [3] VIOCSETTOK : Set the caller's token for a cell | |
2551 | \li [4] VIOCGETVOLSTAT : Get volume status | |
2552 | \li [5] VIOCSETVOLSTAT : Set volume status | |
2553 | \li [6] VIOCFLUSH : Flush an object from the cache | |
2554 | \li [8] VIOCGETTOK : Get the caller's token for a cell | |
2555 | \li [9] VIOCUNLOG : Discard authentication information | |
2556 | \li [10] VIOCCKSERV : Check the status of one or more File Servers | |
2557 | \li [11] VIOCCKBACK : Mark cached volume info as stale | |
2558 | \li [12] VIOCCKCONN : Check caller's tokens/connections | |
2559 | \li [14] VIOCWHEREIS : Find host(s) for a volume | |
2560 | \li [20] VIOCACCESS : Check caller's access on object | |
2561 | \li [21] VIOCUNPAG : See [9] VIOCUNLOG | |
2562 | \li [22] VIOCGETFID : Get fid for named object | |
2563 | \li [24] VIOCSETCACHESIZE : Set maximum cache size in blocks | |
2564 | \li [25] VIOCFLUSHCB : Unilaterally drop a callback | |
2565 | \li [26] VIOCNEWCELL : Set cell service information | |
2566 | \li [27] VIOCGETCELL : Get cell configuration entry | |
2567 | \li [28] VIOCAFS DELETE MT PT : Delete a mount point | |
2568 | \li [29] VIOC AFS STAT MT PT : Get the contents of a mount point | |
2569 | \li [30] VIOC FILE CELL NAME : Get cell hosting a given object | |
2570 | \li [31] VIOC GET WS CELL : Get caller's home cell name | |
2571 | \li [32] VIOC AFS MARINER HOST : Get/set file transfer monitoring output | |
2572 | \li [33] VIOC GET PRIMARY CELL : Get the caller's primary cell | |
2573 | \li [34] VIOC VENUSLOG : Enable/disable Cache Manager logging | |
2574 | \li [35] VIOC GETCELLSTATUS : Get status info for a cell entry | |
2575 | \li [36] VIOC SETCELLSTATUS : Set status info for a cell entry | |
2576 | \li [37] VIOC FLUSHVOLUME : Flush cached data from a volume | |
2577 | \li [38] VIOC AFS SYSNAME : Get/set the @sys mapping | |
2578 | \li [39] VIOC EXPORTAFS : Enable/disable NFS/AFS translation | |
2579 | \li [40] VIOCGETCACHEPARAMS : Get current cache parameter values | |
2580 | ||
2581 | \subsection sec6-4-2 Section 6.4.2: Mount Point Asymmetry | |
2582 | ||
2583 | \par | |
2584 | There is an irregularity which deserves to be mentioned regarding the pioctl() | |
2585 | interface. There are pioctl() operations for getting information about a mount | |
2586 | point (VIOC AFS STAT MT PT) and for deleting a mount point (VIOC AFS DELETE MT | |
2587 | PT), but no operation for creating mount points. To create a mount point, a | |
2588 | symbolic link obeying a particular format must be created. The first character | |
2589 | must be either a "%" or a "#", depending on the type of mount point being | |
2590 | created (see the discussion in Section 6.4.4.4). If the mount point carries the | |
2591 | name of the cell explicitly, the full cell name will appear next, followed by a | |
2592 | colon. In all cases, the next portion of the mount point is the volume name. By | |
2593 | convention, the last character of a mount point must always be a period ("."). | |
2594 | This trailing period is not visible in the output from fs lsmount. | |
2595 | ||
2596 | \subsection sec6-4-3 Section 6.4.3: Volume Operations | |
2597 | ||
2598 | \par | |
2599 | There are several pioctl() opcodes dealing with AFS volumes. It is possible to | |
2600 | get and set volume information (VIOCGETVOLSTAT, VIOCSETVOLSTAT), discover which | |
2601 | volume hosts a particular file system object (VIOCWHEREIS), remove all objects | |
2602 | cached from a given volume (VIOC FLUSHVOLUME), and revalidate cached volume | |
2603 | information (VIOCCKBACK). | |
2604 | ||
2605 | \subsubsection sec6-4-3-1 Section 6.4.3.1: VIOCGETVOLSTAT: Get volume | |
2606 | status for pathname | |
2607 | ||
2608 | \par | |
2609 | [Opcode 4] Fetch information concerning the volume that contains the file | |
2610 | system object named by a pathP. There is no other input for this call, so in | |
2611 | size should be set to zero. The status information is placed into the buffer | |
2612 | named by out, if out size is set to a value of sizeof(struct VolumeStatus) or | |
2613 | larger. Included in the volume information are the volume's ID, quota, and | |
2614 | number of blocks used in the volume as well as the disk partition on which it | |
2615 | resides. Internally, the Cache Manager calls the RXAFS GetVolumeInfo() RPC (See | |
2616 | Section 5.1.3.14) to fetch the volume status. | |
2617 | \par | |
2618 | Among the possible error returns, EINVAL indicates that the object named by a | |
2619 | pathP could not be found. | |
2620 | ||
2621 | \subsubsection sec6-4-3-2 Section 6.4.3.2: VIOCSETVOLSTAT: Set volume | |
2622 | status for pathname | |
2623 | ||
2624 | \par | |
2625 | [Opcode 5] Set the status fields for the volume hosting the file system object | |
2626 | named by a pathP. The first object placed into the input buffer in is the new | |
2627 | status image. Only those fields that may change, namely MinQuota and MaxQuota | |
2628 | fields, are interpreted upon receipt by the File Server, and are set to the | |
2629 | desired values. Immediately after the struct VolumeStatus image, the caller | |
2630 | must place the null-terminated string name of the volume involved in the input | |
2631 | buffer. New settings for the offline message and MOTD (Message of the Day) | |
2632 | strings may appear after the volume name. If there are no changes in the | |
2633 | offline and/or MOTD messages, a null string must appear for that item. The in | |
2634 | size parameter must be set to the total number of bytes so inserted, including | |
2635 | the nulls after each string. Internally, the Cache Manager calls the RXAFS | |
2636 | SetVolumeStatus() RPC (See Section 5.1.3.16) to store the new volume status. | |
2637 | \par | |
2638 | Among the possible error returns, EINVAL indicates that the object named by a | |
2639 | pathP could not be found. | |
2640 | ||
2641 | \subsubsection sec6-4-3-3 Section 6.4.3.3: VIOCWHEREIS: Find the | |
2642 | server(s) hosting the pathname's volume | |
2643 | ||
2644 | \par | |
2645 | [Opcode 14] Find the set of machines that host the volume in which the file | |
2646 | system object named by a pathP resides. The input buffer in is not used by this | |
2647 | call, so in size should be set to zero. The output buffer indicated by out is | |
2648 | filled with up to 8 IP addresses, one for each File Server hosting the | |
2649 | indicated volume. Thus, out size should be set to at least (8*sizeof(long)). | |
2650 | This group of hosts is terminated by the first zeroed IP address that appears | |
2651 | in the list, but under no circumstances are more than 8 host IP addresses | |
2652 | returned. | |
2653 | \par | |
2654 | Among the possible error returns is EINVAL, indicating that the pathname is not | |
2655 | in AFS, hence is not contained within a volume. If ENODEV is returned, the | |
2656 | associated volume information could not be obtained. | |
2657 | ||
2658 | \subsubsection sec6-4-3-4 Section 6.4.3.4: VIOC FLUSHVOLUME: Flush all | |
2659 | data cached from the pathname's volume | |
2660 | ||
2661 | \par | |
2662 | [Opcode 37] Determine the volume in which the file system object named by a | |
2663 | pathP resides, and then throw away all currently cached copies of files that | |
2664 | the Cache Manager has obtained from that volume. This call is typically used | |
2665 | should a user suspect there is some cache corruption associated with the files | |
2666 | from a given volume. | |
2667 | ||
2668 | \subsubsection sec6-4-3-5 Section 6.4.3.5: VIOCCKBACK: Check validity | |
2669 | of all cached volume information | |
2670 | ||
2671 | \par | |
2672 | [Opcode 11] Ask the Cache Manager to check the validity of all cached volume | |
2673 | information. None of the call's parameters are referenced in this call, so a | |
2674 | pathP and in should be set to the null pointer, and in size and out size should | |
2675 | be set to zero. | |
2676 | \par | |
2677 | This operation is performed in two steps: | |
2678 | \li 1 The Cache Manager first refreshes its knowledge of the root volume, | |
2679 | usually named root.afs. On success, it wakes up any of its own threads waiting | |
2680 | on the arrival of this information, should it have been previously unreachable. | |
2681 | This typically happens should the Cache Manager discover in its startup | |
2682 | sequence that information on the root volume is unavailable. Lacking this | |
2683 | knowledge at startup time, the Cache Manager settles into a semi-quiescent | |
2684 | state, checking every so often to see if volume service is available and thus | |
2685 | may complete its own initialization. | |
2686 | \li 2 Each cached volume record is flagged as being stale. Any future attempt | |
2687 | to access information from these volumes will result in the volume record's | |
2688 | data first being refreshed from the Volume Location Server. | |
2689 | ||
2690 | \subsection sec6-4-4 Section 6.4.4: File Server Operations | |
2691 | ||
2692 | \par | |
2693 | One group of pioctl() opcodes is aimed at performing operations against one or | |
2694 | more File Servers directly. Specifically, a caller may translate a pathname | |
2695 | into the corresponding AFS fid (VIOCGETFID), unilaterally discard a set of | |
2696 | callback promises (VIOCFLUSHCB), get status on mount points (VIOC AFS STAT MT | |
2697 | PT), delete unwanted mount points (VIOC AFS DELETE MT PT), and check the health | |
2698 | of a group of File Servers(VIOCCKSERV). | |
2699 | ||
2700 | \subsubsection sec6-4-4-1 Section 6.4.4.1: VIOCGETFID: Get augmented | |
2701 | fid for named file system object | |
2702 | ||
2703 | \par | |
2704 | [Opcode 22] Return the augmented file identifier for the file system object | |
2705 | named by a pathP. The desired struct VenusFid is placed in the output buffer | |
2706 | specified by out. The output buffer size, as indicated by the out size | |
2707 | parameter, must be set to the value of sizeof(struct VenusFid) or greater. The | |
2708 | input buffer is not referenced in this call, so in should be set to the null | |
2709 | pointer and in size set to zero. | |
2710 | \par | |
2711 | Among the possible error returns, EINVAL indicates that the object named by a | |
2712 | pathP was not found. | |
2713 | ||
2714 | \subsubsection sec6-4-4-2 Section 6.4.4.2: VIOCFLUSHCB: Unilaterally | |
2715 | drop a callback | |
2716 | ||
2717 | \par | |
2718 | [Opcode 25] Remove any callback information kept by the Cache Manager on the | |
2719 | file system object named by a pathP. Internally, the Cache Manager executes a | |
2720 | call to the RXAFS GiveUpCallBacks() RPC (See Section 5.1.3.13) to inform the | |
2721 | appropriate File Server that it is being released from its particular callback | |
2722 | promise. Note that if the named file resides on a read-only volume, then the | |
2723 | above call is not made, and success is returned immediately. This optimization | |
2724 | is possible because AFS File Servers do not grant callbacks on files from | |
2725 | read-only volumes. | |
2726 | \par | |
2727 | Among the possible error returns is EINVAL, which indicates that the object | |
2728 | named by a pathP was not found. | |
2729 | ||
2730 | \subsubsection sec6-4-4-3 Section 6.4.4.3: VIOC AFS DELETE MT PT: | |
2731 | Delete a mount point | |
2732 | ||
2733 | \par | |
2734 | [Opcode 28] Remove an AFS mount point. The name of the directory in which the | |
2735 | mount point exists is specified by a pathP, and the string name of the mount | |
2736 | point within this directory is provided through the in parameter. The input | |
2737 | buffer length, in size, is set to the length of the mount point name itself, | |
2738 | including the trailing null. The output buffer is not accessed by this call, so | |
2739 | out should be set to the null pointer and out size to zero. | |
2740 | \par | |
2741 | One important note is that the a followSymLinks argument must be set to zero | |
2742 | for correct operation. This is counter-intuitive, since at first glance it | |
2743 | seems that a symbolic link that resolves to a directory should be a valid | |
2744 | pathname parameter. However, recall that mount points are implemented as | |
2745 | symbolic links that do not actually point to another file system object, but | |
2746 | rather simply contain cell and volume information (see the description in | |
2747 | Section 6.4.2). This "special" symbolic link must not be resolved by the | |
2748 | pioctl(), but rather presented as-is to the Cache Manager, which then properly | |
2749 | interprets it and generates a reference to the given volume's root directory. | |
2750 | As an unfortunate side-effect, a perfectly valid symbolic link referring to a | |
2751 | directory will be rejected out of hand by this operation as a value for the a | |
2752 | pathP parameter. | |
2753 | \par | |
2754 | Among the possible error returns, EINVAL reports that the named directory was | |
2755 | not found, and ENOTDIR indicates that the pathname contained within a pathP is | |
2756 | not a directory. | |
2757 | ||
2758 | \subsubsection sec6-4-4-4 Section 6.4.4.4: VIOC AFS STAT MT PT: Get the | |
2759 | contents of a mount point | |
2760 | ||
2761 | \par | |
2762 | [Opcode 29] Return the contents of the given mount point. The directory in | |
2763 | which the mount point in question resides is provided via the a pathP argument, | |
2764 | and the in buffer contains the name of the mount point object within this | |
2765 | directory. As usual, in size is set to the length of the input buffer, | |
2766 | including the trailing null. If the given object is truly a mount point and the | |
2767 | out buffer is large enough (its length appears in out size), the mount point's | |
2768 | contents are stored into out. | |
2769 | \par | |
2770 | The mount point string returned obeys a stylized format, as fully described in | |
2771 | Section 5.6.2 of the AFS 3.0 System Administrator's Guide[1]. Briefly, a | |
2772 | leading pound sign ("#") indicates a standard mount point, inheriting the | |
2773 | read-only or read-write preferences of the mount point's containing volume. On | |
2774 | the other hand, a leading percent sign ("%") advises the Cache Manager to cross | |
2775 | into the read-write version of the volume, regardless of the existence of | |
2776 | read-only clones. If a colon (":") separator occurs, the portion up to the | |
2777 | colon itself denotes the fully-qualified cell name hosting the volume. The rest | |
2778 | of the string is the volume name itself. | |
2779 | \par | |
2780 | Among the possible error codes is EINVAL, indicating that the named object is | |
2781 | not an AFS mount point. Should the name passed in a pathP be something other | |
2782 | than a directory, then ENOTDIR is returned. | |
2783 | ||
2784 | \subsubsection sec6-4-4-5 Section 6.4.4.5: VIOCCKSERV: Check the status | |
2785 | of one or more File Servers | |
2786 | ||
2787 | \par | |
2788 | [Opcode 10] Check the status of the File Servers that have been contacted over | |
2789 | the lifetime of the Cache Manager. The a pathP parameter is ignored by this | |
2790 | call, so it should be set to the null pointer. The input parameters as | |
2791 | specified by in are completely optional. If something is placed in the input | |
2792 | buffer, namely in size is not zero, then the first item stored there is a | |
2793 | longword used as a bit array of flags. These flags carry instructions as to the | |
2794 | domain and the "thoroughness" of this check. | |
2795 | \par | |
2796 | Only the settings of the least-significant two bits are recognized. Enabling | |
2797 | the lowest bit tells the Cache Manager not to ping its list of servers, but | |
2798 | simply report their status as contained in the internal server records. | |
2799 | Enabling the next-higher bit limits the search to only those File Servers in a | |
2800 | given cell. If in size is greater than sizeof(long),a null-terminated cell name | |
2801 | string follows the initial flag array, specifying the cell to check. If this | |
2802 | search bit is set but no cell name string follows the longword of flags, then | |
2803 | the search is restricted to those servers contacted from the same cell as the | |
2804 | caller. | |
2805 | \par | |
2806 | This call returns at least one longword into the output buffer out, specifying | |
2807 | the number of hosts it discovered to be down. If this number is not zero, then | |
2808 | the longword IP address for each dead (or unreachable) host follows in the | |
2809 | output buffer. At most 16 server addresses will be returned, as this is the | |
2810 | maximum number of servers for which the Cache Manager keeps information. | |
2811 | \par | |
2812 | Among the possible error returns is ENOENT, indicating that the optional cell | |
2813 | name string input value is not known to the Cache Manager. | |
2814 | ||
2815 | \subsection sec6-4-5 Section 6.4.5: Cell Operations | |
2816 | ||
2817 | \par | |
2818 | The Cache Manager is the only active AFS agent that understands the system's | |
2819 | cellular architecture. Thus, it keeps important information concerning the | |
2820 | identities of the cells in the community, which cell is in direct | |
2821 | administrative control of the machine upon which it is running, status and | |
2822 | configuration of its own cell, and what cell-specific operations may be legally | |
2823 | executed. The following pioctl()s allow client processes to access and update | |
2824 | this cellular information. Supported operations include adding or updating | |
2825 | knowledge of a cell, including the cell overseeing the caller's machine | |
2826 | (VIOCNEWCELL), fetching the contents of a cell configuration entry | |
2827 | (VIOCGETCELL), finding out which cell hosts a given file system object (VIOC | |
2828 | FILE CELL NAME), discovering the cell to which the machine belongs (VIOC GET WS | |
2829 | CELL), finding out the caller's "primary" cell (VIOC GET PRIMARY CELL), and | |
2830 | getting/setting certain other per-cell system parameters (VIOC GETCELLSTATUS, | |
2831 | VIOC SETCELLSTATUS). | |
2832 | ||
2833 | \subsubsection sec6-4-5-1 Section 6.4.5.1: VIOCNEWCELL: Set cell | |
2834 | service information | |
2835 | ||
2836 | \par | |
2837 | [Opcode 26] Give the Cache Manager all the information it needs to access an | |
2838 | AFS cell. Exactly eight longwords are placed at the beginning of the in input | |
2839 | buffer. These specify the IP addresses for the machine providing AFS | |
2840 | authentication and volume location authentication services. The first such | |
2841 | longword set to zero will signal the end of the list of server IP addresses. | |
2842 | After these addresses, the input buffer hosts the null-terminated name of the | |
2843 | cell to which the above servers belong. The a pathP parameter is not used, and | |
2844 | so should be set to the null pointer. | |
2845 | \par | |
2846 | Among the possible error returns is EACCES, indicating that the caller does not | |
2847 | have the necessary rights to perform the operation. Only root is allowed to set | |
2848 | cell server information. If either the IP address array or the server name is | |
2849 | unacceptable, EINVAL will be returned. | |
2850 | ||
2851 | \subsubsection sec6-4-5-2 Section 6.4.5.2: VIOCGETCELL: Get cell | |
2852 | configuration entry | |
2853 | ||
2854 | \par | |
2855 | [Opcode 27] Get the i'th cell configuration entry known to the Cache Manager. | |
2856 | The index of the desired entry is placed into the in input buffer as a | |
2857 | longword, with the first legal value being zero. If there is a cell associated | |
2858 | with the given index, the output buffer will be filled with an array of 8 | |
2859 | longwords, followed by a null-terminated string. | |
2860 | \par | |
2861 | The longwords correspond to the list of IP addresses of the machines providing | |
2862 | AFS authentication and volume location services. The string reflects the name | |
2863 | of the cell for which the given machines are operating. There is no explicit | |
2864 | count returned of the number of valid IP addresses in the longword array. | |
2865 | Rather, the list is terminated by the first zero value encountered, or when the | |
2866 | eighth slot is filled. | |
2867 | \par | |
2868 | This routine is intended to be called repeatedly, with the index starting at | |
2869 | zero and increasing each time. The array of cell information records is kept | |
2870 | compactly, without holes. A return value of EDOM indicates that the given index | |
2871 | does not map to a valid entry, and thus may be used as the terminating | |
2872 | condition for the iteration. | |
2873 | ||
2874 | \subsubsection sec6-4-5-3 Section 6.4.5.3: VIOC FILE CELL NAME: Get | |
2875 | cell hosting a given object | |
2876 | ||
2877 | \par | |
2878 | [Opcode 30] Ask the Cache Manager to return the name of the cell in which the | |
2879 | file system object named by a pathP resides. The input arguments are not used, | |
2880 | so in should be set to the null pointer and in size should be set to zero. The | |
2881 | null-terminated cell name string is returned in the out output buffer. | |
2882 | \par | |
2883 | Among the possible error values, EINVAL indicates that the pathname provided in | |
2884 | a pathP is illegal. If there is no cell information associated with the given | |
2885 | object, ESRCH is returned. | |
2886 | ||
2887 | \subsubsection sec6-4-5-4 Section 6.4.5.4: VIOC GET WS CELL: Get | |
2888 | caller's home cell name | |
2889 | ||
2890 | \par | |
2891 | [Opcode 31] Return the name of the cell to which the caller's machine belongs. | |
2892 | This cell name is returned as a null-terminated string in the output buffer. | |
2893 | The input arguments are not used, so in should be set to the null pointer and | |
2894 | in size should be set to zero. | |
2895 | \par | |
2896 | Among the possible error returns is ESRCH, stating that the caller's home cell | |
2897 | information was not available. | |
2898 | ||
2899 | \subsubsection sec6-4-5-5 Section 6.4.5.5: VIOC GET PRIMARY CELL: Get | |
2900 | the caller's primary cell | |
2901 | ||
2902 | \par | |
2903 | [Opcode 33] Ask the Cache Manager to return the name of the caller's primary | |
2904 | cell. Internally, the Cache Manager scans its user records, and the cell | |
2905 | information referenced by that record is used to extract the cell's string | |
2906 | name. The input arguments are not used, so in should be set to the null pointer | |
2907 | and in size should be set to zero. The a pathP pathname argument is not used | |
2908 | either, and should similarly be set to the null pointer. The null-terminated | |
2909 | cell name string is placed into the output buffer pointed to by out if it has | |
2910 | suffcient room. | |
2911 | \par | |
2912 | Among the possible error returns is ESRCH, stating that the caller's primary | |
2913 | cell information was not available. | |
2914 | ||
2915 | \subsubsection sec6-4-5-6 Section 6.4.5.6: VIOC GETCELLSTATUS: Get | |
2916 | status info for a cell entry | |
2917 | ||
2918 | \par | |
2919 | [Opcode 35] Given a cell name, return a single longword of status flags from | |
2920 | the Cache Manager's entry for that cell. The null-terminated cell name string | |
2921 | is expected to be in the in parameter, with in size set to its length plus one | |
2922 | for the trailing null. The status flags are returned in the out buffer, which | |
2923 | must have out size set to sizeof(long) or larger. | |
2924 | \par | |
2925 | The Cache Manager defines the following output flag values for this operation: | |
2926 | \li 0x1 This entry is considered the caller's primary cell. | |
2927 | \li 0x2 The unix setuid() operation is not honored. | |
2928 | \li 0x4 An obsolete version of the Volume Location Server's database is being | |
2929 | used. While defined, this flag should no longer be set in modern systems. | |
2930 | ||
2931 | \par | |
2932 | Among the possible error returns is ENOENT, informing the caller that the Cache | |
2933 | Manager has no knowledge of the given cell name. | |
2934 | ||
2935 | \subsubsection sec6-4-5-7 Section 6.4.5.7: VIOC SETCELLSTATUS: Set | |
2936 | status info for a cell entry | |
2937 | ||
2938 | \par | |
2939 | [Opcode 36] Given a cell name and an image of the cell status bits that should | |
2940 | be set, record the association in the Cache Manager. The input buffer in must | |
2941 | be set up as follows. The first entry is the longword containing the cell | |
2942 | status bits to be set (see the VIOC GETCELLSTATUS description above for valid | |
2943 | flag definitions). The next entry is another longword, ignored by the Cache | |
2944 | Manager. The third and final entry in the input buffer is a null-terminated | |
2945 | string containing the name of the cell for which the status flags are to be | |
2946 | applied. | |
2947 | \par | |
2948 | Among the possible error returns is ENOENT, reflecting the Cache Manager's | |
2949 | inability to locate its record for the given cell. Only root is allowed to | |
2950 | execute this operation, and an EACCES return indicates the caller was not | |
2951 | effectively root when the call took place. | |
2952 | ||
2953 | \subsection sec6-4-6 Section 6.4.6: Authentication Operations | |
2954 | ||
2955 | \par | |
2956 | The Cache Manager serves as the repository for authentication information for | |
2957 | AFS clients. Each client process belongs to a single Process Authentication | |
2958 | Group (PAG). Each process in a given PAG shares authentication information with | |
2959 | the other members, and thus has the identical rights with respect to AFS Access | |
2960 | Control Lists (ACLs) as all other processes in the PAG. As the Cache Manager | |
2961 | interacts with File Servers as a client process' agent, it automatically and | |
2962 | transparently presents the appropriate authentication information as required | |
2963 | in order to gain the access to which the caller is entitled. Each PAG can host | |
2964 | exactly one token per cell. These tokens are objects that unequivocally codify | |
2965 | the principal's identity, and are encrypted for security. Token operations | |
2966 | between a Cache Manager and File Server are also encrypted, as are the | |
2967 | interchanges between clients and the Authentication Servers that generate these | |
2968 | tokens. | |
2969 | \par | |
2970 | There are actually two different flavors of tokens, namely clear and secret. | |
2971 | The data structure representing clear tokens is described in Section 6.2.2, and | |
2972 | the secret token appears as an undifferentiated byte stream. | |
2973 | \par | |
2974 | This section describes the operations involving these tokens, namely getting | |
2975 | and setting the caller's token for a particular cell (VIOCGETTOK, VIOCSETTOK), | |
2976 | checking a caller's access on a specified file system object (VIOCACCESS), | |
2977 | checking the status of caller's tokens associated with the set of File Server | |
2978 | connections maintained on its behalf (VIOCCKCONN), and discarding tokens | |
2979 | entirely (VIOCUNLOG, VIOCUNPAG). These abilities are used by such programs as | |
2980 | login, klog, unlog, and tokens, which must generate, manipulate, and/or destroy | |
2981 | AFS tokens. | |
2982 | ||
2983 | \subsubsection sec6-4-6-1 Section 6.4.6.1: VIOCSETTOK: Set the caller's | |
2984 | token for a cell | |
2985 | ||
2986 | \par | |
2987 | [Opcode 3] Store the caller's secret and clear tokens within the Cache Manager. | |
2988 | The input buffer is used to hold the following quantities, laid out end to end. | |
2989 | The first item placed in the buffer is a longword, specifying the length in | |
2990 | bytes of the secret token, followed by the body of the secret token itself. The | |
2991 | next field is another longword, this time describing the length in bytes of the | |
2992 | struct ClearToken, followed by the structure. These are all required fields. | |
2993 | The caller may optionally include two additional fields, following directly | |
2994 | after the required ones. The first optional field is a longword which is set to | |
2995 | a non-zero value if the cell in which these tokens were generated is to be | |
2996 | marked as the caller's primary cell. The second optional argument is a | |
2997 | null-terminated string specifying the cell in which these tokens apply. If | |
2998 | these two optional arguments do not appear, the Cache Manager will default to | |
2999 | using its home cell and marking the entry as non-primary. The a pathP pathname | |
3000 | parameter is not used, and thus should be set to the null pointer. | |
3001 | \par | |
3002 | If the caller does not have any tokens registered for the cell, the Cache | |
3003 | Manager will store them. If the caller already has tokens for the cell, the new | |
3004 | values will overwrite their old values. Because these are stored per PAG, the | |
3005 | new tokens will thus determine the access rights of all other processes | |
3006 | belonging to the PAG. | |
3007 | \par | |
3008 | Among the possible error returns is ESRCH, indicating the named cell is not | |
3009 | recognized, and EIO, if information on the local cell is not available. | |
3010 | ||
3011 | \subsubsection sec6-4-6-2 Section 6.4.6.2: VIOCGETTOK: Get the caller's | |
3012 | token for a cell | |
3013 | ||
3014 | \par | |
3015 | [Opcode 8] Get the specified authentication tokens associated with the caller. | |
3016 | The a pathP parameter is not used, so it should be set to the null pointer. | |
3017 | Should the input parameter in be set to a null pointer, then this call will | |
3018 | place the user's tokens for the machine's home cell in the out output buffer, | |
3019 | if such tokens exist. In this case, the following objects are placed in the | |
3020 | output buffer. First, a longword specifying the number of bytes in the body of | |
3021 | the secret token is delivered, followed immediately by the secret token itself. | |
3022 | Next is a longword indicating the length in bytes of the clear token, followed | |
3023 | by the clear token. The input parameter may also consist of a single longword, | |
3024 | indicating the index of the token desired. Since the Cache Manager is capable | |
3025 | of storing multiple tokens per principal, this allows the caller to iteratively | |
3026 | extract the full set of tokens stored for the PAG. The first valid index value | |
3027 | is zero. The list of tokens is kept compactly, without holes. A return value of | |
3028 | EDOM indicates that the given index does not map to a valid token entry, and | |
3029 | thus may be used as the terminating condition for the iteration. | |
3030 | \par | |
3031 | Other than EDOM, another possible error return is ENOTCONN, specifying that the | |
3032 | caller does not have any AFS tokens whatsoever. | |
3033 | ||
3034 | \subsubsection sec6-4-6-3 Section 6.4.6.3: VIOCACCESS: Check caller's | |
3035 | access on object | |
3036 | ||
3037 | \par | |
3038 | [Opcode 20] This operation is used to determine whether the caller has specific | |
3039 | access rights on a particular file system object. A single longword is placed | |
3040 | into the input buffer, in, representing the set of rights in question. The | |
3041 | acceptable values for these access rights are listen in Section 6.4.5. The | |
3042 | object to check is named by the a pathP parameter. The output parameters are | |
3043 | not accessed, so out should be set to the null pointer, and out size set to | |
3044 | zero. | |
3045 | If the call returns successfully, the caller has at least the set of rights | |
3046 | denoted by the bits set in the input buffer. Otherwise, EACCESS is returned. | |
3047 | ||
3048 | \subsubsection sec6-4-6-4 Section 6.4.6.4: VIOCCKCONN: Check status of | |
3049 | caller's tokens/connections | |
3050 | ||
3051 | \par | |
3052 | [Opcode 12] Check whether the suite of File Server connections maintained on | |
3053 | behalf of the caller by the Cache Manager has valid authentication tokens. This | |
3054 | function always returns successfully, communicating the health of said | |
3055 | connections by writing a single longword value to the specified output buffer | |
3056 | in out. If zero is returned to the output buffer, then two things are true. | |
3057 | First, the caller has tokens for at least one cell. Second, all tokens | |
3058 | encountered upon a review of the caller's connections have been properly minted | |
3059 | (i.e., have not been generated fraudulently), and, in addition, have not yet | |
3060 | expired. If these conditions do not currently hold for the caller, then the | |
3061 | output buffer value will be set to EACCES. Neither the a pathP nor input | |
3062 | parameters are used by this call. | |
3063 | ||
3064 | \subsubsection sec6-4-6-5 Section 6.4.6.5: VIOCUNLOG: Discard | |
3065 | authentication information | |
3066 | ||
3067 | \par | |
3068 | [Opcode 9] Discard all authentication information held in trust for the caller. | |
3069 | The Cache Manager sweeps through its user records, destroying all of the | |
3070 | caller's associated token information. This results in reducing the rights of | |
3071 | all processes within the caller's PAG to the level of file system access | |
3072 | granted to the special system:anyuser group. | |
3073 | \par | |
3074 | This operation always returns successfully. None of the parameters are | |
3075 | referenced, so they should all be set to null pointers and zeroes as | |
3076 | appropriate. | |
3077 | ||
3078 | \subsubsection sec6-4-6-6 Section 6.4.6.6: VIOCUNPAG: Discard | |
3079 | authentication information | |
3080 | ||
3081 | \par | |
3082 | [Opcode 21] This call is essentially identical to the VIOCUNLOG operation, and | |
3083 | is in fact implemented internally by the same code for VIOCUNLOG. | |
3084 | ||
3085 | \subsection sec6-4-7 Section 6.4.7: ACL Operations | |
3086 | ||
3087 | \par | |
3088 | This set of opcodes allows manipulation of AFS Access Control Lists (ACLs). | |
3089 | Callers are allowed to fetch the ACL on a given directory, or to set the ACL on | |
3090 | a directory. In AFS-3, ACLs are only maintained on directories, not on | |
3091 | individual files. Thus, a directory ACL determines the allowable accesses on | |
3092 | all objects within that directory in conjunction with their normal unix mode | |
3093 | (owner) bits. Should the a pathP parameter specify a file instead of a | |
3094 | directory, the ACL operation will be performed on the directory in which the | |
3095 | given file resides. | |
3096 | \par | |
3097 | These pioctl() opcodes deal only in external formats for ACLs, namely the | |
3098 | actual text stored in an AFS ACL container. This external format is a character | |
3099 | string, composed of a descriptive header followed by some number of individual | |
3100 | principal-rights pairs. AFS ACLs actually specify two sublists, namely the | |
3101 | positive and negative rights lists. The positive list catalogues the set of | |
3102 | rights that certain principals (individual users or groups of users) have, | |
3103 | while the negative list contains the set of rights specifically denied to the | |
3104 | named parties. | |
3105 | \par | |
3106 | These external ACL representations differ from the internal format generated by | |
3107 | the Cache Manager after a parsing pass. The external format may be easily | |
3108 | generated from the internal format as follows. The header format is expressed | |
3109 | with the following printf() statement: | |
3110 | \code | |
3111 | printf("%d\n%d\n", NumPositiveEntries, NumNegativeEntries); | |
3112 | \endcode | |
3113 | \par | |
3114 | The header first specifies the number of entries on the positive rights list, | |
3115 | which appear first in the ACL body. The number of entries on the negative list | |
3116 | is the second item in the header. The negative entries appear after the last | |
3117 | positive entry. | |
3118 | \par | |
3119 | Each entry in the ACL proper obeys the format imposed by the following printf() | |
3120 | statement: | |
3121 | \code | |
3122 | printf("%s\t%d\n", UserOrGroupName, RightsMask); | |
3123 | \endcode | |
3124 | \par | |
3125 | Note that the string name for the user or group is stored in an externalized | |
3126 | ACL entry. The Protection Server stores the mappings between the numerical | |
3127 | identifiers for AFS principals and their character string representations. | |
3128 | There are cases where there is no mapping from the numerical identifier to a | |
3129 | string name. For example, a user or group may have been deleted sometime after | |
3130 | they were added to the ACL and before the Cache Manager externalized the ACL | |
3131 | for storage. In this case, the Cache Manager sets UserOrGroupName to the string | |
3132 | version of the principal's integer identifier. Should the erz principal be | |
3133 | deleted from the Protection Server's database in the above scenario, then the | |
3134 | string '1019' will be stored, since it corresponded to erz's former numerical | |
3135 | identifier. | |
3136 | \par | |
3137 | The RightsMask parameter to the above call represents the set of rights the | |
3138 | named principal may exercise on the objects covered by the ACL. The following | |
3139 | flags may be OR'ed together to construct the desired access rights placed in | |
3140 | RightsMask: | |
3141 | \code | |
3142 | #define PRSFS_READ 1 /*Read files*/ | |
3143 | #define PRSFS_WRITE 2 /*Write & write-lock existing files*/ | |
3144 | #define PRSFS_INSERT 4 /*Insert & write-lock new files*/ | |
3145 | #define PRSFS_LOOKUP 8 /*Enumerate files and examine ACL*/ | |
3146 | #define PRSFS_DELETE 16 /*Remove files*/ | |
3147 | #define PRSFS_LOCK 32 /*Read-lock files*/ | |
3148 | #define PRSFS_ADMINISTER 64 /*Set access list of directory*/ | |
3149 | \endcode | |
3150 | ||
3151 | \subsubsection sec6-4-7-1 Section 6.4.7.1: VIOCSETAL: Set the ACL on a | |
3152 | directory | |
3153 | ||
3154 | \par | |
3155 | [Opcode 1] Set the contents of the ACL associated with the file system object | |
3156 | named by a pathP. Should this pathname indicate a file and not a directory, the | |
3157 | Cache Manager will apply this operation to the file's parent directory. The new | |
3158 | ACL contents, expressed in their externalized form, are made available in in, | |
3159 | with in size set to its length in characters, including the trailing null. | |
3160 | There is no output from this call, so out size should be set to zero. | |
3161 | Internally, the Cache Manager will call the RXAFS StoreACL() RPC (see Section | |
3162 | 5.1.3.3 to store the new ACL on the proper File Server. | |
3163 | \par | |
3164 | Possible error codes include EINVAL, indicating that one of three things may be | |
3165 | true: the named path is not in AFS, there are too many entries in the specified | |
3166 | ACL, or a non-existent user or group appears on the ACL. | |
3167 | ||
3168 | \subsubsection sec6-4-7-2 Section 6.4.7.2: VIOCGETAL: Get the ACL for a | |
3169 | directory | |
3170 | ||
3171 | \par | |
3172 | [Opcode 2] Get the contents of the ACL associated with the file system object | |
3173 | named by a pathP. Should this pathname indicate a file and not a directory, the | |
3174 | Cache Manager will apply this operation to the file's parent directory. The ACL | |
3175 | contents, expressed in their externalized form, are delivered into the out | |
3176 | buffer if out size has been set to a value which indicates that there is enough | |
3177 | room for the specified ACL. This ACL string will be null-terminated. There is | |
3178 | no input to this call, so in size should be set to zero. Internally, the Cache | |
3179 | Manager will call the RXAFS FetchACL() RPC (see Section 5.1.3.1) to fetch the | |
3180 | ACL from the proper File Server. | |
3181 | \par | |
3182 | Possible error codes include EINVAL, indicating that the named path is not in | |
3183 | AFS. | |
3184 | ||
3185 | \subsection sec6-4-8 Section 6.4.8: Cache Operations | |
3186 | ||
3187 | \par | |
3188 | It is possible to inquire about and affect various aspects of the cache | |
3189 | maintained locally by the Cache Manager through the group of pioctl()s | |
3190 | described below. Specifically, one may force certain file system objects to be | |
3191 | removed from the cache (VIOCFLUSH), set the maximum number of blocks usable by | |
3192 | the cache (VIOCSETCACHESIZE), and ask for information about the cache's current | |
3193 | state (VIOCGETCACHEPARAMS). | |
3194 | ||
3195 | \subsubsection sec6-4-8-1 Section 6.4.8.1: VIOCFLUSH: Flush an object | |
3196 | from the cache | |
3197 | ||
3198 | \par | |
3199 | [Opcode 6] Flush the file system object specified by a pathP out of the local | |
3200 | cache. The other parameters are not referenced, so they should be set to the | |
3201 | proper combination of null pointers and zeroes. | |
3202 | \par | |
3203 | Among the possible error returns is EINVAL, indicating that the value supplied | |
3204 | in the a pathP parameter is not acceptable. | |
3205 | ||
3206 | \subsubsection sec6-4-8-2 Section 6.4.8.2: VIOCSETCACHESIZE: Set | |
3207 | maximum cache size in blocks | |
3208 | ||
3209 | \par | |
3210 | [Opcode 24] Instructs the Cache Manager to set a new maximum size (in 1 Kbyte | |
3211 | blocks) for its local cache. The input buffer located at in contains the new | |
3212 | maximum block count. If zero is supplied for this value, the Cache Manager will | |
3213 | revert its cache limit to its value at startup time. Neither the a pathP nor | |
3214 | output buffer parameters is referenced by this operation. The Cache Manager | |
3215 | recomputes its other cache parameters based on this new value, including the | |
3216 | number of cache files allowed to be dirty at once and the total amount of space | |
3217 | filled with dirty chunks. Should the new setting be smaller than the number of | |
3218 | blocks currently being used, the Cache Manager will throw things out of the | |
3219 | cache until it obeys the new limit. | |
3220 | \par | |
3221 | The caller is required to be effectively running as root, or this call will | |
3222 | fail, returning EACCES. If the Cache Manager is configured to run with a memory | |
3223 | cache instead of a disk cache, this operation will also fail, returning EROF. | |
3224 | ||
3225 | \subsubsection sec6-4-8-3 Section 6.4.8.3: VIOCGETCACHEPARAMS: Get | |
3226 | current cache parameter values | |
3227 | ||
3228 | \par | |
3229 | [Opcode 40] Fetch the current values being used for the cache parameters. The | |
3230 | output buffer is filled with MAXGCSTATS (16) longwords, describing these | |
3231 | parameters. Only the first two longwords in this array are currently set. The | |
3232 | first contains the value of afs cacheBlocks, or the maximum number of 1 Kbyte | |
3233 | blocks which may be used in the cache (see Section 6.4.8.2 for how this value | |
3234 | may be set). The second longword contains the value of the Cache Manager's | |
3235 | internal afs blocksUsed variable, or the number of these cache blocks currently | |
3236 | in use. All other longwords in the array are set to zero. Neither the a pathP | |
3237 | nor input buffer arguments are referenced by this call. | |
3238 | \par | |
3239 | This routine always returns successfully. | |
3240 | ||
3241 | \subsection sec6-4-9 Section 6.4.9: Miscellaneous Operations | |
3242 | ||
3243 | \par | |
3244 | There are several other AFS-specific operations accessible via the pioctl() | |
3245 | interface that don't fit cleanly into the above categories. They are described | |
3246 | in this section, and include manipulation of the socket-based Mariner file | |
3247 | trace interface (VIOC AFS MARINER HOST), enabling and disabling of the | |
3248 | file-based AFSLog output interface for debugging (VIOC VENUSLOG), getting and | |
3249 | setting the value of the special @sys pathname component mapping (VIOC AFS | |
3250 | SYSNAME), and turning the NFS-AFS translator service on and off (VIOC | |
3251 | EXPORTAFS). | |
3252 | ||
3253 | \subsubsection sec6-4-9-1 Section 6.4.9.1: VIOC AFS MARINER HOST: | |
3254 | Get/set file transfer monitoring output | |
3255 | ||
3256 | \par | |
3257 | [Opcode 32] This operation is used to get or set the IP address of the host | |
3258 | destined to receive Mariner output. A detailed description of the Cache Manager | |
3259 | Mariner interface may be found in Section 6.7. | |
3260 | \par | |
3261 | The input buffer located at in is used to pass a single longword containing the | |
3262 | IP address of the machine to receive output regarding file transfers between | |
3263 | the Cache Manager and any File Server. If the chosen host IP address is | |
3264 | 0xffffffff, the Cache Manager is prompted to turn off generation of Mariner | |
3265 | output entirely. If the chosen host IP address is zero, then the Cache Manager | |
3266 | will not set the Mariner host, but rather return the current Mariner host as a | |
3267 | single longword written to the out output buffer. Any other value chosen for | |
3268 | the host IP address enables Mariner output (if it was not already enabled) and | |
3269 | causes all further traffic to be directed to the given machine. | |
3270 | \par | |
3271 | This function always returns successfully. | |
3272 | ||
3273 | \subsubsection sec6-4-9-2 Section 6.4.9.2: VIOC VENUSLOG: | |
3274 | Enable/disable Cache Manager logging | |
3275 | ||
3276 | \par | |
3277 | [Opcode 34] Tell the Cache Manager whether to generate debugging information, | |
3278 | and what kind of debugging output to enable. The input buffer located at in is | |
3279 | used to transmit a single longword to the Cache Manager, expressing the | |
3280 | caller's wishes. Of the four bytes making up the longword, the highest byte | |
3281 | indicates the desired value for the internal afsDebug variable, enabling or | |
3282 | disabling general trace output. The next highest byte indicates the desired | |
3283 | value for the internal netDebug variable, enabling or disabling network-level | |
3284 | debugging traces. The third byte is unused, and the low-order byte represents | |
3285 | an overall on/off value for the functionality. There is a special value for the | |
3286 | low-order byte, 99, which instructs the Cache Manager to return the current | |
3287 | debugging setting as a single longword placed into the output buffer pointed to | |
3288 | by out. The a pathP parameter is not referenced by this routine. | |
3289 | \par | |
3290 | Trace output is delivered to the AFSLog file, typically located in the | |
3291 | /usr/vice/etc directory. When this form of debugging output is enabled, the | |
3292 | existing AFSLog file is truncated, and its file descriptor is stored for future | |
3293 | use. When this debugging is disabled, a close() is done on the file, forcing | |
3294 | all its data to disk. For additional information on the AFSLog file for | |
3295 | collecting Cache Manager traces, please see the description in Section 6.6.2.1. | |
3296 | \par | |
3297 | This call will only succeed if the caller is effectively running as root. If | |
3298 | this is not the case, an error code of EACCES is returned. | |
3299 | ||
3300 | \subsubsection sec6-4-9-3 Section 6.4.9.3: VIOC AFS SYSNAME: Get/set | |
3301 | the @sys mapping | |
3302 | ||
3303 | \par | |
3304 | [Opcode 38] Get or set the value of the special @sys pathname component | |
3305 | understood by the Cache Manager. The input buffer pointed to by in is used to | |
3306 | house a longword whose value determines whether the @sys value is being set (1) | |
3307 | or whether the current value is being fetched (0). If it is being set, then a | |
3308 | null-terminated string is expected to follow in the input buffer, specifying | |
3309 | the new value of @sys. Otherwise, if we are asking the Cache Manager for the | |
3310 | current @sys setting, a null-terminated string bearing that value will be | |
3311 | placed in the out output buffer. The a pathP parameter is not used by this | |
3312 | call, and thus should be set to a null pointer. | |
3313 | \par | |
3314 | There are no special privileges required of the caller to fetch the value of | |
3315 | the current @sys mapping. However, a native caller must be running effectively | |
3316 | as root in order to successfully alter the mapping. An unauthorized attempt to | |
3317 | change the @sys setting will be ignored, and cause this routine to return | |
3318 | EACCES. This requirement is relaxed for VIOC AFS SYSNAME pioctl() calls | |
3319 | emanating from foreign file systems such as NFS and accessing AFS files through | |
3320 | the NFS-AFS translator. Each such remote caller may set its own notion of what | |
3321 | the @sys mapping is without affecting native AFS clients. Since the uid values | |
3322 | received in calls from NFS machines are inherently insecure, it is impossible | |
3323 | to enforce the fact that the caller is truly root on the NFS machine. This, | |
3324 | while any principal running on an NFS machine may change that foreign machine's | |
3325 | perception of @sys, it does not impact native AFS users in any way. | |
3326 | ||
3327 | \subsubsection sec6-4-9-4 Section 6.4.9.4: VIOC EXPORTAFS: | |
3328 | Enable/disable NFS/AFS translation | |
3329 | ||
3330 | \par | |
3331 | [Opcode 39] Enable or disable the ability of an AFS-capable machine to export | |
3332 | AFS access to NFS clients. Actually, this is a general facility allowing | |
3333 | exportation of AFS service to any number of other file systems, but the only | |
3334 | support currently in place is for NFS client machines. A single longword is | |
3335 | expected in the input buffer in. This input longword is partitioned into | |
3336 | individual bytes, organized as follows. The high-order byte communicates the | |
3337 | type of foreign client to receive AFS file services. There are currently two | |
3338 | legal values for this field, namely 0 for the null foreign file system and 1 | |
3339 | for NFS. The next byte determines whether the Cache Manager is being asked to | |
3340 | get or set this information. A non-zero value here is interpreted as a command | |
3341 | to set the export information according to what's in the input longword, and a | |
3342 | zero-valued byte in this position instructs the Cache Manager to place a | |
3343 | longword in the output buffer out, which contains the current export settings | |
3344 | for the foreign system type specified in the high-order byte. The third input | |
3345 | byte is not used, and the lowest-order input buffer byte determines whether | |
3346 | export services for the specified system are being enabled or disabled. A | |
3347 | non-zero value will turn on the services, and a zero value will shut them down. | |
3348 | The a pathP pathname parameter is not used by this call, and the routine | |
3349 | generates output only if the export information is being requested instead of | |
3350 | being set. | |
3351 | \par | |
3352 | The caller must be effectively running as root in order for this operation to | |
3353 | succeed. The call returns EACCES if the caller is not so authorized. If the | |
3354 | caller specifies an illegal foreign system type in the high-order byte of the | |
3355 | input longword, then ENODEV is returned. Again, NFS is the only foreign file | |
3356 | system currently supported. | |
3357 | \par | |
3358 | Practically speaking, the machine providing NFS-AFS translation services must | |
3359 | enable this service with this pioctl() before any NFS client machines may begin | |
3360 | accessing AFS files. Conversely, if an administrator turns off this export | |
3361 | facility, the export code on the translator machine will immediately stop | |
3362 | responding to traffic from its active NFS clients. | |
3363 | ||
3364 | \section sec6-5 Section 6.5: RPC Interface | |
3365 | ||
3366 | \subsection sec6-5-1 Section 6.5.1: Introduction | |
3367 | ||
3368 | \par | |
3369 | This section covers the structure and workings of the Cache Manager's RPC | |
3370 | interface. Typically, these calls are made by File Server processes. However, | |
3371 | some of the calls are designed specifically for debugging programs (e.g., the | |
3372 | cmdebug facility) and for collection of statistical and performance information | |
3373 | from the Cache Manager. Any client application that makes direct calls on the | |
3374 | File Server RPC interface must be prepared to export a subset of the Cache | |
3375 | Manager RPC interface, as discussed in Section 5.1.6. | |
3376 | \par | |
3377 | This section will first examine the Cache Manager's use of locks, whose | |
3378 | settings may be observed via one of the RPC interface calls. Next, it will | |
3379 | present some definitions and data structures used in the RPC interface, and | |
3380 | finally document the individual calls available through this interface. | |
3381 | ||
3382 | \subsection sec6-5-2 Section 6.5.2: Locks | |
3383 | ||
3384 | \par | |
3385 | The Cache Manager makes use of locking to insure its internal integrity in the | |
3386 | face of its multi-threaded design. A total of 11 locks are maintained for this | |
3387 | purpose, one of which is now obsolete and no longer used (see below). These | |
3388 | locks are strictly internal, and the Cache Manager itself is the only one able | |
3389 | to manipulate them. The current settings for these system locks are externally | |
3390 | accessible for debugging purposes via the AFSRXCB GetLock() RPC interface call, | |
3391 | as described in Section 6.5.5.4. For each lock, its index in the locking table | |
3392 | is given in the following text. | |
3393 | \li afs xvcache [Index 0]: This lock controls access to the status cache | |
3394 | entries maintained by the Cache Manager. This stat cache keeps stat()-related | |
3395 | information for AFS files it has dealt with. The stat information is kept | |
3396 | separate from actual data contents of the related file, since this information | |
3397 | may change independently (say, as a result of a unix chown() call. | |
3398 | \li afs xdcache [Index 1]: This lock moderates access to the Cache Manager's | |
3399 | data cache, namely the contents of the file system objects it has cached | |
3400 | locally. As stated above, this data cache is separate from the associated | |
3401 | stat() information. | |
3402 | \li afs xserver [Index 2]: This lock controls access to the File Server machine | |
3403 | description table, which keeps tabs on all File Servers contacted in recent | |
3404 | history. This lock thus indirectly controls access to the set of per-server RPC | |
3405 | connection descriptors the File Server table makes visible. | |
3406 | \li afs xvcb [Index 3]: This lock supervises access to the volume callback | |
3407 | information kept by the Cache Manager. This table is referenced, for example, | |
3408 | when a client decides to remove one or more callbacks on files from a given | |
3409 | volume (see the RXAFS GiveUpCallBacks() description on Section 5.1.3.13). | |
3410 | \li afs xbrs [Index 4]: This lock serializes the actions of the Cache Manager's | |
3411 | background daemons, which perform prefetching and background file storage | |
3412 | duties. | |
3413 | \li afs xcell [Index 5]: This lock controls the addition, deletion, and update | |
3414 | of items on the linked list housing information on cells known to the Cache | |
3415 | Manager. | |
3416 | \li afs xconn [Index 6]: This lock supervises operations concerning the set of | |
3417 | RPC connection structures kept by the system. This lock is used in combination | |
3418 | with the | |
3419 | \li afs xserver lock described above. In some internal Cache Manager code | |
3420 | paths, the File Server description records are first locked, and then the afs | |
3421 | xconn lock is used to access the associated Rx connection records. afs xuser | |
3422 | [Index 7]: This lock serializes access to the per-user structures maintained by | |
3423 | the Cache Manager. | |
3424 | \li afs xvolume [Index 8]: This lock is used to control access to the Cache | |
3425 | Manager's volume information cache, namely the set of entries currently in | |
3426 | memory, a subset of those stably housed in the VolumeItems disk file (see | |
3427 | Section 6.6.2.3). | |
3428 | \li afs puttofileLock [Index 9]: This lock is obsolete, and while still defined | |
3429 | by the system is no longer used. It formerly serialized writes to a debugging | |
3430 | output interface buffer, but the internal mechanism has since been updated and | |
3431 | improved. | |
3432 | \li afs ftf [Index 10]: This lock is used when flushing cache text pages from | |
3433 | the machine's virtual memory tables. For each specific machine architecture on | |
3434 | which the Cache Manager runs, there is a set of virtual memory operations which | |
3435 | must be invoked to perform this operation. The result of such activities is to | |
3436 | make sure that the latest contents of new incarnations of binaries are used, | |
3437 | instead of outdated copies of previous versions still resident in the virtual | |
3438 | memory system. | |
3439 | ||
3440 | \subsection sec6-5-3 Section 6.5.3: Definitions and Typedefs | |
3441 | ||
3442 | \par | |
3443 | This section documents some macro definitions and typedefs referenced by the | |
3444 | Cache Manager's RPC interface. Specifically, these definitions and typedefs are | |
3445 | used in the RXAFSCB GetXStats() and RXAFSCB XStatsVersion calls as described in | |
3446 | Sections 6.5.5.6 and 6.5.5.7. | |
3447 | ||
3448 | \code | |
3449 | /* | |
3450 | * Define the version of CacheManager and FileServer extended | |
3451 | * statistics being implemented. | |
3452 | */ | |
3453 | const AFSCB_XSTAT_VERSION = 1; | |
3454 | ||
3455 | /* | |
3456 | * Define the maximum arrays for passing extended statistics | |
3457 | * info for the CacheManager and FileServer back to our caller. | |
3458 | */ | |
3459 | const AFSCB_MAX_XSTAT_LONGS = 2048; | |
3460 | typedef long AFSCB_CollData<AFSCB_MAX_XSTAT_LONGS>; | |
3461 | ||
3462 | /* | |
3463 | * Define the identifiers for the accessible extended stats data | |
3464 | * collections. | |
3465 | */ | |
3466 | const AFSCB_XSTATSCOLL_CALL_INFO = 0; /*CM call counting & info*/ | |
3467 | const AFSCB_XSTATSCOLL_PERF_INFO = 1; /*CM performance info*/ | |
3468 | \endcode | |
3469 | ||
3470 | \subsection sec6-5-4 Section 6.5.4: Structures | |
3471 | ||
3472 | \par | |
3473 | This section documents some structures used in the Cache Manager RPC interface. | |
3474 | As with the constants and typedefs in the previous section, these items are | |
3475 | used in the RXAFSCB GetXStats() and RXAFSCB XStatsVersion calls as described in | |
3476 | Sections 6.5.5.6 and 6.5.5.7. | |
3477 | ||
3478 | \subsubsection sec6-5-4-1 Section 6.5.4.1: struct afs MeanStats | |
3479 | ||
3480 | \par | |
3481 | This structure may be used to collect a running average figure. It is included | |
3482 | in some of the statistics structures described below. | |
3483 | \n \b Fields | |
3484 | \li long average - The computed average. | |
3485 | \li long elements - The number of elements sampled for the above aveage. | |
3486 | ||
3487 | \subsubsection sec6-5-4-2 Section 6.5.4.2: struct afs CMCallStats | |
3488 | ||
3489 | \par | |
3490 | This structure maintains profiling information, communicating the number of | |
3491 | times internal Cache Manager functions are invoked. Each field name has a "C " | |
3492 | prefix, followed by the name of the function being watched. As this structure | |
3493 | has entries for over 500 functions, it will not be described further here. | |
3494 | Those readers who wish to see the full layout of this structure are referred to | |
3495 | Appendix A. | |
3496 | \par | |
3497 | The AFSCB XSTATSCOLL CALL INFO data collection includes the information in this | |
3498 | structure. | |
3499 | ||
3500 | \subsubsection sec6-5-4-3 Section 6.5.4.3: struct afs CMMeanStats | |
3501 | ||
3502 | \par | |
3503 | This is the other part of the information (along with the struct afs | |
3504 | CMCallStats construct described above) returned by the AFSCB XSTATSCOLL CALL | |
3505 | INFO data collection defined by the Cache Manager (see Section 6.5.3). It is | |
3506 | accessible via the RXAFSCB GetXStats() interface routine, as defined in Section | |
3507 | 6.5.5.7. | |
3508 | \par | |
3509 | This structure represents the beginning of work to compute average values for | |
3510 | some of the extended statistics collected by the Cache Manager. | |
3511 | \n \b Fields | |
3512 | \li struct afs MeanStats something - Intended to collect averages for some of | |
3513 | the Cache Manager extended statistics; not yet implemented. | |
3514 | ||
3515 | \subsubsection sec6-5-4-4 Section 6.5.4.4: struct afs CMStats | |
3516 | ||
3517 | \par | |
3518 | This structure defines the information returned by the AFSCB XSTATSCOLL CALL | |
3519 | INFO data collection defined by the Cache Manager (see Section 6.5.3). It is | |
3520 | accessible via the RXAFSCB GetXStats() interface routine, as defined in Section | |
3521 | 6.5.5.7. | |
3522 | \n \b Fields | |
3523 | \li struct afs CallStats callInfo - Contains the counts on the number of times | |
3524 | each internal Cache Manager function has been called. | |
3525 | \li struct afs MeanStats something - Intended to collect averages for some of | |
3526 | the Cache Manager extended statistics; not yet implemented. | |
3527 | ||
3528 | \subsubsection sec6-5-4-5 Section 6.5.4.5: struct afs CMPerfStats | |
3529 | ||
3530 | \par | |
3531 | This is the information returned by the AFSCB XSTATSCOLL PERF INFO data | |
3532 | collection defined by the Cache Manager (see Section 6.5.3). It is accessible | |
3533 | via the RXAFSCB GetXStats() interface routine, as defined in Section 6.5.5.7. | |
3534 | \n \b Fields | |
3535 | \li long numPerfCalls - Number of performance calls received. | |
3536 | \li long epoch - Cache Manager epoch time. | |
3537 | \li long numCellsContacted - Number of cells contacted. | |
3538 | \li long dlocalAccesses - Number of data accesses to files within the local | |
3539 | cell. | |
3540 | \li long vlocalAccesses - Number of stat accesses to files within the local | |
3541 | cell. | |
3542 | \li long dremoteAccesses - Number of data accesses to files outside of the | |
3543 | local cell. | |
3544 | \li long vremoteAccesses - Number of stat accesses to files outside of the | |
3545 | local cell. | |
3546 | \li long cacheNumEntries - Number of cache entries. | |
3547 | \li long cacheBlocksTotal - Number of (1K) blocks configured for the AFS cache. | |
3548 | \li long cacheBlocksInUse - Number of cache blocks actively in use. | |
3549 | \li long cacheBlocksOrig - Number of cache blocks configured at bootup. | |
3550 | \li long cacheMaxDirtyChunks - Maximum number of dirty cache chunks tolerated. | |
3551 | \li long cacheCurrDirtyChunks - Current count of dirty cache chunks. | |
3552 | \li long dcacheHits - Number of data file requests satisfied by the local | |
3553 | cache. | |
3554 | \li long vcacheHits - Number of stat entry requests satisfied by the local | |
3555 | cache. | |
3556 | \li long dcacheMisses - Number of data file requests not satisfied by the local | |
3557 | cache. | |
3558 | \li long vcacheMisses - Number of stat entry requests not satisfied by the | |
3559 | local cache. | |
3560 | \li long cacheFlushes - Number of files flushed from the cache. | |
3561 | \li long cacheFilesReused - Number of cache files reused. | |
3562 | \li long numServerRecords - Number of records used for storing information | |
3563 | concerning File Servers. | |
3564 | \li long ProtServerAddr - IP addres of the Protection Server used (not | |
3565 | implemented). | |
3566 | \li long spare[32] - A set of longword spares reserved for future use. | |
3567 | ||
3568 | \subsection sec6-5-5 Section 6.5.5: Function Calls | |
3569 | ||
3570 | \par | |
3571 | This section discusses the Cache Manager interface calls. No special | |
3572 | permissions are required of the caller for any of these operations. A summary | |
3573 | of the calls making up the interface appears below: | |
3574 | \li RXAFSCB Probe() "Are-you-alive" call. | |
3575 | \li RXAFSCB CallBack() Report callbacks dropped by a File Server. | |
3576 | \li RXAFSCB InitCallBackState() Purge callback state from a File Server. | |
3577 | \li RXAFSCB GetLock() Get contents of Cache Manager lock table. | |
3578 | \li RXAFSCB GetCE() Get cache file description. | |
3579 | \li RXAFSCB XStatsVersion() Get version of extended statistics package. | |
3580 | \li RXAFSCB GetXStats() Get contents of extended statistics data collection. | |
3581 | ||
3582 | \subsubsection sec6-5-5-1 Section 6.5.5.1: RXAFSCB Probe - Acknowledge | |
3583 | that the underlying callback service is still operational | |
3584 | ||
3585 | \code | |
3586 | int RXAFSCB Probe(IN struct rx call *a rxCallP) | |
3587 | \endcode | |
3588 | \par Description | |
3589 | [Opcode 206] This call simply implements an "are-you-alive" operation, used to | |
3590 | determine if the given Cache Manager is still running. Any File Server will | |
3591 | probe each of the Cache Managers with which it has interacted on a regular | |
3592 | basis, keeping track of their health. This information serves an important | |
3593 | purpose for a File Server. In particular, it is used to trigger purging of | |
3594 | deceased Cache Managers from the File Server's callback records, and also to | |
3595 | instruct a new or "resurrected" Cache Manager to purge its own callback state | |
3596 | for the invoking File Server. | |
3597 | \par | |
3598 | Rx call information for the related Cache Manager is contained in a rxCallP. | |
3599 | \par Error Codes | |
3600 | ---No error codes are generated. | |
3601 | ||
3602 | \subsubsection sec6-5-5-2 Section 6.5.5.2: RXAFSCB CallBack - Report | |
3603 | callbacks dropped by a File Server | |
3604 | ||
3605 | \code | |
3606 | int RXAFSCB CallBack(IN struct rx call *a rxCallP, | |
3607 | IN AFSCBFids *a fidArrayP, | |
3608 | IN AFSCBs *a callBackArrayP) | |
3609 | \endcode | |
3610 | \par Description | |
3611 | [Opcode 204] Provide information on dropped callbacks to the Cache Manager for | |
3612 | the calling File Server. The number of fids involved appears in a | |
3613 | fidArrayP->AFSCBFids len, with the fids themselves located at a | |
3614 | fidArrayP->AFSCBFids val. Similarly, the number of associated callbacks is | |
3615 | placed in a callBackArrayP->AFSCBs len, with the callbacks themselves located | |
3616 | at a callBackArrayP->AFSCBs val. | |
3617 | \par | |
3618 | Rx call information for the related Cache Manager is contained in a rxCallP. | |
3619 | \par Error Codes | |
3620 | ---No error codes are generated. | |
3621 | ||
3622 | \subsubsection sec6-5-5-3 Section 6.5.5.3: RXAFSCB InitCallBackState - | |
3623 | Purge callback state from a File Server | |
3624 | ||
3625 | \code | |
3626 | int RXAFSCB InitCallBackState(IN struct rx call *a rxCallP) | |
3627 | \endcode | |
3628 | \par Description | |
3629 | [Opcode 205] This routine instructs the Cache Manager to purge its callback | |
3630 | state for all files and directories that live on the calling host. This | |
3631 | function is typically called by a File Server when it gets a request from a | |
3632 | Cache Manager that does not appear in its internal records. This handles | |
3633 | situations where Cache Managers survive a File Server, or get separated from it | |
3634 | via a temporary network partition. This also happens upon bootup, or whenever | |
3635 | the File Server must throw away its record of a Cache Manager because its | |
3636 | tables have been filled. | |
3637 | \par | |
3638 | Rx call information for the related Cache Manager is contained in a rxCallP. | |
3639 | \par Error Codes | |
3640 | ---No error codes are generated. | |
3641 | ||
3642 | \subsubsection sec6-5-5-4 Section 6.5.5.4: RXAFSCB GetLock - Get | |
3643 | contents of Cache Manager lock table | |
3644 | ||
3645 | \code | |
3646 | int RXAFSCB GetLock(IN struct rx call *a rxCall, | |
3647 | IN long a index, | |
3648 | OUT AFSDBLock *a lockP) | |
3649 | \endcode | |
3650 | \par Description | |
3651 | [Opcode 207] Fetch the contents of entry a index in the Cache Manager lock | |
3652 | table. There are 11 locks in the table, as described in Section 6.5.2. The | |
3653 | contents of the desired lock, including a string name representing the lock, | |
3654 | are returned in a lockP. | |
3655 | \par | |
3656 | This call is not used by File Servers, but rather by debugging tools such as | |
3657 | cmdebug. | |
3658 | \par | |
3659 | Rx call information for the related Cache Manager is contained in a rxCallP. | |
3660 | \par Error Codes | |
3661 | The index value supplied in a index is out of range; it must be between 0 and | |
3662 | 10. | |
3663 | ||
3664 | \subsubsection sec6-5-5-5 Section 6.5.5.5: RXAFSCB GetCE - Get cache | |
3665 | file description | |
3666 | ||
3667 | \code | |
3668 | int RXAFSCB GetCE(IN struct rx call *a rxCall, | |
3669 | IN long a index, | |
3670 | OUT AFSDBCacheEntry *a ceP) | |
3671 | \endcode | |
3672 | \par Description | |
3673 | [Opcode 208] Fetch the description for entry a index in the Cache Manager file | |
3674 | cache, storing it into the buffer to which a ceP points. The structure returned | |
3675 | into this pointer variable is described in Section 4.3.2. | |
3676 | \par | |
3677 | This call is not used by File Servers, but rather by debugging tools such as | |
3678 | cmdebug. | |
3679 | \par | |
3680 | Rx call information for the related Cache Manager is contained in a rxCallP. | |
3681 | \par Error Codes | |
3682 | The index value supplied in a index is out of range. | |
3683 | ||
3684 | \subsubsection sec6-5-5-6 Section 6.5.5.6: RXAFSCB XStatsVersion - Get | |
3685 | version of extended statistics package | |
3686 | ||
3687 | \code | |
3688 | int RXAFSCB XStatsVersion(IN struct rx call *a rxCall, | |
3689 | OUT long *a versionNumberP) | |
3690 | \endcode | |
3691 | \par Description | |
3692 | [Opcode 209] This call asks the Cache Manager for the current version number of | |
3693 | the extended statistics structures it exports (see RXAFSCB GetXStats(), Section | |
3694 | 6.5.5.7). The version number is placed in a versionNumberP. | |
3695 | \par | |
3696 | Rx call information for the related Cache Manager is contained in a rxCallP. | |
3697 | \par Error Codes | |
3698 | ---No error codes are generated. | |
3699 | ||
3700 | \subsubsection sec6-5-5-7 Section 6.5.5.7: RXAFSCB GetXStats - Get | |
3701 | contents of extended statistics data collection | |
3702 | ||
3703 | \code | |
3704 | int RXAFSCB GetXStats(IN struct rx call *a rxCall, | |
3705 | IN long a clientVersionNumber, | |
3706 | IN long a collectionNumber, | |
3707 | OUT long *a srvVersionNumberP, | |
3708 | OUT long *a timeP, | |
3709 | OUT AFSCB CollData *a dataP) | |
3710 | \endcode | |
3711 | \par Description | |
3712 | [Opcode 210] This function fetches the contents of the specified Cache Manager | |
3713 | extended statistics structure. The caller provides the version number of the | |
3714 | data it expects to receive in a clientVersionNumber. Also provided in a | |
3715 | collectionNumber is the numerical identifier for the desired data collection. | |
3716 | There are currently two of these data collections defined: AFSCB XSTATSCOLL | |
3717 | CALL INFO, which is the list of tallies of the number of invocations of | |
3718 | internal Cache Manager procedure calls, and AFSCB XSTATSCOLL PERF INFO, which | |
3719 | is a list of performance-related numbers. The precise contents of these | |
3720 | collections are described in Section 6.5.4. The current version number of the | |
3721 | Cache Manager collections is returned in a srvVersionNumberP, and is always set | |
3722 | upon return, even if the caller has asked for a different version. If the | |
3723 | correct version number has been specified, and a supported collection number | |
3724 | given, then the collection data is returned in a dataP. The time of collection | |
3725 | is also returned, being placed in a timeP. | |
3726 | \par | |
3727 | Rx call information for the related Cache Manager is contained in a rxCallP. | |
3728 | \par Error Codes | |
3729 | The collection number supplied in a collectionNumber is out of range. | |
3730 | ||
3731 | \section sec6-6 Section 6.6: Files | |
3732 | ||
3733 | \par | |
3734 | The Cache Manager gets some of its start-up configuration information from | |
3735 | files located on the client machine's hard disk. Each client is required to | |
3736 | supply a /usr/vice/etc directory in which this configuration data is kept. | |
3737 | Section 6.6.1 describes the format and purpose of the three files contributing | |
3738 | this setup information: ThisCell, CellServDB, and cacheinfo. | |
3739 | ||
3740 | \subsection sec6-6-1 Section 6.6.1: Configuration Files | |
3741 | ||
3742 | \subsubsection sec6-6-1-1 Section 6.6.1.1: ThisCell | |
3743 | ||
3744 | \par | |
3745 | The Cache Manager, along with various applications, needs to be able to | |
3746 | determine the cell to which its client machine belongs. This information is | |
3747 | provided by the ThisCell file. It contains a single line stating the machine's | |
3748 | fully-qualified cell name. | |
3749 | \par | |
3750 | As with the CellServDB configuration file, the Cache Manager reads the contents | |
3751 | of ThisCell exactly once, at start-up time. Thus, an incarnation of the Cache | |
3752 | Manager will maintain precisely one notion of its home cell for its entire | |
3753 | lifetime. Thus, changes to the text of the ThisCell file will be invisible to | |
3754 | the running Cache Manager. However, these changes will affect such application | |
3755 | programs as klog, which allows a user to generate new authentication tickets. | |
3756 | In this example, klog reads ThisCell every time it is invoked, and then | |
3757 | interacts with the set of Authentication Servers running in the given home | |
3758 | cell, unless the caller specifies the desired cell on the command line. | |
3759 | \par | |
3760 | The ThisCell file is not expected to be changed on a regular basis. Client | |
3761 | machines are not imagined to be frequently traded between different | |
3762 | administrative organizations. The Unix mode bits are set to specify that while | |
3763 | everyone is allowed to read the file, only root is allowed to modify it. | |
3764 | ||
3765 | \subsubsection sec6-6-1-2 Section 6.6.1.2: CellServDB | |
3766 | ||
3767 | \par | |
3768 | To conduct business with a given AFS cell, a Cache Manager must be informed of | |
3769 | the cell's name and the set of machines running AFS database servers within | |
3770 | that cell. Such servers include the Volume Location Server, Authentication | |
3771 | Server, and Protection Server. This particular cell information is obtained | |
3772 | upon startup by reading the CellServDB file. Thus, when the Cache Manager | |
3773 | initialization is complete, it will be able to communicate with the cells | |
3774 | covered by CellServDB. | |
3775 | \par | |
3776 | The following is an excerpt from a valid CellServDB file, demonstrating the | |
3777 | format used. | |
3778 | ||
3779 | \code | |
3780 | ... | |
3781 | >transarc.com #Transarc Corporation | |
3782 | 192.55.207.7 #henson.transarc.com | |
3783 | 192.55.207.13 #bigbird.transarc.com | |
3784 | 192.55.207.22 #ernie.transarc.com | |
3785 | >andrew.cmu.edu #Carnegie Mellon University | |
3786 | 128.2.10.2 #vice2.fs.andrew.cmu.edu | |
3787 | 128.2.10.7 #vice7.fs.andrew.cmu.edu | |
3788 | 128.2.10.10 #vice10.fs.andrew.cmu.edu | |
3789 | ... | |
3790 | \endcode | |
3791 | \par | |
3792 | There are four rules describing the legal CellServDB file format: | |
3793 | \li 1. Each cell has a separate entry. The entries may appear in any order. It | |
3794 | may be convenient, however, to have the workstation's local cell be the first | |
3795 | to appear. | |
3796 | \li 2. No blank lines should appear in the file, even at the end of the last | |
3797 | entry. | |
3798 | \li 3. The first line of each cell's entry begins with the '>' character, and | |
3799 | specifies the cell's human-readable, Internet Domain-style name. Optionally, | |
3800 | some white space and a comment (preceded by a '#') may follow, briefly | |
3801 | describing the specified cell. | |
3802 | \li 4. Each subsequent line in a cell's entry names one of the cell's database | |
3803 | server machines. The following must appear on the line, in the order given: | |
3804 | \li The Internet address of the server, in the standard 4-component dot | |
3805 | notation. | |
3806 | \li Some amount of whitespace. | |
3807 | \li A '#', followed by the machine's complete Internet host name. In this | |
3808 | instance, the '#' sign and the text beyond it specifying the machine name are | |
3809 | NOT treated as a comment. This is required information. | |
3810 | \par | |
3811 | The Cache Manager will use the given host name to determine its current address | |
3812 | via an Internet Domain lookup. If and only if this lookup fails does the Cache | |
3813 | Manager fall back to using the dotted Internet address on the first part of the | |
3814 | line. This dotted address thus appears simply as a hint in case of Domain | |
3815 | database downtime. | |
3816 | \par | |
3817 | The CellServDB file is only parsed once, when the Cache Manager first starts. | |
3818 | It is possible, however, to amend existing cell information records or add | |
3819 | completely new ones at any time after Cache Manager initialization completes. | |
3820 | This is accomplished via the VIOCNEWCELL pioctl() (see Section 6.4.5.1. | |
3821 | ||
3822 | \subsubsection sec6-6-1-3 Section 6.6.1.3: cacheinfo | |
3823 | ||
3824 | \par | |
3825 | This one-line file contains three fields separated by colons: | |
3826 | \li AFS Root Directory: This is the directory where the Cache Manager mounts | |
3827 | the AFS root volume. Typically, this is specified to be /afs. | |
3828 | \li Cache Directory: This field names the directory where the Cache Manager is | |
3829 | to create its local cache files. This is typically set to /usr/vice/cache. | |
3830 | \li Cache Blocks: The final field states the upper limit on the number of | |
3831 | 1,024-byte blocks that the Cache Manager is allowed to use in the partition | |
3832 | hosting the named cache directory. | |
3833 | \par | |
3834 | Thus, the following cacheinfo file would instruct the Cache Manager to mount | |
3835 | the AFS filespace at /afs, and inform it that it may expect to be able to use | |
3836 | up to 25,000 blocks for the files in its cache directory, /usr/vice/cache. | |
3837 | \code | |
3838 | /afs:/usr/vice/cache:25000 | |
3839 | \endcode | |
3840 | ||
3841 | \subsection sec6-6-2 Section 6.6.2: Cache Information Files | |
3842 | ||
3843 | \subsubsection sec6-6-2-1 Section 6.6.2.1: AFSLog | |
3844 | ||
3845 | \par | |
3846 | This is the AFS log file used to hold Cache Manager debugging output. The file | |
3847 | is set up when the Cache Manager first starts. If it already exists, it is | |
3848 | truncated. If it doesn't, it is created. Output to this file is enabled and | |
3849 | disabled via the the VIOC VENUSLOG pioctl() (see Section 6.4.9.2). Normal text | |
3850 | messages are written to this file by the Cache Manager when output is enabled. | |
3851 | Each time logging to this file is enabled, the AFSLog file is truncated. Only | |
3852 | root can read and write this file. | |
3853 | ||
3854 | \subsubsection sec6-6-2-2 Section 6.6.2.2: CacheItems | |
3855 | ||
3856 | \par | |
3857 | The Cache Manager only keeps a subset of its data cache entry descriptors in | |
3858 | memory at once. The number of these in-memory descriptors is determined by | |
3859 | afsd. All of the data cache entry descriptors are kept on disk, in the | |
3860 | CacheItems file. The file begins with a header region, taking up four | |
3861 | longwords: | |
3862 | \code | |
3863 | struct fheader { long magic AFS_FHMAGIC 0x7635fab8 long firstCSize: First chunk | |
3864 | size long otherCSize: Next chunk sizes long spare } | |
3865 | \endcode | |
3866 | \par | |
3867 | The header is followed by one entry for each cache file. Each is: | |
3868 | \code | |
3869 | struct fcache { | |
3870 | short hvNextp; /* Next in vnode hash table, or freeDCList */ | |
3871 | short hcNextp; /* Next index in [fid, chunk] hash table */ | |
3872 | short chunkNextp; /* File queue of all chunks for a single vnode */ | |
3873 | struct VenusFid fid; /* Fid for this file */ | |
3874 | long modTime; /* last time this entry was modified */ | |
3875 | long versionNo; /* Associated data version number */ | |
3876 | long chunk; /* Relative chunk number */ | |
3877 | long inode; /* Unix inode for this chunk */ | |
3878 | long chunkBytes; /* Num bytes in this chunk */ | |
3879 | char states; /* Has this chunk been modified? */ | |
3880 | }; | |
3881 | \endcode | |
3882 | ||
3883 | \subsubsection sec6-6-2-3 Section 6.6.2.3: VolumeItems | |
3884 | ||
3885 | \par | |
3886 | The Cache Manager only keeps at most MAXVOLS (50) in-memory volume | |
3887 | descriptions. However, it records all volume information it has obtained in the | |
3888 | VolumeItems file in the chosen AFS cache directory. This file is truncated when | |
3889 | the Cache Manager starts. Each volume record placed into this file has the | |
3890 | following struct fvolume layout: | |
3891 | \code | |
3892 | struct fvolume { | |
3893 | long cell; /*Cell for this entry*/ | |
3894 | long volume; /*Numerical volume ID */ | |
3895 | long next; /*Hash index*/ | |
3896 | struct VenusFid dotdot; /*Full fid for .. dir */ | |
3897 | struct VenusFid mtpoint; /*Full fid for mount point*/ | |
3898 | }; | |
3899 | \endcode | |
3900 | ||
3901 | \section sec6-7 Section 6.7: Mariner Interface | |
3902 | ||
3903 | \par | |
3904 | The Cache Manager Mariner interface allows interested parties to be advised in | |
3905 | real time as to which files and/or directories are being actively transferred | |
3906 | between the client machine and one or more File Servers. If enabled, this | |
3907 | service delivers messages of two different types, as exemplified below: | |
3908 | \code | |
3909 | Fetching myDataDirectory | |
3910 | Fetching myDataFile.c | |
3911 | Storing myDataObj.o | |
3912 | \endcode | |
3913 | \par | |
3914 | In the first message, the myDataDirectory directory is shown to have just been | |
3915 | fetched from a File Server. Similarly, the second message indicates that the C | |
3916 | program myDataFile.c had just been fetched from its File Server of residence. | |
3917 | Finally, the third message reveals that the myDataObj.o object file has just | |
3918 | been written out over the network to its respective server. | |
3919 | \par | |
3920 | In actuality, the text of the messages carries a string prefix to indicate | |
3921 | whether a Fetch or Store operation had been performed. So, the full contents of | |
3922 | the above messages are as follows: | |
3923 | \code | |
3924 | fetch$Fetching myDataDirectory | |
3925 | fetch$Fetching myDataFile.c | |
3926 | store$Storing myDataObj.o | |
3927 | \endcode | |
3928 | The Mariner service may be enabled or disabled for a particular machine by | |
3929 | using the VIOC AFS MARINER HOST pioctl() (see Section 6.4.9.1). This operation | |
3930 | allows any host to be specified as the recipient of these messages. A potential | |
3931 | recipient must have its host be declared the target of such messages, then | |
3932 | listen to a socket on port 2106. | |
3933 | \par | |
3934 | Internally, the Cache Manager maintains a cache of NMAR (10) vnode structure | |
3935 | pointers and the string name (up to 19 characters) of the associated file or | |
3936 | directory. This cache is implemented as an array serving as a circular buffer. | |
3937 | Each time a file is involved in a create or lookup operation on a File Server, | |
3938 | the current slot in this circular buffer is filled with the relevant vnode and | |
3939 | string name information, and the current position is advanced. If Mariner | |
3940 | output is enabled, then an actual network fetch or store operation will trigger | |
3941 | messages of the kind shown above. Since a fetch or store operation normally | |
3942 | occurs shortly after the create or lookup, the mapping of vnode to name is | |
3943 | likely to still be in the Mariner cache when it comes time to generate the | |
3944 | appropriate message. However, since an unbounded number of other lookups or | |
3945 | creates could have been performed in the interim, there is no guarantee that | |
3946 | the mapping entry will not have been overrun. In these instances, the Mariner | |
3947 | message will be a bit vaguer. Going back to our original example, | |
3948 | \code | |
3949 | Fetching myDataDirectory | |
3950 | Fetching a file | |
3951 | Storing myDataObj.o | |
3952 | \endcode | |
3953 | In this case, the cached association between the vnode containing myDataFile.c | |
3954 | and its string name was thrown out of the Mariner cache before the network | |
3955 | fetch operation could be performed. Unable to find the mapping, the generic | |
3956 | phrase "a file" was used to identify the object involved. | |
3957 | \par | |
3958 | Mariner messages only get generated when RPC traffic for fetching or storing a | |
3959 | file system object occurs between the Cache Manager and a File Server. Thus, | |
3960 | file accesses that are handled by the Cache Manager's on-board data cache do | |
3961 | not trigger such announcements. | |
3962 | ||
3963 | \page biblio Bibliography | |
3964 | ||
3965 | \li [1] Transarc Corporation. AFS 3.0 System Administrator's Guide, | |
3966 | F-30-0-D102, Pittsburgh, PA, April 1990. | |
3967 | \li [2] Transarc Corporation. AFS 3.0 Command Reference Manual, F-30-0-D103, | |
3968 | Pittsburgh, PA, April 1990. | |
3969 | \li [3] CMU Information Technology Center. Synchronization and Caching Issues | |
3970 | in the Andrew File System, USENIX Proceedings, Dallas, TX, Winter 1988. | |
3971 | \li [4] Sun Microsystems, Inc. NFS: Network File System Protocol Specification, | |
3972 | RFC 1094, March 1989. | |
3973 | \li [5] Sun Microsystems, Inc. Design and Implementation of the Sun Network | |
3974 | File System, USENIX Summer Conference Proceedings, June 1985. | |
3975 | \li [6] S.P. Miller, B.C. Neuman, J.I. Schiller, J.H. Saltzer. Kerberos | |
3976 | Authentication and Authorization System, Project Athena Technical Plan, Section | |
3977 | E.2.1, M.I.T., December 1987. | |
3978 | \li [7] Bill Bryant. Designing an Authentication System: a Dialogue in Four | |
3979 | Scenes, Project Athena internal document, M.I.T, draft of 8 February 1988. | |
3980 | ||
3981 | */ |