=head1 NAME afsd, afsd.fuse - Initializes the Cache Manager and starts related daemons =head1 SYNOPSIS =for html
B [B<-afsdb>] [B<-backuptree>] S<<< [B<-biods> >] >>> S<<< [B<-blocks> >] >>> S<<< [B<-cachedir> >] >>> S<<< [B<-chunksize> >] >>> S<<< [B<-confdir> >] >>> S<<< [B<-daemons> >] >>> S<<< [B<-dcache> >] >>> [B<-debug>] [B<-dynroot>] [B<-dynroot-sparse>] [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-fakestat>] [B<-fakestat-all>] S<<< [B<-files> >] >>> S<<< [B<-files_per_subdir> > ] >>> [B<-help>] S<<< [B<-logfile> >] >>> S<<< [B<-inumcalc>] > >>> [B<-mem_alloc_sleep>] [B<-memcache>] S<<< [B<-mountdir> >] >>> [B<-nomount>] [B<-nosettime>] S<<< [B<-prealloc> >] >>> [B<-rmtsys>] S<<< [B<-rootvol> >] >>> [B<-rxbind>] S<<< [B<-rxmaxmtu> value for maximum MTU ] >>> S<<< [B<-rxpck> value for rx_extraPackets ] >>> [B<-settime>] [B<-shutdown>] S<<< [B<-splitcache> >] >>> S<<< [B<-stat> >] >>> [B<-verbose>] [B<-disable-dynamic-vcaches>] S<<< [B<-volumes> >] >>> [B<-waitclose>] [B<-rxmaxfrags> >] S<<< [B<-volume-ttl> >] >>> =for html
=head1 DESCRIPTION The B command initializes the Cache Manager on an AFS client machine by transferring AFS-related configuration information into kernel memory and starting several daemons. B is an experimental variant that initializes a FUSE-based Cache Manager instead of one based on a kernel module. The B command performs the following actions: =over 4 =item * Sets a field in kernel memory that defines the machine's cell membership. Some Cache Manager-internal operations and system calls consult this field to learn which cell to execute in. (The AFS command interpreters refer to the F file instead.) This information is transferred into the kernel from the F file and cannot be changed until the B program runs again. =item * Places in kernel memory the names and Internet addresses of the database server machines in the local cell and (optionally) foreign cells. The appearance of a cell's database server machines in this list enables the Cache Manager to contact them and to access files in the cell. Omission of a cell from this list, or incorrect information about its database server machines, prevents the Cache Manager from accessing files in it. By default, the list of database server machines is transferred into the kernel from the F file. Alternatively, when the B<-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 B command to change the kernel-resident list without having to reboot. =item * Mounts the root of the AFS filespace on a directory on the machine's local disk, according to either the first field in the F file (the default) or the B command's B<-mountdir> argument. The conventional value is F. =item * Determines which volume to mount at the root of the AFS file tree. The default is the volume C; use the B<-rootvol> argument to override it. Although the base (read/write) form of the volume name is the appropriate value, the Cache Manager has a bias for accessing the read-only version of the volume (by convention, C) if it is available. =item * Configures the cache on disk (the default) or in machine memory if the B<-memcache> argument is provided. In the latter case, the B program allocates space in machine memory for caching, and the Cache Manager uses no disk space for caching even if the machine has a disk. =item * Defines the name of the local disk directory devoted to caching, when the B<-memcache> argument is not used. If necessary, the B 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 F file is the source for this name. The standard value is F. Use the B<-cachedir> argument to override the value in the B file. =item * Sets the size of the cache. The default source for the value is the third field in the F file, which specifies a number of kilobytes. For a memory cache, the following arguments to the afsd command override the value in the B file: =over 4 =item * The B<-blocks> argument, to specify a different number of kilobyte blocks. =item * The B<-dcache> and B<-chunksize> arguments together, to set both the number of dcache entries and the chunk size (see below for definition of these parameters). In this case, the B program derives cache size by multiplying the two values. Using this combination is not recommended, as it requires the issuer to perform the calculation beforehand to determine the resulting cache size. =item * The B<-dcache> argument by itself. In this case, the B program derives cache size by multiplying the value specified by the B<-dcache> argument by the default memory cache chunk size of eight kilobytes. Using this argument is not recommended, as it requires the issuer to perform the calculation beforehand to determine the resulting cache size. =back For satisfactory memory cache performance, the specified value must leave enough memory free to accommodate all other processes and commands that can run on the machine. If the value exceeds the amount of memory available, the B program exits without initializing the Cache Manager and produces the following message on the standard output stream: afsd: memCache allocation failure at KB where is how many kilobytes were allocated just before the failure. For a disk cache, use the B<-blocks> argument to the B command to override the value in the B file. The value specified in either way sets an absolute upper limit on cache size; values provided for other arguments (such as B<-dcache> and B<-chunksize>) never result in a larger cache. The B 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 B command; the setting persists until the B command runs again or the B command is reissued. The B command does not work for memory caches. =item * Sets the size of each cache I, 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 F> 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 B<-chunksize> argument to provide an integer to be used as an exponent of two; see L for details. For a memory cache, if total cache size divided by chunk size leaves a remainder, the B program rounds down the number of dcache entries, resulting in a slightly smaller cache. =item * Sets the number of chunks in the cache. For a memory cache, the number of chunks is equal to the cache size divided by the chunk size. For a disk cache, the number of chunks (F> files) is set to the largest of the following unless the B<-files> argument is used to set the value explicitly: =over 4 =item * 100 =item * 1.5 times the result of dividing cache size by chunk size (I/I * 1.5) =item * The result of dividing cachesize by 10 KB (I/10240) =back =item * Sets the number of I allocated in machine memory for storing information about the chunks in the cache. For a disk cache, the F file contains one entry for each F> 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 F 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 B program derives it by dividing the cache size by the chunk size. To set the number of dcache entries, use the B<-dcache> argument; the specified value can exceed the default limit of 2,000. Using this argument is not recommended for either type of cache. Increasing the number of dcache entries for a disk cache sometimes improves performance (because more entries are retrieved from memory rather than from disk), but only marginally. Using this argument for a memory cache requires the issuer to calculate the cache size by multiplying this value by the chunk size. =item * Sets the number of I 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 B<-stat> argument to override the default. =back In addition to setting cache configuration parameters, the B program starts the following daemons. (On most system types, these daemons appear as nameless entries in the output of the UNIX B command.) =over 4 =item * One I daemon, which handles callbacks. It also responds to the File Server's periodic probes, which check that the client machine is still alive. =item * One I daemon, which performs the following tasks: =over 4 =item * Garbage collects obsolete data (for example, expired tokens) from kernel memory. =item * Synchronizes files. =item * Refreshes information from read-only volumes once per hour. =item * Does delayed writes for NFS clients if the machine is running the NFS/AFS Translator. =back =item * One I daemon, which flushes the cache when free space is required, by writing cached data and status information to the File Server. =item * One I daemon, which sends a probe to the File Server every few minutes to check that it is still accessible. =item * One or more I daemons that improve performance by pre-fetching files and performing background (delayed) writes of saved data into AFS. The default number of background daemons is two, enough to service at least five simultaneous users of the machine. To increase the number, use the B<-daemons> argument. A value greater than six is not generally necessary. =item * On some system types, one I daemon, which listens for incoming RPCs. =item * On some system types, one I daemon, which reviews the Rx system's queue of tasks and performs them as appropriate. Most items in the queue are retransmissions of failed packets. =item * On machines that run AIX with virtual memory (VM) integration, one or more I daemons (sometimes called I daemons, which transfer data between disk and machine memory. The number of them depends on the setting of the B<-biods> and B<-daemons> arguments: =over 4 =item * If the B<-biods> argument is used, it sets the number of VM daemons. =item * If only the B<-daemons> argument is used, the number of VM daemons is twice the number of background daemons. =item * If neither argument is used, there are five VM daemons. =back =back B is a variant of B 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. B takes all of the same options as B. This command does not use the syntax conventions of the AFS command suites. Provide the command name and all option names in full. =head1 CAUTIONS Before using the B<-shutdown> parameter, use the standard UNIX B command to unmount the AFS root directory (by convention, F). On Linux, unloading the AFS kernel module and then loading it again before restarting AFS after B<-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 B and B, you need to allow inbound and outbound UDP on ports >1024 (probably 1024s). Be sure to set the UDP timeouts on the firewall to be at least twenty minutes for the best callback performance. B was first introduced in OpenAFS 1.5.74. It is only available if OpenAFS was built with the C<--enable-fuse-client> configure switch. It should be considered experimental. =head1 OPTIONS =over 4 =item B<-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 F 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 F. The format of SRV records is defined in RFC 5864, and the AFSDB record format is in RFC 1183. =item B<-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. =item B<-biods> > Sets the number of VM daemons dedicated to performing I/O operations on a machine running a version of AIX with virtual memory (VM) integration. If both this argument and the B<-daemons> argument are omitted, the default is five. If this argument is omitted but the B<-daemons> argument is provided, the number of VM daemons is set to twice the value of the B<-daemons> argument. =item B<-blocks> > Specifies the number of kilobyte blocks to be made available for caching in the machine's cache directory (for a disk cache) or memory (for a memory cache), overriding the default defined in the third field of the F file. For a disk cache, the value cannot exceed 95% of the space available in the cache partition. If using a memory cache, do not combine this argument with the B<-dcache> argument, since doing so can possibly result in a chunk size that is not an exponent of 2. =item B<-cachedir> > Names the local disk directory to be used as the cache. This value overrides the default defined in the second field of the F file. =item B<-chunksize> > Sets the size of each cache chunk. The integer provided, which must be from the range C<0> to C<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 C<13> (8KB) for memory cache and C<18> to C<20> (256 KB to 1MB) for disk cache. A value of C<0> or less, or greater than C<30>, sets chunk size to the appropriate default. Values less than C<10> (which sets chunk size to a 1 KB) are not recommended. Combining this argument with the B<-dcache> argument is not recommended because it requires that the issuer calculate the cache size that results. B<-chunksize> is an important option when tuning for performance. Setting this option to larger values can increase performance when dealing with large files. =item B<-confdir> > Names a directory other than the F directory from which to fetch the F, F, and F configuration files. =item B<-daemons> > Specifies the number of background daemons to run on the machine. These daemons improve efficiency by doing prefetching and background writing of saved data. This value overrides the default of C<2>, which is adequate for a machine serving up to five users. Values greater than C<6> are not generally more effective than C<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 B<-biods> argument is not. If both arguments are omitted, there are five VM daemons. =item B<-dcache> > Sets the number of dcache entries in memory, which are used to store information about cache chunks. For a disk cache, this overrides the default, which is 50% of the number of F> files (cache chunks). For a memory cache, this argument effectively sets the number of cache chunks, but its use is not recommended, because it requires the issuer to calculate the resulting total cache size (derived by multiplying this value by the chunk size). Do not combine this argument with the B<-blocks> argument, since doing so can possibly result in a chunk size that is not an exponent of 2. =item B<-debug> Generates a highly detailed trace of the B program's actions on the standard output stream. The information is useful mostly for debugging purposes. =item B<-dynroot> The standard behaviour of the AFS client without the B<-dynroot> option is to mount the root.afs volume from the default cell on the F path. The F folder and root.afs volume traditionally shows the folders for F and other cells as configured by the AFS cell administrator. The B<-dynroot> option changes this. Using this option, the AFS client does not mount the root.afs volume on F. Instead it uses the contents of the F file to populate the listing of cells in F. This is known as a DYNamic ROOT. A cell is not contacted until the path F> if accessed. This functions similarly to an automounter. The main advantage of using B<-dynroot> is that the AFS client will start properly even without network access, whereas the client not using B<-dynroot> will freeze upon startup if cannot contact the default cell specified in F 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 F will usually be faster because the contents of F 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 F by installing a stripped-down F file, and if dynroot is in effect, the F 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 (B<-dynroot>, B<-dynroot-sparse>) and the fake stat (B<-fakestat>, B<-fakestat-all>) modes are in effect, the cache manager provides a special directory named F which allows access to volumes by volume name or ID. The F directory appears to be empty, but any name in the form of I:I will be resolved as a read-write mount point to the specified volume. For example, the I volume in the I cell would be accessible at the following path: F. 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 (B<-dynroot>, B<-dynroot-sparse>) is not in effect. =item B<-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. =item B<-enable_peer_stats> Activates the collection of Rx statistics and allocates memory for their storage. For each connection with a specific UDP port on another machine, a separate record is kept for each type of RPC (FetchFile, GetStatus, and so on) sent or received. To display or otherwise access the records, use the Rx Monitoring API. =item B<-enable_process_stats> Activates the collection of Rx statistics and allocates memory for their storage. A separate record is kept for each type of RPC (FetchFile, GetStatus, and so on) sent or received, aggregated over all connections to other machines. To display or otherwise access the records, use the Rx Monitoring API. =item B<-fakestat> Return fake values for stat calls on cross-cell mounts. This option makes an C of F much faster since each cell isn't contacted, and this and the B<-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 B<-fakestat>, local cellular mounts count as "cross-cell" mounts. That is, if the local cell is C, a mount for C will count as a "cross-cell" mount and so stat calls for it will be faked with B<-fakestat>. In practice, local cellular mounts are rare and generally discouraged, so this should not generally make a difference. =item B<-fakestat-all> Return fake values for stat calls on all mounts, not just cross-cell mounts. This and the B<-fakestat> options are useful on Mac OS X so that the Finder program doesn't hang when browsing AFS directories. =item B<-files> > Specifies the number of F> files to create in the cache directory for a disk cache, overriding the default that is calculated as described in L. Each F> file accommodates a chunk of data, and can grow to a maximum size of 64 KB by default. Do not combine this argument with the B<-memcache> argument. =item B<-files_per_subdir> > 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). =item B<-help> Prints the online help for this command. All other valid options are ignored. =item B<-logfile> > This option is obsolete and no longer has any effect. =item B<-inumcalc> > Specifies the method used by the Cache Manager to generate inode numbers for files, directories, and symlinks in the AFS filesystem. Valid methods are C and C. The default method is C. When the C 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 C 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 C 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. =item B<-mem_alloc_sleep> This option is obsolete and no longer has any effect. =item B<-memcache> Initializes a memory cache rather than a disk cache. Do not combine this flag with the B<-files> argument. =item B<-mountdir> > Names the local disk directory on which to mount the root of the AFS filespace. This value overrides the default defined in the first field of the F file. If a value other than the F directory is used, the machine cannot access the filespace of cells that do use that value. =item B<-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. =item B<-nosettime> This option is obsolete and no longer has any effect. The operating system provided time keeping daemons should be used to maintain the system time. =item B<-prealloc> > Specifies the number of pieces of memory to preallocate for the Cache Manager's internal use. The default initial value is C<400>, but the Cache Manager dynamically allocates more memory as it needs it. =item B<-rmtsys> Initializes an additional daemon to execute AFS-specific system calls on behalf of NFS client machines. Use this flag only if the machine is an NFS/AFS translator machine serving users of NFS client machines who execute AFS commands. =item B<-rootvol> > Names the read/write volume corresponding to the root directory for the AFS file tree (which is usually the F directory). This value overrides the default of the C volume. This option is ignored if B<-dynroot> is given. =item B<-rxbind> Bind the Rx socket (one interface only). =item B<-rxmaxfrags> > 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. =item B<-rxmaxmtu> > 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. =item B<-rxpck> > 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. =item B<-settime> This option is obsolete and no longer has any effect. The operating system provided time keeping daemons should be used to maintain the system time. =item B<-shutdown> Shuts down the Cache Manager. Before calling B with this option, unmount the AFS file system with B. =item B<-splitcache> > 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, C<-splitcache 75/25> devotes 75% of your cache space to read/write content and 25% to read-only. =item B<-stat> > Specifies the number of entries to allocate in the machine's memory for recording status information about the AFS files in the cache. If this value is not specified, the number of stat entires will be autotuned based on the size of the disk cache. =item B<-verbose> Generates a detailed trace of the B program's actions on the standard output stream. =item B<-volumes> > Specifies the number of memory structures to allocate for storing volume location information. The default value is C<200>. =item B<-disable-dynamic-vcaches> By default, dynamic vcache overrides the B<-stat> option by using the value of B<-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. =item B<-waitclose> Has no effect on the operation of the Cache Manager. The behavior it affected in previous versions of the Cache Manager, to perform synchronous writes to the File Server, is now the default behavior. To perform asynchronous writes in certain cases, use the B command. =item B<-volume-ttl> Specifies the maximum amount of time the Cache Manager will cache volume information retrieved from VL Servers. By default, the Cache Manager will cache read-only volume information as long as a volume callback is held for that volume. The callback may be held as long as files in the read-only volume are being accessed, with no upper limit. For read/write volumes, by default the Cache Manager will cache volume information forever, until a fileserver returns a volume-level error in response to accessing files in that volume. Use the B<-volume-ttl> option to specify the maximum amount of time in seconds that volume information will be cached, regardless of connectivity to the fileservers. Lowering this value can make the Cache Manager recover more quickly from certain volume/fileserver errors, but will increase the load on the VL Servers for contacted cells. A typical value is 7200 seconds (2 hours), which is the same as the default callback duration for read-only volumes. The minimum valid value is 600 seconds (10 minutes). =back =head1 EXAMPLES The B command is normally included in the machine's AFS initialization file, rather than typed at the command shell prompt. For most disk caches, the appropriate form is % /usr/vice/etc/afsd The following command is appropriate when enabling a machine to act as an NFS/AFS Translator machine serving more than five users. % /usr/vice/etc/afsd -daemons 4 -rmtsys The following command initializes a memory cache and sets chunk size to 16 KB (2^14). % /usr/vice/etc/afsd -memcache -chunksize 14 =head1 PRIVILEGE REQUIRED The issuer must be logged in as the local superuser root. =head1 SEE ALSO L, L, L, L RFC 5864 L RFC 1183 L =head1 COPYRIGHT IBM Corporation 2000. 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.