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