afsd, afsd.fuse - Initializes the Cache Manager and starts related daemons
<number of bkg I/O daemons (aix vm)
<1024 byte blocks in cache
<log(2) of chunk size
<number of daemons to use
<number of dcache entries
<files in cache
<log(2) of files per dir
<Place to keep the CM log
<number of 'small' preallocated blocks
<name of AFS root volume
value for maximum MTU ]
value for rx_extraPackets ]
<number of stat entries
<number of volume entries
<max # of fragments
command initializes the Cache Manager on an AFS client machine
by transferring AFS-related configuration information into kernel memory and
starting several daemons. afsd.fuse
is an experimental variant that
initializes a FUSE-based Cache Manager instead of one based on a kernel
command performs the following actions:
- 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 /etc/openafs/ThisCell file instead.) This
information is transferred into the kernel from the
/etc/openafs/ThisCell file and cannot be changed until the
afsd program runs again.
- 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
By default, the list of database server machines is transferred into the
kernel from the /etc/openafs/CellServDB file. Alternatively, when
the -afsdb option is used, the list of database server machines is
taken from the DNS SRV or AFSDB records for each cell. After
initialization, use the fs newcell command to change the
kernel-resident list without having to reboot.
- Mounts the root of the AFS filespace on a directory on the
machine's local disk, according to either the first field in the
/etc/openafs/cacheinfo file (the default) or the afsd
command's -mountdir argument. The conventional value is
- Determines which volume to mount at the root of the AFS
file tree. The default is the volume "root.afs"; use the
-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,
"root.afs.readonly") if it is available.
- Configures the cache on disk (the default) or in machine
memory if the -memcache argument is provided. In the latter case,
the 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
- Defines the name of the local disk directory devoted to
caching, when the -memcache argument is not used. If necessary, the
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 /etc/openafs/cacheinfo file is the source for
this name. The standard value is /usr/vice/cache. Use the
-cachedir argument to override the value in the cacheinfo
- Sets the size of the cache. The default source for the
value is the third field in the /etc/openafs/cacheinfo file, which
specifies a number of kilobytes.
For a memory cache, the following arguments to the afsd command override the
value in the cacheinfo file:
- The -blocks argument, to specify a different number
of kilobyte blocks.
- The -dcache and -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 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.
- The -dcache argument by itself. In this case, the
afsd program derives cache size by multiplying the value specified
by the -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.
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
program exits without initializing the Cache Manager and produces
the following message on the standard output stream:
afsd: memCache allocation failure at <number> KB
where <number> is how many kilobytes were allocated just before the
For a disk cache, use the -blocks
argument to the afsd
override the value in the cacheinfo
file. The value specified in either
way sets an absolute upper limit on cache size; values provided for other
arguments (such as -dcache
) never result in a
larger cache. The 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 fs setcachesize
command; the setting persists until the afsd
command runs again or the fs setcachesize
command is reissued. The
command does not work for memory caches.
- Sets the size of each cache 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
For a disk cache, a chunk is a Vn 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 KB and 1 MB depending on the size of the
cache. The default for a memory cache is 8 KB.
To override the default chunk size for either type of cache, use the
-chunksize argument to provide an integer to be used as an exponent
of two; see "OPTIONS" for details. For a memory cache, if total
cache size divided by chunk size leaves a remainder, the afsd
program rounds down the number of dcache entries, resulting in a slightly
- 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 ( Vn files) is
set to the largest of the following unless the -files argument is
used to set the value explicitly:
- 1.5 times the result of dividing cache size by chunk size (
cachesize/chunksize * 1.5)
- The result of dividing cachesize by 10 KB
- Sets the number of dcache entries allocated in
machine memory for storing information about the chunks in the cache.
For a disk cache, the /usr/vice/cache/CacheItems file contains one
entry for each Vn 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 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
afsd program derives it by dividing the cache size by the chunk
To set the number of dcache entries, use the -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.
- Sets the number of stat entries available in machine
memory for caching status information about cached AFS files. The default
is based on the size of the cache. Use the -stat argument to
override the default.
In addition to setting cache configuration parameters, the afsd
starts the following daemons. (On most system types, these daemons appear as
nameless entries in the output of the UNIX ps
- One callback daemon, which handles callbacks. It
also responds to the File Server's periodic probes, which check that the
client machine is still alive.
- One maintenance daemon, which performs the following
- Garbage collects obsolete data (for example, expired
tokens) from kernel memory.
- Synchronizes files.
- Refreshes information from read-only volumes once per
- Does delayed writes for NFS clients if the machine is
running the NFS/AFS Translator.
- One cache-truncation daemon, which flushes the cache
when free space is required, by writing cached data and status information
to the File Server.
- One server connection daemon, which sends a probe to
the File Server every few minutes to check that it is still accessible. If
the -settime 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.
- One or more 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
-daemons argument. A value greater than six is not generally
- On some system types, one Rx listener daemon, which
listens for incoming RPCs.
- On some system types, one 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.
- On machines that run AIX with virtual memory (VM)
integration, one or more VM daemons (sometimes called I/O
daemons, which transfer data between disk and machine memory. The number
of them depends on the setting of the -biods and -daemons
- If the -biods argument is used, it sets the number
of VM daemons.
- If only the -daemons argument is used, the number of
VM daemons is twice the number of background daemons.
- If neither argument is used, there are five VM
is a variant of afsd
that, instead of initializing a
Cache Manager implemented as a kernel module, initializes a FUSE-based AFS
client. FUSE (Filesystem in USErspace) is a Linux-only mechanism for providing
a file system through a purely user-space daemon without a kernel module
takes all of the same options as afsd
This command does not use the syntax conventions of the AFS command suites.
Provide the command name and all option names in full.
Before using the -shutdown
parameter, use the standard UNIX umount
command to unmount the AFS root directory (by convention, /afs
Linux, unloading the AFS kernel module and then loading it again before
restarting AFS after -shutdown
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. This does not apply to
Linux; it should be safe to restart the AFS client on Linux without rebooting.
In contrast to many client-server applications, not all communication is
initiated by the client. When the AFS client opens a file, it registers a
callback with the AFS 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 AFS client, including
all command-line utilities, the following UDP ports must be open on an
firewalls between the client and the server:
cachemanager 7001/udp (OpenAFS client. Arla uses 4711/udp)
kaserver 7004/udp (not needed with Kerberos v5)
reserved 7006/udp (for future use)
Clients will also need to be able to contact your Kerberos KDC to authenticate.
If you are using kaserver
, you need to allow inbound
and outbound UDP on ports >1024 (probably 1024<port<2048 would
suffice depending on the number of simultaneous klog
Be sure to set the UDP timeouts on the firewall to be at least twenty minutes
for the best callback performance.
was first introduced in OpenAFS 1.5.74. It is only available if
OpenAFS was built with the "--enable-fuse-client" configure switch.
It should be considered experimental.
- Enable afsdb support. This will use DNS to lookup the SRV
or AFSDB records and use that for the database servers for each cell
instead of the values in the CellServDB file. This has the
advantage of only needing to update one set of DNS records to reconfigure
the AFS 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 CellServDB. The format of SRV records is
defined in RFC 5864, and the AFSDB record format is in RFC 1183.
- Prefer backup volumes for mountpoints in backup volumes.
This option means that the AFS 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.
- -biods <number of I/O daemons>
- 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 -daemons argument are
omitted, the default is five. If this argument is omitted but the
-daemons argument is provided, the number of VM daemons is set to
twice the value of the -daemons argument.
- -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 /etc/openafs/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
-dcache argument, since doing so can possibly result in a chunk
size that is not an exponent of 2.
- -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
- -chunksize <chunk size>
- Sets the size of each cache chunk. The integer provided,
which must be from the range 0 to 30, 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 13 (8KB) for memory cache
and 18 to 20 (256 KB to 1MB) for disk cache. A value of 0 or less, or
greater than 30, sets chunk size to the appropriate default. Values less
than 10 (which sets chunk size to a 1 KB) are not recommended. Combining
this argument with the -dcache argument is not recommended because
it requires that the issuer calculate the cache size that results.
-chunksize is an important option when tuning for performance.
Setting this option to larger values can increase performance when dealing
with large files.
- -confdir <configuration directory>
- Names a directory other than the /etc/openafs
directory from which to fetch the cacheinfo, ThisCell, and
CellServDB configuration files.
- -daemons <number of daemons to
- 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 6 are not generally more effective than 6.
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 -biods argument is not. If both arguments are omitted, there
are five VM daemons.
- -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 Vn 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 -blocks argument, since doing so can possibly result in a
chunk size that is not an exponent of 2.
- Generates a highly detailed trace of the afsd
program's actions on the standard output stream. The information is useful
mostly for debugging purposes.
- The standard behaviour of the AFS client without the
-dynroot option is to mount the root.afs volume from the default
cell on the /afs path. The /afs folder and root.afs volume
traditionally shows the folders for ThisCell and other cells as
configured by the AFS cell administrator.
The -dynroot option changes this. Using this option, the AFS client
does not mount the root.afs volume on /afs. Instead it uses the
contents of the CellServDB file to populate the listing of cells in
/afs. This is known as a DYNamic ROOT. A cell is not contacted
until the path /afs/cellname if accessed. This
functions similarly to an automounter. The main advantage of using
-dynroot is that the AFS client will start properly even without
network access, whereas the client not using -dynroot will freeze
upon startup if cannot contact the default cell specified in
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 /afs will
usually be faster because the contents of /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
/afs by installing a stripped-down CellServDB file, and if
dynroot is in effect, the CellAlias file can be used to provide
shortname for common AFS cells which provides equivalent functionality to
the most commonly used symbolic links.
When the dynamic root ( -dynroot, -dynroot-sparse) and the
fake stat ( -fakestat, -fakestat-all) modes are in effect,
the cache manager provides a special directory named /afs/.:mount
which allows access to volumes by volume name or ID. The
/afs/.:mount directory appears to be empty, but any name in the
form of cell:volume will be resolved as a read-write mount
point to the specified volume. This dynamic mount feature is recommended
only for temporary access to a volume. Linux-based cache managers provide
this dynamic mount feature even when dynamic root ( -dynroot,
-dynroot-sparse) is not in effect.
- 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
- 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.
- 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.
- Return fake values for stat calls on cross-cell mounts.
This option makes an "ls -l" of /afs much faster since
each cell isn't contacted, and this and the -fakestat-all options
are useful on Mac OS X so that the Finder program doesn't try to contact
every AFS cell the system knows about.
Note that, for the purposes of -fakestat, local cellular mounts count
as "cross-cell" mounts. That is, if the local cell is
"localcell", a mount for "localcell:root.cell" will
count as a "cross-cell" mount and so stat calls for it will be
faked with -fakestat. In practice, local cellular mounts are rare
and generally discouraged, so this should not generally make a
- Return fake values for stat calls on all mounts, not just
cross-cell mounts. This and the -fakestat options are useful on Mac
OS X so that the Finder program doesn't hang when browsing AFS
- -files <files in cache>
- Specifies the number of Vn files to
create in the cache directory for a disk cache, overriding the default
that is calculated as described in "DESCRIPTION". Each
Vn 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
- -files_per_subdir <files per cache
- 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).
- Prints the online help for this command. All other valid
options are ignored.
- -logfile <log file location>
- This option is obsolete and no longer has any effect.
- -inumcalc <method>
- Specifies the method used by the Cache Manager to generate
inode numbers for files, directories, and symlinks in the AFS filesystem.
Valid methods are "compat" and "md5". The default
method is "compat".
When the "compat" method is in effect, the Cache Manager generates
inode numbers for a given inode by multiplying the AFS volume number by
65536, adding the result to the AFS vnode number, and finally truncating
the result to a signed 32 bit integer.
When the "md5" method is in effect, the Cache Manager generates
inode numbers for a given inode by calculating the MD5 digest of a
combination of the cell number, volume number, and vnode number. The
result is truncated to a signed 32 bit integer. The "md5" method
is computationally more expensive but greatly reduces the chance for inode
number collisions, especially when volumes from multiple cells are mounted
within the AFS filesystem.
- This option is obsolete and no longer has any effect.
- Initializes a memory cache rather than a disk cache. Do not
combine this flag with the -files argument.
- -mountdir <mount location>
- 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 /etc/openafs/cacheinfo file. If a value other
than the /afs directory is used, the machine cannot access the
filespace of cells that do use that value.
- Do not mount AFS on startup. The afs global mount must be
mounted via some other means. This is useful on Mac OS X where /afs is
sometimes mounted in /Network/afs like other network file systems.
- This option is obsolete and no longer has any effect. The
operating system provided time keeping services should be used to maintain
the system time.
- -prealloc <number of preallocated
- 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.
- 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.
- -rootvol <name of AFS root volume>
- Names the read/write volume corresponding to the root
directory for the AFS file tree (which is usually the /afs
directory). This value overrides the default of the "root.afs"
volume. This option is ignored if -dynroot is given.
- Bind the Rx socket (one interface only).
- -rxmaxfrags <max # of fragments>
- Set a limit for the maximum number of UDP fragments Rx will
send per Rx packet, and the maximum number of fragments Rx thinks it can
receive when advertising its receive size to peers. Practically speaking,
setting this option means that you will not see Rx data packets that are
broken into more than N fragments, where N is the value specified for this
option. Setting this option to 1 effectively prevents fragmentation, and
can be useful when dealing with networking equipment that does not
properly handle UDP fragments.
Note that this option just specifies a maximum. The actual number of
fragments seen on the wire may be less than what is specified, depending
on the configuration of the peer.
- -rxmaxmtu <value for maximum MTU>
- Set a limit for the largest maximum transfer unit (network
packet size) that the AFS 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 MTU from being transmitted
- -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 "rxdebug 127.0.0.1 -port 7001
-rxstats" command shows no free Rx packets. Increasing this value may
improve OpenAFS client performance in some circumstances.
- The -settime option is deprecated and should no
longer be specified. The operating system provided time keeping services
should be used to maintain the system time.
The -settime option enables the native AFS time synchronization. If
the -settime option is specified, then a randomly selected a file
server machine in the local cell is used 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.
- Shuts down the Cache Manager. Before calling afsd
with this option, unmount the AFS file system with umount.
- -splitcache <RW/RO Ratio>
- This allows the user to set a certain percentage of the AFS
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,
"-splitcache 75/25" devotes 75% of your cache space to
read/write content and 25% to read-only.
- -stat <number of stat entries>
- Specifies the number of entries to allocate in the
machine's memory for recording status information about the AFS 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.
- Generates a detailed trace of the afsd program's
actions on the standard output stream.
- -volumes <number of volume
- Specifies the number of memory structures to allocate for
storing volume location information. The default value is 200.
- By default, dynamic vcache overrides the -stat
option by using the value of -stat (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.
- 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 fs
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
The following command is appropriate when enabling a machine to act as an
NFS/AFS Translator machine serving more than five users.
% /etc/openafs/afsd -daemons 4 -rmtsys
The following command initializes a memory cache and sets chunk size to 16 KB
% /etc/openafs/afsd -memcache -chunksize 14
The issuer must be logged in as the local superuser root.
RFC 5864 <http://www.ietf.org/rfc/rfc5864.txt> RFC 1183
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
This documentation is covered by the IBM Public License Version 1.0. It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.