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
27 DESCRIPTION
28 ===========
29
30 This test suite contains common tests for different NFS versions
31 (i.e., nfsv4, future 4.1, etc).
32
33
34 TEST STRUCTURE
35 ==============
36
37 ${STF_SUITE_ROOT}
38 |- config.vars
39 |- checkenv_def
40 |- configure.ksh
41 |- unconfigure.ksh
42 |- bin
43 |- lib
44 |- include
45 +- setup
46 | +- nfsv4
47 | | |- checkenv_def
48 | | |- configure.ksh
49 | | |- unconfigure.ksh
50 | ...
51 |
52 +- tests
53 +- delegation
54 +- openlock
55 +- acl
56 +- file_ops
57 +- recovery
58 +- stress
59
60 - programs used by tests are put into STF_TEST_SUITE/bin
61 - c function libs are put into STF_TEST_SUITE/lib
62 - ksh script libs are put into STF_TEST_SUITE/include
63 - test cases are grouped into 6 directories so far, more will
64 be added in the later phases as needed:
65 - delegation: test nfs delegation feature.
66 - openlock: test nfs open/lock state management.
67 - acl: test nfs acl.
68 - file_ops: test file/dir operations via nfs
69 - recovery: test nfs recovery feature.
70 - stress: stress on open/read/write/lock ops.
71
72 To make it easy to write and deploy multiple setups, files for a
73 specific setup are placed under a dedicated subdir.
74
75 User needs to set SETUP env variable to specify which configuration
76 files to use. If SETUP=none, there will be no setup, nor any
77 configuration files. If SETUP=nfsv4, top-level configuration files
78 will redirect call from STF to corresponding files in setup/nfsv4.
79
80 Top-level configuration files also perform some common tasks required
81 by all setups.
82
83
84 PREREQUISITES
85 =============
86
87 Below are the requirements common to all setups:
88
89 1. You must have at least two machines. One is test client where
90 you run those tests, another one is NFS server which is accessed
91 remotely. Some tests(recovery, delegation) need three machines,
92 you should set variable 'CLIENT2" as the second client's name.
93
94 2. All systems under testing (including the local system) must
95 enable r* service (i.e., run the command "netservices open")
96 and be able to do rcp/rsh to each other as root; (i.e., add
97 "local_host_name root" to ~/.rhosts on server, and comment out
98 CONSOLE entry in /etc/default/login).
99
100 3. The suite requires the "root" password to do setup. You can
101 either run the suite as root, or enter the root password when
102 it asks on command line when you do 'stf_configure' as a regular
103 user.
104
105 4. Make sure STF tools be in your PATH.
106
107 5. You must set SETUP env variable to specify the setup on which
108 you want to run your tests. Currently it can have two values:
109
110 nfsv4 - run tests on NFSV4.0 protocol
111 none - run tests on the environment user set up manually.
112
113 "none" setup is a special setup. In this setup, the test suite
114 won't do any setup. That means user should set up a workable
115 environment manually before he runs tests, and set up env
116 variables needed by tests correctly. If you want to use this
117 mode, see more details in "MANUAL SETUP" section below.
118
119 6. Except SETUP=none, SERVER env variable must be set to specify
120 server machine.
121
122 7. If you run tests on TX, you must specify ZONE_PATH env variable
123 to specify the pathname to labeled zone root file system.
124
125 8. If user set SHROPT to "sec=krb5" (or "sec=krb5i", "sec=krb5p")
126 Then test will setup kerberos environment in all machine.
127 In that case, STC krb5tools are required. This test suite
128 can use either a local installation of the SUNWstc-krb5tools
129 package, or a remote, NFS-mounted location of the tools.
130 KRB5TOOLS_HOME points to its root directory. Its default value is
131 /opt/SUNWstc-krb5tools. To use krb5tools from elsewhere,
132 simply set KRB5TOOLS_HOME in your environment, or use the '-c' option,
133 for example:
134
135 $ stf_configure -c \
136 "KRB5TOOLS_HOME=/ws/stcnv-gate/proto/tools/krb5tools"
137
138 Krb5 tests also uses four other env variables: DNS_DOMAIN,
139 SRV_DNS_DOMAIN, CLT2_DNS_DOMAIN, DNS_SERVER:
140
141 DNS_DOMAIN - client dns domain. Default value is
142 sfbay.sun.com.
143 SRV_DNS_DOMAIN CLT2_DNS_DOMAIN
144 - server dns domain and client2 dns domain.
145 If users don't specify them, the values are
146 got from the following resources:
147 - /etc/resolv.conf
148 - default as DNS_DOMAIN
149 So user needs to set them if the machine has
150 a different DNS domain than client.
151 DNS_SERVER - a dns server that can resolve client
152 and server's dns names.
153
154 Notes:
155 - Currently openlock tests don't support krb5 config.
156 - DNS_DOMAIN, SRV_DNS_DOMAIN, CLT2_DNS_DOMAIN is used to construct
157 full qualified domain name for client and server, so they
158 cannot be, for example, "sun.com", instead they should
159 be "sfbay.sun.com", "ireland.sun.com", etc. BTW, although
160 test scripts can get client and server's full qualified
161 domain name automatically from dns sever, that requires
162 reverse dns lookup has been set up for machines being
163 queried, which is not always true for lab machines.
164
165 9. If not all systems participating in test execution are of a single
166 architecture (a "cross-architecture" testing scenario), the user shall
167 be prepared to pkgadd, install, mount or in some other manner make
168 available the appropriate test binaries on all systems participating
169 in the test. or install test suite for all architectures into the client.
170 And make sure the root directory of test suite on all systems is
171 the SAME path. For example, CLIENT2 - sparc; client - i386, if we have
172 a binary in client located under /opt/SUNWstc-suite/bin/386/foo,
173 then we can also find a sparc binary in server or client under
174 /opt/SUNWstc-suite/bin/sparc/foo.
175
176
177 Below are requirements specific to nfsv4 setup:
178
179 1. By default, the test will detect automatically the filesystem type of
180 $SHRDIR on SERVER. If filesystem type is ZFS, tests will run over ZFS;
181 if filesystem type is UFS, tests will run over UFS.
182
183 If SERVER is zfs boot, and you want to run the tests over UFS, you
184 must provide a dir based on UFS and define it to SHRDIR variable;
185 Similarly, if SERVER is ufs boot, and you also want to run the tests
186 over ZFS, you must provide a dir based on ZFS and define it to
187 SHRDIR variable.
188
189
190 OPTIONAL SETTINGS
191 =================
192
193 The following env variables(especially SHROPT and MNTOPT) may be
194 useful when running tests:
195
196 SHRDIR - shared directory on server (default is "/nfsgen_share")
197 SHROPT - share options (default is anon=0 since ACL tests need it)
198 MNTDIR - mount directory on client (default is "/nfsgen_mount"),
199 All tests are run in this directory
200 MNTOPT - mount options (default is "rw")
201 STRESS_TIMEOUT - By default, the stress test will return TIMEOUT if
202 execution time of single test exceeds 3 hours(10800s). If you
203 change the value of the variables in stress/stress.vars,
204 you may need to reset STRESS_TIMEOUT to your expected time.
205 NFSGEN_DEBUG - debug variable, which can be set with
206 1) "all" for whole suite,
207 2) the name of test scripts you want to debug(e.g. srv_setup),
208 3) name of function in test scripts(e.g. wait_now),
209 4) "RUN_CHECK_CMD" or "RUN_CHECK_ALL" for commands
210 called by RUN_CHECK() function,
211 5) "RSH" to get output from the "RSH()" function
212 6) combination of 2-5, separated by ":".
213
214 The test suite provides many other env variables for customizing
215 test environment, but they should work out of box and are not
216 suggested to change. If you have any questions on them, feel
217 free to send email to maintainer of this suite, which you can
218 find in STC.INFO file under the test suite's root directory.
219
220
221 CONFIGURATION
222 =============
223
224 You can choose one of the following ways to define the variables
225 and configure your suite from the top level directory.
226
227 1) define environment variables
228
229 $ export SERVER=foo
230 $ stf_configure
231
232 2) use '-c" option
233 $ stf_configure -c "SERVER=foo" -c ...
234
235 3) use '-f' option
236 $ stf_configure -f ./myconf
237
238
239 EXECUTION
240 =========
241
242 At execution phase, you can only use 'stf_execute' to run whole suite or
243 specified tests via '-r' option.
244
245 Although stf_execute supports "-c" option to specify variables which
246 overrides those specified at configuration phase, you MUST NOT do that
247 for nfs suites, i.e., stf_execute -c "CLIENT2=client2" -c "SHRDIR=testdir",
248 since the suite has done corresponding configuration against those variables,
249 re-defining them at execution phase may cause confusing. But you can
250 print debugging info into journal file via 'stf_execute -c "NFSGEN_DEBUG=:xx:"',
251 which is an exception.
252
253 All results will be saved in the journal file under
254 /var/tmp/nfsgen/results or the directory defined by 'STF_RESULTS'.
255
256 Notes:
257 - Some tests call ipfilter to block packets, but ipfilter doesn't work
258 with RDMA configuration, so if you run the suite w/RDMA, those tests
259 (clntrecov_rw_pos01,clntrecov_rw_pos02) may return TIMEOUT.
260
261
262 UNCONFIGURATION
263 ===============
264
265 You can run the following command from the top level directory
266
267 $ stf_unconfigure
268
269
270 TEST DEVELOPMENT
271 ================
272
273 *NOTE*: This section is intended only for people who work on
274 this test suite. If you don't want to change the test suite, add
275 new setup or tests, you can skip this section.
276
277 nfsgen test suite is unique in that it supports multiple setups,
278 new setups, as well as new tests, can be added over time. For this
279 purpose, it is important to define the interface between setup
280 code and tests.
281
282 Tests can make the following assumptions on the test execution
283 environment:
284
285 1) a test directory with read/write/search access($MNTDIR)
286 2) both client and server have same nfs mapid domain($NFSMAPID_DOMAIN)
287 3) both client and server have a same local group($TGROUP),
288 4) both client and server have two same local users($TUSER01 and $TUSER02),
289 they MUST be in $TGROUP and can be any valid user known by both client
290 and server. If SETUP!=none, the suite configuration will
291 create in locally in both client and server.
292
293 All setup "plugins" should provide this, and tests are not
294 expected to change them during execution.
295
296
297 MANUAL SETUP
298 ============
299
300 As we mentioned before, when user sets SETUP variable, he can
301 set it to "none". This means user will set up the whole test
302 environment manually and let the test suite skip configuration
303 phase(however, user still needs to run stf_configure, which is
304 a step required by STF. It is just that stf_configure will
305 effectively do nothing in term of test environment setup.) This
306 feature is believed to be useful in some cases.
307
308 It should be noted that in this case, user is required to not
309 only set up a workable test environment, but also to set those
310 env variables correctly which compose of the interface between
311 setup code and tests(see "TEST ENVIRONMENT INTERFACE" section).
312
313 These variables are:
314
315 MNTDIR - test directory
316 NFSMAPID_DOMAIN - nfs mapid domain
317 TGROUP - a regular group on both client and server
318 TUSER01 - a regular user in TGROUP on both client and server
319 TUSER02 - a regular user in TGROUP on both client and server
320 TestZFS - If exported filesystem on the server is ZFS,
321 the variable should be set to 1.
322 CLIENT2 - Optional, if you set it, you should make sure
323 the machine can be access via rsh/rcp as root.
324
325
326 In this case, if you want to run acl tests, you still refer to
327 the README file under tests/acl to do more manual setup.
328
329 When SETUP variable is not set to none, the tests under open and
330 lock directories run separately with delegation on and off. But
331 if the variable is set to none, these tests only run with current
332 delegation configuration on the server.