=head1 NAME

afsd - Initializes the Cache Manager and starts related daemons.

=head1 SYNOPSIS

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>]
[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>]
[B<-waitclose>]  [B<-shutdown>]  [B<-enable_peer_stats>]
[B<-enable_process_stats>]  [B<-help>]

This command does not use the syntax conventions of the AFS command
suites. Provide the command name and all option names in full.

=head1 DESCRIPTION

The C<afsd> command initializes the Cache Manager on an AFS client
machine by transferring AFS-related configuration information into
kernel memory and starting several daemons. More specifically, the
C<afsd> command performs the following actions:

=over

=item *

Sets a field in kernel memory that defines the machine's cell
membership. Some Cache Manager-internal operations and system
calls consult this field to learn which cell to execute in. (The
AFS command interpreters refer to the B</usr/vice/etc/ThisCell> file
instead.) This information is transferred into the kernel from the
B</usr/vice/etc/ThisCell> file and cannot be changed until the C<afsd>
program runs again.

=item *

Places in kernel memory the names and Internet addresses of the
database server machines in the local cell and (optionally)
foreign cells. The appearance of a cell's database server machines
in this list enables the Cache Manager to contact them and to
access files in the cell. Omission of a cell from this list, or
incorrect information about its database server machines, prevents
the Cache Manager from accessing files in it.

The list of database server machines is transferred into the
kernel from the B</usr/vice/etc/CellServDB> file. After
initialization, use the C<fs newcell> command to change the
kernel-resident list without having to reboot.

=item *

Mounts the root of the AFS filespace on a directory on the
machine's local disk, according to either the first field in the
B</usr/vice/etc/cacheinfo> file (the default) or the C<afsd> command's
B<-mountdir> argument. The conventional value is B</afs>.

=item *

Determines which volume to mount at the root of the AFS file tree.
The default is the volume B<root.afs>; use the B<-rootvol> argument to
override it. Although the base (read/write) form of the volume
name is the appropriate value, the Cache Manager has a bias for
accessing the read-only version of the volume (by convention,
B<root.afs.readonly>) if it is available.

=item *

Configures the cache on disk (the default) or in machine memory if
the B<-memcache> argument is provided. In the latter case, the C<afsd>
program allocates space in machine memory for caching, and the
Cache Manager uses no disk space for caching even if the machine
has a disk.

=item *

Defines the name of the local disk directory devoted to caching,
when the B<-memcache> argument is not used. If necessary, the C<afsd>
program creates the directory (its parent directory must already
exist). It does not remove the directory that formerly served this
function, if one exists.

The second field in the B</usr/vice/etc/cacheinfo> file is the source
for this name, and the standard value is the B</usr/vice/cache>
directory. Use the B<-cachedir> argument to override the value in the
B<cacheinfo> file.

=item *

Sets the size of the cache. The default source for the value is
the third field in the B</usr/vice/etc/cacheinfo> file, which
specifies a number of kilobytes.

For a memory cache, the following arguments to the C<afsd> command
override the value in the B<cacheinfo> file:

=over

=item *

The B<-blocks> argument, to specify a different number of
kilobyte blocks.

=item *

The B<-dcache> and B<-chunksize> arguments together, to set both
the number of dcache entries and the chunk size (see below
for definition of these parameters). In this case, the C<afsd>
program derives cache size by multiplying the two values.
Using this combination is not recommended, as it requires the
issuer to perform the calculation beforehand to determine the
resulting cache size.

=item *

The B<-dcache> argument by itself. In this case, the C<afsd>
program derives cache size by multiplying the value specified
by the B<-dcache> argument by the default memory cache chunk
size of eight kilobytes. Using this argument is not
recommended, as it requires the issuer to perform the
calculation beforehand to determine the resulting cache size.

=back

For satisfactory memory cache performance, the specified value
must leave enough memory free to accommodate all other processes
and commands that can run on the machine. If the value exceeds the
amount of memory available, the C<afsd> program exits without
initializing the Cache Manager and produces the following message
on the standard output stream:

afsd: memCache allocation failure at I<number> KB

where I<number> is how many kilobytes were allocated just before the
failure.

For a disk cache, use the B<-blocks> argument to the C<afsd> command to
override the value in the B<cacheinfo> file. The value specified in
either way sets an absolute upper limit on cache size; values
provided for other arguments (such as B<-dcache> and B<-chunksize>)
never result in a larger cache. The C<afsd> program rejects any
setting larger than 95% of the partition size, and exits after
generating an error message on the standard output stream, because
the cache implementation itself requires a small amount of disk
space and overfilling the partition can cause the client machine
to panic.

To change the size of a disk cache after initialization without
rebooting, use the C<fs setcachesize> command; the setting persists
until the C<afsd> command runs again or the C<fs setcachesize> command
is reissued. The C<fs setcachesize> command does not work for memory
caches.

=item *

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 B<V>I<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.

To override the default chunk size for either type of cache, use
the B<-chunksize> argument to provide an integer to be used as an
exponent of two; see the B<Options> section for details. For a memory
cache, if total cache size divided by chunk size leaves a
remainder, the C<afsd> program rounds down the number of dcache
entries, resulting in a slightly smaller cache.

=item *

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 (B<V>I<n> files) is set to
the largest of the following unless the B<-files> argument is used to
set the value explicitly:

=over

=item *

100

=item *

1.5 times the result of dividing cache size by chunk size
(I<cachesize>/I<chunksize> * 1.5)

=item *

The result of dividing cachesize by 10 KB (I<cachesize>/10240)

=back

=item *

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 B</usr/vice/cache/CacheItems> file contains one
entry for each B<V>I<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.

For a memory cache, there is no B<CacheItems> file so all information
about cache chunks must be in memory as dcache entries. Thus,
there is no default number of dcache entries for a memory cache;
instead, the C<afsd> program derives it by dividing the cache size by
the chunk size.

To set the number of dcache entries, use the B<-dcache> argument; the
specified value can exceed the default limit of 2,000. Using this
argument is not recommended for either type of cache. Increasing
the number of dcache entries for a disk cache sometimes improves
performance (because more entries are retrieved from memory rather
than from disk), but only marginally. Using this argument for a
memory cache requires the issuer to calculate the cache size by
multiplying this value by the chunk size.

=item *

Sets the number of I<stat> entries available in machine memory for
caching status information about cached AFS files. The default is
300; use the B<-stat> argument to override the default.

=item *

Randomly selects a file server machine in the local cell as the
source for the correct time. Every five minutes thereafter, the
local clock is adjusted (if necessary) to match the file server
machine's clock.

Use the B<-nosettime> flag to prevent the C<afsd> command from selecting
a time standard. This is recommended only on file server machines
that are also acting as clients. File server machines maintain the
correct time using the Network Time Protocol Daemon instead.

=back

In addition to setting cache configuration parameters, the C<afsd>
program starts the following daemons. (On most system types, these
daemons appear as nameless entries in the output of the UNIX C<ps>
command.)

=over

=item *

One I<callback> daemon, which handles callbacks. It also responds to
the File Server's periodic probes, which check that the client
machine is still alive.

=item *

One I<maintenance> daemon, which performs the following tasks:

=over

=item *

Garbage collects obsolete data (for example, expired tokens)
from kernel memory

=item *

Synchronizes files

=item *

Refreshes information from read-only volumes once per hour

=item *

Does delayed writes for NFS clients if the machine is running
the NFS/AFS Translator

=back

=item *

One I<cache-truncation> daemon, which flushes the cache when free
space is required, by writing cached data and status information
to the File Server.

=item *

One I<server connection> daemon, which sends a probe to the File
Server every few minutes to check that it is still accessible. It
also synchronizes the machine's clock with the clock on a
randomly-chosen file server machine, unless the B<-nosettime> flag is
used. There is always one server connection daemon.

=item *

One or more I<background> daemons that improve performance by
pre-fetching files and performing background (delayed) writes of
saved data into AFS.

The default number of background daemons is two, enough to service
at least five simultaneous users of the machine. To increase the
number, use the B<-daemons> argument. A value greater than six is not
generally necessary.

=item *

On some system types, one I<Rx listener> daemon, which listens for
incoming RPCs.

=item *

On some system types, one I<Rx event> daemon, which reviews the Rx
system's queue of tasks and performs them as appropriate. Most
items in the queue are retransmissions of failed packets.

=item *

On machines that run AIX with virtual memory (VM) integration, one
or more I<VM> daemons (sometimes called I<I/O> daemons, which transfer
data between disk and machine memory. The number of them depends
on the setting of the B<-biods> and B<-daemons> arguments:

=over

=item *

If the B<-biods> argument is used, it sets the number of VM
daemons.

=item *

If only the B<-daemons> argument is used, the number of VM
daemons is twice the number of background daemons.

=item *

If neither argument is used, there are five VM daemons.

=back

=back

=head1 OPTIONS

=over 4

=item B<-blocks>

Specifies the number of kilobyte blocks to be made available
for caching in the machine's cache directory (for a disk cache)
or memory (for a memory cache), overriding the default defined
in the third field of the B</usr/vice/etc/cacheinfo> file. For a
disk cache, the value cannot exceed 95% of the space available
in the cache partition. If using a memory cache, do not combine
this argument with the B<-dcache> argument, since doing so can
possibly result in a chunk size that is not an exponent of 2.

=item B<-files>

Specifies the number of B<V>I<n> files to create in the cache
directory for a disk cache, overriding the default that is
calculated as described in the B<Description> section. Each B<V>I<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.

=item B<-rootvol>

Names the read/write volume corresponding to the root directory
for the AFS file tree (which is usually the B</afs> directory).
This value overrides the default of the B<root.afs> volume.

=item B<-stat>

Specifies the number of entries to allocate in the machine's
memory for recording status information about the AFS files in
the cache. This value overrides the default of 300.

=item B<-memcache>

Initializes a memory cache rather than a disk cache. Do not
combine this flag with the B<-files> argument.

=item B<-cachedir>

Names the local disk directory to be used as the cache. This
value overrides the default defined in the second field of the
B</usr/vice/etc/cacheinfo> file.

=item B<-mountdir>

Names the local disk directory on which to mount the root of
the AFS filespace. This value overrides the default defined in
the first field of the B</usr/vice/etc/cacheinfo> file. If a value
other than the B</afs> directory is used, the machine cannot
access the filespace of cells that do use that value.

=item B<-daemons>

Specifies the number of background daemons to run on the
machine. These daemons improve efficiency by doing prefetching
and background writing of saved data. This value overrides the
default of 2, which is adequate for a machine serving up to
five users. Values greater than B<6> are not generally more
effective than B<6>.

B<Note>: On AIX machines with integrated virtual memory (VM), the
number of VM daemons is set to twice the value of this
argument, if it is provided and the B<-biods> argument is not. If
both arguments are omitted, there are five VM daemons.

=item B<-nosettime>

Prevents the Cache Manager from synchronizing its clock with
the clock on a server machine selected at random, by checking
the time on the server machine every five minutes. Use this
flag only on a machine that is already using another time
synchronization protocol (for example, a server machine that is
running the B<runntp> process).

=item B<-verbose>

Generates a detailed trace of the C<afsd> program's actions on the
standard output stream.

=item B<-rmtsys>

Initializes an additional daemon to execute AFS-specific system
calls on behalf of NFS client machines. Use this flag only if
the machine is an NFS/AFS translator machine serving users of
NFS client machines who execute AFS commands.

=item B<-debug>

Generates a highly detailed trace of the C<afsd> program's actions
on the standard output stream. The information is useful mostly
for debugging purposes.

=item B<-chunksize>

Sets the size of each cache chunk. The integer provided, which
must be from the range B<0> to B<30>, is used as an exponent on the
number 2. It overrides the default of 16 for a disk cache (2^16
is 64 KB) and 13 for a memory cache (2^13 is 8 KB). A value of
B<0> or less, or greater than B<30>, sets chunk size to the
appropriate default. Values less than B<10> (which sets chunk size
to a 1 KB) are not recommended. Combining this argument with
the B<-dcache> argument is not recommended because it requires
that the issuer calculate the cache size that results.

=item B<-dcache>

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 B<V>I<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 this value
by the chunk size). Do not combine this argument with the
B<-blocks> argument, since doing so can possibly result in a chunk
size that is not an exponent of 2.

=item B<-volumes>

Specifies the number of memory structures to allocate for
storing volume location information. The default value is 50.

=item B<-biods>

Sets the number of VM daemons dedicated to performing I/O
operations on a machine running a version of AIX with virtual
memory (VM) integration. If both this argument and the B<-daemons>
argument are omitted, the default is five. If this argument is
omitted but the B<-daemons> argument is provided, the number of VM
daemons is set to twice the value of the B<-daemons> argument.

B<Note>: Provide this argument only on a machine that runs AIX with VM
integration.

=item B<-prealloc>

Specifies the number of pieces of memory to preallocate for the
Cache Manager's internal use. The default initial value is 400,
but the Cache Manager dynamically allocates more memory as it
needs it.

=item B<-confdir>

Names a directory other than the B</usr/vice/etc> directory from
which to fetch the B<cacheinfo>, B<ThisCell>, and B<CellServDB>
configuration files.

=item B<-logfile>

Is obsolete and has no real effect. It specifies an alternate
file in which to record a type of trace that the Cache Manager
no longer generates; the default value is B</usr/vice/etc/AFSLog>.

=item B<-waitclose>

Has no effect on the operation of the Cache Manager. The
behavior it affected in previous versions of the Cache Manager,
to perform synchronous writes to the File Server, is now the
default behavior. To perform asynchronous writes in certain
cases, use the C<fs storebehind> command.

=item B<-shutdown>

Shuts down the Cache Manager, but not in the most effective
possible way. Do not use this flag.

=item B<-enable_peer_stats>

Activates the collection of Rx statistics and allocates memory
for their storage. For each connection with a specific UDP port
on another machine, a separate record is kept for each type of
RPC (FetchFile, GetStatus, and so on) sent or received. To
display or otherwise access the records, use the Rx Monitoring
API.

=item B<-enable_process_stats>

Activates the collection of Rx statistics and allocates memory
for their storage. A separate record is kept for each type of
RPC (FetchFile, 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<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 EXAMPLES

The C<afsd> command is normally included in the machine's AFS
initialization file, rather than typed at the command shell prompt.
For most disk caches, the appropriate form is

 /usr/vice/etc/afsd


The following command is appropriate when enabling a machine to act as
an NFS/AFS Translator machine serving more than five users.

 /usr/vice/etc/afsd -daemons 4 -rmtsys

The following command initializes a memory cache and sets chunk size
to 16 KB (2^14).

 /usr/vice/etc/afsd -memcache -chunksize 14

=head1 PRIVILEGE REQUIRED

The issuer must be logged in as the local superuser B<root>.

=head1 CAVEATS

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 C<umount> command to unmount the AFS root directory (by
convention, B</afs>). The machine must then be rebooted to reinitialize
the Cache Manager.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<CacheItems(1)>,
L<CellServDB_client_version(1)>,
L<ThisCell_client_version(1)>,
L<Vn(1)>,
L<cacheinfo(1)>

=cut
