SAM-QFS x.x Planning - Functional Specification Document ======================================================== Updated: 03/27/2008 FEATURE DESCRIPTION: ------------------- The current limit of 128 clients in a shared QFS cluster needs to be increased. Independent of the other issues related to a large number of clients, the current infrastructure for storing the client host table needs to be modified to accomodate a much larger number of clients (the short-term goal is 1024 clients). The current allocated space for the on-disk client hosts table is 16KB. This feature provides the ability to add new client hosts to a shared QFS cluster until the new 2MB of allocated space is exhausted. NOTE: Each client host table entry can be of arbitrary size. The primary influence on the size of each entry is it's host name. From an administrative standpoint, if we assume that the largest practical host name consumes 1/4 KB, then the maximum number of entries in a 2MB host table is on the order of 8K entries. Small client host tables will continue to be supported for existing file systems. sammkfs will allocate a larger (2MB) client host table on-disk for new SAM-QFS file systems. For a SAM-QFS file system that contains a 16KB client host table, that client host table will automatically be relocated into a new 2MB client host table when more than 16KB is necessary to hold the supplied client host table data. A file system with a 2MB client host table will not be mountable on a system running a legacy release of SAM-QFS, except under special circumstances (see section "FUNCTIONAL REQUIREMENTS"). 6555811: RFE: Increase the size of the client host table. SCOPE OF THE PROJECT: -------------------- - The sammkfs command and the libfscmd library will be modified to allow the creation of large host tables. - The new on disk host file will be a 2M direct map file created at sammkfs time. - The behaviour of existing small host tables will not change. A mechanism to convert existing small host tables to large ones will be provided. - In general, configuration and observation of large numbers of SAM-QFS clients via the affected interfaces. All other issues related to large numbers of SAM-QFS clients are outside the scope of this feature. FUNCTIONAL REQUIREMENTS: ----------------------- The existing library interfaces (see section 4.5 Interfaces) that are used to retrieve and update the client host table already include a buffer size embedded within their parameters. This allows SAM-QFS infrastructure to determine whether or not the supplied size is sufficient for retrieving or updating the client host table. However, the behavior of the existing library interfaces will be updated to recognize a buffer size incompatibility, and to return the error code EMSGSIZE ("Message size too long") when that condition is detected. In case of a size incompatibility error, the correct client host table size is embedded within the returned parameters. The parameters and format of existing library interfaces will remain unchanged. An error return code, EMSGSIZE ("Message size too long"), will be added to the set of possible return codes for those library interfaces. Affected library interfaces are: int sam_gethost(const char *fs, int len, char *tab) int sam_sethost(const char *fs, int newserver, int len, const char *tab) The above library interfaces are included in the SAM-QFS library libsam. Those interfaces are unpublished/internal/private. Certain SAM-QFS software components account for the error condition where a corrupted SAM-QFS file system can't be mounted. To retrieve and/or update the client host table those software components open and read/write the client host table directly from/to the appropriate metadata device. Those components will be updated to recognize, read and write both the small and large client host table formats. Affected components are: sammkfs samfsck samfsconfig sharefsd Sun Cluster Agent The small client host table of an existing file system will be automatically converted (i.e. moved) to a newly-allocated large client host table only when the client host table requires more than 16KB of storage space. Available space limitations may require that the new large client host table must be allocated on a non-ordinal-0 metadata device. The SAM-QFS host table management infrastructure, which currently assumes that the client host table always resides on the ordinal 0 metadata device, will be updated so that it can manage a client host table that resides on a metadata device of any available file system ordinal. Once a SAM-QFS file system contains a large client host table (2MB), the ability to mount that file system on a host that is running a legacy release of SAM-QFS becomes limited. Legacy releases of SAM-QFS can only manage a small (16KB) client host table. Therefore, a file system that contains a client host table with more than 16KB of data cannot be mounted on a host running a legacy release of SAM-QFS. However, if a filesystem that supports a 2MB client host table, but contains only 16KB (or less) of client host table data, then it can be mounted on a host running a legacy release of SAM-QFS. This feature will toggle an option bit in the SAM-QFS file system superblock to indicate whether or not the client host table contains more than 16KB of data. That superblock option field controls the ability to mount newer file system versions on hosts running a legacy release of SAM-QFS. DELIVERABLES: ------------ - Restructure the in core host table. - Allocate the on disk host table as a 2M direct map file at sammkfs time. - The existing sam_gethost and sam_sethost interfaces will continue to work for existing host tables and new host tables that fit within the current space limitation of 16k. - The behaviour of the existing interface will change when reading or writing a new large host table. If the caller of sam_gethost or sam_sethost provides a buffer that is too small then EMSGSIZE will be returned but the needed size will be returned in the size element of the argument structure. FUNCTIONAL DEPENDENCIES: ----------------------- This requires that voluntary and involuntary failover be reliable prior to integration of this feature.