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