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 # or http://www.opensolaris.org/os/licensing. 10 # See the License for the specific language governing permissions 11 # and limitations under the License. 12 # 13 # When distributing Covered Code, include this CDDL HEADER in each 14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 # If applicable, add the following below this CDDL HEADER, with the 16 # fields enclosed by brackets "[]" replaced with your own identifying 17 # information: Portions Copyright [yyyy] [name of copyright owner] 18 # 19 # CDDL HEADER END 20 # 21 22 # 23 # Copyright 2009 Sun Microsystems, Inc. All rights reserved. 24 # Use is subject to license terms. 25 # 26 # Copyright 2015 Nexenta Systems, Inc. All rights reserved. 27 # 28 29 DESCRIPTION: 30 =========== 31 This is the 'sharemnt' test suite which consists of tests for 32 share_nfs(1M), mount_nfs(1M), sharemgr(1M) and "zfs set sharenfs". 33 34 35 INSTALLATION: 36 ============ 37 You can install the suite package, or install the suite source and 38 build by yourself. 39 40 1. Installing from Packages 41 42 o In the majority of cases, the test suite can be installed from 43 packages. To do that, you need to be as root. The package is 44 called pkg:/system/test/nfssharemnt and installs into "/opt" by default. 45 Installation is via the standard Solaris package installation 46 tool pkg(1M). To install it simply enter the 47 following command line: 48 49 # pkg install pkg:/system/test/nfssharemnt@<version> 50 51 It is recommended that you install the packages from scratch, 52 rather than on top of an existing installation. Thus, if an 53 old version of the tests is installed: 54 55 # pkg uninstall pkg:/system/test/nfssharemnt@<version> 56 57 2. Installing the Test Suite Source 58 59 You can install the suite source locally as any user. 60 61 62 UNINSTALLATION: 63 ============== 64 Prior to uninstalling the test suite, you may want to run 65 stf_unconfigure first. For more detail see UNCONFIGURATION. 66 67 1. Uninstalling the Test Suite Package 68 69 Use the standard Solaris package installation tool pkg(1M) to 70 uninstall the package as root: 71 72 # pkg uninstall pkg:/system/test/nfssharemnt@<version> 73 74 2. Uninstalling the Test Suite Source 75 76 You can remove the corresponding directory. 77 78 79 BUILDING: 80 ======== 81 The test suite is built as part of kernel nightly build. 82 83 PREREQUISITES: 84 ============= 85 The suite runs in remote networking mode. You need to prepare 86 two systems to run all tests. One is the local host where the 87 tests are run and the other one is the remote system acting as 88 the NFS SERVER. 89 90 Also, please do the followings before running the tests: 91 92 Make sure STF and STC genutils Tools be in your PATH. 93 94 You can use either a local installation of the SUNWstc-stf and 95 SUNWstc-genutils packages: 96 97 $ PATH=$PATH:/opt/SUNWstc-stf/bin/$(isainfo -n) 98 $ PATH=$PATH:/opt/SUNWstc-genutils/bin 99 $ export PATH 100 101 or the tools you build in your own workspace, for example: 102 103 $ PATH=$PATH:<WS_ROOT>/proto/tools/stf/bin/$(isainfo -n) 104 $ PATH=$PATH:<WS_ROOT>/proto/tools/genutils/bin 105 $ export PATH 106 107 Please note that if the STC genutils tool could not be accessed by 108 NFS path, it is required to install SUNWstc-genutils package to the 109 same path on all systems participating in test. 110 111 2. MUST define environment variable "SERVER". 112 113 SERVER is for your server's hostname. 114 115 3. The suite requires the "root" password to setup the server. 116 Run 'stf_configure' as a non-root user and enter the root 117 password when prompted for it. 118 119 4. All systems under testing (including the local system) must 120 enable r* service (i.e. run the command "netservices open") 121 and be able to do rcp/rsh to each other as root; (i.e. add 122 "local_host_name root" to ~root/.rhosts on server). 123 124 5. You can define the following optional variables, if not set, 125 the default value (see config.vars file) will be used. 126 127 NFSSHRDIR - the direcotry exported in server 128 NFSMNTDIR - path for localhost to mount 129 SHAREMNT_DEBUG - debug variable 130 There are two ways to turn debug on: 131 1) export SHAREMNT_DEBUG=<value>; stf_execute ... 132 2) stf_execute -c SHAREMNT_DEBUG=<value> ... 133 134 SHAREMNT_DEBUG can be set to the following <value> 135 1) "all" for the whole suite, 136 2) "RSH" for debug RSH and all scripts executed on server, 137 3) the name of the case file you want to debug (e.g. runtests), 138 4) name of function in tools/genutils/include (e.g. wait_now), 139 5) name of function in include/sharemnt.kshlib (e.g. share_check), 140 6) combination of 2-5, separated by ":". 141 142 For example: 143 1) turn debug on for the whole suite at runtime 144 $ stf_execute -c SHAREMNT_DEBUG=all 145 2) turn debug on in function share_check() and RSH() 146 $ export SHAREMNT_DEBUG=share_check:RSH; stf_execute -m i386 147 148 TESTGRP - testing group used by sharemgr 149 150 6. Trusted Extensions over a CIPSO connection 151 152 If you want to test NFS in Trusted Extensions over a CIPSO 153 connection you MUST define the variable "ZONE_PATH" with 154 <non-global zone path> 155 156 Example: 157 $ stf_configure -c "SERVER=myserver" \ 158 -c "ZONE_PATH=/zone/public" 159 160 This will produce the resultant NFSSHRDIR default of: 161 /zone/public/TESTDIR_shmnt 162 And will produce the resultant NFSMNTDIR default of: 163 /zone/public/MNTDIR_shmnt 164 165 The default for ZONE_PATH is NULL. 166 167 NOTE: Only NFSv3 and NFSv4 are supported under Trusted Extensions. 168 169 7. For stress test, by default, we only share 2000 entries on 170 the server. You can reset the number with the variable 171 "NUM_SHARES". 172 173 If the expected time of sharing $NUM_SHARES entries exceeds 174 2 hours, you SHOULD reset the variable "STRESS_TIMEOUT" 175 with your expected time. Eg. if you want to share 40000 176 entries, and expected time is less than 3 hours, you can set 177 with following configuration: 178 179 $ stf_configure -c "SERVER=myserver" -c "NUM_SHARES=40000"\ 180 -c "STRESS_TIMEOUT=10800" 181 182 For sharemgr group stress test, by default, we create 100 groups, 183 with 5 entries in each group. You can reset the number 184 with the variables "NUM_GROUPS" and "NUM_ENTRYS". Eg. 185 if you want to create 200 groups, with 10 entries in each 186 group, and expected time is less than 3 hours, you can set 187 with following configuration: 188 189 $ stf_configure -c "SERVER=myserver" -c "NUM_GROUPS=200"\ 190 -c "NUM_ENTRYS=10" -c "STRESS_TIMEOUT=10800" 191 192 8. For multiple clients tests. If you want to run this suite on 193 multiple clients with the same SERVER simultaneously, please 194 note the followings: 195 - stress test does not support it. 196 - krb5 test does not support it. 197 - ZFS test does not support it. 198 - NFSSHRDIR, NFSMNTDIR, ZONE_PATH MUST be set as same for 199 nfslogd test. 200 201 9. For krb5 tests. STC krb5tools are required, they can be found in the 202 STC genutils tool, see more details in its README. 203 204 For using krb5tools, please make sure these packages are installed 205 or the related commands are available on your test systems: 206 - SUNWkdcr: Kerberos V5 KDC (root) 207 - SUNWkdcu: Kerberos V5 Master KDC (user) 208 - SUNWkrbr: Kerberos version 5 support (Root) 209 - SUNWkrbu: Kerberos version 5 support (Usr) 210 211 The krb5 tests also use three other env variables: DNS_DOMAIN, 212 SRV_DNS_DOMAIN, DNS_SERVER: 213 214 DNS_DOMAIN - client dns domain. Default value is 215 sfbay.sun.com. 216 SRV_DNS_DOMAIN - server dns domain. By default it has 217 the same value as DNS_DOMAIN. User need 218 to set it if server has a different 219 DNS domain than client. 220 DNS_SERVER - a dns server that can resolve client 221 and server's dns names. 222 223 Notes: DNS_DOMAIN and SRV_DNS_DOMAIN is used to construct 224 full qualified domain name for client and server, so they 225 cannot be, for example, "sun.com", instead they should 226 be "sfbay.sun.com", "ireland.sun.com", etc. BTW, although 227 test scripts can get client and server's full qualified 228 domain name automatially from dns sever, that requires 229 reverse dns lookup has been set up for machines being 230 queried, which is not always true for lab machines. 231 232 10. For sharetab tests. One case needs reboot the server, to run 233 it, please set env variable SHRTAB_REBOOT as TRUE. The 234 default value is FALSE, this case will be UNTEST. 235 236 11. If both client and server are setup with RDMA connection and you 237 want to run the tests with NFS/RDMA, set the following variable 238 before configuration: 239 $ export TESTRDMA=yes (default TESTRDMA=no) 240 241 The "proto=rdma" option will be added to the mount options of the 242 "basic" and "krb5/basic" subdirs, if TESTRMDA=yes. 243 244 12. With more share/mount options are added to basic subdir, its test 245 assertion list becomes bigger, so it takes more time to run basic 246 tests. If time is in pressure, user can choose what to run by picking 247 the option combinations from the default selectable lists(please 248 see SHROPTS_LIST, MNTOPTS_LIST and VEROPTS_LIST defined in 249 basic/basic.vars). Note: other options beyond the relative list 250 are not allowed. 251 252 For example, set the following variables before configuration: 253 254 $ export SHROPTS="rw public" (default SHROPTS=SHROPTS_LIST) 255 $ export MNTOPTS="ro proto=tcp" (default MNTOPTS=MNTOPTS_LIST) 256 $ export VEROPTS="vers=4 vers=2" (default VEROPTS=VEROPTS_LIST) 257 258 In addition, for saving the time of execution, it is strongly 259 suggested to install and use STF tools locally. 260 261 13. By default, krb5/basic will not test public option, if you want 262 to run krb5 tests with public option, set the following variable 263 before configuration: 264 265 $ export KRB5_PUBLIC=yes (default KRB5_PUBLIC=no) 266 267 And if you want to limit the NFS version tests to default, v4, 268 v3, or v2 or combination of these, set the following variable 269 before configuration, e.g. to default and v3, do: 270 271 $ export KRB5_VERS="null 3" (default KRB5_VERS="null 4 3 2") 272 273 Both variables must be set BEFORE or at "stf_configure" to generate 274 the correct set of tests, for example: 275 276 $ export KRB5_VERS="null" ; stf_configure 277 or $ stf_configure -c KRB5_VERS=4 -c KRB5_PUBLIC=yes 278 279 14. To test options quota/noquota of mount_nfs(1M) in misc_opts, if NFSSHRDIR 280 is based on UFS, they will be setup using LOFI (but NOTE that the LOFI 281 setup will be lost if you reboot the SERVER). Tests covered quota/noquota 282 options may fail expectedly if LOFI setup is gone. 283 284 285 CONFIGURATION: 286 ============= 287 You can choose one of the following ways to define the variables 288 and configure your suite from the top level directory. 289 290 1) define environment variables 291 $ export SERVER=myserver 292 $ stf_configure 293 294 2) use '-c" option 295 $ stf_configure -c "SERVER=myserver" \ 296 -c "SHAREMNT_DEBUG=configure" 297 298 3) use '-f' option 299 $ echo "export SERVER=myserver" > /tmp/varfile 300 $ stf_configure -f /tmp/varfile 301 302 303 EXECUTION: 304 ========= 305 At execution phase, you can run 'stf_execute' by itself, or run 306 'stf_execute -c' specifying optional variables which will override 307 those specified in the configure phase. 308 309 All results will be saved in journal files under the 'STF_RESULTS' 310 directory; this directory defaults to 311 /var/tmp/nfssharemnt-tests/results 312 when the test suite is executed from /opt/SUNWstc-nfs-sharemnt 313 314 315 UNCONFIGURATION: 316 =============== 317 You can run 'stf_unconfigure' from the top level directory. 318 $ stf_unconfigure 319 320 Please note that in order to run tests after unconfiguration, 321 'stf_configure' must first be invoked to reconfigure the test 322 suite before running 'stf_execute'. 323 324 325 TEST STRUCTURE: 326 ============== 327 STF_TEST_SUITE--include 328 |-tests-----basic 329 |-krb5 330 |-nfslogd 331 |-others 332 |-sharetab 333 |-stress 334 335 - ksh script libs are put into STF_TEST_SUITE/include 336 - test cases are grouped into 6 directories so far, more will 337 be added in the later phases as needed: 338 - basic: the basic share_nfs/mount_nfs options 339 - krb5: share and mount with sec=krb5* options 340 - nfslogd: tests include log option with different tag 341 - others: tests require specific system configuration 342 and regression tests for the bugs found/fixed 343 sharemgr 344 - sharetab: in-kernel sharetab test 345 - stress: stress test