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 # ident "@(#)README 1.7 09/08/23 SMI"
27 #
28
29
30 DESCRIPTION:
31 ============
32 This test suite is designed to test the functionality of the sharemgr and
33 sharectl, they are file system share configuration utilities.
34
35
36 PREREQUISITES:
37 ==============
38 1. You must be root in global zone to run this test suite, because ordinary
39 user does not have permission to do share, and share in non-global zone
40 is not supported at present. Moreover, tests in sharemgr/zones subdir
41 require to create zones, it cannot be done in non-global zone.
42
43 2. The CTI-TET test harness lite package (SUNWstc-tetlite) is required, because
44 this test suite is implemented based on CTI-TET test harness.
45
46 3. The STC genutils tool package (SUNWstc-genutils) is required, because this
47 test suite uses some functions defined in the libraries of this tool.
48
49 4. Your TESTDIR must have 2G free space at least to test sharemgr functionality,
50 because zone tests need create zone for testing. If there is no enough free
51 space in the default test directory(/SHARE_tests), please provide an
52 alternative directory by setting TESTDIR before configuration:
53
54 For example:
55
56 root# export TESTDIR=<your_alternative_dir>
57 root# run_test -L /var/tmp/share share configure
58
59 or define TESTDIR in run_test command line directly:
60
61 root# run_test -L /var/tmp/share -v TESTDIR=<your_alternative_dir> \
62 share configure
63
64 5. SHR_TMPDIR is the variable used by this test suite for temporary files
65 and test results, its default value is /var/tmp/share. If you want to
66 use alternative path, please set this variable before configuration:
67
68 For example:
69
70 root# export SHR_TMPDIR=<your_alternative_dir>
71 root# run_test -L $SHR_TMPDIR share configure
72
73 or define SHR_TMPDIR in run_test command line directly, and you can also
74 specify alternative path for test results if you want to save them in
75 different directory other than $SHR_TMPDIR:
76
77 root# run_test -v SHR_TMPDIR=<your_alternative_dir1> \
78 -L <your_alternative_dir2> share configure
79
80 NOTE: without "-L <logdir>" in run_test command line, all test results will
81 be saved under /var/tmp directory by default. But in this test suite,
82 once you specify log directory at configure phase, all test results
83 will be saved to that directory automatically even if you do not have
84 "-L <logdir>" in other run_test commands for later execute and
85 unconfigure phases. However, if you really want to save results of
86 different phases to different paths, you can always execute run_test
87 with "-L <any_logdir_you_want>" certainly.
88
89 6. For the reboot test in sharemgr/oneoff subdir, it requires you to run
90 'reboot' scenario for two times, otherwise, you cannot get the final
91 result, on the other hand, the imcomplete run may cause chaos to your
92 test system and therefore affect the results of other tests.
93
94 root# run_test -F $SHR_TMPDIR/test_config share reboot
95 root# <wait for system comes back>
96 root# run_test -F $SHR_TMPDIR/test_config share reboot
97
98
99 CTI-TET INSTALLATION:
100 =====================
101 In the majority of cases, the CTI-TET lite test harness can be installed
102 from packages. The package is called SUNWstc-tetlite and installs into
103 "/opt" by default. Installation is via the standard Solaris package
104 installation tool pkgadd(1M).
105
106 To install SUNWstc-tetlite, enter the following command line:
107
108 root# pkgadd -d <package location> SUNWstc-tetlite
109
110 Where <package location> is the path containing the SUNWstc-tetlite
111 package directory. 'root#' indicates that this command must be run
112 as root.
113
114 o It is recommended that SUNWstc-tetlite be installed from scratch,
115 rather than on top of an existing installation. Thus, if a copy
116 of SUNWstc-tetlite is already installed, remove it:
117
118 root# pkgrm SUNWstc-tetlite
119
120 It is also acceptable to use an NFS-accessible version of the
121 SUNWstc-tetlite package.
122
123
124 STC GENUTILS INSTALLATION:
125 ==========================
126 See "Installation" section of the README of STC genutils tool.
127
128
129 TEST SUITE INSTALLATION:
130 ========================
131 In the majority of cases, the test suite can be installed from packages.
132 The test suite package is called SUNWstc-fs-share and it installs into
133 "/opt" by default. Installation is via the standard Solaris package
134 installation tool, pkgadd(1M). To install SUNWstc-fs-share, enter the
135 following command:
136
137 root# pkgadd -d <package location> SUNWstc-fs-share
138
139 Where <package location> is the path containing the SUNWstc-fs-share
140 package directory.
141
142 o It is recommended that the test suite package be installed from
143 scratch, rather than on top of an existing installation. Thus,
144 if a version of SUNWstc-fs-share is already installed, first
145 remove it:
146
147 root# pkgrm SUNWstc-fs-share
148
149 It is also acceptable to use an NFS-accessible version of the
150 SUNWstc-fs-share package.
151
152 ALTERNATIVELY, the test suite source can be installed locally, built in
153 the source directory tree and run from that location. This is optional.
154
155 To build the test suite from source, first install the test suite
156 source, and then do the following: ('user$' indicates that these
157 commands need not be run as root):
158
159 user$ TET_ROOT=/opt/SUNWstc-tetlite
160 user$ export TET_ROOT
161 user$ CTI_ROOT=$TET_ROOT/contrib/ctitools
162 user$ export CTI_ROOT
163 user$ TET_SUITE_ROOT=/export/STC/usr/src/suites/fs (example location)
164 user$ export TET_SUITE_ROOT
165 user$ cd $TET_SUITE_ROOT/share
166 user$ /usr/ccs/bin/make
167
168 The build can also install into a 'proto' directory below the workspace
169 root directory. The workspace root is the directory below which the
170 'usr/src/suites/fs' directory resides (in the example above, the
171 workspace root is "/export/STC"). To install binaries into the proto
172 directory, do:
173
174 user$ /usr/ccs/bin/make install
175
176 In addition, test suite binary packages can be constructed using the
177 contents of the proto directory. To build the test suite packages, do:
178
179 user$ /usr/ccs/bin/make package
180
181 This can be done instead of, or in addition to 'make install'. The
182 packages thus constructed will be stored in the 'packages' directory
183 under the workspace root.
184
185
186 TEST SUITE CONFIGURATION:
187 =========================
188 Test configuration is required to be done as root.
189
190 1. Set the following environment variables
191 export TET_ROOT=/opt/SUNWstc-tetlite
192 export CTI_ROOT=$TET_ROOT/contrib/ctitools
193 export TET_SUITE_ROOT=/opt/SUNWstc-fs-share (installation path of suite)
194 PATH=$PATH:$CTI_ROOT/bin:/opt/SUNWstc-genutils/bin
195 export PATH
196
197 2. To configure the test suite :
198
199 root# run_test -L <logdir> [-v TESTDIR=<your_alternative_dir>] \
200 [-v setup_once=FALSE] share configure
201
202 where setup_once variable is used to indicate when the needed test file
203 systems will be created, ie. by default(setup_once=TRUE), test file systems
204 are created only once at configure phase, and removed at unconfigure phase,
205 this makes the test suite execute faster; otherwise, test file systems will
206 be created/removed at execution phase by each subdir before/after their tests
207 run, which makes the test suite run with "Clean Slate" in the case of failure
208 propagation.
209
210 2G free space is required for the test suite to operate on. The TESTDIR do
211 not need to have filesystems created in them. The test suite will
212 create the appropriate filesystem types in the specified test dir, based
213 on the fs type of TESTDIR. This also means that any data in the TESTDIR
214 given will be destroyed.
215
216 The 'configure' will always configure a mix of ufs and zfs filesystems, ie.
217 half ufs and half zfs.
218
219
220 TEST SUITE EXECUTION:
221 =====================
222 The test suite executions is required to be done as root.
223
224 If not already available from the configuration phase, set the
225 following environment variables:
226
227 export TET_ROOT=/opt/SUNWstc-tetlite
228 export CTI_ROOT=$TET_ROOT/contrib/ctitools
229 export TET_SUITE_ROOT=/opt/SUNWstc-fs-share (installation path of suite)
230 PATH=$PATH:$CTI_ROOT/bin:/opt/SUNWstc-genutils/bin
231 export PATH
232
233 To run all tests expect those in oneoff subdir, just do the following:
234
235 (make sure to expand SHR_TMPDIR with your real path, or have it
236 defined in your environment, otherwise, run_test will fail)
237 root# run_test -F $SHR_TMPDIR/test_config share
238
239 NOTE: The following usage of the run_test command is supported:
240
241 root# run_test -F $SHR_TMPDIR/test_config \
242 share [<scenario>|tc_dir:[tp_list]]
243
244 For example:
245
246 root# run_test -F $SHR_TMPDIR/test_config share create
247 (run only the 'create' test scenario, see 'SCENARIO DEFINITION'
248 section below for more definitions of scenarios)
249
250 root# run_test -F $SHR_TMPDIR/test_config share sharemgr/create:3
251 (run only the sharemgr/create:3 test)
252
253
254 TEST SUITE UNCONFIGURE:
255 =======================
256 The unconfiguration of the test suite mainly takes out:
257 - the zfs pool created by configure
258 - the test file systems if setup_once=TRUE
259 - the configuration file
260 from the current host, so that an NFS-mounted point for execution
261 can be used. More important, it does NOT unconfigure any shares that
262 might have been left around due to test suite failure.
263
264 To unconfigure the test suite, run:
265
266 root# run_test -F $SHR_TMPDIR/test_config share unconfigure
267
268
269 SCENARIO DEFINITION:
270 ====================
271 The tet_scen file defines main scenarios that this test suite contains, you can
272 choose any scenario to run according to your specific test requirement. The
273 following matrix illustrates which scenario covers what tests.
274
275 +--------------+----------------------------------------+----------------------+
276 | Scenario | Involved | Comment |
277 | Name | Tests | |
278 +--------------+----------------------------------------+----------------------+
279 | all | all sharemgr and sharectl tests except | it is the default |
280 | | tests in 'oneoff' subdir | scenario |
281 +--------------+----------------------------------------+----------------------+
282 | sharemgr | all functional tests for sharemgr | it includes tests in |
283 | | | many subdirs |
284 +--------------+----------------------------------------+----------------------+
285 | sharectl | all functional tests for sharectl | tests in one subdir |
286 +--------------+----------------------------------------+----------------------+
287 | short | equivalent to 'all' scenario, but | create zone takes |
288 | | without 'zone' tests | more time |
289 +--------------+----------------------------------------+----------------------+
290 | add | test "sharemgr add-share" subcommand | |
291 +--------------+----------------------------------------+----------------------+
292 | create | test "sharemgr create" subcommand | |
293 +--------------+----------------------------------------+----------------------+
294 | delete | test "sharemgr delete" subcommand | |
295 +--------------+----------------------------------------+----------------------+
296 | disable | test "sharemgr disable|enable" | |
297 | | subcommands | |
298 +--------------+----------------------------------------+----------------------+
299 | move | test "sharemgr move-share" subcommand | |
300 +--------------+----------------------------------------+----------------------+
301 | remove | test "sharemgr remove-share" subcommand| |
302 +--------------+----------------------------------------+----------------------+
303 | set_ | test "sharemgr set" subcommand | |
304 +--------------+----------------------------------------+----------------------+
305 | set_security | test "sharemgr set|unset" subcommands | |
306 | | with different security properties | |
307 +--------------+----------------------------------------+----------------------+
308 | set_share | test "sharemgr set-share" subcommand | |
309 +--------------+----------------------------------------+----------------------+
310 | show | test "sharemgr show" subcommand | |
311 +--------------+----------------------------------------+----------------------+
312 | unset_ | test "sharemgr unset" subcommand | |
313 +--------------+----------------------------------------+----------------------+
314 | usage | check if usage presents correct info | |
315 +--------------+----------------------------------------+----------------------+
316 | zfs | test interaction of "sharemgr" and | interoperability |
317 | | "zfs set sharenfs" | |
318 +--------------+----------------------------------------+----------------------+
319 | zones | negative tests in non-global zone | zone will be created |
320 +--------------+----------------------------------------+----------------------+
321 | oneoff | one test to check sharemgr behavior if | for bug verify only |
322 | | mountd is killed | |
323 +--------------+----------------------------------------+----------------------+
324 | reboot | one test to check if shares and groups | for bug verify only |
325 | | can survive system reboot | |
326 +--------------+----------------------------------------+----------------------+
327 | configure | for test suite configuration only | not a test |
328 +--------------+----------------------------------------+----------------------+
329 | unconfigure | for test suite unconfiguration only | not a test |
330 +--------------+----------------------------------------+----------------------+