NAME

yfs-client.conf - AuriStor File System client configuration file

DESCRIPTION

The yfs-client.conf file contains client configuration information. This includes the locations of the servers that run the protection server and location server (the ptserver and vlserver) processes which maintain a cell's administrative databases.

Additionally the yfs-client.conf file contains global settings for the client. The global settings include the name of the default cell, whether to use DNS for cell server lookups, the client IP addresses to advertise to servers, and other settings.

STRUCTURE

The yfs-client.conf file syntax is in the Kerberos 5 configuration file, krb5.conf, style. Sections begin with a section name enclosed with square braces ([)(]), one section per line. For example:

    [defaults]

would introduce the "defaults" section.

Individual settings are listed below each section header, of the form:

    [defaults]
        thiscell = your-cell-name.com

or

    [cells]
        your-cell-name.com = {
            description = "My test cell"
        }

You can include other configuration files using the include or includedir directives at the beginning of the file. Included files must start with a section identifier and use an absolute path. For example:

    include /path/to/cellservdb.conf

If, for example, the included cellservdb.conf contains a [cells] section, AuriStor File System will combine that data with the [cells] section in the main file.

SECTIONS

The yfs-client.conf file may contain three sections, [afsd], [defaults], or [cells]. The [afsd] section defines settings for the Cache Manager and is only applicable on UNIX-style operating systems. The [defaults] section defines universal settings for a client. The [cells] section defines the information for each individual cell.

[afsd]

The [afsd] section may contain the following settings:

afsdb

Specify yes or no.

When this feature is enabled (with yes), the client will rely on the use_dns setting for each cell. See the "use_dns" section for more information.

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

The default setting is yes.

backuptree

Specify yes or no.

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.

The default setting is yes.

blacklist-afsmountdir

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

blacklist-dns

Do not perform DNS lookups for AFSDB or SRV records of a cell with this name.

blacklist-volroot

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.

blacklist-volrootprefix

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.

blocks

Specify an integer.

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

cachedir

Specify the full filesystem path to a cache directory.

chunksize

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.

daemons

Specify an integer.

This setting tells the client how many background daemons to run. 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.

dcache

Specify an integer.

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

Specify yes or no.

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

dynamic-vcaches

Specify yes or no.

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

This setting is only effective on Linux.

The default is yes.

discovery

Specify yes or no.

If set to yes, 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 no.

dynroot

Specify yes, or no, or all.

When the dynroot option is set to no, the client mounts 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 cell administrator.

With the default yes setting, the client does not mount the root.afs volume on /afs. Instead it uses the contents of the [cells] section to populate the listing of cells in /afs. This is known as a DYNamic ROOT. The client does not contact a cell until the user accesses the path /afs/cellname. This functions similarly to an automounter. The main advantage of using dynroot is that the 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.

When set to yes, cells other than the local cell are not shown by default until a lookup occurs. Cell aliases as set in the [cells] section are shown as normal, although they may appear to be dangling links until traversed. When set to all, dynroot behaves the same way as yes, except that the client will immediately show every cell in the [cells] section without waiting for a lookup.

Two advantages of not using dynroot are that listing /afs will usually be faster because the contents of /afs are limited to what the cell administrator decides and that symbolic links are traditionally created by the cell administrator to provide a short name for the cell (i.e. cellname.example.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 alias settings can be used to provide shortname for common cells which provides equivalent functionality to the most commonly used symbolic links.

When the dynamic root (dynroot is set to yes or all) and the fake stat (fakestat, fakestat-all) modes are in effect, the Cache Manager provides a special directory named /afs/.:mount which allows access to volumes by volume name or ID. The /afs/.:mount directory appears to be empty, but any name in the form of cell:volume will be resolved as a read-write mount point to the specified volume. For example, the user.jdoe volume in the your-cell-name.com cell would be accessible at the following path: /afs/.:mount/your-cell-name.com:user.jdoe. This dynamic mount feature is recommended only for temporary access to a volume. Linux-based Cache Managers provide this dynamic mount feature even when dynamic root (dynroot) is not in effect.

The default setting is yes.

fakestat

Specify yes or no.

If set to yes, the client will 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. This option and the fakestat-all option are useful on Mac OS X so that the Finder program doesn't try to contact every 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 your-cell-name.com, a mount for your-cell-name.com: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.

The default setting is yes.

fakestat-all

Specify yes or no.

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 AuriStor File System directories.

The default setting is no.

files

Specify an integer.

This is the number of Vn files to create in the cache directory for a disk cache. This overrides the default that the client calculates as described in the DESCRIPTION section of afsd(8). Each Vn file accommodates a chunk of data, and can grow to a maximum size of 64 KB by default. Do not combine this setting with the memcache setting.

files_per_subdir

Specify an integer.

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

launchd

Specify yes or no. If set to yes 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 no.

memcache

Specify yes or no.

When set to yes, the client initializes a memory cache rather than a disk cache. Do not combine this setting with the files setting.

The default is no.

modpath

Specify the full filesystem path to the kernel module. This setting is only available on Mac OS X.

mountdir

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

nomount

Specify yes or no.

If set to yes, the client 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 no.

prealloc

Specify an integer (the number of preallocated blocks).

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

rootvol

Specify the name of the AFS root volume.

This setting names the read/write volume corresponding to the root directory for the AFS file tree (which is usually the /afs directory). This option is ignored if unless dynroot is set to no.

The default is root.afs.

rxbind

Specify yes or no.

Bind the Rx socket (one interface only).

The default is no.

rxmaxfrags

Specify an integer (the maximum number of fragments).

This setting limits the maximum number of UDP fragments Rx will send per Rx packet, and the maximum number of fragments Rx thinks it can receive when advertising its receive size to peers. Practically speaking, setting this option means that you will not see Rx data packets that are broken into more than N fragments, where N is the value specified for this option. Setting this option to 1 effectively prevents fragmentation, and can be useful when dealing with networking equipment that does not properly handle UDP fragments.

Note that this option just specifies a maximum. The actual number of fragments seen on the wire may be less than what is specified, depending on the configuration of the peer.

rxmaxmtu

Specify an integer (the value for maximum MTU).

This setting limits the largest maximum transfer unit (network packet size) that the client on this machine will be willing to transmit. This setting can be used where an artificial limit on the network precludes packets as large as the discoverable MTU from being transmitted successfully.

rxpck

Specify an integer (the number of extra Rx packet structures).

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 client performance in some circumstances.

splitcache

Specify an fraction (the RW/RO ratio).

This allows the user to set a certain percentage of the client 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

Specify an integer (the number of stat entries).

The client will allocate this number of entries in memory for recording status information about the 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

Specify yes or no.

When this option is set to yes, the client will generate a detailed trace of the afsd program's actions on the standard output stream.

The default is no.

volumes

Specify an integer (the number of volume entries)

The client will allocate this number of memory structures for storing volume location information. The default value is 200.

[defaults]

The [defaults] section may contain the following settings:

netinfo

For a client, use this setting to specify one or more IP addresses to use when communicating with the cell File Servers.

If the netinfo parameter is set when the Cache Manager initializes, the Cache Manager uses its contents as the basis for a list of local interfaces. Otherwise, the Cache Manager uses the list of interfaces configured with the operating system. It then removes from the list any addresses that appear in the netrestrict list, if it exists. The Cache Manager records the resulting list in kernel memory. The first time it establishes a connection to a File Server, it registers the list with the File Server.

The File Server uses the addresses when it initiates a remote procedure call (RPC) to the Cache Manager (as opposed to responding to an RPC sent by the Cache Manager). There are two common circumstances in which the File Server initiates RPCs: when it breaks callbacks and when it pings the client machine to verify that the Cache Manager is still accessible.

If specifying multiple values, separate each IP address with a space, and the list should be on a single line. The IP addresses should be specified in dotted decimal format. The order of the addresses is not significant. There is currently no mechanism to specify a range of addresses or a wildcard; each IP address must be listed individually.

To prohibit the Cache Manager absolutely from using one or more addresses, list them in the netrestrict setting. To display the addresses the Cache Manager is currently registering with File Servers, use the fs getclientaddrs command. To replace the current list of interfaces with a new list between reboots of the client machine, use the fs setclientaddrs command.

The default value for this setting is an empty list, which means the Cache Manager uses the list of interfaces configured with the operating system.

netrestrict

For a client, use this setting to specify one or more IP addresses to avoid using when communicating with the cell servers.

The Cache Manager will not register these IP addresses with a File Server when first establishing a connection to it. For an explanation of how the File Server uses the registered interfaces, see netinfo above.

As it initializes, the Cache Manager constructs a list of interfaces to register, from the netinfo setting if it exists, or from the list of interfaces configured with the operating system otherwise. The Cache Manager then removes from the list any addresses that appear in the this netrestrict setting, if it exists. The Cache Manager records the resulting list in kernel memory.

To display the addresses the Cache Manager is currently registering with File Servers, use the fs getclientaddrs command.

If specifying multiple values, separate each IP address with a space, and the list should be on a single line. The IP addresses should be specified in dotted decimal format. The order of the addresses is not significant. There is currently no mechanism to specify a range of addresses or a wildcard; each IP address must be listed individually.

The default value for this setting is an empty list, which means the Cache Manager uses all the addresses it found when examining the netinfo setting.

thiscell

This parameter sets the default cell for the workstation. All AuriStor File System tools will default to using this cell.

[cells]

Each entry in the [cells] section is the name of a AuriStor File System or AFS cell (from this point forward referred to only as a cell.)

Cell service information must be obtained whenever an AuriStorFS cache manager, server or administration tool (from this point forward referred to as the client) has to contact a cell's Location Service, Protection Service, or Backup Service. Cell information can be distributed via DNS SRV records [RFC 5864], DNS AFSDB records [RFC 1183], local configuration or a combination of DNS and local configuration.

Here is an example:

    qa.your-cell-name.com = {
        description = "Your Example Cell"
        aliases = ycn
        use_dns = yes
        kerberos_realm = YOUR-REALM-NAME.COM
        linked_cell = prod.your-cell-name.com
        servers = {
            afsdb1.qa.your-cell-name.com = {
                address = [2001:DB8:30:84:20c:29ff:fe2a:fcc]
                address = 192.0.2.37
            }
            afsdb2.qa.your-cell-name.com = {
                address = [2001:DB8:88:27:20c:29ff:fe19:de6f]
                address = 198.51.100.47
            }
            afsdb3.qa.your-cell-name.com = {
                address = [2001:DB8:1f07:f77:20c:29ff:fe3b:c525]
                address = 203.0.113.252
            }
        }
    }

For each cell you can specify the following settings:

aliases

Specify one or more aliases for the cell. If specifying multiple values, separate each alias with a space, and the list should be on a single line.

description

This is a textual comment describing the cell. You may use this setting to identify the organization associated with the cell.

This value may be used by tools such as a monitoring service. The Windows client exports the description as part of the \\afs\cell\ browser record.

linkedcell

Specify the name of a linked cell. You may link to a cell for the purpose of retrying volume lookups. When two cells are linked, a volume lookup in one cell that fails is retried in the linked cell.

use_dns

Specify yes or no.

If set to no, then the servers list will be used and DNS SRV and AFSDB records will not be requested. This is the default behavior.

If set to yes, the client will query DNS to discover location servers and protection servers in the cell. First, SRV records [RFC 5864] will be requested. If none are found, then AFSDB records [RFC 1183] will be requested. If neither DNS SRV nor AFSDB records are obtained for the cell, then the servers list will be used as a fallback.

kerberos_realm

If specified, this Kerberos realm will override the normal Kerberos realm discovery process for the cell.

servers

This is a list of the servers for the cell. Each server is specified as its fully qualified DNS hostname and a block.

    fqdn = {
    }

If no list is specified or if the use_dns setting is enabled as described above, then the client will discover the cell's server list using DNS SRV or AFSDB records. If use_dns is enabled, then the server list is used as a fallback in case DNS SRV or AFSDB records cannot be obtained.

Each server block can optionally specify the following settings:

address

The IPv4 or IPv6 address of the server.

The default is to use DNS to locate the server.

type

Specify one of: dbserver, vlserver, ptserver or buserver.

The default is dbserver which indicates the server might host any of the Location Service, Protection Service or Backup Service.

SIMPLE EXAMPLE

The following example defines an "your-cell-name.com" cell with one server.

The first and only server in the example is db1.your-cell-name.com. No IP address is specified, so the Cache Manager will use DNS to find the server. No type is specified for this server, so the Cache Manager will treat the server as a protection server and location server.

    [defaults]
        thiscell = your-cell-name.com

    [cells]
        your-cell-name.com = {
            description = "My very own cell"
            servers = {
                db1.your-cell-name.com = {
                }
            }
        }

COMPLEX EXAMPLE

The following example defines two cells, "production" and "testing".

The production cell has three servers. The first server in this cell is db1.your-cell-name.com. Our example user did not want to rely on DNS, so the user set an explicit IPv4 address for the server.

The second server in the production cell is db2.your-cell-name.com. The type is explicitly set to vlserver, so the client will only use this for VLDB services. No IP address is specified, so the client will use DNS to locate db2.your-cell-name.com.

The third server in the production cell is not specified by hostname at all, only by an IPv4 address. The server is only running a ptserver, and the client will access it using a non-standard port, 1025.

The second cell in the file is the testing cell, and this cell has two servers. The first server is 198.51.100.1. The second server is 203.0.113.2, which has an explicit rank defined to 100. This means that the second server will outrank the first server's default rank of 10,000, and the Cache Manager will attempt to contact the location server on 203.0.113.2 first.

The testing cell also has two aliases: beta and staging. This means that our example user can access the cell via /afs/beta/ and /afs/staging/ locations as well as the full /afs/testing.your-cell-name.com/ location.

Additionally, an afsd option to set the system name list as described in fs_sysname(1) is set.

    [defaults]
        thiscell = production.your-cell-name.com

    [afsd]
        sysname = amd64_linux26 amd64_rh60

    [cells]
        production.your-cell-name.com = {
            description = "My production cell"
            servers = {
                yfs1.your-cell-name.com = {
                    address = 192.0.2.1
                }
                udp/yfs2.your-cell-name.com:7003 = {
                    type = vlserver
                }
                192.0.2.3:1025 = {
                    type = ptserver
                    clone = yes
                }
            }
        }

    testing.your-cell-name.com = {
        description = "My testing cell"
        aliases = beta staging
            servers = {
                198.51.100.1 = {
            }
            203.0.113.2 = {
                rank = 100
            }
        }
    }

COMPARISON WITH AFS

For users familiar with AFS, the yfs-client.conf file replaces the functionality of many older files in AFS: cacheinfo, CellServDB, NetInfo, NetRestrict, ThisCell

The afsd process in AFS had several command-line options that are now available as configuration file options under the [afsd] section in yfs-client.conf.

The AFS client did not enable dynroot functionality by default. The AuriStor client enables the behavior of AFS's -dynroot and -dynroot-sparse options by default.

SEE ALSO

All servers use a similar configuration file: yfs-server.conf(5)

RFC 5864: DNS SRV Resource Records for AFS

RFC 1183: New DNS RR Definitions

COPYRIGHT

Copyright AuriStor, Inc. 2014-2017. https://www.auristor.com/ All Rights Reserved.

Portions Copyright 2000 IBM Corporation. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0.

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.