man-page-updates-20070726
[openafs.git] / doc / man-pages / pod8 / afsd.pod
index 4491921..27c58a1 100644 (file)
@@ -4,23 +4,29 @@ afsd - Initializes the Cache Manager and starts related daemons
 
 =head1 SYNOPSIS
 
-B<afsd> [B<-blocks> <I<1024 byte blocks in cache>>]  
-     [B<-files> <I<files in cache>>]
-     [B<-rootvol> <I<name of AFS root volume>>]
-     [B<-stat> <I<number of stat entries>>]
-     [B<-memcache>] [B<-cachedir> <I<cache directory>>]  
-     [B<-mountdir> <I<mount location>>]
-     [B<-daemons> <I<number of daemons to use>>]  
+=for html
+<div class="synopsis">
+
+B<afsd> S<<< [B<-blocks> <I<1024 byte blocks in cache>>] >>>
+     S<<< [B<-files> <I<files in cache>>] >>>
+     S<<< [B<-rootvol> <I<name of AFS root volume>>] >>>
+     S<<< [B<-stat> <I<number of stat entries>>] >>>
+     [B<-memcache>] S<<< [B<-cachedir> <I<cache directory>>] >>>
+     S<<< [B<-mountdir> <I<mount location>>] >>>
+     S<<< [B<-daemons> <I<number of daemons to use>>] >>>
      [B<-nosettime>] [B<-verbose>] [B<-rmtsys>] [B<-debug>]
-     [B<-chunksize> <I<log(2) of chunk size>>]
-     [B<-dcache> <I<number of dcache entries>>]
-     [B<-volumes> <I<number of volume entries>>]  
-     [B<-biods> <I<number of bkg I/O daemons (aix vm)>>]
-     [B<-prealloc> <I<number of 'small' preallocated blocks>>]
-     [B<-confdir> <I<configuration directory>>]
-     [B<-logfile> <I<Place to keep the CM log>>]  
+     S<<< [B<-chunksize> <I<log(2) of chunk size>>] >>>
+     S<<< [B<-dcache> <I<number of dcache entries>>] >>>
+     S<<< [B<-volumes> <I<number of volume entries>>] >>>
+     S<<< [B<-biods> <I<number of bkg I/O daemons (aix vm)>>] >>>
+     S<<< [B<-prealloc> <I<number of 'small' preallocated blocks>>] >>>
+     S<<< [B<-confdir> <I<configuration directory>>] >>>
+     S<<< [B<-logfile> <I<Place to keep the CM log>>] >>>
      [B<-waitclose>] [B<-shutdown>] [B<-enable_peer_stats>]
-     [B<-enable_process_stats>] [B<-help>]
+     [B<-enable_process_stats>] [B<-dynroot>] [B<-help>]
+
+=for html
+</div>
 
 =head1 DESCRIPTION
 
@@ -156,7 +162,7 @@ Sets the size of each cache I<chunk>, and by implication the amount of
 data that the Cache Manager requests at a time from the File Server (how
 much data per fetch RPC, since AFS uses partial file transfer).
 
-For a disk cache, a chunk is a F<< VIZ<><n> >> file and this parameter
+For a disk cache, a chunk is a F<VI<n>> file and this parameter
 sets the maximum size to which each one can expand; the default is 64
 KB. For a memory cache, each chunk is a collection of contiguous memory
 blocks; the default is size is 8 KB.
@@ -171,7 +177,7 @@ the number of dcache entries, resulting in a slightly smaller cache.
 
 Sets the number of chunks in the cache. For a memory cache, the number of
 chunks is equal to the cache size divided by the chunk size.  For a disk
-cache, the number of chunks (F<< VIZ<><n> >> files) is set to the largest
+cache, the number of chunks (F<VI<n>> files) is set to the largest
 of the following unless the B<-files> argument is used to set the value
 explicitly:
 
@@ -198,7 +204,7 @@ Sets the number of I<dcache entries> allocated in machine memory for
 storing information about the chunks in the cache.
 
 For a disk cache, the F</usr/vice/cache/CacheItems> file contains one
-entry for each F<< VIZ<><n> >> file. By default, one half the number of
+entry for each F<VI<n>> file. By default, one half the number of
 these entries (but not more that 2,000) are duplicated as dcache entries
 in machine memory for quicker access.
 
@@ -338,11 +344,16 @@ suites. Provide the command name and all option names in full.
 
 =head1 CAUTIONS
 
-Do not use the B<-shutdown> parameter. It does not shutdown the Cache
-Manager effectively. Instead, halt Cache Manager activity by using the
-standard UNIX B<umount> command to unmount the AFS root directory (by
-convention, F</afs>). The machine must then be rebooted to reinitialize
-the Cache Manager.
+Before using the B<-shutdown> parameter, use the standard UNIX B<umount>
+command to unmount the AFS root directory (by convention, F</afs>).  On
+Linux, unloading the AFS kernel module and then loading it again before
+restarting AFS after B<-shutdown> is recommended.
+
+AFS has for years had difficulties with being stopped and restarted
+without an intervening reboot.  While most of these issues have been
+ironed out, stopping and restarting AFS is not recommended unless
+necessary and rebooting before restarting AFS is still the safest course
+of action.
 
 =head1 OPTIONS
 
@@ -360,9 +371,9 @@ doing so can possibly result in a chunk size that is not an exponent of 2.
 
 =item B<-files> <I<files in cache>>
 
-Specifies the number of F<< VIZ<><n> >> files to create in the cache
+Specifies the number of F<VI<n>> files to create in the cache
 directory for a disk cache, overriding the default that is calculated as
-described in L<DESCRIPTION>. Each F<< VIZ<><n> >> file accommodates a
+described in L<DESCRIPTION>. Each F<VI<n>> file accommodates a
 chunk of data, and can grow to a maximum size of 64 KB by default. Do not
 combine this argument with the B<-memcache> argument.
 
@@ -451,7 +462,7 @@ requires that the issuer calculate the cache size that results.
 
 Sets the number of dcache entries in memory, which are used to store
 information about cache chunks. For a disk cache, this overrides the
-default, which is 50% of the number of F<< VIZ<><n> >> files (cache
+default, which is 50% of the number of F<VI<n>> files (cache
 chunks). For a memory cache, this argument effectively sets the number of
 cache chunks, but its use is not recommended, because it requires the
 issuer to calculate the resulting total cache size (derived by multiplying
@@ -519,6 +530,36 @@ GetStatus, and so on) sent or received, aggregated over all connections to
 other machines. To display or otherwise access the records, use the Rx
 Monitoring API.
 
+=item B<-dynroot>
+
+The standard behaviour of the AFS client without the B<-dynroot> option is
+to mount the root.afs volume from the default cell on the F</afs> path. The 
+F</afs> folder and root.afs volume traditionally shows the folders for 
+F<ThisCell> and other cells as configured by the AFS cell administrator.
+
+The B<-dynroot> option changes this. Using this option, the AFS client does
+NOT mount the root.afs volume on F</afs>. Instead it uses the contents of
+the F<CellServDB> file to populate the listing of cells in F</afs>. This
+is known as a DYNamic ROOT. A cell is not contacted until the path
+F</afs/I<cellname>> if accessed. This functions similarly to an automounter.
+The main advantage of using B<-dynroot> is that the AFS client will
+start properly even without network access, whereas the client not using
+B<-dynroot> will freeze upon startup if cannot contact the default cell
+specified in F<ThisCell> and mount the root.afs volume. Dynamic root mode
+is also sometimes called travelling mode because it works well for laptops
+which don't always have network connectivity.
+
+Two advantages of not using dynroot are that listing F</afs> will usually
+be faster because the contents of F</afs> are limited to what the AFS
+administrator decides and that symbolic links are traditionally created
+by the AFS administrator to provide a short name for the cell (i.e.
+cellname.domain.com is aliased to cellname).  However, with dynroot, the
+local system administrator can limit the default contents of F</afs> by
+installing a stripped-down F<CellServDB> file, and if dynroot is in effect,
+the F<CellAlias> file can be used to provide shortname for common AFS cells
+which provides equivalent functionality to the most commonly used symbolic
+links.
+
 =item B<-help>
 
 Prints the online help for this command. All other valid options are
@@ -550,7 +591,7 @@ The issuer must be logged in as the local superuser root.
 
 =head1 SEE ALSO
 
-L<CacheItems(5)>,
+L<afs_cache(5)>,
 L<CellServDB(5)>,
 L<cacheinfo(5)>