1 # 2 # CDDL HEADER START 3 # 4 # The contents of this file are subject to the terms of the 5 # Common Development and Distribution License (the "License"). 6 # You may not use this file except in compliance with the License. 7 # 8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 # See the License for the specific language governing permissions 10 # and limitations under the License. 11 # 12 # When distributing Covered Code, include this CDDL HEADER in each 13 # file and include the License file at usr/src/OPENSOLARIS.LICENSE. 14 # If applicable, add the following below this CDDL HEADER, with the 15 # fields enclosed by brackets "[]" replaced with your own identifying 16 # information: Portions Copyright [yyyy] [name of copyright owner] 17 # 18 # CDDL HEADER END 19 # 20 21 # 22 # Copyright 2009 Sun Microsystems, Inc. All rights reserved. 23 # Use is subject to license terms. 24 # 25 26 Overview 27 -------- 28 29 This "nfsv4" is a general test framework consists of different tests for 30 testing NFSv4 server and client. Test sub-directories include : 31 32 acl - access control list tests 33 basic_ops - server tests of basic operations for RFC3530 34 num_attrs - number attribute tests 35 named_attr - named attribute tests 36 other_tests - uidmapping and I18N 37 recovery - client recovery and server unshare tests 38 srv_namespc - server namespace tests 39 40 The tests under these subdirs are written in different programming languages, 41 including C, Shell(s) and TCL that uses "nfsv4sh" tool. Makefiles are 42 provided to build and install the executables to the "proto" directory or 43 package for execution. Scripts are also included for automation of setup 44 and cleanup. 45 46 47 Requirements 48 ------------ 49 50 The following requirements must be met before running the tests: 51 52 1) Require minimum of two systems, a localhost and a remote host. Both 53 systems under test must be able to 'rsh' to each other as root. 54 55 2) Must be "root" to run the setup and cleanup and the recovery tests. 56 57 3) Define the following required environment variables. For those 58 that are optional, if not set, the default value will be used: 59 60 setenv SERVER remote_host_w/NFSv4_available (required) 61 No default for this variable 62 setenv LOGDIR the_result_logs_directory (optional) 63 default is /var/tmp/nfsv4-test/results 64 setenv DNS_SERVER a_DNS_server_accessed_by_all_systems (optional) 65 default is jurassic.eng.sun.com 66 67 4) TCL (Tools Command Language, tcl8.5), must be available or 68 installed in the localhost before building and running the tests. 69 70 5) If run on opensolaris, please make sure the SUNWhea (SunOS Header Files) 71 package is installed or the related headers are available on the server, 72 otherwise, the uidmapping_stress01 test will fail. 73 74 75 Other setup (optional) 76 ---------------------- 77 78 There are several test filesystems required for testing. The tests 79 currently support two types of filesystem, one is ZFS, the other is UFS. 80 81 By default, tests itself will detect automatically the filesystem type of 82 BASEDIR on SERVER. 83 If filesystem type is ZFS, tests will run over ZFS; 84 If filesystem type is UFS, tests will run over UFS; 85 Otherwise, tests will print error message and exit. 86 setenv BASEDIR a_base_testing_directory_in_server (optional) 87 default is /NFSv4Test 88 89 If SERVER is zfs boot, and you also want to run the tests over UFS, 90 you must provide a dir based on UFS and define BASEDIR as the following: 91 setenv BASEDIR your_ufs_dir_in_server 92 93 Similarly, if SERVER is ufs boot, and you also want to run the tests over ZFS, 94 you must provide a dir based on ZFS and define BASEDIR as the following: 95 setenv BASEDIR your_zfs_dir_in_server 96 97 If tests would be run over UFS, by default they will be setup using LOFI (but 98 NOTE that the LOFI setup will be lost if you reboot the SERVER). If you prefer 99 not to use LOFI setup, but to supply your own real filesystems, you must provide 100 the following filesystems and UFS mount them to the correct directory names. 101 BASEDIR the base testing directory, default is /NFSv4Test 102 PUBTDIR to $BASEDIR/PublicFS, e.g. /NFSv4Test/PublicFS 103 ROOTDIR to $BASEDIR/RootFS, e.g. /NFSv4Test/RootFS 104 ROFSDIR to $BASEDIR/RoFS, e.g. /NFSv4Test/RoFS 105 NSPCDIR to $BASEDIR/NoSPC_FS, e.g. /NFSv4Test/NoSPC_FS 106 (where NSPCDIR must be a small filesystem, e.g. 3MB) 107 KRB5DIR to $BASEDIR/KRB5C_FS, e.g. /NFSv4Test/KRB5C_FS 108 SSPCDIR to $BASEDIR/SRVsp_FS, e.g. /NFSv4Test/SRVsp_FS 109 SSPCDIR2 to $SSPCDIR/hide/SRVsp_d2 110 e.g. /NFSv4Test/SRVsp_FS/hide/SRVsp_d2 111 SSPCDIR3 to $SSPCDIR2/hide2/SRVsp_d3 112 e.g. /NFSv4Test/SRVsp_FS/hide/SRVsp_d2/hide2/SRVsp_d3 113 114 Tests may fail unexpectedly if these test filesystems are not pre-setup 115 correctly when not using LOFI. 116 117 Sometimes during the recovery tests the server is not visible on the network 118 for several minutes after the server has rebooted. This causes some of the 119 tests that are intended to run in the grace period to fail. The solution to 120 this problem is to add an /etc/defaultrouter file to the server. 121 122 If your server takes a long time to reboot, e.g. a SunFire machine that has 123 lots of memory/disk, you may want to set the following variable a bigger value 124 (in seconds): 125 setenv REBOOTIMER 1800 (optional) 126 default is 480 127 128 Note: the recovery tests will reboot the server. It may ask for fsck 129 during the rebboot due to the LOFI setup. Hence, it may help 130 to turn on logging (via /etc/vfstab) of the filesystem that 131 the BASEDIR, e.g. /NFSv4Test, is set to before running the tests. 132 133 Note: This test suite now uses sharectl(1M) to change/reset the NFS properties, 134 which would restart the corresponding services. Any transient (or 135 temporary) exported filesystems in the test systems shared prior to the 136 test run would get lost/unshared. If these shares in the test systems 137 need to be available after running the suite, make sure they are shared 138 permanently, e.g. use sharemgr(1M) "share -p" to share the filesystems. 139 140 IPv6 support 141 ------------ 142 The test suite has IPv6 support turned on by default. If your client and 143 server supports NFS over IPv6 and you want to run the tests over the IPv6 144 connection, please make sure the SERVER variable is set to the valid name 145 for IPv6 and set the following variable before running the tests: 146 setenv TRANSPORT tcp6 147 default is tcp 148 149 Trusted Extensions over a CIPSO connection 150 ------------------------------------------ 151 In order to successfully test NFS in Trusted Extensions over a CIPSO 152 connection, the NFS server MUST be configured with at least two IP 153 addresses, one of which is allocated solely for use by the global zone. 154 The following variable must also be defined: 155 156 setenv ZONE_PATH /zone/<zone name> (required) 157 158 where: 159 /zone directory is where the non-global zone 160 paths reside. 161 162 example: 163 setenv ZONE_PATH /zone/public 164 165 This would produce the resultant MNTPTR default of: 166 /zone/public/NFS4_Mnt 167 And would produce the resultant BASEDIR default of: 168 /zone/public/NFSv4Test 169 And would produce the resultant QUOTADIR variable to contain: 170 /zone/public/root/NFSv4Test/QUOTA_FS 171 172 NOTE: 173 For the NFS client, there is no need to allocate a unique IP to 174 the global zone; the entire system can be configured to have just 175 a single all-zones IP address. 176 177 The default for ZONE_PATH is NULL. 178 179 180 A journal file of the test results will be created for each subdir, along 181 with a Summary file containing condensed test status under $LOGDIR directory. 182 These Summary files can be compared against the baseline results. 183 184 185 References: 186 ----------- 187 188 Please check the NFSv4 specification for more information on NFS version 4 189 protocols. 190 http://www.ietf.org/rfc/rfc3530.txt 191 192 193 The nfsv4shell/nfsh/nfsh.man manpage details the usage of each NFSv4 194 operation in the nfsv4shell, which is used for most of the tests in 195 the basic_ops subdir, and a few tests in other subdirs as well. 196 197 198 ------------- 199 End of README