.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "AFSD 8"
.TH AFSD 8 "2012-01-23" "OpenAFS" "AFS Command Reference"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
afsd, afsd.fuse \- Initializes the Cache Manager and starts related daemons
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBafsd\fR [\fB\-afsdb\fR] [\fB\-backuptree\fR]
[\fB\-biods\fR\ <\fInumber\ of\ bkg\ I/O\ daemons\ (aix\ vm)\fR>]
[\fB\-blocks\fR\ <\fI1024\ byte\ blocks\ in\ cache\fR>]
[\fB\-cachedir\fR\ <\fIcache\ directory\fR>]
[\fB\-chunksize\fR\ <\fI\fIlog\fI\|(2)\ of\ chunk\ size\fR>]
[\fB\-confdir\fR\ <\fIconfiguration\ directory\fR>]
[\fB\-daemons\fR\ <\fInumber\ of\ daemons\ to\ use\fR>]
[\fB\-dcache\fR\ <\fInumber\ of\ dcache\ entries\fR>] [\fB\-debug\fR]
[\fB\-dynroot\fR] [\fB\-dynroot\-sparse\fR] [\fB\-enable_peer_stats\fR]
[\fB\-enable_process_stats\fR] [\fB\-fakestat\fR] [\fB\-fakestat\-all\fR]
[\fB\-files\fR\ <\fIfiles\ in\ cache\fR>]
[\fB\-files_per_subdir\fR\ <\fI\fIlog\fI\|(2)\ of\ files\ per\ dir\fR>\ ]
[\fB\-help\fR] [\fB\-logfile\fR\ <\fIPlace\ to\ keep\ the\ \s-1CM\s0\ log\fR>]
[\fB\-mem_alloc_sleep\fR] [\fB\-memcache\fR]
[\fB\-mountdir\fR\ <\fImount\ location\fR>] [\fB\-nomount\fR]
[\fB\-nosettime\fR]
[\fB\-prealloc\fR\ <\fInumber\ of\ 'small'\ preallocated\ blocks\fR>]
[\fB\-rmtsys\fR] [\fB\-rootvol\fR\ <\fIname\ of\ \s-1AFS\s0\ root\ volume\fR>]
[\fB\-rxbind\fR] [\fB\-rxmaxmtu\fR\ value\ for\ maximum\ \s-1MTU\s0\ ]
[\fB\-rxpck\fR\ value\ for\ rx_extraPackets\ ]
[\fB\-settime\fR] [\fB\-shutdown\fR]
[\fB\-splitcache\fR\ <\fI\s-1RW/RO\s0\ ratio\fR>]
[\fB\-stat\fR\ <\fInumber\ of\ stat\ entries\fR>] [\fB\-verbose\fR]
[\fB\-disable\-dynamic\-vcaches\fR]
[\fB\-volumes\fR\ <\fInumber\ of\ volume\ entries\fR>]
[\fB\-waitclose\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBafsd\fR command initializes the Cache Manager on an \s-1AFS\s0 client machine
by transferring AFS-related configuration information into kernel memory
and starting several daemons. \fBafsd.fuse\fR is an experimental variant that
initializes a FUSE-based Cache Manager instead of one based on a kernel
module.
.PP
The \fBafsd\fR command performs the following actions:
.IP "\(bu" 4
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 \s-1AFS\s0 command
interpreters refer to the \fI/usr/vice/etc/ThisCell\fR file instead.) This
information is transferred into the kernel from the
\&\fI/usr/vice/etc/ThisCell\fR file and cannot be changed until the \fBafsd\fR
program runs again.
.IP "\(bu" 4
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.
.Sp
By default, the list of database server machines is transferred into the
kernel from the \fI/usr/vice/etc/CellServDB\fR file. Alternatively, when the
\&\fB\-afsdb\fR option is used, the list of database server machines is taken
from the \s-1DNS\s0 \s-1SRV\s0 or \s-1AFSDB\s0 records for each cell. After initialization, use the
\&\fBfs newcell\fR command to change the kernel-resident list without having to
reboot.
.IP "\(bu" 4
Mounts the root of the \s-1AFS\s0 filespace on a directory on the machine's local
disk, according to either the first field in the
\&\fI/usr/vice/etc/cacheinfo\fR file (the default) or the \fBafsd\fR command's
\&\fB\-mountdir\fR argument. The conventional value is \fI/afs\fR.
.IP "\(bu" 4
Determines which volume to mount at the root of the \s-1AFS\s0 file tree. The
default is the volume \f(CW\*(C`root.afs\*(C'\fR; use the \fB\-rootvol\fR 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, \f(CW\*(C`root.afs.readonly\*(C'\fR) if
it is available.
.IP "\(bu" 4
Configures the cache on disk (the default) or in machine memory if the
\&\fB\-memcache\fR argument is provided. In the latter case, the \fBafsd\fR 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.
.IP "\(bu" 4
Defines the name of the local disk directory devoted to caching, when the
\&\fB\-memcache\fR argument is not used. If necessary, the \fBafsd\fR program
creates the directory (its parent directory must already exist). It does
not remove the directory that formerly served this function, if one
exists.
.Sp
The second field in the \fI/usr/vice/etc/cacheinfo\fR file is the source for
this name. The standard value is \fI/usr/vice/cache\fR. Use the \fB\-cachedir\fR
argument to override the value in the \fBcacheinfo\fR file.
.IP "\(bu" 4
Sets the size of the cache. The default source for the value is the third
field in the \fI/usr/vice/etc/cacheinfo\fR file, which specifies a number of
kilobytes.
.Sp
For a memory cache, the following arguments to the afsd command override
the value in the \fBcacheinfo\fR file:
.RS 4
.IP "\(bu" 4
The \fB\-blocks\fR argument, to specify a different number of kilobyte blocks.
.IP "\(bu" 4
The \fB\-dcache\fR and \fB\-chunksize\fR 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 \fBafsd\fR 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.
.IP "\(bu" 4
The \fB\-dcache\fR argument by itself. In this case, the \fBafsd\fR program
derives cache size by multiplying the value specified by the \fB\-dcache\fR
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.
.RE
.RS 4
.Sp
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 \fBafsd\fR program exits without initializing the Cache
Manager and produces the following message on the standard output stream:
.Sp
.Vb 1
\& afsd: memCache allocation failure at <number> KB
.Ve
.Sp
where <number> is how many kilobytes were allocated just before the
failure.
.Sp
For a disk cache, use the \fB\-blocks\fR argument to the \fBafsd\fR command to
override the value in the \fBcacheinfo\fR file. The value specified in either
way sets an absolute upper limit on cache size; values provided for other
arguments (such as \fB\-dcache\fR and \fB\-chunksize\fR) never result in a larger
cache. The \fBafsd\fR 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.
.Sp
To change the size of a disk cache after initialization without rebooting,
use the \fBfs setcachesize\fR command; the setting persists until the \fBafsd\fR
command runs again or the \fBfs setcachesize\fR command is reissued. The \fBfs
setcachesize\fR command does not work for memory caches.
.RE
.IP "\(bu" 4
Sets the size of each cache \fIchunk\fR, and by implication the amount of
data that the Cache Manager requests at a time from the File Server (how
much data per fetch \s-1RPC\s0, since \s-1AFS\s0 uses partial file transfer).
.Sp
For a disk cache, a chunk is a \fIV\fIn\fI\fR file and this parameter sets the
maximum size to which each one can expand. For a memory cache, each chunk
is a collection of contiguous memory blocks. The default for a disk cache
is between 256 \s-1KB\s0 and 1 \s-1MB\s0 depending on the size of the cache. The default
for a memory cache is 8 \s-1KB\s0.
.Sp
To override the default chunk size for either type of cache, use the
\&\fB\-chunksize\fR argument to provide an integer to be used as an exponent of
two; see \s-1OPTIONS\s0 for details. For a memory cache, if total cache size
divided by chunk size leaves a remainder, the \fBafsd\fR program rounds down
the number of dcache entries, resulting in a slightly smaller cache.
.IP "\(bu" 4
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 (\fIV\fIn\fI\fR files) is set to the largest
of the following unless the \fB\-files\fR argument is used to set the value
explicitly:
.RS 4
.IP "\(bu" 4
100
.IP "\(bu" 4
1.5 times the result of dividing cache size by chunk size
(\fIcachesize\fR/\fIchunksize\fR * 1.5)
.IP "\(bu" 4
The result of dividing cachesize by 10 \s-1KB\s0 (\fIcachesize\fR/10240)
.RE
.RS 4
.RE
.IP "\(bu" 4
Sets the number of \fIdcache entries\fR allocated in machine memory for
storing information about the chunks in the cache.
.Sp
For a disk cache, the \fI/usr/vice/cache/CacheItems\fR file contains one
entry for each \fIV\fIn\fI\fR 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.
.Sp
For a memory cache, there is no \fICacheItems\fR 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 \fBafsd\fR
program derives it by dividing the cache size by the chunk size.
.Sp
To set the number of dcache entries, use the \fB\-dcache\fR 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.
.IP "\(bu" 4
Sets the number of \fIstat\fR entries available in machine memory for caching
status information about cached \s-1AFS\s0 files. The default is based on the
size of the cache. Use the \fB\-stat\fR argument to override the default.
.IP "\(bu" 4
If the \fB\-settime\fR option is specified, then it 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. This is not enabled by default. It
is recommended, instead, that the Network Time Protocol Daemon be used to
synchronize the time.
.PP
In addition to setting cache configuration parameters, the \fBafsd\fR program
starts the following daemons. (On most system types, these daemons appear
as nameless entries in the output of the \s-1UNIX\s0 \fBps\fR command.)
.IP "\(bu" 4
One \fIcallback\fR daemon, which handles callbacks. It also responds to the
File Server's periodic probes, which check that the client machine is
still alive.
.IP "\(bu" 4
One \fImaintenance\fR daemon, which performs the following tasks:
.RS 4
.IP "\(bu" 4
Garbage collects obsolete data (for example, expired tokens) from kernel
memory.
.IP "\(bu" 4
Synchronizes files.
.IP "\(bu" 4
Refreshes information from read-only volumes once per hour.
.IP "\(bu" 4
Does delayed writes for \s-1NFS\s0 clients if the machine is running the \s-1NFS/AFS\s0
Translator.
.RE
.RS 4
.RE
.IP "\(bu" 4
One \fIcache-truncation\fR daemon, which flushes the cache when free space is
required, by writing cached data and status information to the File
Server.
.IP "\(bu" 4
One \fIserver connection\fR daemon, which sends a probe to the File
Server every few minutes to check that it is still accessible. If the
\&\fB\-settime\fR option is set, it also synchronizes the machine's clock
with the clock on a randomly-chosen file server machine. There is
always one server connection daemon.
.IP "\(bu" 4
One or more \fIbackground\fR daemons that improve performance by pre-fetching
files and performing background (delayed) writes of saved data into \s-1AFS\s0.
.Sp
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 \fB\-daemons\fR argument. A value greater than six is not generally
necessary.
.IP "\(bu" 4
On some system types, one \fIRx listener\fR daemon, which listens for
incoming RPCs.
.IP "\(bu" 4
On some system types, one \fIRx event\fR 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.
.IP "\(bu" 4
On machines that run \s-1AIX\s0 with virtual memory (\s-1VM\s0) integration, one or more
\&\fI\s-1VM\s0\fR daemons (sometimes called \fII/O\fR daemons, which transfer data
between disk and machine memory. The number of them depends on the setting
of the \fB\-biods\fR and \fB\-daemons\fR arguments:
.RS 4
.IP "\(bu" 4
If the \fB\-biods\fR argument is used, it sets the number of \s-1VM\s0 daemons.
.IP "\(bu" 4
If only the \fB\-daemons\fR argument is used, the number of \s-1VM\s0 daemons is
twice the number of background daemons.
.IP "\(bu" 4
If neither argument is used, there are five \s-1VM\s0 daemons.
.RE
.RS 4
.RE
.PP
\&\fBafsd.fuse\fR is a variant of \fBafsd\fR that, instead of initializing a Cache
Manager implemented as a kernel module, initializes a FUSE-based \s-1AFS\s0
client. \s-1FUSE\s0 (Filesystem in USErspace) is a Linux-only mechanism for
providing a file system through a purely user-space daemon without a
kernel module component. \fBafsd.fuse\fR takes all of the same options as
\&\fBafsd\fR.
.PP
This command does not use the syntax conventions of the \s-1AFS\s0 command
suites. Provide the command name and all option names in full.
.SH "CAUTIONS"
.IX Header "CAUTIONS"
Before using the \fB\-shutdown\fR parameter, use the standard \s-1UNIX\s0 \fBumount\fR
command to unmount the \s-1AFS\s0 root directory (by convention, \fI/afs\fR). On
Linux, unloading the \s-1AFS\s0 kernel module and then loading it again before
restarting \s-1AFS\s0 after \fB\-shutdown\fR is recommended.
.PP
\&\s-1AFS\s0 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 \s-1AFS\s0 is not recommended unless
necessary and rebooting before restarting \s-1AFS\s0 is still the safest course
of action. This does not apply to Linux; it should be safe to restart the
\&\s-1AFS\s0 client on Linux without rebooting.
.PP
In contrast to many client-server applications, not all communication is
initiated by the client. When the \s-1AFS\s0 client opens a file, it registers a
callback with the \s-1AFS\s0 server. If the file changes, the server notifies the
client that the file has changed and that all cached copies should be
discarded. In order to enable full functionality on the \s-1AFS\s0 client,
including all command-line utilities, the following \s-1UDP\s0 ports must be open
on an firewalls between the client and the server:
.PP
.Vb 8
\& fileserver 7000/udp
\& cachemanager 7001/udp (OpenAFS client. Arla uses 4711/udp)
\& ptserver 7002/udp
\& vlserver 7003/udp
\& kaserver 7004/udp (not needed with Kerberos v5)
\& volserver 7005/udp
\& reserved 7006/udp (for future use)
\& bosserver 7007/udp
.Ve
.PP
Clients will also need to be able to contact your Kerberos \s-1KDC\s0 to
authenticate. If you are using \fBkaserver\fR and \fBklog\fR, you need to allow
inbound and outbound \s-1UDP\s0 on ports >1024 (probably 1024<port<2048 would
suffice depending on the number of simultaneous \fBklog\fRs).
.PP
Be sure to set the \s-1UDP\s0 timeouts on the firewall to be at least twenty
minutes for the best callback performance.
.PP
\&\fBafsd.fuse\fR was first introduced in OpenAFS 1.5.74. It is only available
if OpenAFS was built with the \f(CW\*(C`\-\-enable\-fuse\-client\*(C'\fR configure switch.
It should be considered experimental.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-afsdb\fR" 4
.IX Item "-afsdb"
Enable afsdb support. This will use \s-1DNS\s0 to lookup the \s-1SRV\s0 or \s-1AFSDB\s0 records and
use that for the database servers for each cell instead of the values
in the \fICellServDB\fR file. This has the advantage of only needing to
update one set of \s-1DNS\s0 records to reconfigure the \s-1AFS\s0 clients for a new
database server as opposed to touching all of the clients, and also
allows one to access a cell without preconfiguring its database
servers in \fICellServDB\fR. The format of \s-1SRV\s0 records is defined in
\&\s-1RFC\s0 5864, and the \s-1AFSDB\s0 record format is in \s-1RFC\s0 1183.
.IP "\fB\-backuptree\fR" 4
.IX Item "-backuptree"
Prefer backup volumes for mountpoints in backup volumes. This option means
that the \s-1AFS\s0 client will prefer to resolve mount points to backup volumes
when a parent of the current volume is a backup volume. This is similar to
the standard behaviour of preferring read-only volumes over read-write
volumes when the parent volume is a read-only volume.
.IP "\fB\-biods\fR <\fInumber of I/O daemons\fR>" 4
.IX Item "-biods <number of I/O daemons>"
Sets the number of \s-1VM\s0 daemons dedicated to performing I/O operations on a
machine running a version of \s-1AIX\s0 with virtual memory (\s-1VM\s0) integration. If
both this argument and the \fB\-daemons\fR argument are omitted, the default
is five. If this argument is omitted but the \fB\-daemons\fR argument is
provided, the number of \s-1VM\s0 daemons is set to twice the value of the
\&\fB\-daemons\fR argument.
.IP "\fB\-blocks\fR <\fIblocks in cache\fR>" 4
.IX Item "-blocks <blocks in cache>"
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
\&\fI/usr/vice/etc/cacheinfo\fR 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 \fB\-dcache\fR argument, since
doing so can possibly result in a chunk size that is not an exponent of 2.
.IP "\fB\-cachedir\fR <\fIcache directory\fR>" 4
.IX Item "-cachedir <cache directory>"
Names the local disk directory to be used as the cache. This value
overrides the default defined in the second field of the
\&\fI/usr/vice/etc/cacheinfo\fR file.
.IP "\fB\-chunksize\fR <\fIchunk size\fR>" 4
.IX Item "-chunksize <chunk size>"
Sets the size of each cache chunk. The integer provided, which must be
from the range \f(CW0\fR to \f(CW30\fR, is used as an exponent on the number 2. If not
supplied, a default chunksize will be determined based on the cache type and
cache size, and will range from \f(CW13\fR (8KB) for memory cache and \f(CW18\fR to
\&\f(CW20\fR (256 \s-1KB\s0 to 1MB) for disk cache. A value of \f(CW0\fR or less, or greater than
\&\f(CW30\fR, sets chunk size to the appropriate default. Values less than \f(CW10\fR
(which sets chunk size to a 1 \s-1KB\s0) are not recommended. Combining this
argument with the \fB\-dcache\fR argument is not recommended because it
requires that the issuer calculate the cache size that results.
.Sp
\&\fB\-chunksize\fR is an important option when tuning for performance. Setting
this option to larger values can increase performance when dealing with
large files.
.IP "\fB\-confdir\fR <\fIconfiguration directory\fR>" 4
.IX Item "-confdir <configuration directory>"
Names a directory other than the \fI/usr/vice/etc\fR directory from which to
fetch the \fIcacheinfo\fR, \fIThisCell\fR, and \fICellServDB\fR configuration
files.
.IP "\fB\-daemons\fR <\fInumber of daemons to use\fR>" 4
.IX Item "-daemons <number of daemons to use>"
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 \f(CW2\fR, which is adequate
for a machine serving up to five users. Values greater than \f(CW6\fR are not
generally more effective than \f(CW6\fR.
.Sp
Note: On \s-1AIX\s0 machines with integrated virtual memory (\s-1VM\s0), the number of
\&\s-1VM\s0 daemons is set to twice the value of this argument, if it is provided
and the \fB\-biods\fR argument is not. If both arguments are omitted, there
are five \s-1VM\s0 daemons.
.IP "\fB\-dcache\fR <\fInumber of dcache entries\fR>" 4
.IX Item "-dcache <number of dcache entries>"
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 \fIV\fIn\fI\fR 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 \fB\-blocks\fR
argument, since doing so can possibly result in a chunk size that is not
an exponent of 2.
.IP "\fB\-debug\fR" 4
.IX Item "-debug"
Generates a highly detailed trace of the \fBafsd\fR program's actions on the
standard output stream. The information is useful mostly for debugging
purposes.
.IP "\fB\-dynroot\fR" 4
.IX Item "-dynroot"
The standard behaviour of the \s-1AFS\s0 client without the \fB\-dynroot\fR option is
to mount the root.afs volume from the default cell on the \fI/afs\fR path. The
\&\fI/afs\fR folder and root.afs volume traditionally shows the folders for
\&\fIThisCell\fR and other cells as configured by the \s-1AFS\s0 cell administrator.
.Sp
The \fB\-dynroot\fR option changes this. Using this option, the \s-1AFS\s0 client
does not mount the root.afs volume on \fI/afs\fR. Instead it uses the
contents of the \fICellServDB\fR file to populate the listing of cells in
\&\fI/afs\fR. This is known as a DYNamic \s-1ROOT\s0. A cell is not contacted until
the path \fI/afs/\fIcellname\fI\fR if accessed. This functions similarly to an
automounter. The main advantage of using \fB\-dynroot\fR is that the \s-1AFS\s0
client will start properly even without network access, whereas the client
not using \fB\-dynroot\fR will freeze upon startup if cannot contact the
default cell specified in \fIThisCell\fR 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.
.Sp
Two advantages of not using dynroot are that listing \fI/afs\fR will usually
be faster because the contents of \fI/afs\fR are limited to what the \s-1AFS\s0
administrator decides and that symbolic links are traditionally created
by the \s-1AFS\s0 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 \fI/afs\fR by
installing a stripped-down \fICellServDB\fR file, and if dynroot is in effect,
the \fICellAlias\fR file can be used to provide shortname for common \s-1AFS\s0 cells
which provides equivalent functionality to the most commonly used symbolic
links.
.IP "\fB\-dynroot\-sparse\fR" 4
.IX Item "-dynroot-sparse"
In addition to operating in the manner described for dynroot above,
cells other than the local cell are not shown by default until a lookup
occurs. Cell aliases as set in the CellAliases file are shown as normal,
although they may appear to be dangling links until traversed.
.IP "\fB\-enable_peer_stats\fR" 4
.IX Item "-enable_peer_stats"
Activates the collection of Rx statistics and allocates memory for their
storage. For each connection with a specific \s-1UDP\s0 port on another machine,
a separate record is kept for each type of \s-1RPC\s0 (FetchFile, GetStatus, and
so on) sent or received. To display or otherwise access the records, use
the Rx Monitoring \s-1API\s0.
.IP "\fB\-enable_process_stats\fR" 4
.IX Item "-enable_process_stats"
Activates the collection of Rx statistics and allocates memory for their
storage. A separate record is kept for each type of \s-1RPC\s0 (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 \s-1API\s0.
.IP "\fB\-fakestat\fR" 4
.IX Item "-fakestat"
Return fake values for stat calls on cross-cell mounts. This option makes
an \f(CW\*(C`ls \-l\*(C'\fR of \fI/afs\fR much faster since each cell isn't contacted, and
this and the \fB\-fakestat\-all\fR options are useful on Mac \s-1OS\s0 X so that the
Finder program doesn't try to contact every \s-1AFS\s0 cell the system knows
about.
.Sp
Note that, for the purposes of \fB\-fakestat\fR, local cellular mounts count
as \*(L"cross-cell\*(R" mounts. That is, if the local cell is \f(CW\*(C`localcell\*(C'\fR, a
mount for \f(CW\*(C`localcell:root.cell\*(C'\fR will count as a \*(L"cross-cell\*(R" mount and
so stat calls for it will be faked with \fB\-fakestat\fR. In practice, local
cellular mounts are rare and generally discouraged, so this should not
generally make a difference.
.IP "\fB\-fakestat\-all\fR" 4
.IX Item "-fakestat-all"
Return fake values for stat calls on all mounts, not just cross-cell
mounts. This and the \fB\-fakestat\fR options are useful on Mac \s-1OS\s0 X so that
the Finder program doesn't hang when browsing \s-1AFS\s0 directories.
.IP "\fB\-files\fR <\fIfiles in cache\fR>" 4
.IX Item "-files <files in cache>"
Specifies the number of \fIV\fIn\fI\fR files to create in the cache directory
for a disk cache, overriding the default that is calculated as described
in \s-1DESCRIPTION\s0. Each \fIV\fIn\fI\fR file accommodates a chunk of data, and
can grow to a maximum size of 64 \s-1KB\s0 by default. Do not combine this
argument with the \fB\-memcache\fR argument.
.IP "\fB\-files_per_subdir\fR <\fIfiles per cache subdirectory\fR>" 4
.IX Item "-files_per_subdir <files per cache subdirectory>"
Limits the number of cache files in each subdirectory of the cache
directory. The value of the option should be the base-two log of the
number of cache files per cache subdirectory (so 10 for 1024 files, 14 for
16384 files, and so forth).
.IP "\fB\-help\fR" 4
.IX Item "-help"
Prints the online help for this command. All other valid options are
ignored.
.IP "\fB\-logfile\fR <\fIlog file location\fR>" 4
.IX Item "-logfile <log file location>"
This option is obsolete and no longer has any effect.
.IP "\fB\-mem_alloc_sleep\fR" 4
.IX Item "-mem_alloc_sleep"
This option is obsolete and no longer has any effect.
.IP "\fB\-memcache\fR" 4
.IX Item "-memcache"
Initializes a memory cache rather than a disk cache. Do not combine this
flag with the \fB\-files\fR argument.
.IP "\fB\-mountdir\fR <\fImount location\fR>" 4
.IX Item "-mountdir <mount location>"
Names the local disk directory on which to mount the root of the \s-1AFS\s0
filespace. This value overrides the default defined in the first field of
the \fI/usr/vice/etc/cacheinfo\fR file. If a value other than the \fI/afs\fR
directory is used, the machine cannot access the filespace of cells that
do use that value.
.IP "\fB\-nomount\fR" 4
.IX Item "-nomount"
Do not mount \s-1AFS\s0 on startup. The afs global mount must be mounted via
some other means. This is useful on Mac \s-1OS\s0 X where /afs is sometimes
mounted in /Network/afs like other network file systems.
.IP "\fB\-nosettime\fR" 4
.IX Item "-nosettime"
This is enabled by default. It 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.
This is the recommended behavior; instead of the \s-1AFS\s0 Cache Manager, the
Network Time Protocol Daemon should be used to synchronize the system
time.
.IP "\fB\-prealloc\fR <\fInumber of preallocated blocks\fR>" 4
.IX Item "-prealloc <number of preallocated blocks>"
Specifies the number of pieces of memory to preallocate for the Cache
Manager's internal use. The default initial value is \f(CW400\fR, but the Cache
Manager dynamically allocates more memory as it needs it.
.IP "\fB\-rmtsys\fR" 4
.IX Item "-rmtsys"
Initializes an additional daemon to execute AFS-specific system calls on
behalf of \s-1NFS\s0 client machines. Use this flag only if the machine is an
\&\s-1NFS/AFS\s0 translator machine serving users of \s-1NFS\s0 client machines who
execute \s-1AFS\s0 commands.
.IP "\fB\-rootvol\fR <\fIname of \s-1AFS\s0 root volume\fR>" 4
.IX Item "-rootvol <name of AFS root volume>"
Names the read/write volume corresponding to the root directory for the
\&\s-1AFS\s0 file tree (which is usually the \fI/afs\fR directory). This value
overrides the default of the \f(CW\*(C`root.afs\*(C'\fR volume. This option is ignored if
\&\fB\-dynroot\fR is given.
.IP "\fB\-rxbind\fR" 4
.IX Item "-rxbind"
Bind the Rx socket (one interface only).
.IP "\fB\-rxmaxmtu\fR <\fIvalue for maximum \s-1MTU\s0\fR>" 4
.IX Item "-rxmaxmtu <value for maximum MTU>"
Set a limit for the largest maximum transfer unit (network packet size) that
the \s-1AFS\s0 client on this machine will be willing to transmit. This switch can
be used where an artificial limit on the network precludes packets as large
as the discoverable \s-1MTU\s0 from being transmitted successfully.
.IP "\fB\-rxpck\fR <\fIvalue for rx_extraPackets\fR>" 4
.IX Item "-rxpck <value for rx_extraPackets>"
Set rx_extraPackets to this value. This sets the number of extra Rx
packet structures that are available to handle Rx connections. This
value should be increased if the \*(L"rxdebug 127.0.0.1 \-port 7001
\&\-rxstats\*(R" command shows no free Rx packets. Increasing this value may
improve OpenAFS client performance in some circumstances.
.IP "\fB\-settime\fR" 4
.IX Item "-settime"
Enable native \s-1AFS\s0 time synchronization. This option is the opposite of
\&\fB\-nosettime\fR and cannot be used with the \fB\-nosettime\fR option.
.IP "\fB\-shutdown\fR" 4
.IX Item "-shutdown"
Shuts down the Cache Manager. Before calling \fBafsd\fR with this option,
unmount the \s-1AFS\s0 file system with \fBumount\fR.
.IP "\fB\-splitcache\fR <\fI\s-1RW/RO\s0 Ratio\fR>" 4
.IX Item "-splitcache <RW/RO Ratio>"
This allows the user to set a certain percentage of the \s-1AFS\s0 cache be
reserved for read/write content and the rest to be reserved for read-only
content. The ratio should be written as a fraction. For example,
\&\f(CW\*(C`\-splitcache 75/25\*(C'\fR devotes 75% of your cache space to read/write content
and 25% to read-only.
.IP "\fB\-stat\fR <\fInumber of stat entries\fR>" 4
.IX Item "-stat <number of stat entries>"
Specifies the number of entries to allocate in the machine's memory for
recording status information about the \s-1AFS\s0 files in the cache. If this value
is not specified, the number of stat entires will be autotuned based on the
size of the disk cache.
.IP "\fB\-verbose\fR" 4
.IX Item "-verbose"
Generates a detailed trace of the \fBafsd\fR program's actions on the
standard output stream.
.IP "\fB\-volumes\fR <\fInumber of volume entries\fR>" 4
.IX Item "-volumes <number of volume entries>"
Specifies the number of memory structures to allocate for storing volume
location information. The default value is \f(CW200\fR.
.IP "\fB\-disable\-dynamic\-vcaches\fR" 4
.IX Item "-disable-dynamic-vcaches"
By default, dynamic vcache overrides the \fB\-stat\fR option by using the value of
\&\fB\-stat\fR (or the default) as the initial size of the stat (or vcache) pool and
increases the pool dynamically as needed on supported platforms. This flag will
disable this new functionality and honor the '\-stat' setting.
.IP "\fB\-waitclose\fR" 4
.IX Item "-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 \fBfs storebehind\fR command.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The \fBafsd\fR command is normally included in the machine's \s-1AFS\s0
initialization file, rather than typed at the command shell prompt. For
most disk caches, the appropriate form is
.PP
.Vb 1
\& % /usr/vice/etc/afsd
.Ve
.PP
The following command is appropriate when enabling a machine to act as an
\&\s-1NFS/AFS\s0 Translator machine serving more than five users.
.PP
.Vb 1
\& % /usr/vice/etc/afsd \-daemons 4 \-rmtsys
.Ve
.PP
The following command initializes a memory cache and sets chunk size to 16
\&\s-1KB\s0 (2^14).
.PP
.Vb 1
\& % /usr/vice/etc/afsd \-memcache \-chunksize 14
.Ve
.SH "PRIVILEGE REQUIRED"
.IX Header "PRIVILEGE REQUIRED"
The issuer must be logged in as the local superuser root.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIfs_newcell\fR\|(1),
\&\fIafs_cache\fR\|(5),
\&\fICellServDB\fR\|(5),
\&\fIcacheinfo\fR\|(5)
.PP
\&\s-1RFC\s0 5864 <http://www.ietf.org/rfc/rfc5864.txt>
\&\s-1RFC\s0 1183 <http://www.ietf.org/rfc/rfc1183.txt>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
\&\s-1IBM\s0 Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
.PP
This documentation is covered by the \s-1IBM\s0 Public License Version 1.0. It
was converted from \s-1HTML\s0 to \s-1POD\s0 by software written by Chas Williams and
Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.