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