lcfg-openafs - The LCFG openafs component
This documentation refers to lcfg-openafs version 0.0.34
This is an LCFG component to manage the configuration of openafs clients and servers. It is capable of managing the various configuration files, updating the running daemons and starting and stopping AFS services. Also provided is a translator for generating the necessary nagios configuration for using the monitoring scripts provided by Russ Allbery.
This section details all the general resources which apply to the configuration for both the openafs client and server.
The location of the sysconfig file, the default value is /etc/sysconfig/openafs. This file is read by both the client and server startup scripts and contains environment variables which specify various command line options. Those options can be controlled via LCFG resources, see below for details.
This section details all the resources which apply to the configuration for the openafs client.
This is the name of the local AFS cell, the default value is the value stored in the profile.domain resource. See ThisCell(5) for more details. Changing this will only have an effect from the next client restart.
The local disk directory at which the Cache Manager mounts the AFS namespace. The default value is /afs. See cacheinfo(5) for more details. Changing this will only have an effect from the next client restart.
The client cache size as a number of 1-kilobyte blocks. The default value is 100000. See cacheinfo(5) for more details. Changing this will have an immediate effect on platforms which are supported by the Perl AFS module.
The local disk directory to use as a cache. The default value is /usr/vice/cache. See cacheinfo(5) for more details. Changing this will only have an effect from the next client restart.
This is a list of tags which identify extra cells for which you want to add database server information. See CellServDB(5) for full details. Associated with each tag is a cell name, a comment and a list of database servers. For each server you need to specify the name and the IP address. Those resources are described below. Currently changing this list only has an effect from the next client restart, the intention is to add support fs newcell at some point in the future.
The name of the cell for this tag, this is usually a domain name.
A comment to associate with this cell name, this is usually a longer descriptive name of the institution providing this cell.
A list of tags, one for each database server. You then need to specify the host name and IP address using the following two resources.
The IP address for this database server.
The host name for this database server.
The directory where the client configuration files are stored. The default value is /usr/vice/etc
The init script used to start and stop the openafs client. The default is /etc/init.d/openafs-client
This is a boolean value which controls whether PAGs should be garbage collected. The default value is false. This is set when the client is started, changing the value will only have an effect from the next client restart.
This is a boolean value which controls the status of network traffic encryption for file traffic in the AFS client. This encryption applies to file traffic going to and coming from the AFS File Server for users with valid tokens. This command does not control the encryption used for authentication, which normally uses Kerberos 5. The default value is true. Changing this value is only possible on platforms which are supported by the Perl AFS module.
This is a boolean value which controls whether the client is actually managed (i.e. configured and started) by the component. The default is true. You may want to turn off client management on AFS servers.
The following options are those stored in the sysconfig file and passed to the openafs client at startup time. See afsd(8) for full details. Changing the values for options specified in the sysconfig file only has an effect at the next restart of the openafs client.
This is a boolean value. When set to true the list of database server machines is taken from the AFSDB DNS records for each cell. The default value is false, in which case the list of database server machines is taken from the client CellServDB file.
This is an integer which controls the size of each cache chunk in kilobytes). It must be in the range of 0 to 30 and is used as an exponent on the number 2. A value of 16 translates into 64KB (2^16). A value of zero sets the chunk size to the appropriate default value. This is an important option when tuning for performance, setting this option to larger values can increase performance when dealing with large files.
This is an integer which specifies the number of background daemons to run on the machine. These daemons improve efficiency by doing prefetching and background writing of saved data. The default value is 2 which is adequate for a machine serving up to five users.
This is an integer which sets the number of dcache entries in memory, which are used to store information about cache chunks. Generally afsd will do a good job of tuning this and it should not need to be specified.
This is a boolean value which controls whether the AFS client uses a dynamic root. If it is set to true then the AFS client uses the contents of the CellServDB file to populate the listing of cells in the /afs folder. A cell is then not contacted until the /afs/cell path is accessed. This has the big advantage that the client can be started properly without network access. The default value is true.
This is a boolean value. When set to true 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 is not contacted. The default value is true.
This is an integer which specifies the number of files to create in the cache directory for a disk cache. This will be auto-configured by afsd so it is probably best left unspecified.
This is an integer which specifies the number of entries to allocate in the machine memory for recording status information about the AFS files in the cache. This will be auto-configured by afsd so it is probably best left unspecified.
This is an integer which specifies the number of memory structures to allocate for storing volume location information. The default value is 200.
This section details all the resources which apply to the configuration for the openafs server. See bos(8) and bosserver(8) for full details. Note that a server can ONLY be managed by this component on a system which is supported by the Perl AFS module.
The list of principals for users who are authorized to issue privileged bos and vos commands. Changes to the administrator list take effect immediately.
This is a space-separated list of Kerberos5 realms which are trusted to authenticate to the local AFS cell. This is only needed when the Kerberos5 realm does not match the cell name or multiple Kerberos5 realms authenticate to the same AFS cell.
The directory where the server configuration files are stored. The default value is /usr/afs/etc
The directory where the various AFS server binaries are stored. The default value is /usr/afs/bin/.
The directory into which various AFS local files are written (e.g. NetInfo and BosConfig). The default value is /usr/afs/local.
The init script used to start and stop the openafs client. The default is /etc/init.d/openafs-client
This is the list of AFS services which you want to run. See bos_create(8) for more details. This resource will normally contain a list of names which match the standard AFS service list (e.g. fs, vlserver, ptserver, buserver). BEWARE that changing the LCFG resources for services in any way for a running system will result in IMMEDIATE changes which could involve stopping, deleting and recreating the service. If you have lots of users you might want to warn them first!
For each service you will need to specify various resources, see below:
This is a boolean value which controls whether the service will actually be started. This makes it possible to define all the information without actually starting the service. Note that if the specific service is already running and the value of this resource changes to false the service will be stopped but not deleted. The default value is false.
This is the type of service required. The acceptable values are cron, fs and simple, the default value is simple. Normally this only needs to be changed for a fileserver service.
This is a list of commands to run for the service. Note that the order of this list is important when specifying multiple commands. For the filesystem service (fs) this would be fileserver volserver salvager.
If the command is one of the standard AFS server binaries and is stored in the directory referred to in the server_binpath resource then you do not need to specify the full path. This resource is useful for non-sstandard services or filesystem layouts.
This is the list of command line options which should be passed into the specific command.
This is the list of IP addresses which should be registered with AFS Database Servers or used to talk to other database servers. See NetInfo(5) for more information. Note that the running services will not notice any change to this resource until the next restart. This might change at some point in the future.
This is the list of IP addresses which should not be registered with AFS Database Servers or used to talk to other database servers. See NetRestrict(5) for more information. Note that the running services will not notice any change to this resource until the next restart. This might change at some point in the future.
The time at which the BOS Server restarts itself and then any AFS process marked with the Run status flag in the BosConfig file. This can be a string containing a time, a day and time, the keyword "never" or the keyword "now". See bos_setrestart(8) for full details. The default value is sunday 04:00.
This is the time each day at which the BOS Server restarts any currently running process for which the timestamp on the binary file in the server_binpath directory is later than the time the process last started or restarted. See bos_setrestart(8) for full details. The default value is 05:00.
This is a tag which is used to identify the cell to which the server machine belongs for the purposes of server-to-server communication. See CellServDB(5) for full details. Associated with each tag is a cell name, a comment and a list of database servers. For each server you need to specify the name and the IP address.
Those resources are described below, it is important to note that these are deliberately intended to overlap with any resources you specified for the client configuration. This means that it is only necessary to specify the information for a local cell once.
The name of the cell for this tag, this is usually a domain name.
A comment to associate with this cell name, this is usually a longer descriptive name of the institution providing this cell.
A list of tags, one for each database server. You then need to specify the host name and IP address using the following two resources.
The IP address for this database server.
The host name for this database server.
This is a boolean value which controls whether the server is actually managed (i.e. configured and started) by the component. The default is false.
The following options are those stored in the sysconfig file and passed to the openafs server at startup time. See bosserver(8) for full details. Note that changes to options stored in the sysconfig file will not take effect until the next restart of the bosserver.
This is a path to a file, specifying a value turns on audit logging for bos. 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.
This is a boolean value which controls whether the bos server records in the BosLog file the names of all users who successfully issue a privileged bos command (one that requires being listed in the admin_users resource). The default is false.
This is a boolean value which controls whether the bos server collects Rx statistics and allocates memory for their storage. For each connection with a specific UDP port on another machine, a separate record is kept for each type of RPC sent or received. The default value is false.
This is a boolean value which controls whether the bos server collects Rx statistics and allocates memory for their storage. A separate record is kept for each type of RPC sent or received, aggregated over all connections to other machines. The default value is false.
This is a boolean value which controls whether kerberos principals with a dot in the first component of their name are allowed. The default value is false. Note that this only applies to bos, if you want to allow dotted principals in other services, you have to explicitly specify this in their command line. It is likely that if you've done this for bos, you'll want to do this there too.
This component requires the following Perl modules: IPC::Run, List::MoreUtils and Readonly. Where available the AFS module will be used to dynamically configure the client, it is required for management of servers.
This is the list of platforms on which we have tested this software. We expect this software to work on any Unix-like platform which is supported by Perl.
ScientificLinux5, Fedora12, Fedora13
Note that this software has only been tested with the openafs packages distributed by the OpenAFS project. We cannot make any guarantees about RPMs built and distributed by other groups such as ScientificLinux.
This component will only work on systems which are supported by the Perl AFS module.
For full documentation on OpenAFS see the project website: http://www.openafs.org/
Please report any problems to bugs@lcfg.org, feedback and patches are also always very welcome.
Stephen Quinney <squinney@inf.ed.ac.uk>
Copyright (C) 2008-2009 University of Edinburgh. All rights reserved.This library is free software; you can redistribute it and/or modify it under the terms of the GPL, version 2 or later.