| 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 | */ |