yfs-client.conf - AuriStor File System client configuration file
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.
The AuriStor File System configuration 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
includedir /path/to/directory
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.
The includedir directory can store zero or more configuration files that are included. A file is included only if its filename is valid. A valid filename either terminates with the .conf extension or consists of characters from the following categories:
Alphabetic characters
Numeric digits
The underscore '_'
The hypen '-'
Any filenames that do not meet these criteria are ignored. These rules are intended to prevent the inclusion of backup or temporary files created by text editors or packaging systems.
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.
The [afsd] section may contain the following settings:
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.
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.
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.
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.
Defaults to 100000.
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 /var/cache/yfs.
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.
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.
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.
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.
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.
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.
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.
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.
The default setting is yes.
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 section 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 IP 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.
Enable exporting paths under /afs over nfs. Note that if this setting is enabled then fakestat is disabled.
The default setting is no.
Specify yes or no or all.
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.
If set to all, the client will 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.
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.
On Linux, the fakestat setting will be forced to no if exportnfs is yes, as it can interfere with the nfs server's path reconnection logic and result in stale file handle errors on the nfs clients.
The default setting is yes.
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.
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).
Do not perform filename lookups in the root of the AFS mount; Instead act as if an empty file by the name specified exists.
The cache manager will not perform on-demand resolution a cell's location servers for any cell that matches a name in this list.
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.
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.
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).)
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.
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.
Specify the full filesystem path to the kernel module. This setting is only available on Mac OS X.
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.
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.
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.
This setting is ignored by afsd.fuse.
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.
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.
Names the script to be run after cache manager initialization has completed.
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 dynroot is enabled.
The default is root.afs.
Specify yes or no.
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 no.
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.
Specify an integer (the 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.
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 between 16 and 8192.
The default RX window size for the cache manager is 512 packets.
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.
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.
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.
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.
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.
The [defaults] section may contain the following settings:
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.
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.
This parameter sets the default cell for the workstation. All AuriStor File System tools will default to using this cell.
Specify the full filesystem path to a keytab.
Allow specification of a keytab for utilities and services to read a key such that commands like pts and vos.
See also the [afsd] keytab option.
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:
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.
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.
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.
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.
If specified, this Kerberos realm will override the normal Kerberos realm discovery process for the cell.
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:
The IPv4 or IPv6 address of the server.
The default is to use DNS to locate the server.
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.
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 = {
}
}
}
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
}
}
}
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.
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 AuriStor, Inc. 2014-2021. 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.
"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.