NAME

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

DESCRIPTION

The yfs-server.conf file contains server 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.

STRUCTURE

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:

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.

SECTIONS

The yfs-server.conf file consists of the following sections:

Each section is further explained below.

[defaults]

The [defaults] section can contain the following settings:

allow-dotted-principals

Specify yes or no.

By default, the RXKAD security layer will disallow access by Kerberos principals with a dot in the first component of their name. This is to avoid the confusion where principals user/admin and user.admin are both mapped to the user.admin PTS entry. Sites whose Kerberos realms don't have these collisions between principal names can disable this check by starting the server with this option.

auditlog

Specify yes, no or the full filesystem path to the the audit log file, SYSV message queue, or syslog ident depending upon the audit-interface value.

The audit log records information about RPC calls, including the name of the RPC call, the host that submitted the call, the authenticated entity (user) that issued the call, the parameters for the call, and if the call succeeded or failed.

The default is to disable audit logging.

When yes is specified and audit-interface = file, the default audit log filename will be service specific.

bosserver

/var/log/yfs/BosAuditLog

buserver

/var/log/yfs/BackupAuditLog

fileserver

/var/log/yfs/FileAuditLog

ptserver

/var/log/yfs/PtAuditLog

vlserver

/var/log/yfs/VLAuditLog

volserver

/var/log/yfs/VolserAuditLog

audit-interface

Specify one of three values: file, or syslog, or sysvmq.

The file interface writes audit messages to the file set in auditlog. The sysvmq interface writes audit messages to a SYSV message (see msgget(2) and msgrcv(2)). The message queue the sysvmq interface writes to has the key ftok(path, 1), where path is the path specified in the auditlog option. The syslog interface writes audit messages to the syslog(1) facility. The path provided is used as the syslog ident.

The default setting is file.

debug

Sets the detail level for the debugging trace written to the logs (by default, logs are individual files in /var/log/yfs). Provide one of the following values, each of which produces an increasingly detailed trace: 0, 1, 5, 25, and 125. The default value of 0 produces only a few messages.

databases

For a server hosting the Location Service, Protection Service, and/or Backup Service, the databases section is mandatory. Common configuration can be specified under the [defaults] section or per service configuration can be specified under the [vlserver], [ptserver], and buserver] sections.

The databases block contains a mandatory servers block.

servers

This is a mandatory list of one or more servers for the cell. Each server is specified as a unique hostname and a block.

    hostname = {
    }

The hostname is for description purposes only. Each server block must specify one or more address values. All of the other values are optional.

address

An IPv4 address of the server. IPv6 addresses are not supported for database communications.

clone

Specify yes or nonvoting to configure the database server as a non-voting clone. A non-voting clone can neither be elected as the coordinator nor can it vote for the coordinator. In other words, the existence of a non-voting database server is not counted towards the quorum size.

Specify voting to configure the database server as a voting clone. A voting clone cannot be elected the coordinator but it can vote for the coordinator and as such is included in the quorum size.

Specify no to configure the database server as eligible to be elected the coordinator. Such a server is included in the quorum size and votes for the coordinator.

The default setting is no.

rank

Specify an integer to assign a rank to assist with the selection of the coordinator for. Servers with the lowest rank are selected in preference to servers with higher ranks. Valid values are any integer from one 1 to 4294967295 inclusive.

When the rank is not specified, it will be calculated by ordering the servers by lowest IPv4 address starting at 1.

The rank must be specified for all servers, or no servers.

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.

afscompat

The afscompat option in the [ubik] databases stanza of the /etc/yfs/server/yfs-server.conf file enables automatic detection and fallback to AFS3 Ubik protocols. If an AFS3 Ubik peer is detected, the configured server will not run for election as coordinator. When no AFS3 Ubik peers are detected, the server will run and if elected will become the coordinator. This mode is only intended to be used during conversion of a cell from IBM AFS or OpenAFS to AuriStorFS. In this mode, it is possible that no coordinator will be elected the required wait period for detection of OpenAFS peers expires. This time period is based upon the number of Ubik servers in the cell.

ubik_debug

When set, overrides the debug detail level for the debugging trace written by the ubik database engine to the logs (by default, logs are individual files in /var/log/yfs). The default value of 0 permits the trace level to be determined by the debug setting. Other valid values are: 5, 25, and 125. All errors are logged at level 0. Levels 5 and 25 contain increasing verbosity of operational details excluding transactional events. All transaction entries are logged at level 125.

An example databases block follows:

    databases = {
        servers = {
            afsdb1.your-cell-name.com = {
                address = 192.0.2.37
                rank = 1
                type = dbserver
            }
            afsdb2.your-cell-name.com = {
                address = 198.51.100.47
                rank = 2
                type = dbserver
            }
            afsdb3.your-cell-name.com = {
                type = dbserver
                address = 203.0.113.252
                rank = 3
                clone = voting
            }
        }
        ubik_debug = 25
        afscompat = no
    }
netinfo

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

If the netinfo setting exists when the File Server initializes, the File Server uses its contents as the basis for a list of interfaces to register in the VLDB. Otherwise, it uses the list of network interfaces configured with the operating system. It then removes from the list any addresses that appear in the netrestrict setting, if it exists. The File Server records the resulting list in the /var/yfs/sysid file and registers the interfaces in the VLDB. The database server processes use a similar procedure when initializing to determine which interfaces to use for communication with the peer processes on other database servers in the cell.

To display the File Server interface addresses registered in the VLDB, use the vos listaddrs 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 server uses the list of interfaces configured with the operating system.

netrestrict

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

As it initializes, the File Server 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 File Server then removes from the list any addresses that appear in the netrestrict setting, if it exists. The File Server records the resulting list in the /var/yfs/sysid file and registers the interfaces in the VLDB. The database server processes use a similar procedure when initializing to determine which interfaces to use for communication with the peer processes on other database servers in the cell.

To display the File Server interface addresses registered in the VLDB, use the vos listaddrs 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 server uses all the addresses it found when examining the netinfo setting.

rxbind

Specify yes or no.

Force the server to bind the Rx socket to the primary interface only. (If not specified, the Rx socket will listen on all interfaces.)

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.

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.

syslog

Specify yes to send messages to syslog at the default LOG_USER level. Alternatively, you can specify a custom log level with this option.

If you provide a value for this configuration option, AuriStor servers will send logging output to syslog instead of the normal log file. Server processes will tag syslog messages with the name of the process, for example fileserver or ptserver.

The default behavior is to ignore syslog and send logging output to normal log files.

thiscell

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

See also fs_wscell(1).

[fileserver]

The [fileserver] section can contain any of the settings described in [defaults] above, as well as the following settings:

abortthreshold

Specify a integer (the number of erroring FetchStatus requests).

Sets the abort threshold, which is triggered when an client sends a number of FetchStatus requests in a row and all of them fail due to access control or some other error. When the abort threshold is reached, the file server starts to slow down the responses to the problem client in order to reduce the load on the file server.

The throttling behavior can cause issues especially for the Mac OS X AFS client. When browsing the directory tree, directories with only "lookup" access for the current user can load more slowly because of the throttling. This is because the Mac OS X AFS client sends FetchStatus calls one at a time instead of InlineBulkStatus calls.

Setting the threshold to 0 disables the throttling behavior.

b

Specify a positive integer (the number of buffers).

Sets the number of directory buffers.

banner

Specify yes or no.

Prints the following banner to /dev/console about every 10 minutes.

   File Server is running at I<time>.
busyat

Specify a positive integer. The fileserver will redirect clients when the queue is larger than this number.

This setting defines the number of incoming RPCs that can be waiting for a response from the File Server before the File Server returns the error code VBUSY to the Cache Manager that sent the latest RPC. In response, the Cache Manager retransmits the RPC after a delay. This argument prevents the accumulation of so many waiting RPCs that the File Server can never process them all.

The default value is 600.

cb

Specify a positive integer (the number of callbacks).

Sets the number of callbacks the File Server can track.

hr

Specify an integer (the number of hours between refreshing the host cps)

Specifies how often the File Server refreshes its knowledge of the machines that belong to protection groups (refreshes the host CPSs for machines). The File Server must update this information to enable users from machines recently added to protection groups to access data for which those machines now have the necessary ACL permissions.

implicit

Defines the set of permissions granted by default to the system:administrators group on the ACL of every directory in a volume stored on the file server machine.

Provide one or more of the standard permission letters (rlidwka) and auxiliary permission letters (ABCDEFGH), or one of the shorthand notations for groups of permissions (all, none, read, and write). To review the meaning of the permissions, see the fs setacl reference page.

l

Specify a positive integer (the number of large vnodes).

Sets the number of large vnodes available in memory for caching directory elements.

logfile

Sets the file to use for server logging. If logfile is not specified and no other logging options are supplied, this will be /var/log/yfs/FileLog. Note that this option is intended for debugging and testing purposes. Changing the location of the log file from the command line can result in undesirable interactions with tools such as bos.

nobusy

Specify yes or no.

This option slightly changes the error codes reported to clients when an unattached volume is accessed by a client during fileserver startup.

There is usually no reason to use this option under normal operation.

novbc

Specify yes or no.

Prevents the File Server from breaking the callbacks that Cache Managers hold on a volume that the File Server is reattaching after the volume was offline (as a result of the vos restore command, for example). Use of this option is strongly discouraged.

offline-timeout

Specify an integer (the timeout in seconds).

Setting this option to N means that if any clients are reading from a volume when we want to offline that volume (for example, as part of releasing a volume), we will wait N seconds for the clients' request to finish. If the clients' requests have not finished, we will then interrupt the client requests and send an error to those clients, allowing the volume to go offline.

If a client is interrupted, from the client's point of view, it will appear as if they had accessed the volume after it had gone offline. For RO volumes, this mean the client should fail-over to other valid RO sites for that volume. This option can speed up volume releases if volumes are being accessed by clients that have slow or unreliable network connections.

Setting this option to 0 means to interrupt clients immediately if a volume is waiting to go offline. Setting this option to -1 means to wait forever for client requests to finish. The default value is -1.

offline-shutdown-timeout

Specify an integer (the timeout in seconds).

This option behaves similarly to offline-timeout but applies to volumes that are going offline as part of the fileserver shutdown process. If the value specified is N, we will interrupt any clients reading from volumes after N seconds have passed since we first needed to wait for a volume to offline during the shutdown process.

Setting this option to 0 means to interrupt all clients reading from volumes immediately during the shutdown process. Setting this option to -1 means to wait forever for client requests to finish during the shutdown process.

If offline-timeout is specified, the default value of offline-shutdown-timeout is the value specified for offline-timeout. Otherwise, the default value is -1.

pctspare

Specify an integer between 0 and 99 (the percentage spare).

Specifies the amount by which the File Server allows a volume to exceed its quota as a percentage of the quota. A value of 0 prevents the volume from ever exceeding its quota. Do not combine this argument with the spare option.

readonly

Specify yes or no.

If set to yes, the fileserver will not permit clients to write to the server.

rxdbg

Specify yes or no.

When set to yes, the fileserver will write a trace of operations on Rx packets to the file /var/log/yfs/rx_dbg.

rxpck

Specify an integer (the number of rx extra packets).

Controls the number of Rx packets the File Server uses to store data for incoming RPCs that it is currently handling, that are waiting for a response, and for replies that are not yet complete.

s

Specify a positive integer (the number of small vnodes).

Sets the number of small vnodes available in memory for caching file elements.

security

Specify a list of colon-separated pairs.

Specifies the acceptable security class and level combinations as a list of colon-separated pairs.

The following classes are recognized:

rxnull, rxkad, yfs-rxgk

The following levels are recognized:

clear, auth, crypt

For example, to enforce that all connections use the yfs-rxgk class with a minimum level of auth:

  -security yfs-rxgk:auth yfs-rxgk:crypt
sendsize

Specify a positive integer (the size of send buffer in bytes).

Sets the size of the send buffer, which is 16384 bytes by default.

spare

Specify a positive integer (the number of spare blocks).

Specifies the number of additional kilobytes an application can store in a volume after the quota is exceeded. A value of 0 prevents the volume from ever exceeding its quota. Do not combine this argument with the pctspare option.

sync

Specify one of three values: always, or onclose, or none.

This option changes how hard the fileserver tries to ensure that data written to volumes actually hits the physical disk.

Normally, when the fileserver writes to disk, the underlying filesystem or Operating System can delay writes from actually going to disk, and reorder which writes hit the disk first. So, during an unclean shutdown of the machine (if the power goes out, or the machine crashes, etc), file data can become lost that the server previously told clients was already successfully written.

To try to mitigate this, the fileserver will try to "sync" file data to the physical disk at numerous points during various I/O. However, this can result in significantly reduced performance. Depending on the usage patterns, this might or might not be acceptable. This option dictates specifically what the fileserver does when it wants to perform a "sync".

The default setting is onclose.

always

This causes a sync operation to always sync immediately and synchronously. This is the slowest option that provides the greatest protection against data loss in the event of a crash.

onclose

This causes a sync to do nothing immediately, but causes the relevant file to be flagged as potentially needing a sync. When a volume is detached, volume metadata files flaged for synced are synced, as well as data files that have been accessed recently. Events that cause a volume to detach include: performing volume operations (dump, restore, clone, etc), a clean shutdown of the fileserver, or during DAFS "soft detachment".

Effectively this option is the same as never while a volume is attached and actively being used, but if a volume is detached, there is an additional guarantee for the data's consistency.

never

This causes all syncs to never do anything. This is the fastest option, with the weakest guarantees for data consistency.

Depending on the underlying filesystem and Operating System, there can be guarantees that any data written to disk will hit the physical media after a certain amount of time. For example, Linux's pdflush process usually makes this guarantee, and ext3 can make certain various consistency guarantees according to the options given. ZFS on Solaris can also provide similar guarantees, as can various other platforms and filesystems. Consult the documentation for your platform if you are unsure.

Which option you choose is not an easy decision to make. It can depend on the specific scenario and workload involved. Some argue that the always option does not provide significantly greater guarantees over any other option, whereas others argue that choosing anything besides the always option allows for an unacceptable risk of data loss. This can depend on your usage patterns, your platform and filesystem, and who you talk to about this topic.

udpsize

Specify a positive integer (the size of socket buffer in bytes).

Sets the size of the UDP buffer, which is 64 KB by default. Provide a positive integer, preferably larger than the default.

vattachpar

Specify a positive integer (the number of volume attach threads).

The number of threads assigned to attach and detach volumes. The default is 1.

Warning: many of the I/O parallelism features of Demand-Attach Fileserver are turned off when the number of volume attach threads is only 1.

vc

Specify a positive integer (the volume cachesize).

Sets the number of volumes the File Server can cache in memory.

vhandle-setaside

Specify a positive integer (the number of file descriptors reserved for non-cache I/O).

The filserver will set aside this number of file handles for I/O not in the cache. The default setting is 128.

vhandle-initial-cachesize

Specify a positive integer (the number of file descriptors reserved for cache I/O).

The fileserver will set aside this number of file handles for I/O in the cache. The default setting is 128.

vhandle-max-cachesize

Specify a positive integer (the maximum number of open files).

This is the maximum number of file handles available to the fileserver.

[vlserver]

The [vlserver] section may contain any of the settings described in [defaults] above, as well as the following settings:

auditlog

Specify the full filesystem path to the the audit log.

The audit log records information about RPC calls, including the name of the RPC call, the host that submitted the call, the authenticated entity (user) that issued the call, the parameters for the call, and if the call succeeded or failed.

audit-interface

Specify one of three values: file, or syslog, or sysvmq.

The file interface writes audit messages to the file set in auditlog. The sysvmq interface writes audit messages to a SYSV message (see msgget(2) and msgrcv(2)). The message queue the sysvmq interface writes to has the key ftok(path, 1), where path is the path specified in the auditlog option. The syslog interface writes audit messages to the syslog(1) facility. The path provided is used as the syslog ident.

The default setting is file.

noauth

Specify yes or no.

Turns off all authorization checks, and allows all connecting users to act as administrators, even unauthenticated users. The use of this option is inherently insecure, and should only be used in controlled environments for experimental or debug purposes.

smallmem

Specify yes or no.

Specifies that the vlserver should limit its memory usage during certain operations, and return an error to the calling client instead of allocating more memory. This option is only useful on systems where memory is severely limited, and should not be needed on any remotely modern system.

trace

Specify the full filesystem path to a trace file.

Turns on low-level Rx packet tracing, and logs the trace information to the specified file. The trace file can be later dumped into a human-readable form with a tool called dumptrace.

It is not recommended to turn on this option during normal operation, since the detailed tracing may cause performance issues and use up a lot of disk space.

logfile

Specify the full filesystem path to a log file.

Sets the file to use for server logging. If logfile is not specified and no other logging options are supplied, this will be /var/log/yfs/VLLog. Note that this option is intended for debugging and testing purposes. Changing the location of the log file from the command line can result in undesirable interactions with tools such as bos.

database

Specify the full filesystem path to the directory in which the Volume Location Database files reside. Provide the complete pathname ending in the base filename to which the .DB0 and .DBSYS1 extensions are appended. For example, the appropriate value for the default database files is /etc/yfs/vldb, and the two files are vldb.DB0 and vldb.DBSYS1.

This option is intended primarily for testing purposes.

keytab

Specify the full filesystem path to a keytab.

The vlserver will use this keytab for the rxgk negotiation service. If this option is not specified, the kerberos defaults will apply.

restricted_query

Specify one of two values: anyuser or admin.

Restrict RPCs that query information about volumes to a specific group of users. Only the RPCs that are not used by Cache Managers will be restricted, since Cache Manager connections to the Volume Server are always unauthenticated. You can use admin to restrict to AuriStor File System cell administrators. The anyuser option doesn't restrict the RPCs and leaves it open for all users including unauthenticated users, this is the default.

[volserver]

The [volserver] section may contain any of the settings described in [defaults] above, as well as the following settings:

auditlog

Specify the full filesystem path to the the audit log.

The audit log records information about RPC calls, including the name of the RPC call, the host that submitted the call, the authenticated entity (user) that issued the call, the parameters for the call, and if the call succeeded or failed.

audit-interface

Specify one of three values: file, or syslog, or sysvmq.

The file interface writes audit messages to the file set in auditlog. The sysvmq interface writes audit messages to a SYSV message (see msgget(2) and msgrcv(2)). The message queue the sysvmq interface writes to has the key ftok(path, 1), where path is the path specified in the auditlog option. The syslog interface writes audit messages to the syslog(1) facility. The path provided is used as the syslog ident.

The default setting is file.

log

Records in the /var/log/yfs/VolserLog file the names of all users who successfully initiate a vos command. The Volume Server also records any file removals that result from issuing the vos release command with the -f flag.

udpsize

Specify a positive integer (the size of socket buffer in bytes).

Sets the size of the UDP buffer, which is 64 KB by default. Provide a positive integer, preferably larger than the default.

[ptserver]

The [ptserver] section can contain any of the settings described in [defaults] above, as well as the following settings:

database

Specify the full filesystem path to the directory in which the Protection Database files reside. Provide the complete pathname ending in the base filename to which the .DB0 and .DBSYS1 extensions are appended. For example, the appropriate value for the default database files is /etc/yfs/prdb, and the two files are prdb.DB0 and prdb.DBSYS1.

This option is intended primarily for testing purposes.

groupdepth

Specify an integer (the number of nested groups).

This is the maximum group depth for nested groups. The default depth for nested groups is 5.

default_access

Specify a string of five characters. The first five characters are for user access, and the second five characters are for group access.

When a cell administrator creates a new PTS entry, the protection server will apply these default user and group privacy flags to the new entry. See pts_examine(1) for more information on the flags.

logfile

Specify the full filesystem path to the file to use for server logging. If logfile is not specified, and no other logging options are supplied, this will be /var/log/yfs/PTLog.

Note that this option is intended for debugging and testing purposes. Changing the location of the log file from the command line can result in undesirable interactions with tools such as bos.

restrict_anonymous

Specify yes or no.

Run the protection server in restricted anonymous access mode. While in this mode, only authenticated users will be able to access the PTS database.

restricted

Specify yes or no.

Run the protection server in restricted mode. While in restricted mode, only members of the system:administrators PTS group may make any PTS changes.

[kerberos]

The [kerberos] section can contain the following settings:

local_realms

Use this setting to specify which Kerberos realms are trusted to authenticate to the local cell.

If specifying multiple values, separate each realm with a space, and the list should be on a single line. The order of the realms is not significant. There is currently no mechanism to specify a wildcard; each realm must be listed individually.

The default behavior is to only trust a Kerberos realm that has the same name as the cell. If the Kerberos realm matches the cell name (case-insensitive), then this setting can be omitted.

local_realms is only needed when the Kerberos realm does not match the cell name or multiple Kerberos realms authenticate to the same cell.

foreign_principals

List exceptions to the algorithm of mapping Kerberos principals to AuriStor File System identities.

If a principal appears in this list, that principal will never be recognized by an server as a local identity, even if the realm is specified as a local realm in local_realms.

The principal names specified in this file must include the realm and should be in Kerberos 4 format. That is, specify user.inst@REALM, not user/inst@REALM, user.inst, nor user/inst.

It is possible to use the local_realms configuration to specify that multiple Kerberos realms can be considered "local" realms by servers, and those realms can be used nearly interchangeably. A site can list FOO.EXAMPLE.COM and BAR.EXAMPLE.COM to allow users to access an AuriStor File System cell by using Kerberos tickets from either FOO.EXAMPLE.COM or BAR.EXAMPLE.COM, and be treated as AuriStor File System users local to that cell.

In many setups, one realm is really a "local" realm that is managed by the AuriStor File System administrators, and another "foreign" realm is specified in local_realms that is managed by someone else, but in the same organization. In such a case, the principal names for users are the same, so users should be able to use either realm to authenticate to AuriStor File System. However, the principals for administrators are not the same between the two realms, and so the administrators in the "foreign" realm should not be considered AuriStor File System administrators. Specifying the administrator principals in the "foreign" realm prevents this, but still allows users to use either realm.

If specifying multiple values, separate each principal with a space, and the list should be on a single line. The order of the principals is not significant. There is currently no mechanism to specify a wildcard; each principal must be listed individually.

[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-server.conf file replaces the functionality of many older files in AFS: CellServDB, krb.conf, NetInfo, NetRestrict, ThisCell

SEE ALSO

All clients use a similar configuration file: yfs-client.conf(5)

The server daemons use the settings in yfs-server.conf: bosserver(8), fileserver(8), ptserver(8), salvager(8), vlserver(8), volserver(8)

RFC 5864: DNS SRV Resource Records for AFS

RFC 1183: New DNS RR Definitions

COPYRIGHT

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.

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.