Provided by: openafs-client_1.6.1-1_amd64 bug

NAME

       afsd, afsd.fuse - 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] [-dynroot-sparse] [-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] [-rxmaxmtu value for maximum MTU ]
            [-rxpck value for rx_extraPackets ]
            [-settime] [-shutdown]
            [-splitcache <RW/RO ratio>]
            [-stat <number of stat entries>] [-verbose]
            [-disable-dynamic-vcaches]
            [-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.
       afsd.fuse is an experimental variant that initializes a FUSE-based Cache Manager instead
       of one based on a kernel module.

       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 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 /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.  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 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 based on the size of the cache. 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.

       afsd.fuse 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 component.  afsd.fuse 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.

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

       Clients will also need to be able to contact your Kerberos KDC to authenticate.  If you
       are using kaserver and klog, 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.

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

OPTIONS

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

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

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

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

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

       -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
           This option is obsolete and no longer has any effect.

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

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

       -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. If this value is not specified,
           the number of stat entires will be autotuned based on the size of the disk cache.

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

       -disable-dynamic-vcaches
           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.

       -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 5864 <http://www.ietf.org/rfc/rfc5864.txt> RFC 1183
       <http://www.ietf.org/rfc/rfc1183.txt>

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.