SAM-QFS 5.0 Functional Specification v.2008.02.01 0.0 Log of Updates to this Document 2008/1/24 - Added version ID (date) to title. - Added section 0.0 Log of Updates to this Document. - Fixed general mis-spellings. - Replaced references to "root" user/privilege with "appropriately authorized" user or "appropriately privileged" process (see reviewer comment ID gcs-4). - Added statements to section 3.6 "Exported Tunable Parameters" regarding the large number, and management, of SAM-QFS tunable parameters (see reviewer comment ID gcs-5). - Changed the incorrectly-referenced section number from "6.2 Dependencies" to "3.2.1 Dependencies" in section 3.2. - Updated section "3.9.1 Roles, Authorizations, Rights Profiles" with the specific authorizations used by the SAM-QFS GUI. - Updated section "8.4.1 Identity Management" with details about authentication via the SAM-QFS GUI, and product registration due to the reference from question 4.5 in the Security document. - Updated section "8.4.3 Privilege by Proxy" to simplify the wording. Moved the identification and authentication statement to section "8.4.1 Identity Management". - Updated section "5.1 Shared Libraries" to provide the list of shared libraries used by the SAM-QFS GUI instead of referring the reader to an external file. - Updated section "5.6 Other Interfaces" to list the SAM-QFS/Solaris CLI commands used by the SAM-QFS GUI/management software. 2008/01/29 - Updated section "2.3 Packages and RPMs" to replace "SAM-QFS WORM pkg" with "SAM-QFS package additions for WORM support" (see reviewer comment ID ram-2). - Updated section "1.4 SAM-QFS Interface Types" to include a definition of ACSLS, and reference to supplied customer documentation (see reviewer comment ID ram-3). - Updated section "1.6.5 Scalability" to clarify the maximum number of SAM-QFS client nodes (see reviewer comment ID ram-4). - Updated section "3.2.1.2 System Requirements" to refer to supplied public documentation for SAM-QFS Linux client details, instead of Sun internal web pages (see reviewer comment regarding "open" inception review requirements). - Updated wording in section "4.4.1 Solaris Dynamic Reconfiguration (DR)" (see reviewer comment ID ram-6). - Updated wording in section "3.2.1.5 Java" (see reviewer comment ID ram-8). - Updated wording in section "5.11 Interface Versioning" (see reviewer comment ID ram-11). - Marked section 3.2.1.1 as "This Section Intentionally Omitted" (see reviewer comment ID ram-17). 2008/02/01 - Added section "0.1 Disclaimer". - Updated section "1.4 SAM-QFS Interface Types" to include references to the shared SAM-QFS protocol document, and to the object-based shared SAM-QFS documentation. - Updated section "6.2 Heterogeneous Environments" to describe automated disk discovery (see review comment ID ram-12). - Added new section "3.4.10 Message Catalog System" to add a statement about the message catalog translation system interface (see reviewer comment ID ram-5). 0.1 Disclaimer Any and all references in this document to SAM-QFS 5.0 capabilities reflect current plans only. Those plans are not a commitment to deliver any of those capabilities within any particular release, nor within any time frame, nor ever. The contents and existence of this document is subject to change without notice. 1.0 Background QFS is a high-performance file system available in stand-alone and shared configurations to provide heterogeneous shared access to data. For general info and product documentation see: http://www.sun.com/storagetek/management_software/data_management/qfs/ and http://docs.sun.com/app/docs/coll/qfs4.6 SAM is the Storage and Archive Manager that can be bundled with QFS to provide policy-based file services and continuous archiving of data. For general info and product documentation see: http://www.sun.com/storagetek/management_software/data_management/sam/ and http://docs.sun.com/app/docs/coll/sam4.6 For a brief description with diagrams of a typical shared SAM-QFS environment, see: http://www.visualgenomics.ca/index.php?option=com_content&task=view&id=113&Itemid=206 1.1 QFS File System QFS is a 64-bit file system that is implemented using the standard Sun Solaris virtual file system (vfs/vnode) interface. The file system is identified as type "samfs" in the /etc/vfstab file and the mount(1M) command. QFS includes a built-in volume manager that provides striping and round robin disk access. QFS uses an adjustable disk allocation unit (DAU) and allows separation of the metadata from the data portion of a file, enabling high performance reads and writes, as well as the ability to mirror metadata. Solaris Cluster can be added for high availability. A web-based management portal enables administrators to remotely and securely manage multiple QFS servers. 1.2 QFS Shared File System The QFS shared file system is a distributed file system that supports both Solaris and Linux clients. One Solaris host is configured as the metadata server (MDS), and the additional Solaris and Linux hosts are configured as clients. Both block and object interfaces are supported. 1.3 Storage and Archive Manager (SAM) SAM is tightly integrated with QFS to provide the following functions transparently to the user. A web-based management portal enables administrators to remotely and securely manage multiple SAM-QFS servers. * Archiving - Automatically saves up to four copies of file data to local or remote disk, tape, or magneto-optical storage according to user-defined policies. Data files are batched together and written to media in open, non-proprietary tar format (see attached diagram). Tape labels are written to ANSI Standard X3.27; optical devices use ISO/IEC 13346 for the volume area and ISO/TC97/SC23 for the data area. All archived data is retrievable on foreign systems without the use of SAM. * Releasing - Automatically frees file system space by removing the data portion of a file from the file system according to user-defined criteria. Only files with a valid archive copy of data can be released. The metadata portion of a file is not released as part of this operation. * Staging - Automatically copies file data from the archive media to the file system on demand. Access time to file data is determined by the physical characteristics of the archive media device, such as tape drive speed and location of data on a tape. For a sequential read of an offline file, the read operation tracks along directly behind the staging operation, allowing the file to be immediately available to an application before completely staging the file. * Recycling - Reclaims available space on archive media for expired archive copies according to user-defined criteria. Automatically moves unexpired archive copies to other archive media. 1.4 SAM-QFS Interface Types User processes interact with SAM-QFS using a command line interface (CLI), GUI, and SAM-QFS APIs. See the provided reference manuals for a more complete description of all of these interface types. SAM interacts with tape library hardware via the Sun/StorageTek Automated Cartridge System Library Software (ACSLS) to perform library-related operations (e.g., insert/remove tape cartridge from drive, retrieve the type(s) of connected library hardware, etc.). For additional details, see the supplied ACSLS Installation, Configuration, and Administration Guide (CustomerDocs/ACSLSAdminGuide.pdf). Shared SAM-QFS file system clients and metadata server (MDS) communicate via a proprietary protocol. For details, see the supplied shared SAM-QFS protocol document (QFSprotocol.sxw). Object-based shared SAM-QFS file system initiator and target storage nodes communicate with each other to manage storage allocation. For details concerning the object-based shared SAM-QFS file system, see the supplied document (SAM-QFS_OSD.odt). Functional specifications for object-based features are located at: http://www.opensolaris.org/os/project/samqfs/specs/50_Specs/ 1.5 Related Projects Related projects are: - File system: Solaris UFS, ZFS, SVM, Lustre CFS, pNFS. - HSM: ADM. - Media Management: MMS. SAM-QFS 5.0 is complimentary with the other Solaris file systems, HSM, and Media Management projects. It is strategic to the storage software strategy and HPC growth target. SAM-QFS is positioned as a shared file system, unlike UFS or ZFS which are local file systems. SAM-QFS is a Solaris cluster file system whereas Lustre CFS is a Linux cluster file system. SAM-QFS is differentiated by a tightly integrated HSM and archive capability that includes media management. ADM with MMS will provide standards-based file HSM that could support any Solaris file system. The first consumer of ADM is ZFS will be the Solaris NAS offering. 1.6 SAM-QFS Differentiators 1.6.1 Reliability 1.6.1.1 Multiple Archive Copies The ability to create multiple archive copies of customer data onto alternate media (local or remote) helps mitigate against possible loss of data. Applications may retrieve a valid copy of that data seamlessly from among the collection of archived copies, even if some of those copies have been corrupted. 1.6.2 Availability 1.6.2.1 Seamless Storage Space Expansion The seamless archive, and release capabilities that are unique to the SAM-QFS filesystem help alleviate the impact to applications running at the filesystem full threshold. A SAM-QFS customer may define an archive policy for copying data from one storage medium to another (for example, when a file has not been accessed in a defined timeframe). That customer may configure a release policy (for example, when the available space reaches some threshold) to free the space that the archived data consumed on the original storage medium. That freed space may then be re-allocated to hold additional customer data. 1.6.2.2 Shared Filesystem Failover The MDS failover capability, that is unique to the SAM-QFS filesystem in shared mode, helps minimize or eliminate downtime for SAM-QFS client host applications. A SAM-QFS filesystem in shared mode, with at least two MDS-capable hosts (i.e. that have functional connectivity to all metadata storage devices for that filesystem), may be configured such that, after an unacceptible period of primary MDS unresponsiveness, the responsibility for MDS services will be taken over by that filesystem's secondary MDS. 1.6.2.3 Efficient Data Recovery The SAM-QFS utility samfsdump takes advantage of the SAM-QFS architecture to quickly generate a back-up of filesystem metadata. This, together with SAM-QFS seamless data archiving, facilitates full or partial filesystem restoration after a catastrophic failure or accident. Periodic samfsdump back-ups can be scheduled easily via the SAM-QFS GUI or the Solaris cron utility. 1.6.3 Serviceability 1.6.3.1 Online Grow The SAM-QFS filesystem online grow capability permits an administrator to expand filesystem space without impacting filesystem dependent applications that are running during that procedure. 1.6.3.2 Online Shrink The SAM-QFS filesystem online shrink capability permits an administrator to eliminate damaged filesystem space without requiring that the filesystem be unmounted. Only applications that require access to that damaged space are impacted during this procedure. 1.6.4 Performance SAM-QFS is designed to serve data to the end-user applications at, or very near, line rate speeds. 1.6.5 Scalability A shared filesystem SAM-QFS environment will scale up to 1024 client nodes. 2.0 SAM-QFS Components 2.1 SAM-QFS Kernel Modules samfs - QFS Filesystem. samaio - QFS pseudo Device Driver for asynchronous I/O. samioc - SAM-QFS pseudo Device Driver for ioctl system call interface. samst - SAM device driver for SCSI media changers and optical drives. 2.2 SAM-QFS Daemons and Processes The following SAM-QFS GUI related daemons are present during SAM-QFS operations: fsmgmtd - File System Manager daemon. The File System Manager software is a browser-based graphical user interface that enables you to configure, control, protect, and monitor one or more file systems in your network from a central location. fsmdb - Recovery point daemon used by the GUI to enable indexing and browsing recovery points and restore of individual files and directories. This daemon is started as needed. QFS filesystem and SAM daemons are listed below. Indentation indicates a parent-child relationship. /usr/lib/fs/samfs/sam-fsd - Master (file system) daemon. Initializes the SAM-QFS environment and performs various tasks including configuration management, trace file management, and daemon startup management for sam-sharefsd, sam-archiverd, sam-stagerd, sam-stagealld, sam-rftd, sam-amld. sam-fsd is started by init(1M) using an entry in /etc/inittab, or may alternatively be managed via SMF, but not both. sam-sharefsd - Shared file system daemon (per shared file system). Manages communication between the MDS and the shared clients. sam-archiverd - Archiver daemon. Manages archiving of files. sam-arfind - Process (per file system) that monitors file system archive events and manages archive requests. sam-arcopy - Process (per available drive) that copies files from the file system to archive media. sam-stagerd - Stager daemon. Manages staging of files. sam-stagerd_copy - Process (per available drive) that copies files from archive media to the file system. sam-stagealld - Associative staging daemon. Manages associative staging of files. sam-recycler - Archive media recycler process. Reclaims available space on archive media for expired archive copies. sam-releaser - Disk space releaser process. Makes disk cache available by identifying archived files and releasing their disk cache space. sam-rftd - File transfer daemon. Used for transferring file data to and from a remote network site (for remote disk archiving and SAM-Remote configurations). sam-amld - Automatic media library daemon. Starts and manages the execution of the following SAM daemons. sam-catserverd - Media manager (removeable media catalog) daemon. sam-rpcd - RPC API server daemon. Manages the remote procedure call (RPC) application programming interface (API) (libsamrpc). sam-scannerd - Monitors all manually mounted removable media devices. sam-robotsd - Robots daemon. Starts and manages the execution of the media changer library control daemons. sam-genericd - Generic media changer daemon. Manages the direct-attached SCSI, ADIC/Grau, and Fujitsu LMF media changers. sam-stkd - STK media changer daemon. Manages the STK network-attached tape libraries using ACSAPI interface. /opt/SUNWsamfs/sbin/ssi_so - STK ACSAPI client daemon. sam-stk_helper - STK ACSAPI command daemon. sam-ibm3494d - IBM media changer daemon. Manages the IBM network-attached tape libraries using DAS interface. /opt/SUNWsamfs/lib/libibmlmcp.so - IBM DAS client daemon. sam-sonyd - Sony media changer daemon. Manages the Sony network-attached tape libraries using DZC-8000S interface. /opt/SUNWsamfs/lib/libpsc.so - Sony DZC-8000S client daemon. sam-clientd - SAM-Remote client daemon. Used for maintaining the removable media catalog between the SAM-Remote server and clients. sam-serverd - SAM-Remote server daemon. Used for maintaining the removable media catalog between the SAM-Remote server and clients. 2.3 Packages and RPMs Available packages for Solaris are: Package Description ------------ ----------- SUNWqfsr QFS root pkg SUNWqfsu QFS usr pkg SUNWsamfsr SAM-QFS root pkg SUNWsamfsu SAM-QFS usr pkg SUNWsamfswm SAM-QFS package additions for WORM support SUNWfsmgrr FS MGR root pkg SUNWfsmgru FS MGR usr pkg NOTE: SUNWqfsr/SUNWqfsu and SUNWsamfsr/SUNWsamfsu are mutually exclusive. Avaliable shared QFS client RPMs for Linux are: Linux X64: (10 total) --------------------- RH5 RH4U2 through RH4U4 RH3U5 through RH3U8 S10FCS S9SP2 S8SP4 Linux X86: (4 total) -------------------- RH3U5 through RH3U8 Linux IA64 (Altix) (1 total) ---------------------------- S9SP2 2.4 Databases Sleepycat Software's Berkeley DB is used by SAM to store the disk archive volume catalog. It is also used by the File System Manager to store the information needed by the recovery point feature and metrics displays. 2.5 Files and Directories /etc/fs/samfs/mount /etc/fs/samfs/umount /etc/init.d/samfs.shared /etc/rc0.d/K41samfs.shared /etc/rc2.d/S73samfs.shared /etc/sysevent/config/SUNW,SUNWsamfs,sysevent.conf 2.6 Drivers and Driver Configuration Files /kernel/drv/samaio /kernel/drv/samaio.conf /kernel/drv/samioc /kernel/drv/samioc.conf /kernel/drv/samst /kernel/drv/samst.conf /kernel/drv/amd64/samaio /kernel/drv/amd64/samioc /kernel/drv/amd64/samst /kernel/drv/sparcv9/samaio /kernel/drv/sparcv9/samioc /kernel/drv/sparcv9/samst 2.7 Loadable Kernel Modules: /kernel/fs/samfs /kernel/fs/amd64/samfs /kernel/fs/sparcv9/samfs 2.8 Device Link Generators: /usr/lib/devfsadm/linkmod/SUNW_samaio_link.so /usr/lib/devfsadm/linkmod/SUNW_samst_link.so 2.9 File System Specific Wrappers /usr/lib/fs/samfs/bcheck /usr/lib/fs/samfs/fsck /usr/lib/fs/samfs/fstyp /usr/lib/fs/samfs/libsamconf.so /usr/lib/fs/samfs/mkfs /usr/lib/fs/samfs/mount /usr/lib/fs/samfs/ncheck /usr/lib/fs/samfs/sam-fsd /usr/lib/fs/samfs/samfsdump /usr/lib/fs/samfs/samfsrestore /usr/lib/fs/samfs/i386/fsck /usr/lib/fs/samfs/i386/mkfs /usr/lib/fs/samfs/amd64/fsck /usr/lib/fs/samfs/amd64/mkfs /usr/lib/fs/samfs/amd64/libsamconf.so /usr/lib/fs/samfs/sparcv7/fsck /usr/lib/fs/samfs/sparcv7/mkfs /usr/lib/fs/samfs/sparcv9/fsck /usr/lib/fs/samfs/sparcv9/mkfs /usr/lib/fs/samfs/sparcv9/libsamconf.so /usr/lib/fs/samfs/umount 2.10 Message Catalog /usr/lib/locale/C/LC_MESSAGES/SUNWsamfs 2.11 SNMP Trap and E-mail Alert Handlers /usr/sfw/bin/notify /usr/sfw/bin/tapealert_log /usr/sfw/bin/tapealert_trap 2.12 SNMP MIB files /var/snmp/mib/* 2.13 SMF Manifest Files FS Manager Daemon: /var/svc/manifest/application/management/ 2.14 Configuration Files /opt/SUNWfsmgr/samqfsui/tmp/host.conf /etc/opt/SUNWfsmgr/* /etc/opt/SUNWsamfs/* /var/log/webconsole/host.conf 2.15 Command Directories /opt/SUNWfsmgr/bin/* /opt/SUNWsamfs/bin/* /opt/SUNWsamfs/sbin/* /opt/SUNWsamfs/sbin/i386/* /opt/SUNWsamfs/sbin/amd64/* /opt/SUNWsamfs/sbin/sparcv7/* /opt/SUNWsamfs/sbin/sparcv9/* /var/sadm/samqfsui/* 2.16 Documentation and Examples /opt/SUNWfsmgr/doc/* /opt/SUNWfsmgr/man/* /opt/SUNWsamfs/doc/* /opt/SUNWsamfs/man/* /opt/SUNWsamfs/examples/* 2.17 Include Files /opt/SUNWsamfs/include/* 2.18 RPC API Client Files /opt/SUNWsamfs/client/* 2.19 Relocatable Libraries /opt/SUNWsamfs/lib/* /opt/SUNWsamfs/lib/amd64/* /opt/SUNWsamfs/lib/sparcv9/* /usr/lib/libfsmgmtrpc.so /usr/lib/libfsmgmtjni.so 2.20 Migration Toolkit Files /opt/SUNWsamfs/migkit/* 2.21 SunCluster Agent Directories /opt/SUNWsamfs/sc/* 2.22 Unsupported Tools Directories /opt/SUNWsamfs/unsupported/samsnoop/* 2.23 Library Error Code Handler Tables /var/opt/SUNWsamfs/errcodes/* 2.24 Device Catalogs, Trace and Log Files /var/log/webconsole/console/* /var/opt/SUNWsamfs/* 2.25 SAM-QFS GUI Miscellaneous Files /opt/SUNWfsmgr/* (including images, xml, jsp, html, etc.) 2.26 Set-User-ID Executables SAM-QFS does not introduce any new setuid executables. 3.0 System Administration 3.1 Administration Requirements Installation, configuration, and upgrades are performed by an appropriately authorized administrive user. Thorough knowledge of Solaris Administration is highly recommended. 3.2 Installation and Upgrades In general, SAM-QFS installation and upgrades on Solaris are accomplished by installing or updating all SAM-QFS packages using the pkgadd/patchadd utilities. Installation and upgrades of the SAM-QFS client on Linux are accomplished by installing or replacing all SAM-QFS RPMs using the SAM-QFS RPM scripts Install and Uninstall. The SAM-QFS installation and upgrade procedures are documented in the SAM and QFS Installation and Upgrade Guides and relevant patch README files. For current details, see: http://docs.sun.com/app/docs/coll/qfs4.6 and http://docs.sun.com/app/docs/coll/sam4.6 SAM-QFS GUI installation and upgrade is done via the fsmgr_setup script. Sun ships, or provide for download, a CD Image to the customer. This image contains the packages for each Solaris platform and architecture. The fsmgr_setup script installs the appropriate GUI packages based on the server and sets up the necessary RBAC authorizations. The Sun Java Web Console (Lockhart) will be installed/upgraded if the minimum version is not already installed. The SAM-QFS GUI is delivered in the SUNWfsmgru/r packages but has dependencies on additional software. For the convenience of the user an installation script 'fsmgr_setup' is provided. This script can be used to install, upgrade or remove the SAM-QFS GUI. The script checks on the dependencies and will install the needed software if it is missing. See section 3.2.1 "Dependencies" below for more information. 3.2.1 Dependencies 3.2.1.1 This Section Intentionally Omitted 3.2.1.2 System Requirements SAM-QFS runs on all SPARC, AMD64, and EM64T Solaris platforms. Shared QFS client runs on x86 Solaris platforms. Shared QFS client also runs on x86, AMD64, EM64T, and SGI Altix Itanium Linux platforms. The SAM-QFS product provides unbundled Solaris packages for the following systems: Solaris 9 SPARC Solaris 10 SPARC Solaris 10 AMD64 (also supports EM64T) Solaris Nevada SPARC Solaris Nevada AMD64 (also supports EM64T) The SAM-QFS product also provides shared QFS client RPMs for a variety of Linux platforms (see section "2.3 Packages and RPMs" above). For more details on supported Linux configurations, installation and configuration, see the supplied Linux Client Guide (CustomerDocs/LinuxClientGuide.pdf). **NOTE** The SAM-QFS GUI cannot be run on SAM-QFS Linux clients. 3.2.1.3 Global System Tables SAM-QFS does not require installation within any global system tables. 3.2.1.4 Naming Services NIS and NIS+ can optionally be used. The SAM-QFS shared file system daemon sam-sharefsd, RPC API server daemon sam-rpcd, and sendtrap(1M) may use these. The SAM-QFS GUI runs in the Sun Java Web Console which uses the naming services to authenticate users and determine their authorizations. 3.2.1.5 Java The SAM-QFS GUI depends on the Sun Java Web Console version 3. Sun Java Web Console version 3 depends on JDK 1.5. Both Sun Java Web Console version 3 and JDK 1.5 are provided with the distribution CD (or downloadable image). If a suitable Sun Java Web Console Lochart version is not present the users will be asked if they wish to upgrade it. The newer version of Lockhart is backwards compatible with the older ones. If the user answers yes that they wish to upgrade- the fsmgr_setup script executes the Sun Java Web Console setup script. This searches for a suitable JDK on the system. If JDK 1.5 or newer is not found, the console setup script will install JDK 1.5. It does so without removing the existing JDKs. The console will continue working even if other JDKs are installed subsequently. 3.2.1.6 Kernel Features SAM-QFS is dependent on the kernel features only that are provided by default with the Solaris (or Linux) kernel. 3.3 Configuration and Re-Configuration SAM-QFS configuration is performed by an appropriately authorized administrative user. A thorough configuration guide is necessary. It is the responsibility of the system administrator to know and understand Solaris Administration. SAM-QFS GUI configuration is done via the fsmgr_setup script. Sun ships, or provide for download, a CD Image to the customer. This image contains the packages for each Solaris platform and architecture. The fsmgr_setup script installs the appropriate GUI packages based on the server and sets up the necessary RBAC authorizations. The Sun Java Web Console (Lockhart) will be installed/upgraded if the minimum version is not already installed. The SAM-QFS GUI simplifies the configuration experience for new users through the use of a First-Time Configuration Checklist and wizards to configure automated libraries, file systems and archive policies. Together these reduce the need for new users to become familiar with the syntax and relationships between the SAM-QFS configuration files. **NOTE** The SAM-QFS GUI cannot be run on SAM-QFS Linux clients. Also, there is no management daemon for SAM-QFS Linux client hosts so the SAM-QFS GUI cannot be used to configure shared SAM-QFS filesystems from Linux clients. However, some basic information about Linux clients can be displayed in the SAM-QFS GUI on the MDS. 3.4 Diagnostic Procedures and Tools Unanticipated SAM-QFS behavior is typically characterized by unusually slow I/O performance. The following procedures and tools are available to determine the health of your SAM-QFS filesystem: 3.4.1 SAM-QFS GUI The GUI provides a monitoring console where the status of the libraries, drives, file systems, archive volumes(tape and disk), archive media utilization, and the archiver stager and releaser work queues are available. Items that are behaving outside of the expected range will be flagged. For example: file systems over their space high water mark would be flagged, archive sets that are running out of archive media are flagged. The SAM-QFS GUI prominently displays faults that may be at the root of a problem and allows administrators to register for e-mail alerts. The SAM-QFS GUI provides the ability to collect file system and archive media utilization statistics. Archive media utilization statistics are generated on demand. File system utilization data collection can be done during recovery point generation or can be scheduled separately. This data is used to provide graphs of file distribution by age, size, owner, group and the quantity of data within the various tiers of storage. 3.4.2 E-Mail Alerts Administrators can register for SAM-QFS e-mail alerts via the SAM-QFS GUI or via the CLI notify facility. There are 10 conditions that will result in an e-mail alert: 3.4.2.1 File System Alerts No space available on file system File system exceeded its high water mark Error generating a scheduled recovery point Warning when generated a scheduled recovery point. 3.4.2.2 Media Alerts A library or tape drive is marked down A requested volume is unavailable ACSLS errors ACSLS information or warning 3.4.2.3 Archive Alerts Archiving is interrupted Recycling is complete 3.4.3 SAM-QFS Trace Files SAM-QFS can be configured to have each key process (e.g., daemon, etc.) create and write to a process-specific trace file in the directory /var/opt/SUNWsamfs/trace. 3.4.4 SAM Log File SAM-QFS can be configured to create the general SAM log file /var/adm/sam-log, that contains key information written by a variety of SAM processes. 3.4.5 Third-Party Log Files SAM-QFS third-party device-specific (e.g., tape robot, etc.) log files, are written by third-party software in the directory /etc/opt/SUNWsamfs/devlog. 3.4.6 Critical SAM-QFS Messages Critical SAM-QFS filesystem messages are written to both the file /var/adm/messages, and to the system console. 3.4.7 SAM-QFS Administrative Tools The primary SAM-QFS administrative tools are: /opt/SUNWsamfs/sbin/samu - Facilitates observation of filesystem data, state, statistics, SAM status, etc. /opt/SUNWsamfs/sbin/samexplorer - Outputs key SAM-QFS config, debug, and core file info /opt/SUNWsamfs/sbin/showqueue - Displays SAM archiver and stager queue status /opt/SUNWsamfs/sbin/archiver - The -lv arguments force validation of the SAM archiver configuration 3.4.8 SAM-QFS MIB The SAM-QFS code base provides the definition of a SAM-QFS MIB. A customer-provided SNMP agent may gather SAM-QFS statistics, state, and associated errors via that MIB, and perform customer defined actions. SNMP Traps are provided for file system, archiver, device errors and tape alerts. The specific events are documented in the SAM-QFS MIB file installed at: /var/snmp/mib/SUN-SAM-MIB.mib 3.4.9 User Error Codes User applications will receive standard Solaris error codes from the SAM-QFS filesystem to indicate success or failure status. NOTE: While SAM automated space expansion is in progress, an application that is requesting unavailable storage space may experience a temporary delay, instead of receiving an ENOSPC error, until the requested amount of space is reserved. 3.4.10 Message Catalog System SAM-QFS software has used the catgets() interface into a message catalog translation system since before the gettext() interface became the standard within Solaris. Its use is fairly pervasive, so the risk of conversion to gettext() may be too high for minimal customer benefit, unless a full internationalization/localization effort is undertaken. 3.5 Maintenance - Periodic file system checks using samfsck. - If SAM is used, periodically ensure that archiving media is available, and check for errors. - Periodic rotation of SAM-QFS log files. This may be accomplished with a crontab entry and the commmand log_rotate(1M). An example is provided in the SAM-QFS examples directory /opt/SUNWsamfs/examples. - Periodic rotation of SAM-QFS daemon trace files. This is managed via the sam-fsd daemon according to the SAM-QFS configuration specified in the file /etc/opt/SUNWsamfs/defaults.conf, and the command trace_rotate(1M). 3.6 Exported Tunable Parameters SAM-QFS architects recognize the supreme benefit of exporting only a small set of very powerful tunable parameters. While in traditional, general-purpose computing environments, this is a common expectation, it has often been a deficiency in the many unique and specialized SAM-QFS computing environments. Historically, key (large) customers have often requested the ability to tune filesystem performance directly to their unique job requirements. This has led those familiar with mainly general-purpose computing environments to be overwhelmed by the quantity of SAM-QFS tunables. To mitigate this, the default values for the tunables have been selected such that they are appropriate for more general-purpose SAM-QFS computing environments. The SAM-QFS GUI takes advantage of this and simplifies the user experience by presenting a sub-set of the tunables as advanced options in the wizards and configuration screens. The full set of tunables that are available through configuration files are considered a strategic, competitive advantage of SAM-QFS for government and commercial high-performance computing (HPC) customers. SAM-QFS tunable parameters are defined in the following files under the /etc/opt/SUNWsamfs directory. Each has an associated man page, as well as additional documentation in the SAM-QFS manuals. These do not require a system reboot. defaults.conf archiver.cmd ftp.cmd notify.cmd nrecycler.cmd preview.cmd recycler.cmd releaser.cmd rft.cmd samfs.cmd stager.cmd The following Common Solaris tunable parameters are described in the SAM and QFS Installation Guides: /etc/syslog.conf - sam-log logging facility (no reboot) /kernel/drv/st.conf - tape drive support (no reboot) The following Common Solaris tunable parameters are described in the SAM and QFS Administration Guides: /etc/system - samfs:ninodes - number of inodes (reboot) /etc/system - samfs:nhino - in-core inode hash table (reboot) Additional Solaris system parameters can be tuned to optimize performance of the system. These parameters are described in the "Advanced Topics" section of the SAM and QFS Administration guides. 3.7 Performance Tuning In addition to appropriate configuration of exported SAM-QFS tunable parameters, SAM-QFS performance tuning is accomlished by configuring the filesystem parameters during filesystem creation and filesystem mount time that best support the style of applications that the customer will run. For option details, see the following man pages: sammkfs(1M) mount_samfs(1M) 3.8 Un-Install Use the pkgrm/patchrm utilities to uninstall the Solaris SAM-QFS root and user software. On Linux clients, use the RPM script Uninstall. The SAM-QFS The GUI is removed using the script fsmgr_uninstall script. Which uninstalls the packages and prompts the user to see if they want to remove the RBAC authorizations added during installation. 3.9 Sun Standard System Administration Framework 3.9.1 Roles, Authorizations, Rights Profiles The SAM-QFS GUI adds five authorizations to the Solaris authorization description database (/etc/security/auth_attr). These authorizations can be granted to profiles, roles or users. During installation they are granted to the root user. The GUI checks the authorizations to determine the operations that a user will be allowed perform. Operations for which a user is not authorized will be grayed out (not selectable) in the GUI. The following authorizations are added: com.sun.netstorage.fsmgr.config com.sun.netstorage.fsmgr.operator.media com.sun.netstorage.fsmgr.operator.sam.control com.sun.netstorage.fsmgr.operator.file com.sun.netstorage.fsmgr.operator.filesystem SAM-QFS also uses root ownership, administrative group IDs, and appropriate file permissions to control the usage of administrative commands. 3.9.2 Solaris BSM Administrative Auditing SAM-QFS uses the Solaris BSM secpolicy() interface for privilege validation. To ensure that the use of privilege is audited only when privilege is actually applied, SAM-QFS is structured to issue secpolicy() calls only after normal privilege rights checks fail. SAM-QFS administrative auditing audits only the "use of privilege", as provided via the secpolicy() interface. 3.9.3 Solaris Management Console(SMC) and Web-Based Management(WBEM) The SAM-QFS GUI runs on the Sun Java Web Console (Lockhart). 4.0 SAM-QFS Behavior 4.1 System Boot SAM-QFS is not currently a bootable (i.e. root) filesystem. However, as with any other supported filesystem type, it may optionally be automounted during system boot time. To have a negligible affect on system boot time, it is expected that each automounted SAM-QFS filesystem host is appropriately configured with access to all required filesystem devices, and that each automounted SAM-QFS filesystem client host has access to its MDS. SAM-QFS filesystem automount is managed via the SMF facility. Filesystem misconfiguration may lead to a timeout condition delay during system boot, the behavior of which is consistent with other filesystem types. 4.2 SAM-QFS Startup 4.2.1 SAM-QFS GUI The management daemon 'fsmgmtd' for the SAM-QFS GUI uses SMF on Solaris 10 and Nevada. The service "application/management/fsmgmt" and its dependencies are defined in: /var/svc/manifest/application/management/fsmgmt.xml On Solaris 9 it adds the following entry in the inittab: sfad:3:respawn:/opt/SUNWsamfs/sbin/fsmgmtd 4.2.2 SAM-QFS Master Filesystem Daemon Upon SAM-QFS package install, the SAM-QFS master filesystem daemon (sam-fsd) is activated upon the first mount of a SAM-QFS filesystem. It will accept connections only from the local host, and can be administratively disabled using the command fsadm config -n. The SAM-QFS 5.0 sam-fsd daemon will be started by SMF on Solaris 10 and Nevada. The service manifest will be located at: /var/svc/manifest/system/sam-fsd.xml On Solaris 9, the sam-fsd daemon is managed by init via an entry in /etc/inittab, added upon sam-fsd startup, as: sf:023456:respawn:/usr/lib/fs/samfs/sam-fsd 4.2.3 Other SAM-QFS Processes Other SAM-QFS processes are activated upon the first mount of a SAM-QFS filesystem is mounted, as initiated by the sam-fsd daemon. 4.3 SAM-QFS Failure Conditions & Recovery 4.3.1 System Panic SAM-QFS software uses explicit calls to panic() only as a practical resiliency-improvement tool for a mature product. They exist only in code paths that are thought impossible to reach. When called, it is only the result of a significant oversight in SAM-QFS programming that must be repaired immediately. Down time as the result of an explicit call to panic() is rare (i.e. Statistically less than one occurrence per year across all customers). 4.3.2 System Reboot Condition The system requires a reboot only as the result of untimely network or device reconfiguration and/or power brown-outs. Neither case appears directly and completely addressable by the SAM-QFS product architecture. 4.3.3 SAM-QFS Filesystem Out of Space If archiving is enabled, user data may be archived and the filesystem space may be released according to the configured SAM-QFS policy. If archiving is not enabled, an application will receive and out-of-space error code return from the SAM-QFS filesystem. 4.3.4 SAM-QFS MDS Outage If a SAM-QFS filesystem is configured as shared, and a secondary MDS is available and properly configured, then failover may occur to the secondary MDS, without impact to the filesystem client applications. 4.3.5 SAM-QFS Storage Device Failure An appropriate error code will be propagated from the device or network layer through the SAM-QFS filesystem, and returned to the application. 4.3.6 SAM-QFS Configuration Errors When the SAM-QFS configuration is changed via the GUI, backups of the previous configuration files are made. Up to 25 copies of each file that can be modified through the GUI are kept. In the event of a total or partial failure, these backups can be used to restore the configuration to its previous state. 4.3.7 Network Failures SAM-QFS communication to a failed host, device, or via a failed network link is attempted until time-out occurs. After time-out, an appropriate error is returned to the application. In shared SAM-QFS mode, if communication with the MDS fails, and a secondary MDS is available, then shared QFS filesystem failover occurs. When the SAM-QFS GUI encounters network communication failures it reports an error that informs the user of things to check determine and remedy the cause. 4.3.8 Configuration Corruption SAM-QFS configuration files and binaries reside on other filesystem types, and are subject to the integrity mechanisms provided by those filesystems (e.g., journaling, etc.). Those critical to system security are restricted to privileged access only. SAM-QFS processes that parse those configuration files perform syntax validation, will notify the administrator via log/trace files in case of error. Those processes safely avoid completion of their functions in case of error. 4.3.9 Management File Re-Use Upon restart or failover, SAM-QFS processes are not impacted by old locks and management files. 4.3.10 Checkpoint/Restart SAM-QFS does not support the ability to checkpoint and restart its affiliated processes. 4.4 Interaction with Other Solaris Features 4.4.1 Solaris Dynamic Reconfiguration (DR) SAM-QFS is tolerant of CPU and memory DR events. SAM-QFS is not reliably tolerant of storage devices undergoing DR. 4.5 UNIX Operational Environment 4.5.1 Environment Variables Core SAM-QFS behavior uses the following environment variables: Name Purpose ------------------ ---------------------------------- PATH Search paths for commands LD_LIBRARY_PATH Search paths for libraries to load SAMHOST Optional hostname for sam_initrpc() library function. SAM_AWAIT_CLIENT Max time in seconds that the MDS will wait for all client hosts to unmount a shared QFS filesystem before it is unmounted on the MDS via umount(1m). 4.5.2 Commands and Command Exit Status See supplied SAM-QFS man page documentation for SAM-QFS commands detail, including exit status. Virtually all SAM-QFS commands conform to getopt() parsing requirements. 4.5.3 Signals SAM-QFS daemon management depends on signals to indicate the current state of a child daemon (i.e. child died) or desired daemon actions (e.g., re-read configuration after change, daemon stop, etc.). 4.5.4 Hidden Files Hidden files are neither created nor installed on the host system root filesystem (UFS, ZFS, Ext3, etc.) for SAM-QFS. Each SAM-QFS filesystem is formatted with the following hidden (and access-restricted) files in its root (mount point) directory: File Name I-Node Number Description --------- ------------- ----------------------------------- .inodes 1 File of inodes .blocks 3 File of small (4K) blocks .archive 5 Directory of removeable media files for archiving .stage 7 Directory of removeable media files for staging SAM-QFS reserves inode numbers 1 - 1023 for internal use. 4.5.5 Temporary Files When configuration changes are made in files through the SAM-QFS GUI, temporary configuration files are written so that they can be verified prior to writing the actual configuration. These files are created at /var/opt/SUNWsamfs/tmpfiles/fsmgmtd/ with a name that includes a random number. The files are automatically unlinked so the will not accumulate. 4.5.6 Lock Files The SAM-QFS GUI log facility uses a lock file. The lock is reset when the webserver is restarted. The lock file is located at: /var/log/webconsole/console/fsmgr.log.lck SAM-QFS processes create various lock files in /tmp to manage single instance access to controlled services. 4.5.7 Standard Forms Support for standard forms (e.g. "-display" for X programs) is not needed by the SAM-QFS GUI and SAM-QFS commands. The SAM-QFS GUI runs in a web browser so has no dependency on window/desktop operational environment other than requiring a web browser from the list of supported web browsers. 4.5.8 64-Bit Environment There are no known issues with SAM-QFS operation in a 64-bit environment. 4.5.9 Internationalization SAM-QFS is internationalized. 4.5.10 Localization SAM-QFS was localized somewhat in the SAM-QFS 4.0 release. However, that product localization was neither updated for subsequent minor releases nor SAM-QFS 5.0. 4.5.11 IPV6 Interfaces and Addresses All SAM-QFS software is IPV6 compatible. 4.5.12 ICCCM Compliance Not provided. This is not a known requirement for SAM-QFS software. Response to ICCCM client messages is also not supported for the same reason. 4.5.13 X Property Dependence None. This is not a known requirement for SAM-QFS software. 4.5.14 User Interface Facilities The SAM-QFS GUI supports cut/paste and the web browser's find and stop operations. Users can drag and drop text into entry fields in browsers that support it but the GUI does not support Drag and Drop of application objects. Extensive online Help is provided using JavaHelp. The online-help is also published separately in pdf format. Help is also available via SAM-QFS man pages and other product documentation. 4.5.15 Property Change Notification Response Not supported. This is not a known requirement for SAM-QFS software. 4.5.16 Window-System Toolkit/Desktop SAM-QFS does not depend on a window-system toolkit/desktop. This is not a known requirement for SAM-QFS software. 4.5.17 Remote Execution The SAM-QFS GUI can execute remotely. It is recommended that the SAM-QFS GUI be run within the SAM-QFS physically-secure environment, preferably with strong physical access accountability. The user accesses the SAM-QFS GUI through a web browser and must enter the host name in order to access it. The GUI provides the user with the ability to manage multiple SAM-QFS hosts. Once the user is logged into the GUI the user selects a host to manage. The name of the host being managed is displayed prominently in the upper left hand side of the application. 4.5.18 X Extensions Not supported. This is not a known requirement for SAM-QFS software. 4.5.19 Colormap Entries Not supported. This is not a known requirement for SAM-QFS software. 4.5.20 24-Bit Operation Not supported. This is not a known requirement for SAM-QFS software. 4.6.23 ToolTalk Not supported. This is not a known requirement for SAM-QFS software. 4.6.24 Redirection and Piping SAM-QFS commands interact well with standard Solaris commands. 4.6.25 Significant File Formats, Names, Syntax, and Semantics None. 4.6.26 Public Namespace SAM-QFS enforces a traditional UNIX filesystem public namespace, with the exception of hidden SAM-QFS files in the root mountpoint directory. 5.0 SAM-QFS Interfaces 5.1 Shared Libraries The SAM-QFS GUI's management servers use the following shared libraries: libsam libsamut libsamapi libgen libfsmgmt libnsl libintl libdl libcsn libsocket libc libdoor libdb-4.4 libgen libz libnsl libpthread.so The SAM-QFS filesystem commands and daemons use the following shared libraries: libsam libsamapi libsamcat libsamconf libsamdbg libsamfm libsamfs libsamftp libsamjumbo libsammgmt libsammgmtjni libsammig libsamos libsamrft libsamsanergy libsamspm libsamut 5.2 Static Libraries The SAM-QFS mount command uses static libraries. The Management GUI uses openssl and libcurl for product registration. The crypto export office required the use of static linking for these. 5.3 Imported and Exported Interfaces The SAM-QFS GUI does not export any code interfaces. A table of imported and exported interfaces, including stability levels, is provided below. These interfaces are classified according to the Interface Taxonomy -- e.g., "Committed," "Uncommitted," and "*Private" -- using the following format: Interfaces Imported Interface Classification Comments The_referring_standard Committed ANSI Xy.Tz 1999 draft 37 Somebody_else () Consolidation Private Interfaces Exported Interface Classification Comments My_subroutine_name Committed MY_MACRO Project Private Etc, etc, etc... NOTE: For Interface Taxonomy details, see: http://sac.sfbay/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp Interfaces Imported Interface Classification Comments --------- ------------------- -------- SAM-QFS API routines Unstable Documented in (3) and (3x) manpages as follows: The SAM-QFS API allows an SAM-QFS file to be requested from within an application program. The application program can reside either on the host upon which the Sun SAM-QFS file system is running or on another machine on the network. This man page provides an introduction to the Sun SAM-QFS routines. API Overview ------------ When a request is made, the process or program making the request is the client process or program, running on the client machine. The requests are received and processed by the server, running on the server, or host, machine. For the API routines, the server machine is always the machine upon which the Sun SAM-FS or SAM-QFS file system is running. In the simplest case, the client and server machines are the same, and no network communication is necessary. In other cases, however, the application programmer needs to allow for the client program to run on a machine where the Sun SAM-FS and SAM-QFS file system] is not running. In this case, networked library calls must be used. The two API libraries available with the Sun SAM-QFS file systems are: * libsam. The library calls in libsam do not perform network communication. They only make local requests. In this case, each library call makes a system call, and the server is the local operating system. * libsamrpc. The library calls in libsamrpc use Remote Procedure Calls (RPCs) to communicate with a special server process, sam-rpcd. Because of the RPC mechanism, the client and server can exist on the same machine or on different machines in the network. The server process always runs on the machine upon which the Sun SAM-QFS file system is running. Both libsam and libsamrpc are released in shared object (.so) and archive (.a) format for Solaris platforms. libsam.so and libsam.a are installed in /opt/SUNWsamfs/lib. libsamrpc.so and libsamrpc.a are installed in /opt/SUNWsamfs/client/lib, with symbolic links to them in /opt/SUNWsamfs/lib. API Library Routines -------------------- The library calls included in the Sun SAM-FS and SAM-QFS API include calls for the Sun QFS, SAM-FS, and SAM-QFS environments. In addition, some are supported in libsam and some are supported in libsamrpc. Table 1 lists the API library routines and indicates the environments in which they are supported. In addition, table 1 indicates the libraries in which they are included. All interfaces listed in table 1 adhere to the following interface taxonomy: Interfaces Imported Interface Classification Comments --------- ------------------- -------- SAM-QFS API routines Unstable Documented in (3) and (3x) manpages as follows: Table 1. Library routine availability Interfaces Imported Interface Classification Comments --------- ------------------- -------- SAM-QFS API routines Unstable Documented in (3) and (3x) manpages as follows: Routine Description ------- ----------- sam_advise Provides advice about expected behavior of an application when accessing data via the supplied file descriptor. Availability: QFS, and SAM-QFS Libraries: libsam. sam_archive Sets archive attributes on a file or directory. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_cancelstage Cancels the pending or in-progress stage of a file. Availability: SAM-QFS Libraries: libsam. sam_closecat Ends access to an automated library catalog. Availability: SAM-QFS Libraries: libsam. sam_closerpc Closes down the RPC connection that was originally created via sam_initrpc(). Availability: SAM-QFS Libraries: libsamrpc. sam_damage Marks archive copies of a file or directory as damaged. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_devstat, sam_ndevstat Gets status information of a SAM-QFS filesystem device. sam_ndevstat accepts a longer device name. Availability: SAM-QFS Libraries: libsam. sam_devstr Translates numeric device status into a character string. Availability: SAM-QFS Libraries: libsam. sam_exarchive Exchanges archive copies of a file or directory. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_getcatalog Retrieves a range of entries from the catalog of an automated library of the historian. Availability: SAM-QFS Libraries: libsam. sam_initrpc Initializes the RPC connection. Availability: SAM-QFS Libraries: libsamrpc. sam_lstat Retrieves file information for a symbolic link. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_opencat Accesses the VSN catalog for an automated library. Availability: SAM-QFS Libraries: libsam. sam_readrminfo Gets information for a removable media file. Availability: SAM-QFS Libraries: libsam. sam_rearch Sets rearchive attributes on a file or directory. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_release Releases and sets release attributes on a file. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_request Creates a removable media file. Availability: SAM-QFS Libraries: libsam. sam_restore_copy Creates an archive copy for a file. Availability: SAM-QFS Libraries: libsam. sam_restore_file Creates an offline file. Availability: SAM-QFS Libraries: libsam. sam_segment Sets segment attributes on a file or directory. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_segment_1stat Retrieves attributes of a segmented symbolic link. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_segment_stat Retrieves attributes of a segmented file. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_segment_vsn_stat Retrieves VSN information for a segmented file. Availability: SAM-QFS Libraries: libsam. sam_setfa Sets file attributes. Availability: QFS and SAM-QFS Libraries: libsam and libsamrpc. sam_ssum Sets checksum attributes on a file. Availability: SAM-QFS Libraries: libsam. sam_stage Stages and sets stage attributes on a file. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_stat Retrieves attribute information for a file that is neither segmented nor a symbolic link. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_unarchive Removes archive copies for a file or directory. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_undamage Clears damaged and stale status of archive entries of a file or directory. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_unrearch Removes rearchive attributes from a file or directory. Availability: SAM-QFS Libraries: libsam and libsamrpc. sam_vsn_stat Retrieves VSN information for an archive non-segmented file. Availability: SAM-QFS Libraries: libsam. The APIs for manipulating archive copies are supported for archiving to cartridges in libraries. They are not supported for disk archive copies. For more details about each library routine, see the individual corresponding man page for that routine. Library routines contained in libsam are found in section 3 of the online man pages. Library routines contained in libsamrpc are found in section 3X of the online man pages. 5.4 Exported Public Library APIs and ABIs See supplied SAM-QFS public documentation and man pages. 5.5 Protocols (Public or Private) The SAM-QFS GUI uses RPC to communicate with the management daemon running on a host being managed. This interface is classified as project private. Also, the management daemon communicates with the fsmdb recovery point daemon to get information from indexed recovery points. This interface is classified as project private. For the internal Shared QFS Protocol Specification, see provided "QFSprotocol.sxw" document. 5.6 Other Interfaces The following SAM-QFS/Solaris CLI commands are used by the SAM-QFS GUI/management software: /opt/SUNWsamfs/sbin/sam-fsd /opt/SUNWsamfs/sbin/samfsconfig /opt/SUNWsamfs/sbin/sammkfs /opt/SUNWsamfs/sbin/samgrowfs /opt/SUNWsamfs/sbin/samsharefs /opt/SUNWsamfs/sbin/samd /opt/SUNWsamfs/sbin/samfsdump /opt/SUNWsamfs/sbin/samcrondump /opt/SUNWsamfs/sbin/samcronfix /opt/SUNWsamfs/bin/stage /opt/SUNWsamfs/bin/release /opt/SUNWsamfs/bin/archive /opt/SUNWsamfs/sbin/samexplorer /usr/sbin/ifconfig -a /usr/sbin/cfgadm /usr/sbin/devfsadm /usr/sbin/smcwebserver /usr/sbin/unshare /usr/sbin/share /usr/sbin/mount /usr/sbin/umount /usr/sbin/newfs /usr/sbin/metastat -p /usr/sbin/metadb /usr/sbin/vxdisk -e list /usr/sbin/vxprint -hq /usr/sbin/zfs /usr/bin/crontab /usr/sbin/ping /usr/bin/gunzip /usr/bin/awk /usr/bin/sed /usr/bin/mailx /usr/proc/bin/ptree /usr/cluster/bin/scdidadm -L -o name -o host /usr/cluster/bin/scha_cluster_get 5.7 Reentrant Interfaces All SAM-QFS interfaces are reentrant. 5.8 Interoperation with Other Applications The SAM-QFS GUI provides a link to launch the SunPlex Manager GUI when the customer is managing a HA file systems in a cluster environment. 5.9 Interface Documentation All externally-available interfaces are clearly specified in publicly-available SAM-QFS technical documentation. 5.10 Interface Extensibility The project private interface between the SAM-QFS GUI and the management daemon will evolve as support is added for new functionality. Extension of the SAM-QFS filesystem interfaces is managed using feature bits. 5.11 Interface Versioning Version is handled by a system replacement using pkgrm/pkgadd. SAM-QFS software handles multiple versions of file system data structures. Specific versioning is managed by SAM-QFS software using hard-coded version identifiers in key file system data structures (e.g., superblock, inodes, directories, etc.). The project private interface between the SAM-QFS GUI and the management daemon has a version number that gets incremented with each interface change. The RPC server and clients check the interface levels. The client is written to handle the current released version and one released version back. The server is written to reject connection requests from clients running versions other than its own. The goal was to allow the management of multiple SAM-QFS hosts running at different release levels as long as the SAM-QFS client is the newest. Also, SAM-QFS 5.0 supports rolling upgrades. To facilitate this, the management GUI will display the current version for all clients of the file system. 5.12 Transition to Modified Interface All upgrade issues and procedures are described in the Installation and Upgrade manuals that accompany the release. See provided documentation. Transition to a new SAM-QFS version is managed via feature bits and rolling upgrades. 5.13 Interface Adaptation SAM-QFS has no direct relationship with multimedia components or desktop windowing software. The SAM-QFS GUI runs in a web browser, and is periodically updated to accomodate Java updates. None of the mentioned items is an issue for the SAM-QFS GUI. SAM-QFS is designed for computers that are part of a Storage Area Network and would not be appropriate for storage-less clients or nomadic computers. NFS-sharing of QFS and Shared-QFS filesystems is supported, with or without SAM. 6.0 Industry Interoperability 6.1 Standard Protocols NFS packages such as Samba and Butterfly are used to interact with the Microsoft platforms. SAM-QFS interoperates with NFS v3 and v4. No other network filesystems are currently supported. 6.2 Heterogeneous Environments SAM-QFS in shared mode supports clients for a number of RedHat Linux and SUSE Linux versions. On Linux distributions SAM-QFS uses the 'rpm' package manager. The shared SAM-QFS nodes do not need to know which clients are running Solaris and which are running Linux. Linux and Solaris SAM-QFS hosts can also perform automatic disk discovery. This is accomplished by walking through all configured raw devices, opening each and reading the location where a SAM-QFS superblock could be located, and verifying the result. Solaris hosts issue an extra ioctl to check for EFI labels. 6.3 Centralized Administration SAM-QFS allows only a Solaris node to be a SAM-QFS MDS. 7.0 SAM-QFS Performance 7.1 Impact to System Environment System overhead is impacted as with other unix file systems (e.g., the more files that are in a directory, the greater impact to metadata stat-type operations, etc.) On an MDS there are daemons which handle messages from the clients. These daemons may have a slight impact on the system load of the MDS, depending on the amount of traffic from the clients. We have no record of customer comments in regard to any impact on percieved performance due to these. SAM daemons and processes working in the background are usually tuned by the site administrators to do their heavy processing during a site's "idle" time. 7.2 Performance Expectations SAM-QFS strives to achieve near-wire throughput to the filesystem and to the tape libraries. The test team measures this as a part of every release cycle. 7.3 Negative Impacts to Applications A user application should never perceive a pause during I/O to the filesystem unless they have attempted to do I/O to an offline file, or when the archiving facility is actively recovering space for a full filesystem. In either event, an application will block in the I/O path while SAM reads the file from tape (for example) and puts it back on the disk, or releases the space used by already-archived data. Users of the SAM-QFS GUI may also experience a brief pause when creating large file systems. Other long running tasks are accomplished in the background freeing the user up to continue to use the application. 7.4 Multithreading Model Some utilities use libpthread. XXX Found in... src/archiver/lib/GNUmakefile src/fs/fsd/GNUmakefile src/fs/sharefs/GNUmakefile src/fs/tools/pdvt/GNUmakefile src/fs/tools/trace/GNUmakefile src/fs/tools/trace/GNUmakefile src/lib/sammgmt/GNUmakefile src/lib/sammgmt/rpc/client/GNUmakefile src/lib/samspm/GNUmakefile src/utility/fsmdb/GNUmakefile src/utility/fsmupd/GNUmakefile src/utility/samrestore/samcrondump/GNUmakefile Most operations performed through the SAM-QFS GUI are executed on the managed host in the RPC daemon's service thread. Longer running operations are executed in other threads returning control to the service thread. Status for these longer running operations is provided by the GUI in the Jobs section. 7.5 Impact to System Performance On an MDS without SAM there will be one sam-fsd on the system and one sam-sharefsd per mounted filesystem. The GUI has one fsmgmtd running, when the GUI is being actively used. When SAM is running there will be....? On a shared SAM-QFS client the impact on system performance is minimal and we have no records of customer comments in this regard. Under any configuration, a SAM-QFS node is expected to be dedicated to MDS duties and SAM duties and the exact impact on the system is determined by the amount of messaging and metadata work required to satisfy the client-induced workload. All SAM-QFS daemons and commands use shared libraries for their functionality. 7.6 SAM-QFS Process Management The archive processes use a time interval. For a complete description of the archiver in the System Administration manual. The filesystem-specific daemons may wait in the kernel on a CV, where the kernel may wake them up to handle necessary processing for an action (for example, to indicate the initiation of voluntary failover). The SAM daemons will wait in the kernel for various filesystem events, such as to stage a file back to disk. These wake-ups are in response to events, rather than due to time slices. The SAM-QFS GUI and management daemon are active only when users are connected. 7.7 Large Files/Databases None. 7.8 Growth of Needed Space Log and trace files will grow. SAM-QFS includes a log rotation and cleanup utility. The SAM-QFS GUI allows users to schedule the generation and indexing of samfsdumps to facilitate disaster recovery. The space consumed will grow over time as additional samfsdumps are collected. However, the schedule includes a configurable retention period allowing the user to avoid excessive resource utilization. 8.0 Security 8.1 Areas of Responsibility SAM-QFS is responsible for initializing and enforcing filesystem object access controls, enforcing privilege for filesystem operations, and protecting against the visibility of residual filesystem data. The SAM-QFS product addresses the following issues: - Filesystem Object Security Attribute Initialization - Filesystem Object Security Attribute Management - Filesystem Object Access Control Policy - User Data Protection - Filesystem Operations Privilege Policy - Filesystem Operations Audit Policy - Use of Privilege - Filesystem Network Security Policy Statement 8.2 Certifications The SAM-QFS filesystem was not included in the certified configuration of the Solaris BSM, nor as a component of any other formally evaluated secure computing base. Sun customers who use the SAM-QFS filesystem, or any other uncertified component, within their certified system configuration will invalidate their official certification. However, using SAM-QFS, or any other uncertified component, may be acceptible subject to the results of a risk assessment conducted by the customer's site security officer. 8.3 Solaris BSM With regard to maintaining the spirit of the Solaris BSM certification, the SAM-QFS filesystem addresses security-relevant areas as follows: 8.3.1 Filesystem Operations Audit Policy - Use of Privilege As a non-bootable (non-root) filesystem, SAM-QFS neither supports nor audits system identification and authentication (I & A) operations for the system on which it is mounted. For other security relevant events, SAM-QFS does not invoke the the Solaris BSM security audit interfaces directly. On Solaris 10 and later platforms, SAM-QFS determines the granting or denial of privilege via calls to appropriate secpolicy() interfaces. The result is audited only to the extent carried out via those secpolicy() interfaces, which are implemented outside the scope of SAM-QFS software. Calls to the secpolicy() interfaces within SAM-QFS, with with the exception of the vnode setattr operation, are architected to check for appropriate privilege only after all un-privileged access checks fail. Therefore, SAM-QFS does not promote unnecessary auditing of privilege results via the secpolicy() interfaces. On Solaris 9 platforms, SAM-QFS neither directly nor indirectly audits security-relevant events. 8.3.2 User Data Protection 8.3.2.1 Discretionary Access Control (DAC) Attribute Storage SAM-QFS stores the following DAC attributes for filesystem named-objects: Owning user ID Owning group ID Permissions mode (owner, group, other) Access control list * Default access control list (directory only) * * Access control lists conform to POSIX 1003.6 D12 specification 8.3.2.2 DAC Attribute Initialization Named-objects are created on a SAM-QFS filesystem via the following VOP interfaces: sam_create_vn sam_open_vn (with O_CREAT mode flag) sam_mkdir_vn sam_rename_vn (with target across filesystem mount points) sam_symlink_vn 8.3.2.3 DAC Policy Enforcement SAM-QFS enforces the following named-object DAC policy: The requested access mode (read, write, execute/search) is granted to a process if: - If the process' effective user ID matches the object's owning user ID, then: If the requested access mode is permitted by the object's permissions mode user mode bits, or the process has appropriate privilege to override that restriction, then the requested access is granted. Otherwise, access is denied. - Otherwise, if the object ACL has a user-type entry that matches the process' effective user ID: If the requested access mode is permitted by both the matching ACL entry and the ACL mask value, or the process has appropriate privilege to override that restriction, then the requested access is granted. Otherwise, access is denied. - Otherwise, if the process' effective group ID, or any of its supplementary group IDs, matches the object's owning group ID: If the requested access mode is permitted by the object's permissions mode user mode bits, or the process has appropriate privilege to override that restriction, then the requested access is granted. Otherwise, access is denied. - Otherwise, if the object ACL has any group-type entries that match the process' effective group ID or any of the group IDs in its group list: If the requested access mode is permitted by both the ACL mask value and any of the matching ACL entries, or the process has appropriate privilege to override that restriction, then the requested access is granted. Otherwise, access is denied. - Otherwise, If the requested access is permitted by the 'other' permissions mode bits, or the process has appropriate privilege to override that restriction, then the requested access is granted. Otherwise, access is denied. 8.3.2.4 Filesystem Object Residual Information Protection SAM-QFS assures that residual data on available SAM-QFS managed storage space is observable only as zeroes to processes upon re-allocation of that space. The exception to this is, when using direct I/O, for performance reasons residual data is zeroed only when the SAM-QFS filesystem has been mounted with the dio_szero mount option enabled. 8.3.3 Filesystem Object Security Attribute Management 8.3.3.1 DAC Attribute Revocation SAM-QFS permits modifying named-object DAC attributes via the following VOP interfaces: sam_setattr_vn sam_setsecattr_vn 8.3.3.2 DAC Attribute Revocation Policy SAM-QFS applies the following policy for modifying named-object DAC attributes: The process requesting the update must be the object's owner, or must have appropriate privilege to override that restriction. In addition, if the POSIX Restricted Chown semantics are enforced, then the process can neither give away its ownership of an object, nor change the owning group of an owned object to one in which that process is not a member, UNLESS the process has appropriate privilege to override those restrictions. 8.3.3.3 Set-User/Group-ID Revocation Policy SAM-QFS applies the following policy for modifying named-object set-user/group-ID bits: set-group-ID: If the requesting process is not the object's owner, and does not have appropriate privilege to override that restriction, then deny the request. Otherwise, if the supplied vnode attributes have the set-group-ID bit enabled, and the creating process is a member of the object's owning group, or the creating process has appropriate privilege to override that restriction, then set the object's set-group-ID bit. Otherwise, clear the object's set-group-ID bit. set-user-ID: If the requesting process is not the object's owner, and does not have appropriate privilege to override that restriction, then deny the request. Otherwise, if the supplied vnode attributes have the set-user-ID bit enabled, then set the object's set-user-ID bit. Otherwise, clear the object's set-user-ID bit. 8.3.4 Filesystem Object Security Attribute Initialization 8.3.4.1 DAC Attribute Initialization Policy Upon named-object creation, SAM-QFS initializes the object DAC attributes according to the following policy: Owning User ID: Set to creating process' effective user ID Owning Group ID: If the parent directory owning group is, or the creating process' group membership includes, the supplied vnode attribute group ID, or the creating process has appropriate privilege to override those restrictions, then set the new named-object's owning group to the supplied vnode attribute group ID. Otherwise, if the parent directory set-group-ID bit is set, then set the new named-object's owning group to the parent directory's owning group. Otherwise, set the new named-object's owning group to the creating process' effective group ID. Permissions Mode:Set to the supplied vnode attribute access mode (owner, group, other). ACL: Same as parent directory's default ACL, if any. Otherwise, same as owning user ID, owning group, and permissions mode above. Default ACL: (Directory only) Same as parent directory's default ACL, if any. Otherwise, none. 8.3.4.1 Set-User/Group-ID Attribute Initialization Policy Upon named-object creation, SAM-QFS initializes the object set-user/group-ID attributes according to the following policy: set-group-ID: If the supplied vnode attributes have the set-group-ID bit enabled, and the creating process is a member of the new named-object's owning group, or the process has appropriate privilege to override that restriction, then set the new named-object's set-group-ID bit. Otherwise, clear the new named-object set-group-ID bit. set-user-ID: Set the new named-object's set-user-ID bit to the value of the supplied vnode attributes set-user-ID bit. 8.3.5 Filesystem Network Security Policy Statement SAM-QFS client hosts, the SAM-QFS MDS host, filesystem storage devices, and tape robots, and management daemons communicate with each other across wired networks, using both industry standard and SAM-QFS proprietary protocols. Network traffic between SAM-QFS client hosts, their MDS, and storage devices (i.e. tape robot, tape drives, disks) is subject to exploitation by those with physical access to the environment. To protect SAM-QFS network traffic from exploitation, all network cables, network devices (i.e. switches, routers), HBAs and hosts must reside in a physically secure environment, preferably with strong physical access accountability. The SAM-QFS management GUI is web based. It should be run in the same physically secure environment, preferably with strong physical access accountability. Users connect to the host running the Sun Java Web Console using https. The GUI application running in the web console can be used to manage multiple hosts and uses RPC to connect to the managed hosts. If users wish to use the management GUI they must start the RPC management daemon on the hosts that they wish to manage and authorize the daemon to accept connections from the hosts running the Sun Java Web Console. 8.4 Access to SAM-QFS Resources 8.4.1 Identity Management User/process identities are authenticated, assigned, and supplied to the filesystem via standard interfaces from the host OS (Solaris or Linux). SAM-QFS processes that run on behalf of the user either inherit the identity of the user completely, or function as a privileged entity (i.e. to perform privileged operations) on behalf of the user. In either case, the user identity for security purposes is composed of an effective user ID, real user ID, saved set-user ID, and group membership IDs. SAM-QFS applies a process' user identity and granular privileges (if any) to access control policies via calls to the secpolicy() function. The OS (Solaris and Linux) securely controls whether or not a process may directly (i.e. via a set-id system call) or indirectly (i.e. via a set-id application) change its identity. SAM-QFS securely restricts the creation of set-id applications. Tampering with process identities, and set-id applications, is limited only to processes with appropriate privilege. Tampering with the network traffic that is associated with those entities is limited only to persons with the authority to access the physically secure environment, preferably with strong physical access accountability. Users of the SAM-QFS GUI are authenticated by the Sun Java Webconsole. Authentications are checked using the AuthorizationService classes from the Sun Java Webconsole. The SAM-QFS Management GUI also provides a user initiated product registration. During product registration the user enters their Sun Online Account ID and password. These are transmitted by SSL to the Sun's registration service. The password is never stored. Nor is it available from the command line or an environment variable and the memory locations in which the password is held are zeroed after use. 8.4.2 RPC Management Daemon The RPC management daemon will only accept connections from the local host or hosts that have been administratively added to its protected list of allowed hosts by running the fsmadm add command. When the management daemon recieves a request from a client it calls svc_getrpccaller() to obtain the identity of the caller and checks the result against the trusted list of allowed hosts. 8.4.3 Privilege by Proxy The user/process identities, supplied to the filesystem via standard interfaces from the host OS (Solaris or Linux), are assumed to be unmodified at the time of receipt, and since the initiation of transport, based on support from the site network and environment physical security policy. SAM-QFS daemons exercise appropriate privilege to complete restricted filesystem operations that are initiated at user-level. The SAM-QFS kernel tasks run with appropriate privileges to perform restricted kernel-relevant functions. 8.5 Install-Time Security 8.5.1 Administrator Input The SAM-QFS installation process via the pkgadd utility requires administrator input with no default choices provided. Secure execution is maintained no matter what input the adminidstrator provides. 8.5.2 Service Guidance SAM-QFS services are primarily comprised of components that manage communication for shared filesystem operations, and archive management. Those services use protected socket connections and the TCP protocol. SAM-QFS satisfies service guidance category SVC3. SAM-QFS is automatically used in a way that satisfies all of the minimum security requirements: IN1, IN2, OUT1, OUT2, and OUT3. Furthermore, where filesystem permissions are used for access control, the permissions set by the installation permit owner access only. 8.5.3 File System Guidance SAM-QFS satisfies file system guidance categories F1-F7. Named filesystem objects are installed and maintained with appropriate permissions at all times. 8.5.4 Other Guidance SAM-QFS satisfies other guidance category OTH1. SAM-QFS installation procedures may be accomplished only by an administrator with the minimum required privileges.