Provided by: openafs-client_1.4.9.dfsg1-0+ubuntu3_i386 bug

NAME

       afsd - Initializes the Cache Manager and starts related daemons

SYNOPSIS

       afsd [-afsdb] [-backuptree]
            [-biods <number of bkg I/O daemons (aix vm)>]
            [-blocks <1024 byte blocks in cache>]
            [-cachedir <cache directory>]
            [-chunksize <log(2) of chunk size>]
            [-confdir <configuration directory>]
            [-daemons <number of daemons to use>]
            [-dcache <number of dcache entries>] [-debug]
            [-dynroot] [-enable_peer_stats] [-enable_process_stats]
            [-fakestat] [-fakestat-all]
            [-files <files in cache>]
            [-files_per_subdir <log(2) of files per dir> ]
            [-help] [-logfile <Place to keep the CM log>]
            [-mem_alloc_sleep] [-memcache]
            [-mountdir <mount location>] [-nomount]
            [-nosettime]
            [-prealloc <number of ’small’ preallocated blocks>]
            [-rmtsys] [-rootvol <name of AFS root volume>]
            [-rxbind] [-rxpck value for rx_extraPackets ]
            [-settime] [-shutdown]
            [-splitcache <RW/RO ratio>]
            [-stat <number of stat entries>] [-verbose]
            [-volumes <number of volume entries>]
            [-waitclose]

DESCRIPTION

       The 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 afsd
       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 in it.

           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 AFSDB DNS 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 /afs.

       ·   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 disk.

       ·   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 file.

       ·   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 afsd 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
           failure.

           For a disk cache, use the -blocks argument to the afsd command to
           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 and -chunksize) 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 fs setcachesize 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 file
           transfer).

           For a disk cache, a chunk is a Vn 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 -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 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 (Vn files) is set to
           the largest of the following unless the -files argument is used to
           set the value explicitly:

           ·   100

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

           ·   The result of dividing cachesize by 10 KB (cachesize/10240)

       ·   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 size.

           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
           300; use the -stat argument to override the default.

       ·   If the -settime 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.

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

       ·   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 tasks:

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

           ·   Synchronizes files.

           ·   Refreshes information from read-only volumes once per hour.

           ·   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 necessary.

       ·   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 arguments:

           ·   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 daemons.

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

CAUTIONS

       Before using the -shutdown parameter, use the standard UNIX umount
       command to unmount the AFS root directory (by convention, /afs).  On
       Linux, unloading the AFS kernel module and then loading it again before
       restarting AFS after -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. 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:

          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

       Additionally, for klog to work through the firewall you need to allow
       inbound and outbound UDP on ports >1024 (probably 1024<port<2048 would
       suffice depending on the number of simultaneous klogs).

       Be sure to set the UDP timeouts on the firewall to be at least twenty
       minutes for the best callback performance.

OPTIONS

       -afsdb
           Enable afsdb support. This will use DNS to lookup the AFSDB record
           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 DNS record 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 AFSDB records is
           defined in RFC 1183.

       -backuptree
           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
           /etc/openafs/cacheinfo file.

       -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.
           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 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 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 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.

       -debug
           Generates a highly detailed trace of the afsd program’s actions on
           the standard output stream. The information is useful mostly for
           debugging purposes.

       -dynroot
           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.

       -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.

       -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.

       -fakestat
           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.

       -fakestat-all
           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
           directories.

       -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 -memcache argument.

       -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).

       -help
           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.

       -mem_alloc_sleep
           Allows sleeps when allocating a memory cache.

       -memcache
           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.

       -nomount
           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.

       -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 AFS
           Cache Manager, the Network Time Protocol Daemon should be used to
           synchronize the system time.

       -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 400, but
           the Cache Manager dynamically allocates more memory as it needs it.

       -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.

       -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.

       -rxbind
           Bind the Rx socket (one interface only).

       -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.

       -settime
           Enable native AFS time synchronization. This option is the opposite
           of -nosettime and cannot be used with the -nosettime option.

       -shutdown
           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.
           This value overrides the default of 300.

       -verbose
           Generates a detailed trace of the afsd program’s actions on the
           standard output stream.

       -volumes <number of volume entries>
           Specifies the number of memory structures to allocate for storing
           volume location information. The default value is 50.

       -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 fs
           storebehind command.

EXAMPLES

       The 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

          % /etc/openafs/afsd

       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 (2^14).

          % /etc/openafs/afsd -memcache -chunksize 14

PRIVILEGE REQUIRED

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

SEE ALSO

       fs_newcell(1), afs_cache(5), CellServDB(5), cacheinfo(5)

       RFC 1183 <http://www.faqs.org/rfcs/rfc1183.html>

COPYRIGHT

       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.