Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | afsd, afsd.fuse - Initializes the Cache Manager and starts related daemons | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<afsd> [B<-afsdb>] [B<-backuptree>] | |
11 | S<<< [B<-biods> <I<number of bkg I/O daemons (aix vm)>>] >>> | |
12 | S<<< [B<-blocks> <I<1024 byte blocks in cache>>] >>> | |
13 | S<<< [B<-cachedir> <I<cache directory>>] >>> | |
14 | S<<< [B<-chunksize> <I<log(2) of chunk size>>] >>> | |
15 | S<<< [B<-confdir> <I<configuration directory>>] >>> | |
16 | S<<< [B<-daemons> <I<number of daemons to use>>] >>> | |
17 | S<<< [B<-dcache> <I<number of dcache entries>>] >>> [B<-debug>] | |
18 | [B<-dynroot>] [B<-dynroot-sparse>] [B<-enable_peer_stats>] | |
19 | [B<-enable_process_stats>] [B<-fakestat>] [B<-fakestat-all>] | |
20 | S<<< [B<-files> <I<files in cache>>] >>> | |
21 | S<<< [B<-files_per_subdir> <I<log(2) of files per dir>> ] >>> | |
22 | [B<-help>] S<<< [B<-logfile> <I<Place to keep the CM log>>] >>> | |
23 | S<<< [B<-inumcalc>] <I<method>> >>> | |
24 | [B<-mem_alloc_sleep>] [B<-memcache>] | |
25 | S<<< [B<-mountdir> <I<mount location>>] >>> [B<-nomount>] | |
26 | [B<-nosettime>] | |
27 | S<<< [B<-prealloc> <I<number of 'small' preallocated blocks>>] >>> | |
28 | [B<-rmtsys>] S<<< [B<-rootvol> <I<name of AFS root volume>>] >>> | |
29 | [B<-rxbind>] S<<< [B<-rxmaxmtu> value for maximum MTU ] >>> | |
30 | S<<< [B<-rxpck> value for rx_extraPackets ] >>> | |
31 | [B<-settime>] [B<-shutdown>] | |
32 | S<<< [B<-splitcache> <I<RW/RO ratio>>] >>> | |
33 | S<<< [B<-stat> <I<number of stat entries>>] >>> [B<-verbose>] | |
34 | [B<-disable-dynamic-vcaches>] | |
35 | S<<< [B<-volumes> <I<number of volume entries>>] >>> | |
36 | [B<-waitclose>] [B<-rxmaxfrags> <I<max # of fragments>>] | |
37 | S<<< [B<-volume-ttl> <I<vldb cache timeout>>] >>> | |
38 | ||
39 | =for html | |
40 | </div> | |
41 | ||
42 | =head1 DESCRIPTION | |
43 | ||
44 | The B<afsd> command initializes the Cache Manager on an AFS client machine | |
45 | by transferring AFS-related configuration information into kernel memory | |
46 | and starting several daemons. B<afsd.fuse> is an experimental variant that | |
47 | initializes a FUSE-based Cache Manager instead of one based on a kernel | |
48 | module. | |
49 | ||
50 | The B<afsd> command performs the following actions: | |
51 | ||
52 | =over 4 | |
53 | ||
54 | =item * | |
55 | ||
56 | Sets a field in kernel memory that defines the machine's cell | |
57 | membership. Some Cache Manager-internal operations and system calls | |
58 | consult this field to learn which cell to execute in. (The AFS command | |
59 | interpreters refer to the F</usr/vice/etc/ThisCell> file instead.) This | |
60 | information is transferred into the kernel from the | |
61 | F</usr/vice/etc/ThisCell> file and cannot be changed until the B<afsd> | |
62 | program runs again. | |
63 | ||
64 | =item * | |
65 | ||
66 | Places in kernel memory the names and Internet addresses of the database | |
67 | server machines in the local cell and (optionally) foreign cells. The | |
68 | appearance of a cell's database server machines in this list enables the | |
69 | Cache Manager to contact them and to access files in the cell. Omission of | |
70 | a cell from this list, or incorrect information about its database server | |
71 | machines, prevents the Cache Manager from accessing files in it. | |
72 | ||
73 | By default, the list of database server machines is transferred into the | |
74 | kernel from the F</usr/vice/etc/CellServDB> file. Alternatively, when the | |
75 | B<-afsdb> option is used, the list of database server machines is taken | |
76 | from the DNS SRV or AFSDB records for each cell. After initialization, use the | |
77 | B<fs newcell> command to change the kernel-resident list without having to | |
78 | reboot. | |
79 | ||
80 | =item * | |
81 | ||
82 | Mounts the root of the AFS filespace on a directory on the machine's local | |
83 | disk, according to either the first field in the | |
84 | F</usr/vice/etc/cacheinfo> file (the default) or the B<afsd> command's | |
85 | B<-mountdir> argument. The conventional value is F</afs>. | |
86 | ||
87 | =item * | |
88 | ||
89 | Determines which volume to mount at the root of the AFS file tree. The | |
90 | default is the volume C<root.afs>; use the B<-rootvol> argument to | |
91 | override it. Although the base (read/write) form of the volume name is the | |
92 | appropriate value, the Cache Manager has a bias for accessing the | |
93 | read-only version of the volume (by convention, C<root.afs.readonly>) if | |
94 | it is available. | |
95 | ||
96 | =item * | |
97 | ||
98 | Configures the cache on disk (the default) or in machine memory if the | |
99 | B<-memcache> argument is provided. In the latter case, the B<afsd> program | |
100 | allocates space in machine memory for caching, and the Cache Manager uses | |
101 | no disk space for caching even if the machine has a disk. | |
102 | ||
103 | =item * | |
104 | ||
105 | Defines the name of the local disk directory devoted to caching, when the | |
106 | B<-memcache> argument is not used. If necessary, the B<afsd> program | |
107 | creates the directory (its parent directory must already exist). It does | |
108 | not remove the directory that formerly served this function, if one | |
109 | exists. | |
110 | ||
111 | The second field in the F</usr/vice/etc/cacheinfo> file is the source for | |
112 | this name. The standard value is F</usr/vice/cache>. Use the B<-cachedir> | |
113 | argument to override the value in the B<cacheinfo> file. | |
114 | ||
115 | =item * | |
116 | ||
117 | Sets the size of the cache. The default source for the value is the third | |
118 | field in the F</usr/vice/etc/cacheinfo> file, which specifies a number of | |
119 | kilobytes. | |
120 | ||
121 | For a memory cache, the following arguments to the afsd command override | |
122 | the value in the B<cacheinfo> file: | |
123 | ||
124 | =over 4 | |
125 | ||
126 | =item * | |
127 | ||
128 | The B<-blocks> argument, to specify a different number of kilobyte blocks. | |
129 | ||
130 | =item * | |
131 | ||
132 | The B<-dcache> and B<-chunksize> arguments together, to set both the | |
133 | number of dcache entries and the chunk size (see below for definition of | |
134 | these parameters). In this case, the B<afsd> program derives cache size by | |
135 | multiplying the two values. Using this combination is not recommended, as | |
136 | it requires the issuer to perform the calculation beforehand to determine | |
137 | the resulting cache size. | |
138 | ||
139 | =item * | |
140 | ||
141 | The B<-dcache> argument by itself. In this case, the B<afsd> program | |
142 | derives cache size by multiplying the value specified by the B<-dcache> | |
143 | argument by the default memory cache chunk size of eight kilobytes. Using | |
144 | this argument is not recommended, as it requires the issuer to perform the | |
145 | calculation beforehand to determine the resulting cache size. | |
146 | ||
147 | =back | |
148 | ||
149 | For satisfactory memory cache performance, the specified value must leave | |
150 | enough memory free to accommodate all other processes and commands that | |
151 | can run on the machine. If the value exceeds the amount of memory | |
152 | available, the B<afsd> program exits without initializing the Cache | |
153 | Manager and produces the following message on the standard output stream: | |
154 | ||
155 | afsd: memCache allocation failure at <number> KB | |
156 | ||
157 | where <number> is how many kilobytes were allocated just before the | |
158 | failure. | |
159 | ||
160 | For a disk cache, use the B<-blocks> argument to the B<afsd> command to | |
161 | override the value in the B<cacheinfo> file. The value specified in either | |
162 | way sets an absolute upper limit on cache size; values provided for other | |
163 | arguments (such as B<-dcache> and B<-chunksize>) never result in a larger | |
164 | cache. The B<afsd> program rejects any setting larger than 95% of the | |
165 | partition size, and exits after generating an error message on the | |
166 | standard output stream, because the cache implementation itself requires a | |
167 | small amount of disk space and overfilling the partition can cause the | |
168 | client machine to panic. | |
169 | ||
170 | To change the size of a disk cache after initialization without rebooting, | |
171 | use the B<fs setcachesize> command; the setting persists until the B<afsd> | |
172 | command runs again or the B<fs setcachesize> command is reissued. The B<fs | |
173 | setcachesize> command does not work for memory caches. | |
174 | ||
175 | =item * | |
176 | ||
177 | Sets the size of each cache I<chunk>, and by implication the amount of | |
178 | data that the Cache Manager requests at a time from the File Server (how | |
179 | much data per fetch RPC, since AFS uses partial file transfer). | |
180 | ||
181 | For a disk cache, a chunk is a F<VI<n>> file and this parameter sets the | |
182 | maximum size to which each one can expand. For a memory cache, each chunk | |
183 | is a collection of contiguous memory blocks. The default for a disk cache | |
184 | is between 256 KB and 1 MB depending on the size of the cache. The default | |
185 | for a memory cache is 8 KB. | |
186 | ||
187 | To override the default chunk size for either type of cache, use the | |
188 | B<-chunksize> argument to provide an integer to be used as an exponent of | |
189 | two; see L</OPTIONS> for details. For a memory cache, if total cache size | |
190 | divided by chunk size leaves a remainder, the B<afsd> program rounds down | |
191 | the number of dcache entries, resulting in a slightly smaller cache. | |
192 | ||
193 | =item * | |
194 | ||
195 | Sets the number of chunks in the cache. For a memory cache, the number of | |
196 | chunks is equal to the cache size divided by the chunk size. For a disk | |
197 | cache, the number of chunks (F<VI<n>> files) is set to the largest | |
198 | of the following unless the B<-files> argument is used to set the value | |
199 | explicitly: | |
200 | ||
201 | =over 4 | |
202 | ||
203 | =item * | |
204 | ||
205 | 100 | |
206 | ||
207 | =item * | |
208 | ||
209 | 1.5 times the result of dividing cache size by chunk size | |
210 | (I<cachesize>/I<chunksize> * 1.5) | |
211 | ||
212 | =item * | |
213 | ||
214 | The result of dividing cachesize by 10 KB (I<cachesize>/10240) | |
215 | ||
216 | =back | |
217 | ||
218 | =item * | |
219 | ||
220 | Sets the number of I<dcache entries> allocated in machine memory for | |
221 | storing information about the chunks in the cache. | |
222 | ||
223 | For a disk cache, the F</usr/vice/cache/CacheItems> file contains one | |
224 | entry for each F<VI<n>> file. By default, one half the number of | |
225 | these entries (but not more that 2,000) are duplicated as dcache entries | |
226 | in machine memory for quicker access. | |
227 | ||
228 | For a memory cache, there is no F<CacheItems> file so all information | |
229 | about cache chunks must be in memory as dcache entries. Thus, there is no | |
230 | default number of dcache entries for a memory cache; instead, the B<afsd> | |
231 | program derives it by dividing the cache size by the chunk size. | |
232 | ||
233 | To set the number of dcache entries, use the B<-dcache> argument; the | |
234 | specified value can exceed the default limit of 2,000. Using this argument | |
235 | is not recommended for either type of cache. Increasing the number of | |
236 | dcache entries for a disk cache sometimes improves performance (because | |
237 | more entries are retrieved from memory rather than from disk), but only | |
238 | marginally. Using this argument for a memory cache requires the issuer to | |
239 | calculate the cache size by multiplying this value by the chunk size. | |
240 | ||
241 | =item * | |
242 | ||
243 | Sets the number of I<stat> entries available in machine memory for caching | |
244 | status information about cached AFS files. The default is based on the | |
245 | size of the cache. Use the B<-stat> argument to override the default. | |
246 | ||
247 | =back | |
248 | ||
249 | In addition to setting cache configuration parameters, the B<afsd> program | |
250 | starts the following daemons. (On most system types, these daemons appear | |
251 | as nameless entries in the output of the UNIX B<ps> command.) | |
252 | ||
253 | =over 4 | |
254 | ||
255 | =item * | |
256 | ||
257 | One I<callback> daemon, which handles callbacks. It also responds to the | |
258 | File Server's periodic probes, which check that the client machine is | |
259 | still alive. | |
260 | ||
261 | =item * | |
262 | ||
263 | One I<maintenance> daemon, which performs the following tasks: | |
264 | ||
265 | =over 4 | |
266 | ||
267 | =item * | |
268 | ||
269 | Garbage collects obsolete data (for example, expired tokens) from kernel | |
270 | memory. | |
271 | ||
272 | =item * | |
273 | ||
274 | Synchronizes files. | |
275 | ||
276 | =item * | |
277 | ||
278 | Refreshes information from read-only volumes once per hour. | |
279 | ||
280 | =item * | |
281 | ||
282 | Does delayed writes for NFS clients if the machine is running the NFS/AFS | |
283 | Translator. | |
284 | ||
285 | =back | |
286 | ||
287 | =item * | |
288 | ||
289 | One I<cache-truncation> daemon, which flushes the cache when free space is | |
290 | required, by writing cached data and status information to the File | |
291 | Server. | |
292 | ||
293 | =item * | |
294 | ||
295 | One I<server connection> daemon, which sends a probe to the File | |
296 | Server every few minutes to check that it is still accessible. | |
297 | ||
298 | =item * | |
299 | ||
300 | One or more I<background> daemons that improve performance by pre-fetching | |
301 | files and performing background (delayed) writes of saved data into AFS. | |
302 | ||
303 | The default number of background daemons is two, enough to service at | |
304 | least five simultaneous users of the machine. To increase the number, use | |
305 | the B<-daemons> argument. A value greater than six is not generally | |
306 | necessary. | |
307 | ||
308 | =item * | |
309 | ||
310 | On some system types, one I<Rx listener> daemon, which listens for | |
311 | incoming RPCs. | |
312 | ||
313 | =item * | |
314 | ||
315 | On some system types, one I<Rx event> daemon, which reviews the Rx | |
316 | system's queue of tasks and performs them as appropriate. Most items in | |
317 | the queue are retransmissions of failed packets. | |
318 | ||
319 | =item * | |
320 | ||
321 | On machines that run AIX with virtual memory (VM) integration, one or more | |
322 | I<VM> daemons (sometimes called I<I/O> daemons, which transfer data | |
323 | between disk and machine memory. The number of them depends on the setting | |
324 | of the B<-biods> and B<-daemons> arguments: | |
325 | ||
326 | =over 4 | |
327 | ||
328 | =item * | |
329 | ||
330 | If the B<-biods> argument is used, it sets the number of VM daemons. | |
331 | ||
332 | =item * | |
333 | ||
334 | If only the B<-daemons> argument is used, the number of VM daemons is | |
335 | twice the number of background daemons. | |
336 | ||
337 | =item * | |
338 | ||
339 | If neither argument is used, there are five VM daemons. | |
340 | ||
341 | =back | |
342 | ||
343 | =back | |
344 | ||
345 | B<afsd.fuse> is a variant of B<afsd> that, instead of initializing a Cache | |
346 | Manager implemented as a kernel module, initializes a FUSE-based AFS | |
347 | client. FUSE (Filesystem in USErspace) is a Linux-only mechanism for | |
348 | providing a file system through a purely user-space daemon without a | |
349 | kernel module component. B<afsd.fuse> takes all of the same options as | |
350 | B<afsd>. | |
351 | ||
352 | This command does not use the syntax conventions of the AFS command | |
353 | suites. Provide the command name and all option names in full. | |
354 | ||
355 | =head1 CAUTIONS | |
356 | ||
357 | Before using the B<-shutdown> parameter, use the standard UNIX B<umount> | |
358 | command to unmount the AFS root directory (by convention, F</afs>). On | |
359 | Linux, unloading the AFS kernel module and then loading it again before | |
360 | restarting AFS after B<-shutdown> is recommended. | |
361 | ||
362 | AFS has for years had difficulties with being stopped and restarted | |
363 | without an intervening reboot. While most of these issues have been | |
364 | ironed out, stopping and restarting AFS is not recommended unless | |
365 | necessary and rebooting before restarting AFS is still the safest course | |
366 | of action. This does not apply to Linux; it should be safe to restart the | |
367 | AFS client on Linux without rebooting. | |
368 | ||
369 | In contrast to many client-server applications, not all communication is | |
370 | initiated by the client. When the AFS client opens a file, it registers a | |
371 | callback with the AFS server. If the file changes, the server notifies the | |
372 | client that the file has changed and that all cached copies should be | |
373 | discarded. In order to enable full functionality on the AFS client, | |
374 | including all command-line utilities, the following UDP ports must be open | |
375 | on an firewalls between the client and the server: | |
376 | ||
377 | fileserver 7000/udp | |
378 | cachemanager 7001/udp (OpenAFS client. Arla uses 4711/udp) | |
379 | ptserver 7002/udp | |
380 | vlserver 7003/udp | |
381 | kaserver 7004/udp (not needed with Kerberos v5) | |
382 | volserver 7005/udp | |
383 | reserved 7006/udp (for future use) | |
384 | bosserver 7007/udp | |
385 | ||
386 | Clients will also need to be able to contact your Kerberos KDC to | |
387 | authenticate. If you are using B<kaserver> and B<klog>, you need to allow | |
388 | inbound and outbound UDP on ports >1024 (probably 1024<port<2048 would | |
389 | suffice depending on the number of simultaneous B<klog>s). | |
390 | ||
391 | Be sure to set the UDP timeouts on the firewall to be at least twenty | |
392 | minutes for the best callback performance. | |
393 | ||
394 | B<afsd.fuse> was first introduced in OpenAFS 1.5.74. It is only available | |
395 | if OpenAFS was built with the C<--enable-fuse-client> configure switch. | |
396 | It should be considered experimental. | |
397 | ||
398 | =head1 OPTIONS | |
399 | ||
400 | =over 4 | |
401 | ||
402 | =item B<-afsdb> | |
403 | ||
404 | Enable afsdb support. This will use DNS to lookup the SRV or AFSDB records and | |
405 | use that for the database servers for each cell instead of the values | |
406 | in the F<CellServDB> file. This has the advantage of only needing to | |
407 | update one set of DNS records to reconfigure the AFS clients for a new | |
408 | database server as opposed to touching all of the clients, and also | |
409 | allows one to access a cell without preconfiguring its database | |
410 | servers in F<CellServDB>. The format of SRV records is defined in | |
411 | RFC 5864, and the AFSDB record format is in RFC 1183. | |
412 | ||
413 | =item B<-backuptree> | |
414 | ||
415 | Prefer backup volumes for mountpoints in backup volumes. This option means | |
416 | that the AFS client will prefer to resolve mount points to backup volumes | |
417 | when a parent of the current volume is a backup volume. This is similar to | |
418 | the standard behaviour of preferring read-only volumes over read-write | |
419 | volumes when the parent volume is a read-only volume. | |
420 | ||
421 | =item B<-biods> <I<number of I/O daemons>> | |
422 | ||
423 | Sets the number of VM daemons dedicated to performing I/O operations on a | |
424 | machine running a version of AIX with virtual memory (VM) integration. If | |
425 | both this argument and the B<-daemons> argument are omitted, the default | |
426 | is five. If this argument is omitted but the B<-daemons> argument is | |
427 | provided, the number of VM daemons is set to twice the value of the | |
428 | B<-daemons> argument. | |
429 | ||
430 | =item B<-blocks> <I<blocks in cache>> | |
431 | ||
432 | Specifies the number of kilobyte blocks to be made available for caching | |
433 | in the machine's cache directory (for a disk cache) or memory (for a | |
434 | memory cache), overriding the default defined in the third field of the | |
435 | F</usr/vice/etc/cacheinfo> file. For a disk cache, the value cannot exceed | |
436 | 95% of the space available in the cache partition. If using a memory | |
437 | cache, do not combine this argument with the B<-dcache> argument, since | |
438 | doing so can possibly result in a chunk size that is not an exponent of 2. | |
439 | ||
440 | =item B<-cachedir> <I<cache directory>> | |
441 | ||
442 | Names the local disk directory to be used as the cache. This value | |
443 | overrides the default defined in the second field of the | |
444 | F</usr/vice/etc/cacheinfo> file. | |
445 | ||
446 | =item B<-chunksize> <I<chunk size>> | |
447 | ||
448 | Sets the size of each cache chunk. The integer provided, which must be | |
449 | from the range C<0> to C<30>, is used as an exponent on the number 2. If not | |
450 | supplied, a default chunksize will be determined based on the cache type and | |
451 | cache size, and will range from C<13> (8KB) for memory cache and C<18> to | |
452 | C<20> (256 KB to 1MB) for disk cache. A value of C<0> or less, or greater than | |
453 | C<30>, sets chunk size to the appropriate default. Values less than C<10> | |
454 | (which sets chunk size to a 1 KB) are not recommended. Combining this | |
455 | argument with the B<-dcache> argument is not recommended because it | |
456 | requires that the issuer calculate the cache size that results. | |
457 | ||
458 | B<-chunksize> is an important option when tuning for performance. Setting | |
459 | this option to larger values can increase performance when dealing with | |
460 | large files. | |
461 | ||
462 | =item B<-confdir> <I<configuration directory>> | |
463 | ||
464 | Names a directory other than the F</usr/vice/etc> directory from which to | |
465 | fetch the F<cacheinfo>, F<ThisCell>, and F<CellServDB> configuration | |
466 | files. | |
467 | ||
468 | =item B<-daemons> <I<number of daemons to use>> | |
469 | ||
470 | Specifies the number of background daemons to run on the machine. These | |
471 | daemons improve efficiency by doing prefetching and background writing of | |
472 | saved data. This value overrides the default of C<2>, which is adequate | |
473 | for a machine serving up to five users. Values greater than C<6> are not | |
474 | generally more effective than C<6>. | |
475 | ||
476 | Note: On AIX machines with integrated virtual memory (VM), the number of | |
477 | VM daemons is set to twice the value of this argument, if it is provided | |
478 | and the B<-biods> argument is not. If both arguments are omitted, there | |
479 | are five VM daemons. | |
480 | ||
481 | =item B<-dcache> <I<number of dcache entries>> | |
482 | ||
483 | Sets the number of dcache entries in memory, which are used to store | |
484 | information about cache chunks. For a disk cache, this overrides the | |
485 | default, which is 50% of the number of F<VI<n>> files (cache chunks). For | |
486 | a memory cache, this argument effectively sets the number of cache chunks, | |
487 | but its use is not recommended, because it requires the issuer to | |
488 | calculate the resulting total cache size (derived by multiplying this | |
489 | value by the chunk size). Do not combine this argument with the B<-blocks> | |
490 | argument, since doing so can possibly result in a chunk size that is not | |
491 | an exponent of 2. | |
492 | ||
493 | =item B<-debug> | |
494 | ||
495 | Generates a highly detailed trace of the B<afsd> program's actions on the | |
496 | standard output stream. The information is useful mostly for debugging | |
497 | purposes. | |
498 | ||
499 | =item B<-dynroot> | |
500 | ||
501 | The standard behaviour of the AFS client without the B<-dynroot> option is | |
502 | to mount the root.afs volume from the default cell on the F</afs> path. The | |
503 | F</afs> folder and root.afs volume traditionally shows the folders for | |
504 | F<ThisCell> and other cells as configured by the AFS cell administrator. | |
505 | ||
506 | The B<-dynroot> option changes this. Using this option, the AFS client | |
507 | does not mount the root.afs volume on F</afs>. Instead it uses the | |
508 | contents of the F<CellServDB> file to populate the listing of cells in | |
509 | F</afs>. This is known as a DYNamic ROOT. A cell is not contacted until | |
510 | the path F</afs/I<cellname>> if accessed. This functions similarly to an | |
511 | automounter. The main advantage of using B<-dynroot> is that the AFS | |
512 | client will start properly even without network access, whereas the client | |
513 | not using B<-dynroot> will freeze upon startup if cannot contact the | |
514 | default cell specified in F<ThisCell> and mount the root.afs | |
515 | volume. Dynamic root mode is also sometimes called travelling mode because | |
516 | it works well for laptops which don't always have network connectivity. | |
517 | ||
518 | Two advantages of not using dynroot are that listing F</afs> will usually | |
519 | be faster because the contents of F</afs> are limited to what the AFS | |
520 | administrator decides and that symbolic links are traditionally created | |
521 | by the AFS administrator to provide a short name for the cell (i.e. | |
522 | cellname.domain.com is aliased to cellname). However, with dynroot, the | |
523 | local system administrator can limit the default contents of F</afs> by | |
524 | installing a stripped-down F<CellServDB> file, and if dynroot is in effect, | |
525 | the F<CellAlias> file can be used to provide shortname for common AFS cells | |
526 | which provides equivalent functionality to the most commonly used symbolic | |
527 | links. | |
528 | ||
529 | When the dynamic root (B<-dynroot>, B<-dynroot-sparse>) and the fake stat | |
530 | (B<-fakestat>, B<-fakestat-all>) modes are in effect, the cache manager | |
531 | provides a special directory named F</afs/.:mount> which allows access to | |
532 | volumes by volume name or ID. The F</afs/.:mount> directory appears to be | |
533 | empty, but any name in the form of I<cell>:I<volume> will be resolved as a | |
534 | read-write mount point to the specified volume. For example, the | |
535 | I<user.jdoe> volume in the I<example.com> cell would be accessible at the | |
536 | following path: F</afs/.:mount/example.com:user.jdoe>. This dynamic mount | |
537 | feature is recommended only for temporary access to a volume. Linux-based | |
538 | cache managers provide this dynamic mount feature even when dynamic root | |
539 | (B<-dynroot>, B<-dynroot-sparse>) is not in effect. | |
540 | ||
541 | =item B<-dynroot-sparse> | |
542 | ||
543 | In addition to operating in the manner described for dynroot above, | |
544 | cells other than the local cell are not shown by default until a lookup | |
545 | occurs. Cell aliases as set in the CellAliases file are shown as normal, | |
546 | although they may appear to be dangling links until traversed. | |
547 | ||
548 | =item B<-enable_peer_stats> | |
549 | ||
550 | Activates the collection of Rx statistics and allocates memory for their | |
551 | storage. For each connection with a specific UDP port on another machine, | |
552 | a separate record is kept for each type of RPC (FetchFile, GetStatus, and | |
553 | so on) sent or received. To display or otherwise access the records, use | |
554 | the Rx Monitoring API. | |
555 | ||
556 | =item B<-enable_process_stats> | |
557 | ||
558 | Activates the collection of Rx statistics and allocates memory for their | |
559 | storage. A separate record is kept for each type of RPC (FetchFile, | |
560 | GetStatus, and so on) sent or received, aggregated over all connections to | |
561 | other machines. To display or otherwise access the records, use the Rx | |
562 | Monitoring API. | |
563 | ||
564 | =item B<-fakestat> | |
565 | ||
566 | Return fake values for stat calls on cross-cell mounts. This option makes | |
567 | an C<ls -l> of F</afs> much faster since each cell isn't contacted, and | |
568 | this and the B<-fakestat-all> options are useful on Mac OS X so that the | |
569 | Finder program doesn't try to contact every AFS cell the system knows | |
570 | about. | |
571 | ||
572 | Note that, for the purposes of B<-fakestat>, local cellular mounts count | |
573 | as "cross-cell" mounts. That is, if the local cell is C<localcell>, a | |
574 | mount for C<localcell:root.cell> will count as a "cross-cell" mount and | |
575 | so stat calls for it will be faked with B<-fakestat>. In practice, local | |
576 | cellular mounts are rare and generally discouraged, so this should not | |
577 | generally make a difference. | |
578 | ||
579 | =item B<-fakestat-all> | |
580 | ||
581 | Return fake values for stat calls on all mounts, not just cross-cell | |
582 | mounts. This and the B<-fakestat> options are useful on Mac OS X so that | |
583 | the Finder program doesn't hang when browsing AFS directories. | |
584 | ||
585 | =item B<-files> <I<files in cache>> | |
586 | ||
587 | Specifies the number of F<VI<n>> files to create in the cache directory | |
588 | for a disk cache, overriding the default that is calculated as described | |
589 | in L</DESCRIPTION>. Each F<VI<n>> file accommodates a chunk of data, and | |
590 | can grow to a maximum size of 64 KB by default. Do not combine this | |
591 | argument with the B<-memcache> argument. | |
592 | ||
593 | =item B<-files_per_subdir> <I<files per cache subdirectory>> | |
594 | ||
595 | Limits the number of cache files in each subdirectory of the cache | |
596 | directory. The value of the option should be the base-two log of the | |
597 | number of cache files per cache subdirectory (so 10 for 1024 files, 14 for | |
598 | 16384 files, and so forth). | |
599 | ||
600 | =item B<-help> | |
601 | ||
602 | Prints the online help for this command. All other valid options are | |
603 | ignored. | |
604 | ||
605 | =item B<-logfile> <I<log file location>> | |
606 | ||
607 | This option is obsolete and no longer has any effect. | |
608 | ||
609 | =item B<-inumcalc> <I<method>> | |
610 | ||
611 | Specifies the method used by the Cache Manager to generate inode numbers for | |
612 | files, directories, and symlinks in the AFS filesystem. Valid methods are | |
613 | C<compat> and C<md5>. The default method is C<compat>. | |
614 | ||
615 | When the C<compat> method is in effect, the Cache Manager generates inode | |
616 | numbers for a given inode by multiplying the AFS volume number by 65536, adding | |
617 | the result to the AFS vnode number, and finally truncating the result to a | |
618 | signed 32 bit integer. | |
619 | ||
620 | When the C<md5> method is in effect, the Cache Manager generates inode numbers | |
621 | for a given inode by calculating the MD5 digest of a combination of the cell | |
622 | number, volume number, and vnode number. The result is truncated to a signed 32 | |
623 | bit integer. The C<md5> method is computationally more expensive but greatly | |
624 | reduces the chance for inode number collisions, especially when volumes from | |
625 | multiple cells are mounted within the AFS filesystem. | |
626 | ||
627 | =item B<-mem_alloc_sleep> | |
628 | ||
629 | This option is obsolete and no longer has any effect. | |
630 | ||
631 | =item B<-memcache> | |
632 | ||
633 | Initializes a memory cache rather than a disk cache. Do not combine this | |
634 | flag with the B<-files> argument. | |
635 | ||
636 | =item B<-mountdir> <I<mount location>> | |
637 | ||
638 | Names the local disk directory on which to mount the root of the AFS | |
639 | filespace. This value overrides the default defined in the first field of | |
640 | the F</usr/vice/etc/cacheinfo> file. If a value other than the F</afs> | |
641 | directory is used, the machine cannot access the filespace of cells that | |
642 | do use that value. | |
643 | ||
644 | =item B<-nomount> | |
645 | ||
646 | Do not mount AFS on startup. The afs global mount must be mounted via | |
647 | some other means. This is useful on Mac OS X where /afs is sometimes | |
648 | mounted in /Network/afs like other network file systems. | |
649 | ||
650 | =item B<-nosettime> | |
651 | ||
652 | This option is obsolete and no longer has any effect. The operating system | |
653 | provided time keeping daemons should be used to maintain the system time. | |
654 | ||
655 | =item B<-prealloc> <I<number of preallocated blocks>> | |
656 | ||
657 | Specifies the number of pieces of memory to preallocate for the Cache | |
658 | Manager's internal use. The default initial value is C<400>, but the Cache | |
659 | Manager dynamically allocates more memory as it needs it. | |
660 | ||
661 | =item B<-rmtsys> | |
662 | ||
663 | Initializes an additional daemon to execute AFS-specific system calls on | |
664 | behalf of NFS client machines. Use this flag only if the machine is an | |
665 | NFS/AFS translator machine serving users of NFS client machines who | |
666 | execute AFS commands. | |
667 | ||
668 | =item B<-rootvol> <I<name of AFS root volume>> | |
669 | ||
670 | Names the read/write volume corresponding to the root directory for the | |
671 | AFS file tree (which is usually the F</afs> directory). This value | |
672 | overrides the default of the C<root.afs> volume. This option is ignored if | |
673 | B<-dynroot> is given. | |
674 | ||
675 | =item B<-rxbind> | |
676 | ||
677 | Bind the Rx socket (one interface only). | |
678 | ||
679 | =item B<-rxmaxfrags> <I<max # of fragments>> | |
680 | ||
681 | Set a limit for the maximum number of UDP fragments Rx will send per Rx | |
682 | packet, and the maximum number of fragments Rx thinks it can receive when | |
683 | advertising its receive size to peers. Practically speaking, setting this | |
684 | option means that you will not see Rx data packets that are broken into more | |
685 | than N fragments, where N is the value specified for this option. Setting this | |
686 | option to 1 effectively prevents fragmentation, and can be useful when dealing | |
687 | with networking equipment that does not properly handle UDP fragments. | |
688 | ||
689 | Note that this option just specifies a maximum. The actual number of fragments | |
690 | seen on the wire may be less than what is specified, depending on the | |
691 | configuration of the peer. | |
692 | ||
693 | =item B<-rxmaxmtu> <I<value for maximum MTU>> | |
694 | ||
695 | Set a limit for the largest maximum transfer unit (network packet size) that | |
696 | the AFS client on this machine will be willing to transmit. This switch can | |
697 | be used where an artificial limit on the network precludes packets as large | |
698 | as the discoverable MTU from being transmitted successfully. | |
699 | ||
700 | =item B<-rxpck> <I<value for rx_extraPackets>> | |
701 | ||
702 | Set rx_extraPackets to this value. This sets the number of extra Rx | |
703 | packet structures that are available to handle Rx connections. This | |
704 | value should be increased if the "rxdebug 127.0.0.1 -port 7001 | |
705 | -rxstats" command shows no free Rx packets. Increasing this value may | |
706 | improve OpenAFS client performance in some circumstances. | |
707 | ||
708 | =item B<-settime> | |
709 | ||
710 | This option is obsolete and no longer has any effect. The operating system | |
711 | provided time keeping daemons should be used to maintain the system time. | |
712 | ||
713 | =item B<-shutdown> | |
714 | ||
715 | Shuts down the Cache Manager. Before calling B<afsd> with this option, | |
716 | unmount the AFS file system with B<umount>. | |
717 | ||
718 | =item B<-splitcache> <I<RW/RO Ratio>> | |
719 | ||
720 | This allows the user to set a certain percentage of the AFS cache be | |
721 | reserved for read/write content and the rest to be reserved for read-only | |
722 | content. The ratio should be written as a fraction. For example, | |
723 | C<-splitcache 75/25> devotes 75% of your cache space to read/write content | |
724 | and 25% to read-only. | |
725 | ||
726 | =item B<-stat> <I<number of stat entries>> | |
727 | ||
728 | Specifies the number of entries to allocate in the machine's memory for | |
729 | recording status information about the AFS files in the cache. If this value | |
730 | is not specified, the number of stat entires will be autotuned based on the | |
731 | size of the disk cache. | |
732 | ||
733 | =item B<-verbose> | |
734 | ||
735 | Generates a detailed trace of the B<afsd> program's actions on the | |
736 | standard output stream. | |
737 | ||
738 | =item B<-volumes> <I<number of volume entries>> | |
739 | ||
740 | Specifies the number of memory structures to allocate for storing volume | |
741 | location information. The default value is C<200>. | |
742 | ||
743 | =item B<-disable-dynamic-vcaches> | |
744 | ||
745 | By default, dynamic vcache overrides the B<-stat> option by using the value of | |
746 | B<-stat> (or the default) as the initial size of the stat (or vcache) pool and | |
747 | increases the pool dynamically as needed on supported platforms. This flag will | |
748 | disable this new functionality and honor the '-stat' setting. | |
749 | ||
750 | =item B<-waitclose> | |
751 | ||
752 | Has no effect on the operation of the Cache Manager. The behavior it | |
753 | affected in previous versions of the Cache Manager, to perform synchronous | |
754 | writes to the File Server, is now the default behavior. To perform | |
755 | asynchronous writes in certain cases, use the B<fs storebehind> command. | |
756 | ||
757 | =item B<-volume-ttl> | |
758 | ||
759 | Specifies the maximum amount of time the Cache Manager will cache volume | |
760 | information retrieved from VL Servers. | |
761 | ||
762 | By default, the Cache Manager will cache read-only volume information as long | |
763 | as a volume callback is held for that volume. The callback may be held as long | |
764 | as files in the read-only volume are being accessed, with no upper limit. For | |
765 | read/write volumes, by default the Cache Manager will cache volume information | |
766 | forever, until a fileserver returns a volume-level error in response to | |
767 | accessing files in that volume. | |
768 | ||
769 | Use the B<-volume-ttl> option to specify the maximum amount of time in seconds | |
770 | that volume information will be cached, regardless of connectivity to the | |
771 | fileservers. Lowering this value can make the Cache Manager recover more | |
772 | quickly from certain volume/fileserver errors, but will increase the load on | |
773 | the VL Servers for contacted cells. | |
774 | ||
775 | A typical value is 7200 seconds (2 hours), which is the same as the default | |
776 | callback duration for read-only volumes. The minimum valid value is 600 seconds | |
777 | (10 minutes). | |
778 | ||
779 | =back | |
780 | ||
781 | =head1 EXAMPLES | |
782 | ||
783 | The B<afsd> command is normally included in the machine's AFS | |
784 | initialization file, rather than typed at the command shell prompt. For | |
785 | most disk caches, the appropriate form is | |
786 | ||
787 | % /usr/vice/etc/afsd | |
788 | ||
789 | The following command is appropriate when enabling a machine to act as an | |
790 | NFS/AFS Translator machine serving more than five users. | |
791 | ||
792 | % /usr/vice/etc/afsd -daemons 4 -rmtsys | |
793 | ||
794 | The following command initializes a memory cache and sets chunk size to 16 | |
795 | KB (2^14). | |
796 | ||
797 | % /usr/vice/etc/afsd -memcache -chunksize 14 | |
798 | ||
799 | =head1 PRIVILEGE REQUIRED | |
800 | ||
801 | The issuer must be logged in as the local superuser root. | |
802 | ||
803 | =head1 SEE ALSO | |
804 | ||
805 | L<fs_newcell(1)>, | |
806 | L<afs_cache(5)>, | |
807 | L<CellServDB(5)>, | |
808 | L<cacheinfo(5)> | |
809 | ||
810 | RFC 5864 L<http://www.ietf.org/rfc/rfc5864.txt> | |
811 | RFC 1183 L<http://www.ietf.org/rfc/rfc1183.txt> | |
812 | ||
813 | =head1 COPYRIGHT | |
814 | ||
815 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
816 | ||
817 | This documentation is covered by the IBM Public License Version 1.0. It | |
818 | was converted from HTML to POD by software written by Chas Williams and | |
819 | Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |