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