6114a7e5ca2557bed0b42f22593806ede9484000
[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      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 a read-only volume. The callback may be held
764 as long as files in the read-only volume are being accessed.  The Cache Manager
765 will cache read/write volume information as long as volume level errors are not
766 returned from fileservers while accessing files within the volume.
767
768 Use the B<-volume-ttl> to specify the maximum amount of time in seconds
769 volume information will be cached, regardless of connectivity to the
770 fileserers. The minimum valid value is 600 seconds (10 minutes).
771
772 =back
773
774 =head1 EXAMPLES
775
776 The B<afsd> command is normally included in the machine's AFS
777 initialization file, rather than typed at the command shell prompt. For
778 most disk caches, the appropriate form is
779
780    % /usr/vice/etc/afsd
781
782 The following command is appropriate when enabling a machine to act as an
783 NFS/AFS Translator machine serving more than five users.
784
785    % /usr/vice/etc/afsd -daemons 4 -rmtsys
786
787 The following command initializes a memory cache and sets chunk size to 16
788 KB (2^14).
789
790    % /usr/vice/etc/afsd -memcache -chunksize 14
791
792 =head1 PRIVILEGE REQUIRED
793
794 The issuer must be logged in as the local superuser root.
795
796 =head1 SEE ALSO
797
798 L<fs_newcell(1)>,
799 L<afs_cache(5)>,
800 L<CellServDB(5)>,
801 L<cacheinfo(5)>
802
803 RFC 5864 L<http://www.ietf.org/rfc/rfc5864.txt>
804 RFC 1183 L<http://www.ietf.org/rfc/rfc1183.txt>
805
806 =head1 COPYRIGHT
807
808 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
809
810 This documentation is covered by the IBM Public License Version 1.0.  It
811 was converted from HTML to POD by software written by Chas Williams and
812 Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.