NAME

afsd, afsd.fuse - Initializes the Cache Manager and starts related daemons

SYNOPSIS

afsd [-afsdb [<true/false>]] [-backuptree [<true/false>]] [-biods <number of bkg I/O daemons (aix vm)>] [-blocks <1024 byte blocks in cache>] [-cachedir <cache directory>] [-chunksize <log(2) of chunk size>] [-config <configuration file>] [-daemons <number of daemons to use>] [-dcache <number of dcache entries>] [-debug] [-dynroot [<true/false/all>]] [-enable_peer_stats] [-enable_process_stats] [-fakestat [<true/false/all>]] [-files <files in cache>] [-files_per_subdir <log(2) of files per dir> ] [-help] [-keytab <path to keytab for system tokens>] [-principal <keytab principal for system tokens>] [-logfile <Place to keep the CM log>] [-mem_alloc_sleep] [-memcache] [-mountdir <mount location>] [-mountopts <mount options>] [-exportnfs] [-nomount] [-postscript <path to script>] [-rmtsys] [-rootvol <name of AFS root volume>] [-rxbind] [-rxmaxmtu value for maximum MTU ] -rxwindow <maximum window size in packets>] [-rxpck value for rx_extraPackets ] [-shutdown] [-splitcache <RW/RO ratio>] [-stat <number of stat entries>] [-verbose] [-dynamic-vcaches [<true/false>]] [-volumes <number of volume entries>] [-rxmaxfrags <max # of fragments>] [-discovery]

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:

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

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 state changes, the server notifies the client and all cached state information is discarded. In order to enable full functionality on the AFS client, including all command-line utilities, the following UDP ports must be open on all firewalls between the client and the server:

   fileserver      7000/udp
   cachemanager    7001/udp     (default, but can be any unused port)
   ptserver        7002/udp
   vlserver        7003/udp
   volserver       7005/udp
   bosserver       7007/udp

However, the cache manager only contacts the fileserver and vlserver.

Clients must be able to contact your Kerberos KDC to authenticate. The standard Kerberos ports are:

   kerberos        88/udp and 88/tcp
   kerberos-adm    749/tcp

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

OPTIONS

-afsdb [<true/false>]

Enabling DNS 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 yfs-client.conf. The format of SRV records is defined in RFC 5864, and the AFSDB record format is in RFC 1183.

When this feature is enabled (with true), the client will rely on the use_dns setting for each cell. See the use_dns section of yfs-client.conf(5) for more information.

When this feature is disabled (with false), the client will avoid using DNS to lookup the location servers and protection servers for all cells.

The default setting is true.

-backuptree [<true/false>]

When this feature is enabled, the client will prefer backup volumes for mountpoints in backup volumes. This option means that the 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 behavior of preferring read-only volumes over read-write volumes when the parent volume is a read-only volume.

This behavior is enabled by default.

-biods <number of I/O daemons> (AIX only)

Specify an integer greater than or equal to 5.

This option determines 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 value and the daemons value are omitted, the default is 8. If this value is omitted but the daemons argument is provided, the number of VM daemons is set to twice the value of the daemons value.

-blocks <blocks in cache>

Specify an integer 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). 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 setting with the dcache setting, since doing so can possibly result in a chunk size that is not an exponent of 2.

The defaults value is 100000 1 KB blocks.

-cachedir <cache directory>

Specify the full filesystem path to a cache directory. It is recommended but not required that the specified path refer to a filesystem dedicated for use as the AuriStorFS cache.

Defaults to /Library/Application Support/com.auristor.afsd/cache.

-chunksize <chunk size>

Specify an integer from the range 0 to 30.

This specifies the size of each cache chunk. The chunksize parameter 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 setting with the dcache setting 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.

-config <configuration file>

The location of the configuration file to be used. The default name is yfs-client.conf and the default location is /etc/yfs.

-daemons <number of daemons to use>

Specify an integer number of background daemons to execute in the cache manager. These daemons improve efficiency by doing prefetching and background writing of saved data. Values greater than 6 are not generally more effective than 6.

The default setting is 2, which is adequate for a machine serving up to five users.

On AIX machines with integrated virtual memory (VM), the number of VM daemons is set to twice this value, if it is provided and the biods value is not. If both arguments are omitted, there are 8 VM daemons.

-dcache <number of dcache entries>

Specify an integer 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 setting 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 setting with the blocks setting, since doing so can possibly result in a chunk size that is not an exponent of 2.

-debug [<true/false>]

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

The default is false.

-dynamic-vcaches [<true/false>] (Linux only)

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. If set to false, the client will disable this new functionality and honor the stat setting.

This setting is only effective on Linux.

The default is true.

-discovery [<true/false>]

If set to true, the client will use mDNS/DNS-SD Zeroconf to add cells announced on the local network and associated servers to the kernel's internal table of cells.

The default is false.

-dynroot [<true/false/all>]

The behaviour of the AFS client when the -dynroot option is set to false 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 the local cell and other cells as configured by the AFS cell administrator.

With the default -dynroot true setting, the AFS client does not mount the root.afs volume on /afs. Instead it uses the local cell and other cells explicitly marked to be shown to populate the listing of cells in /afs. Cells other than these cells are not shown by default until a lookup occurs. Cell aliases are shown as normal, although they may appear to be dangling links until traversed.

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

When -dynroot all is specified, all cells listed in the local configuration are shown.

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 yfs-client.conf 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.

The default setting is true.

dynroot-fake <list of file names>

When -dynroot is enabled, this setting specifies a list of file names that are created as fake entries in the dynamic root directory.

The default is an empty list.

This setting must be configured in yfs-client.conf(5).

endpoint-priorities subsection

This afsd subsection of yfs-client.conf(5) contains a list of network and priority specifications, in the form

    endpoint-priorities = {
        10.0.0.0/8 = 20000
        10.10.10.10 = 30000
        server.your-cell-name.com = 10000
    }

The network specification may be an IPv4 address, IPv6 address, hostname or CIDR style network range specification. The priority is an integer, with the same meaning as the server ranks passed to fs_setserverprefs(1).

The default setting is to have no server priority information.

This setting must be configured in yfs-client.conf(5).

-enable-peer-stats [<true/false>]

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 [<true/false>]

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.

-exportnfs [<true/false>] (Linux only)

Enable exporting paths under /afs over nfs. Note that if this setting is enabled then fakestat is disabled.

The default setting is false.

-fakestat [<true/false/all>]

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 option is useful on Mac OS X so that the Finder program doesn't try to contact every AFS cell the system knows about. This option is enabled (true) by default.

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.

Choosing -fakestat all returns fake values for stat calls on all mounts, not just cross-cell mounts.

The -fakestat setting will be forced to false if -exportnfs is on, as it can interfere with the nfs server's path reconnection logic and result in stale file handle errors on the nfs clients.

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

ignorelist-afsmountdir <list of file names>

Do not perform filename lookups in the root of the AFS mount; Instead act as if an empty file by the name specified exists.

This setting must be configured in yfs-client.conf(5).

ignorelist-dns <list of cell names>

The cache manager will not perform on-demand resolution a cell's location servers for any cell that matches a name in this list.

This setting must be configured in yfs-client.conf(5).

ignorelist-volroot <list of filenames>

Do not perform filename lookups in the root of a volume for names in this list. This is used to preclude crossing mountpoints when for instance a graphical environment may be looking for context about entries across an entire directory.

This setting is ignored if -fakestat is disabled.

This setting must be configured in yfs-client.conf(5).

ignorelist-volrootprefix <list of file names>

Do not perform filename lookups in the root of a volume for names beginning with strings in this list. This is used to preclude crossing mountpoints when for instance a graphical environment may be looking for context about entries across an entire directory.

This setting is ignored if -fakestat is disabled.

This setting must be configured in yfs-client.conf(5).

-keytab <path to keytab file for system tokens>

Specify the full path to a keytab file containing a key or a Kerberos principal for which the cache manager will maintain authentication at all times. If -principal is not specified, then the first entry in the keytab file is used. This principal may match a PTS entry of type machine as created with pts_createuser(1).

When the cache manager is keyed with a cache manager identity, the cache manager tokens will be combined with the user tokens. The combined keys protect against cache poisoning attacks, and provide integrity protection and wire privacy for users without tokens. Combined identity lists can be used to grant rights via multi-factor access control entities. (See auristorfs_acls(7).)

-launchd [<true/false>] (MacOS X only)

If enabled on Mac OS X, afsd will stay in the foreground and not daemonize. Enable this setting if you are starting the client using Mac OS X's launchd service.

The default setting is false.

-memcache [<true/false>]

When enabled, the cache manager initializes a memory cache rather than a disk cache. Do not combine this flag with the -files argument.

modpath (MacOS X only)

Specify the full filesystem path to the kernel module.

This setting must be configured in yfs-client.conf(5).

-mountdir <mount location>

Specifies the full filesystem path to a mount point location.

Names the local disk directory on which to mount the root of the AuriStor File System file namespace.

The default is /afs.

-mountopts <mount options> (Linux only)

This setting allows specifying mount options as would be specified with mount -o. Typically this will not be used, but for Linux, SELinux context may be specified with a mountopts of

  context=SELinux context string

For example,

  context=unconfined_u:object_r:user_home_t:s0

On Linux, if this field is not set, the default is

  context=system_u:object_r:nfs_t:s0

This setting is ignored by afsd.fuse or if SELinux is disabled.

-nomount [<true/false>]

If true, the cache manager will 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.

The default is false.

This setting is ignored by afsd.fuse.

-principal <keytab principal to use for system tokens>

Specifies the Kerberos v5 principal name to use when selecting a keytab entry from the keytab file. If -principal is not specified, then the principal associated with the first entry in the keytab file is used as the system token authentication identity.

-postscript <path to script>

Specify the full filesystem path to a script. This script can be used to do such things as set preferences with fs setserverprefs or enable debug logging with fstrace.

This setting is ignored by afsd.fuse.

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

-rxbind [<true/false>]

Bind the Rx socket if only a single interface remains after applying the netinfo and netrestrict configuration from yfs-client.conf(5).

The default is false.

-rxmaxmtu <bytes>

Specify the maximum transmission unit (MTU) value. The value must be between the minimum (520) and maximum (16384) Rx packet sizes.

It artificially limits the maximum Rx data packet size that will be transmitted. It can be used when the maximum size that can be successfully transmitted is smaller than the reported network interface MTU.

-rxpck <number of extra Rx packet structures>

This sets the number of extra Rx packets that should be allocated at startup to handle Rx calls. This setting is not required as Rx packets are allocated on demand.

The default is not to allocate extra Rx packets at startup.

-rxwindow <packets>

Specify the maximum sliding window size that RX may use on the wire. Larger windows improve performance on networks with a high latency, at the expense of higher memory usage. The value specified must be less than the maximum RX window size of 65535.

The default rx window for the cache manager is 512 packets.

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

-token-levels <security levels list>

The token-levels setting can be used to specify security levels to be used when acquiring tokens for the cache manager identity. If specified, the specified security levels will override those specified in any [defaults] token-security-levels subsection.

-verbose [<true/false>]

If enabled, a detailed trace of the afsd program's actions will be generated on the standard output stream.

The default is false.

-volumes <number of volume entries>

Specifies the number of memory structures to allocate for storing volume location information. The default value is 200.

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

   % /Library/Auristor/Tools/sbin/afsd

The following command is appropriate when enabling a machine to act as an NFS/AFS Translator machine serving more than five users.

   % /Library/Auristor/Tools/sbin/afsd -daemons 4 -rmtsys

The following command initializes a memory cache and sets chunk size to 16 KB (2^14).

   % /Library/Auristor/Tools/sbin/afsd -memcache -chunksize 14

The following command sets an SELinux context on a mountpoint.

   % /Library/Auristor/Tools/sbin/afsd -mountopts "context=unconfined_u:object_r:user_home_t:s0"

PRIVILEGE REQUIRED

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

SEE ALSO

fs_newcell(1), afs_cache(5), yfs-client.conf(5), auristorfs_linux_exportnfs(7)

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.

ACKNOWLEDGEMENTS

"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.