c852b6c8d8095e3d33f8f21f8e5b3c04e0b4079a
[openafs.git] / doc / man-pages / pod8 / afsd.pod
1 =head1 NAME
2
3 afsd - Initializes the Cache Manager and starts related daemons.
4
5 =head1 SYNOPSIS
6
7 B<afsd> [-blocks <I<1024 byte blocks in cache>>]  
8 [B<-files> <I<files in cache>>]
9      [-rootvol <I<name of AFS root volume>>]
10      [-stat <I<number of stat entries>>]
11      [B<-memcache>]  [-cachedir <I<cache directory>>]  
12      [-mountdir <I<mount location>>]
13      [-daemons <I<number of daemons to use>>]  
14      [B<-nosettime>]  [B<-verbose>]  [B<-rmtsys>]  [-debug]  
15      [-chunksize <I<log(2) of chunk size>>]
16      [-dcache <I<number of dcache entries>>]
17      [-volumes <I<number of volume entries>>]  
18      [-biods <I<number of bkg I/O daemons (aix vm)>>]
19      [-prealloc <I<number of 'small' preallocated blocks>>]
20      [-confdir <I<configuration directory>>]
21      [-logfile <I<Place to keep the CM log>>]  
22      [B<-waitclose>]  [B<-shutdown>]  [-enable_peer_stats]  
23      [B<-enable_process_stats>]  [-help]
24
25 This command does not use the syntax conventions of the AFS command
26 suites. Provide the command name and all option names in full.
27
28 =head1 DESCRIPTION
29
30 The afsd command initializes the Cache Manager on an AFS client
31 machine by transferring AFS-related configuration information into kernel
32 memory and starting several daemons. More specifically, the
33 B<afsd> command performs the following actions:
34
35 =over 4
36
37 =item *
38
39 Sets a field in kernel memory that defines the machine's cell
40 membership. Some Cache Manager-internal operations and system calls
41 consult this field to learn which cell to execute in. (The AFS command
42 interpreters refer to the B</usr/vice/etc/ThisCell> file
43 instead.) This information is transferred into the kernel from the
44 B</usr/vice/etc/ThisCell> file and cannot be changed until the
45 B<afsd> program runs again.
46
47
48 =item *
49
50 Places in kernel memory the names and Internet addresses of the database
51 server machines in the local cell and (optionally) foreign cells. The
52 appearance of a cell's database server machines in this list enables the
53 Cache Manager to contact them and to access files in the cell. Omission
54 of a cell from this list, or incorrect information about its database server
55 machines, prevents the Cache Manager from accessing files in it.
56
57
58 The list of database server machines is transferred into the kernel from
59 the B</usr/vice/etc/CellServDB> file. After initialization, use
60 the B<fs newcell> command to change the kernel-resident list without
61 having to reboot.
62
63 =item *
64
65 Mounts the root of the AFS filespace on a directory on the machine's
66 local disk, according to either the first field in the
67 B</usr/vice/etc/cacheinfo> file (the default) or the B<afsd>
68 command's B<-mountdir> argument. The conventional value is
69 B</afs>.
70
71
72 =item *
73
74 Determines which volume to mount at the root of the AFS file tree.
75 The default is the volume B<root.afs>; use the
76 B<-rootvol> argument to override it. Although the base
77 (read/write) form of the volume name is the appropriate value, the Cache
78 Manager has a bias for accessing the read-only version of the volume (by
79 convention, B<root.afs.readonly>) if it is
80 available.
81
82
83 =item *
84
85 Configures the cache on disk (the default) or in machine memory if the
86 B<-memcache> argument is provided. In the latter case, the
87 B<afsd> program allocates space in machine memory for caching, and the
88 Cache Manager uses no disk space for caching even if the machine has a
89 disk.
90
91
92 =item *
93
94 Defines the name of the local disk directory devoted to caching, when the
95 B<-memcache> argument is not used. If necessary, the
96 B<afsd> program creates the directory (its parent directory must
97 already exist). It does not remove the directory that formerly served
98 this function, if one exists.
99
100
101 The second field in the /usr/vice/etc/cacheinfo file is the
102 source for this name, and the standard value is the B</usr/vice/cache>
103 directory. Use the B<-cachedir> argument to override the value
104 in the B<cacheinfo> file.
105
106 =item *
107
108 Sets the size of the cache. The default source for the value is the
109 third field in the B</usr/vice/etc/cacheinfo> file, which specifies a
110 number of kilobytes.
111
112
113 For a memory cache, the following arguments to the afsd command
114 override the value in the B<cacheinfo> file:
115
116 =over 4
117
118 =item *
119
120 The -blocks argument, to specify a different number of kilobyte
121 blocks.
122
123
124 =item *
125
126 The B<-dcache> and -chunksize arguments together, to
127 set both the number of dcache entries and the chunk size (see below for
128 definition of these parameters). In this case, the B<afsd>
129 program derives cache size by multiplying the two values. Using this
130 combination is not recommended, as it requires the issuer to perform the
131 calculation beforehand to determine the resulting cache size.
132
133
134 =item *
135
136 The -dcache argument by itself. In this case, the
137 B<afsd> program derives cache size by multiplying the value specified
138 by the B<-dcache> argument by the default memory cache chunk size of
139 eight kilobytes. Using this argument is not recommended, as it requires
140 the issuer to perform the calculation beforehand to determine the resulting
141 cache size.
142
143
144 =back
145
146 For satisfactory memory cache performance, the specified value must leave
147 enough memory free to accommodate all other processes and commands that can
148 run on the machine. If the value exceeds the amount of memory
149 available, the B<afsd> program exits without initializing the Cache
150 Manager and produces the following message on the standard output
151 stream:
152
153    afsd: memCache allocation failure at I<number> KB
154
155 where I<number> is how many kilobytes were allocated just before the
156 failure.
157
158 For a disk cache, use the -blocks argument to the
159 B<afsd> command to override the value in the B<cacheinfo>
160 file. The value specified in either way sets an absolute upper limit on
161 cache size; values provided for other arguments (such as
162 B<-dcache> and B<-chunksize>) never result in a larger
163 cache. The B<afsd> program rejects any setting larger than 95%
164 of the 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 client
167 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
171 the B<afsd> command runs again or the B<fs setcachesize>
172 command is reissued. The B<fs setcachesize> command does not
173 work for memory caches.
174
175 =item *
176
177 Sets the size of each cache I<chunk>, and by implication the amount
178 of 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
182 For a disk cache, a chunk is a VI<n> file and this
183 parameter sets the maximum size to which each one can expand; the default
184 is 64 KB. For a memory cache, each chunk is a collection of contiguous
185 memory blocks; the default is size 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
189 of two; see the B<Options> section for details. For a
190 memory cache, if total cache size divided by chunk size leaves a remainder,
191 the B<afsd> program rounds down the number of dcache entries,
192 resulting in a slightly smaller cache.
193
194 =item *
195
196 Sets the number of chunks in the cache. For a memory cache, the
197 number of chunks is equal to the cache size divided by the chunk size.
198 For a disk cache, the number of chunks (B<V>I<n> files) is set
199 to the largest of the following unless the B<-files> argument is used
200 to set the value explicitly:
201
202
203 =over 4
204
205 =item *
206
207 100
208
209
210 =item *
211
212 1.5 times the result of dividing cache size by chunk size
213 (I<cachesize>/I<chunksize> * 1.5)
214
215
216 =item *
217
218 The result of dividing cachesize by 10 KB (I<cachesize>/10240)
219
220
221 =back
222
223 =item *
224
225 Sets the number of I<dcache entries> allocated in machine memory for
226 storing information about the chunks in the cache.
227
228
229 For a disk cache, the /usr/vice/cache/CacheItems file contains
230 one entry for each B<V>I<n> file. By default, one half
231 the number of these entries (but not more that 2,000) are duplicated as dcache
232 entries in machine memory for quicker access.
233
234 For a memory cache, there is no CacheItems file so all
235 information about cache chunks must be in memory as dcache entries.
236 Thus, there is no default number of dcache entries for a memory cache;
237 instead, the B<afsd> program derives it by dividing the cache size by
238 the chunk size.
239
240 To set the number of dcache entries, use the -dcache
241 argument; the specified value can exceed the default limit of
242 2,000. Using this argument is not recommended for either type of
243 cache. Increasing the number of dcache entries for a disk cache
244 sometimes improves performance (because more entries are retrieved from memory
245 rather than from disk), but only marginally. Using this argument for a
246 memory cache requires the issuer to calculate the cache size by multiplying
247 this value by the chunk size.
248
249 =item *
250
251 Sets the number of I<stat> entries available in machine memory for
252 caching status information about cached AFS files. The default is
253 300; use the B<-stat> argument to override the default.
254
255
256 =item *
257
258 Randomly selects a file server machine in the local cell as the source for
259 the correct time. Every five minutes thereafter, the local clock is
260 adjusted (if necessary) to match the file server machine's clock.
261
262
263 Use the B<-nosettime> flag to prevent the afsd command
264 from selecting a time standard. This is recommended only on file server
265 machines that are also acting as clients. File server machines maintain
266 the correct time using the Network Time Protocol Daemon instead.
267
268 =back
269
270 In addition to setting cache configuration parameters, the afsd
271 program starts the following daemons. (On most system types, these
272 daemons appear as nameless entries in the output of the UNIX B<ps>
273 command.)
274
275 =over 4
276
277 =item *
278
279 One I<callback> daemon, which handles callbacks. It also
280 responds to the File Server's periodic probes, which check that the
281 client machine is still alive.
282
283
284 =item *
285
286 One I<maintenance> daemon, which performs the following
287 tasks:
288
289
290 =over 4
291
292 =item *
293
294 Garbage collects obsolete data (for example, expired tokens) from kernel
295 memory
296
297
298 =item *
299
300 Synchronizes files
301
302
303 =item *
304
305 Refreshes information from read-only volumes once per hour
306
307
308 =item *
309
310 Does delayed writes for NFS clients if the machine is running the NFS/AFS
311 Translator
312
313
314 =back
315
316 =item *
317
318 One I<cache-truncation> daemon, which flushes the cache when free
319 space is required, by writing cached data and status information to the File
320 Server.
321
322
323 =item *
324
325 One I<server connection> daemon, which sends a probe to the File
326 Server every few minutes to check that it is still accessible. It also
327 synchronizes the machine's clock with the clock on a randomly-chosen file
328 server machine, unless the B<-nosettime> flag is used. There is
329 always one server connection daemon.
330
331
332 =item *
333
334 One or more I<background> daemons that improve performance by
335 pre-fetching files and performing background (delayed) writes of saved data
336 into AFS. 
337
338
339 The default number of background daemons is two, enough to service at least
340 five simultaneous users of the machine. To increase the number, use the
341 B<-daemons> argument. A value greater than six is not generally
342 necessary.
343
344 =item *
345
346 On some system types, one I<Rx listener> daemon, which listens for
347 incoming RPCs.
348
349
350 =item *
351
352 On some system types, one I<Rx event> daemon, which reviews the Rx
353 system's queue of tasks and performs them as appropriate. Most
354 items in the queue are retransmissions of failed packets.
355
356
357 =item *
358
359 On machines that run AIX with virtual memory (VM) integration, one or more
360 I<VM> daemons (sometimes called I<I/O> daemons, which transfer
361 data between disk and machine memory. The number of them depends on the
362 setting of the B<-biods> and B<-daemons> arguments:
363
364
365 =over 4
366
367 =item *
368
369 If the -biods argument is used, it sets the number of VM
370 daemons.
371
372
373 =item *
374
375 If only the -daemons argument is used, the number of VM daemons
376 is twice the number of background daemons.
377
378
379 =item *
380
381 If neither argument is used, there are five VM daemons.
382
383
384 =back
385
386 =back
387
388 =head1 CAUTIONS
389
390 Do not use the -shutdown parameter. It does not shutdown
391 the Cache Manager effectively. Instead, halt Cache Manager activity by
392 using the standard UNIX B<umount> command to unmount the AFS root
393 directory (by convention, B</afs>). The machine must then be
394 rebooted to reinitialize the Cache Manager.
395
396 =head1 OPTIONS
397
398 =over 4
399
400 =item -blocks
401
402 Specifies the number of kilobyte blocks to be made available for caching
403 in the machine's cache directory (for a disk cache) or memory (for a
404 memory cache), overriding the default defined in the third field of the
405 B</usr/vice/etc/cacheinfo> file. For a disk cache, the value
406 cannot exceed 95% of the space available in the cache partition. If
407 using a memory cache, do not combine this argument with the B<-dcache>
408 argument, since doing so can possibly result in a chunk size that is not an
409 exponent of 2.
410
411 =item -files
412
413 Specifies the number of VI<n> files to create in the
414 cache directory for a disk cache, overriding the default that is calculated as
415 described in the B<Description> section. Each
416 B<V>I<n> file accommodates a chunk of data, and can grow to a
417 maximum size of 64 KB by default. Do not combine this argument with the
418 B<-memcache> argument.
419
420 =item -rootvol
421
422 Names the read/write volume corresponding to the root directory for the
423 AFS file tree (which is usually the B</afs> directory). This
424 value overrides the default of the B<root.afs> volume.
425
426 =item -stat
427
428 Specifies the number of entries to allocate in the machine's memory
429 for recording status information about the AFS files in the cache. This
430 value overrides the default of 300.
431
432 =item -memcache
433
434 Initializes a memory cache rather than a disk cache. Do not combine
435 this flag with the B<-files> argument.
436
437 =item -cachedir
438
439 Names the local disk directory to be used as the cache. This value
440 overrides the default defined in the second field of the
441 B</usr/vice/etc/cacheinfo> file.
442
443 =item -mountdir
444
445 Names the local disk directory on which to mount the root of the AFS
446 filespace. This value overrides the default defined in the first field
447 of the B</usr/vice/etc/cacheinfo> file. If a value other than
448 the B</afs> directory is used, the machine cannot access the filespace
449 of cells that do use that value.
450
451 =item -daemons
452
453 Specifies the number of background daemons to run on the machine.
454 These daemons improve efficiency by doing prefetching and background writing
455 of saved data. This value overrides the default of 2, which is adequate
456 for a machine serving up to five users. Values greater than
457 B<6> are not generally more effective than B<6>. 
458
459 Note: On AIX machines with integrated virtual memory (VM),
460 the number of VM daemons is set to twice the value of this argument, if it is
461 provided and the B<-biods> argument is not. If both arguments
462 are omitted, there are five VM daemons.
463
464 =item -nosettime
465
466 Prevents the Cache Manager from synchronizing its clock with the clock on
467 a server machine selected at random, by checking the time on the server
468 machine every five minutes. Use this flag only on a machine that is
469 already using another time synchronization protocol (for example, a server
470 machine that is running the B<runntp> process).
471
472 =item -verbose
473
474 Generates a detailed trace of the afsd program's actions
475 on the standard output stream.
476
477 =item -rmtsys
478
479 Initializes an additional daemon to execute AFS-specific system calls on
480 behalf of NFS client machines. Use this flag only if the machine is an
481 NFS/AFS translator machine serving users of NFS client machines who execute
482 AFS commands.
483 L<(1)>
484
485 =item -debug
486
487 Generates a highly detailed trace of the afsd program's
488 actions on the standard output stream. The information is useful mostly
489 for debugging purposes.
490
491 =item -chunksize
492
493 Sets the size of each cache chunk. The integer provided, which must
494 be from the range B<0> to B<30>, is used as an exponent on the
495 number 2. It overrides the default of 16 for a disk cache
496 (216 is 64 KB) and 13 for a memory cache (213 is 8
497 KB). A value of B<0> or less, or greater than B<30>,
498 sets chunk size to the appropriate default. Values less than
499 B<10> (which sets chunk size to a 1 KB) are not recommended.
500 Combining this argument with the B<-dcache> argument is not
501 recommended because it requires that the issuer calculate the cache size that
502 results.
503
504 =item -dcache
505
506 Sets the number of dcache entries in memory, which are used to store
507 information about cache chunks. For a disk cache, this overrides the
508 default, which is 50% of the number of B<V>I<n> files (cache
509 chunks). For a memory cache, this argument effectively sets the number
510 of cache chunks, but its use is not recommended, because it requires the
511 issuer to calculate the resulting total cache size (derived by multiplying
512 this value by the chunk size). Do not combine this argument with the
513 B<-blocks> argument, since doing so can possibly result in a chunk
514 size that is not an exponent of 2.
515
516 =item -volumes
517
518 Specifies the number of memory structures to allocate for storing volume
519 location information. The default value is 50.
520
521 =item -biods
522
523 Sets the number of VM daemons dedicated to performing I/O operations on a
524 machine running a version of AIX with virtual memory (VM) integration.
525 If both this argument and the B<-daemons> argument are omitted, the
526 default is five. If this argument is omitted but the
527 B<-daemons> argument is provided, the number of VM daemons is set to
528 twice the value of the B<-daemons> argument. 
529
530 =item -prealloc
531
532 Specifies the number of pieces of memory to preallocate for the Cache
533 Manager's internal use. The default initial value is 400, but the
534 Cache Manager dynamically allocates more memory as it needs it.
535
536 =item -confdir
537
538 Names a directory other than the /usr/vice/etc directory from
539 which to fetch the B<cacheinfo>, B<ThisCell>, and
540 B<CellServDB> configuration files.
541
542 =item -logfile
543
544 Is obsolete and has no real effect. It specifies an alternate file
545 in which to record a type of trace that the Cache Manager no longer
546 generates; the default value is B</usr/vice/etc/AFSLog>.
547
548 =item -waitclose
549
550 Has no effect on the operation of the Cache Manager. The behavior
551 it affected in previous versions of the Cache Manager, to perform synchronous
552 writes to the File Server, is now the default behavior. To perform
553 asynchronous writes in certain cases, use the B<fs storebehind>
554 command.
555
556 =item -shutdown
557
558 Shuts down the Cache Manager, but not in the most effective possible
559 way. Do not use this flag.
560
561 =item -enable_peer_stats
562
563 Activates the collection of Rx statistics and allocates memory for their
564 storage. For each connection with a specific UDP port on another
565 machine, a separate record is kept for each type of RPC (FetchFile, GetStatus,
566 and so on) sent or received. To display or otherwise access the
567 records, use the Rx Monitoring API.
568
569 =item -enable_process_stats
570
571 Activates the collection of Rx statistics and allocates memory for their
572 storage. A separate record is kept for each type of RPC (FetchFile,
573 GetStatus, and so on) sent or received, aggregated over all connections to
574 other machines. To display or otherwise access the records, use the Rx
575 Monitoring API.
576
577 =item -help
578
579 Prints the online help for this command. All other valid options
580 are ignored.
581
582 =back
583
584 =head1 EXAMPLES
585
586 The afsd command is normally included in the machine's AFS
587 initialization file, rather than typed at the command shell prompt. For
588 most disk caches, the appropriate form is
589
590    /usr/vice/etc/afsd
591
592 The following command is appropriate when enabling a machine to act as an
593 NFS/AFS Translator machine serving more than five users.
594
595    /usr/vice/etc/afsd -daemons 4 -rmtsys
596
597 The following command initializes a memory cache and sets chunk size to 16
598 KB (214).
599
600    /usr/vice/etc/afsd -memcache -chunksize 14
601
602 =head1 PRIVILEGE REQUIRED
603
604 The issuer must be logged in as the local superuser root.
605
606 =head1 SEE ALSO
607
608 L<CacheItems(1)>,
609 L<CellServDB (client version)(1)>
610
611 L<ThisCell (client version)(1)>
612
613 L<VI<n>(1)>,
614 L<cacheinfo(1)>
615 L<(1)>
616 L<(1)>
617 L<(1)>
618 L<(1)>
619 L<(1)>
620
621 =head1 COPYRIGHT
622
623 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
624
625 This documentation is covered by the IBM Public License Version 1.0.  It was
626 converted from HTML to POD by software written by Chas Williams and Russ
627 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.