man-page-updates-20070726
[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<-dynroot>] [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 Before using the B<-shutdown> parameter, use the standard UNIX B<umount>
348 command to unmount the AFS root directory (by convention, F</afs>).  On
349 Linux, unloading the AFS kernel module and then loading it again before
350 restarting AFS after B<-shutdown> is recommended.
351
352 AFS has for years had difficulties with being stopped and restarted
353 without an intervening reboot.  While most of these issues have been
354 ironed out, stopping and restarting AFS is not recommended unless
355 necessary and rebooting before restarting AFS is still the safest course
356 of action.
357
358 =head1 OPTIONS
359
360 =over 4
361
362 =item B<-blocks> <I<blocks in cache>>
363
364 Specifies the number of kilobyte blocks to be made available for caching
365 in the machine's cache directory (for a disk cache) or memory (for a
366 memory cache), overriding the default defined in the third field of the
367 F</usr/vice/etc/cacheinfo> file. For a disk cache, the value cannot exceed
368 95% of the space available in the cache partition. If using a memory
369 cache, do not combine this argument with the B<-dcache> argument, since
370 doing so can possibly result in a chunk size that is not an exponent of 2.
371
372 =item B<-files> <I<files in cache>>
373
374 Specifies the number of F<VI<n>> files to create in the cache
375 directory for a disk cache, overriding the default that is calculated as
376 described in L<DESCRIPTION>. Each F<VI<n>> file accommodates a
377 chunk of data, and can grow to a maximum size of 64 KB by default. Do not
378 combine this argument with the B<-memcache> argument.
379
380 =item B<-rootvol> <I<name of AFS root volume>>
381
382 Names the read/write volume corresponding to the root directory for the
383 AFS file tree (which is usually the F</afs> directory). This value
384 overrides the default of the C<root.afs> volume.
385
386 =item B<-stat> <I<number of stat entries>>
387
388 Specifies the number of entries to allocate in the machine's memory for
389 recording status information about the AFS files in the cache. This value
390 overrides the default of C<300>.
391
392 =item B<-memcache>
393
394 Initializes a memory cache rather than a disk cache. Do not combine this
395 flag with the B<-files> argument.
396
397 =item B<-cachedir> <I<cache directory>>
398
399 Names the local disk directory to be used as the cache. This value
400 overrides the default defined in the second field of the
401 F</usr/vice/etc/cacheinfo> file.
402
403 =item B<-mountdir> <I<mount location>>
404
405 Names the local disk directory on which to mount the root of the AFS
406 filespace. This value overrides the default defined in the first field of
407 the F</usr/vice/etc/cacheinfo> file. If a value other than the F</afs>
408 directory is used, the machine cannot access the filespace of cells that
409 do use that value.
410
411 =item B<-daemons> <I<number of daemons to use>>
412
413 Specifies the number of background daemons to run on the machine.  These
414 daemons improve efficiency by doing prefetching and background writing of
415 saved data. This value overrides the default of C<2>, which is adequate
416 for a machine serving up to five users. Values greater than C<6> are not
417 generally more effective than C<6>.
418
419 Note: On AIX machines with integrated virtual memory (VM), the number of
420 VM daemons is set to twice the value of this argument, if it is provided
421 and the B<-biods> argument is not. If both arguments are omitted, there
422 are five VM daemons.
423
424 =item B<-nosettime>
425
426 Prevents the Cache Manager from synchronizing its clock with the clock on
427 a server machine selected at random, by checking the time on the server
428 machine every five minutes. Use this flag only on a machine that is
429 already using another time synchronization protocol (for example, a server
430 machine that is running the B<runntp> process).
431
432 =item B<-verbose>
433
434 Generates a detailed trace of the B<afsd> program's actions on the
435 standard output stream.
436
437 =item B<-rmtsys>
438
439 Initializes an additional daemon to execute AFS-specific system calls on
440 behalf of NFS client machines. Use this flag only if the machine is an
441 NFS/AFS translator machine serving users of NFS client machines who
442 execute AFS commands.
443
444 =item B<-debug>
445
446 Generates a highly detailed trace of the B<afsd> program's actions on the
447 standard output stream. The information is useful mostly for debugging
448 purposes.
449
450 =item B<-chunksize> <I<chunk size>>
451
452 Sets the size of each cache chunk. The integer provided, which must be
453 from the range C<0> to C<30>, is used as an exponent on the number 2. It
454 overrides the default of 16 for a disk cache (2^16 is 64 KB) and 13 for a
455 memory cache (2^13 is 8 KB). A value of C<0> or less, or greater than
456 C<30>, sets chunk size to the appropriate default. Values less than C<10>
457 (which sets chunk size to a 1 KB) are not recommended.  Combining this
458 argument with the B<-dcache> argument is not recommended because it
459 requires that the issuer calculate the cache size that results.
460
461 =item B<-dcache> <I<number of dcache entries>>
462
463 Sets the number of dcache entries in memory, which are used to store
464 information about cache chunks. For a disk cache, this overrides the
465 default, which is 50% of the number of F<VI<n>> files (cache
466 chunks). For a memory cache, this argument effectively sets the number of
467 cache chunks, but its use is not recommended, because it requires the
468 issuer to calculate the resulting total cache size (derived by multiplying
469 this value by the chunk size). Do not combine this argument with the
470 B<-blocks> argument, since doing so can possibly result in a chunk size
471 that is not an exponent of 2.
472
473 =item B<-volumes> <I<number of volume entries>>
474
475 Specifies the number of memory structures to allocate for storing volume
476 location information. The default value is C<50>.
477
478 =item B<-biods> <I<number of I/O daemons>>
479
480 Sets the number of VM daemons dedicated to performing I/O operations on a
481 machine running a version of AIX with virtual memory (VM) integration.  If
482 both this argument and the B<-daemons> argument are omitted, the default
483 is five. If this argument is omitted but the B<-daemons> argument is
484 provided, the number of VM daemons is set to twice the value of the
485 B<-daemons> argument.
486
487 =item B<-prealloc> <I<number of preallocated blocks>>
488
489 Specifies the number of pieces of memory to preallocate for the Cache
490 Manager's internal use. The default initial value is C<400>, but the Cache
491 Manager dynamically allocates more memory as it needs it.
492
493 =item B<-confdir> <I<configuration directory>>
494
495 Names a directory other than the F</usr/vice/etc> directory from which to
496 fetch the F<cacheinfo>, F<ThisCell>, and F<CellServDB> configuration
497 files.
498
499 =item B<-logfile> <I<log file location>>
500
501 Is obsolete and has no real effect. It specifies an alternate file in
502 which to record a type of trace that the Cache Manager no longer
503 generates; the default value is F</usr/vice/etc/AFSLog>.
504
505 =item B<-waitclose>
506
507 Has no effect on the operation of the Cache Manager. The behavior it
508 affected in previous versions of the Cache Manager, to perform synchronous
509 writes to the File Server, is now the default behavior. To perform
510 asynchronous writes in certain cases, use the B<fs storebehind> command.
511
512 =item B<-shutdown>
513
514 Shuts down the Cache Manager, but not in the most effective possible
515 way. Do not use this flag.
516
517 =item B<-enable_peer_stats>
518
519 Activates the collection of Rx statistics and allocates memory for their
520 storage. For each connection with a specific UDP port on another machine,
521 a separate record is kept for each type of RPC (FetchFile, GetStatus, and
522 so on) sent or received. To display or otherwise access the records, use
523 the Rx Monitoring API.
524
525 =item B<-enable_process_stats>
526
527 Activates the collection of Rx statistics and allocates memory for their
528 storage. A separate record is kept for each type of RPC (FetchFile,
529 GetStatus, and so on) sent or received, aggregated over all connections to
530 other machines. To display or otherwise access the records, use the Rx
531 Monitoring API.
532
533 =item B<-dynroot>
534
535 The standard behaviour of the AFS client without the B<-dynroot> option is
536 to mount the root.afs volume from the default cell on the F</afs> path. The 
537 F</afs> folder and root.afs volume traditionally shows the folders for 
538 F<ThisCell> and other cells as configured by the AFS cell administrator.
539
540 The B<-dynroot> option changes this. Using this option, the AFS client does
541 NOT mount the root.afs volume on F</afs>. Instead it uses the contents of
542 the F<CellServDB> file to populate the listing of cells in F</afs>. This
543 is known as a DYNamic ROOT. A cell is not contacted until the path
544 F</afs/I<cellname>> if accessed. This functions similarly to an automounter.
545 The main advantage of using B<-dynroot> is that the AFS client will
546 start properly even without network access, whereas the client not using
547 B<-dynroot> will freeze upon startup if cannot contact the default cell
548 specified in F<ThisCell> and mount the root.afs volume. Dynamic root mode
549 is also sometimes called travelling mode because it works well for laptops
550 which don't always have network connectivity.
551
552 Two advantages of not using dynroot are that listing F</afs> will usually
553 be faster because the contents of F</afs> are limited to what the AFS
554 administrator decides and that symbolic links are traditionally created
555 by the AFS administrator to provide a short name for the cell (i.e.
556 cellname.domain.com is aliased to cellname).  However, with dynroot, the
557 local system administrator can limit the default contents of F</afs> by
558 installing a stripped-down F<CellServDB> file, and if dynroot is in effect,
559 the F<CellAlias> file can be used to provide shortname for common AFS cells
560 which provides equivalent functionality to the most commonly used symbolic
561 links.
562
563 =item B<-help>
564
565 Prints the online help for this command. All other valid options are
566 ignored.
567
568 =back
569
570 =head1 EXAMPLES
571
572 The B<afsd> command is normally included in the machine's AFS
573 initialization file, rather than typed at the command shell prompt. For
574 most disk caches, the appropriate form is
575
576    /usr/vice/etc/afsd
577
578 The following command is appropriate when enabling a machine to act as an
579 NFS/AFS Translator machine serving more than five users.
580
581    /usr/vice/etc/afsd -daemons 4 -rmtsys
582
583 The following command initializes a memory cache and sets chunk size to 16
584 KB (2^14).
585
586    /usr/vice/etc/afsd -memcache -chunksize 14
587
588 =head1 PRIVILEGE REQUIRED
589
590 The issuer must be logged in as the local superuser root.
591
592 =head1 SEE ALSO
593
594 L<afs_cache(5)>,
595 L<CellServDB(5)>,
596 L<cacheinfo(5)>
597
598 =head1 COPYRIGHT
599
600 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
601
602 This documentation is covered by the IBM Public License Version 1.0.  It was
603 converted from HTML to POD by software written by Chas Williams and Russ
604 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.